1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
|
<?xml version="1.0" encoding="UTF-8"?>
<guide self="appendices/devbook-guide/">
<chapter>
<title>Gentoo DevBook XML guide</title>
<section>
<title>DevBook XML design goals</title>
<body>
<p>
The DevBook XML syntax is lightweight yet expressive, so that it is easy to
learn yet also provides all the features we need for the creation of web
documentation. The number of tags is kept to a minimum <d/> just those we need.
This makes it easy to transform DevBook XML into other formats, such as DocBook
XML/SGML or web-ready HTML.
</p>
<p>
The goal is to make it easy to <e>create</e> and <e>transform</e> DevBook XML
documents.
</p>
</body>
</section>
<section>
<title>Basic structure</title>
<body>
<p>
Let's start learning the DevBook XML syntax. We'll start with the initial tags
used in a DevBook XML document:
</p>
<codesample lang="sgml" caption="The preamble of a DevBook XML document">
<?xml version="1.0" encoding="UTF-8"?>
<guide self="appendices/devbook-guide/">
<chapter>
<title>Gentoo DevBook XML guide</title>
</codesample>
<p>
On the first lines, we see the XML declaration that identifies this as an XML
document. Next, there's a <c><guide></c> tag <d/> the entire document is
enclosed within a <c><guide> </guide></c> pair. Its <c>self</c>
attribute must point to the relative path of the document from the root node;
in the example above the path is <c>appendices/devbook-guide/</c>. An exception
is the root node itself, which has <c><guide root="true"></c> instead.
</p>
<p>
Next, there is a <c><chapter></c> tag. Every document must have exactly
one chapter. Its <c><title></c> is used to set the title for the entire
document.
</p>
<p>
All elements must be closed of course, so the document ends with:
</p>
<codesample lang="sgml">
</chapter>
</guide>
</codesample>
</body>
<subsection>
<title>Sections and subsections</title>
<body>
<p>
Once the initial tags have been specified, you're ready to start adding the
structural elements of the document. Chapters are divided into sections;
each section can hold zero or more subsections, which can contain zero or more
subsubsections. Section, subsection and subsubsection elements must have a
title. Here's an example section with a single subsection, consisting of a
paragraph:
</p>
<codesample lang="sgml" caption="Minimal DevBook example">
<section>
<title>This is my section</title>
<subsection>
<title>This is subsection one of my section</title>
<body>
<p>
This is the actual text content of my subsection.
</p>
</body>
</subsection>
</section>
</codesample>
<p>
Above, I set the section title by adding a child <c><title></c> element
to the <c><section></c> element. Then, I created a subsection by adding
a <c><subsection></c> element. If you look inside the
<c><subsection></c> element, you'll see that it has two child elements
<d/> a <c><title></c> and a <c><body></c>. While the
<c><title></c> is nothing new, the <c><body></c> is <d/>
it contains the actual text content of this particular subsection. We'll look
at the tags that are allowed inside a <c><body></c> element in a bit.
</p>
<note>
The <c><chapter></c>, <c><section></c>, <c><subsection></c>
and <c><subsubsection></c> elements contain a <c><body></c> and/or
any number of section elements of the next lower level. Skipping of levels is
not allowed, e.g., a subsection cannot be directly below a chapter.
</note>
</body>
</subsection>
<subsection>
<title>Including sub-documents</title>
<body>
<p>
The manual is organized as a tree. Each directory contains one document, which
can include multiple sub-documents using the <c><include href="foo/"/></c>
tag. Note that the trailing slash in the <c>href</c> value is mandatory.
</p>
<p>
A table of contents can be generated with <c><contentsTree></c>.
Typically, this would be the only element in its own section body, as in
the following example:
</p>
<codesample lang="sgml">
<section>
<title>Contents</title>
<body>
<contentsTree/>
</body>
</section>
</codesample>
</body>
</subsection>
<subsection>
<title>An example <body></title>
<body>
<p>
Now, it's time to learn how to mark up actual content. Here's the XML code for
an example <c><body></c> element:
</p>
<codesample lang="sgml" caption="Example of a body element">
<p>
This is a paragraph. <c>/etc/passwd</c> is a file.
<uri>https://www.gentoo.org/</uri> is my favorite website.
Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now.
</p>
<pre>
This is text output or code.
# this is user input
</pre>
<codesample lang="sgml">
Make HTML/XML easier to read by using selective emphasis:
&lt;foo&gt;bar&lt;/foo&gt;
</codesample>
<note>
This is a note.
</note>
<important>
This is important.
</important>
<warning>
This is a warning.
</warning>
<todo>
Text inside a <c>todo</c> element will appear in the
<uri link="::appendices/todo-list/"/>.
</todo>
</codesample>
<p>
Now, here's how the <c><body></c> element above is rendered:
</p>
<p>
This is a paragraph. <c>/etc/passwd</c> is a file.
<uri>https://www.gentoo.org/</uri> is my favorite web site.
Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now.
</p>
<pre>
This is text output or code.
# this is user input
</pre>
<codesample lang="sgml">
Make HTML/XML easier to read by using selective emphasis:
<foo>bar</foo>
</codesample>
<note>
This is a note.
</note>
<important>
This is important.
</important>
<warning>
This is a warning.
</warning>
<todo>
Text inside a <c>todo</c> element will appear in the
<uri link="::appendices/todo-list/"/>.
</todo>
</body>
</subsection>
</section>
<section>
<title>Body elements</title>
<body>
<p>
We introduced a lot of new tags in the previous section <d/> here's what you
need to know. The <c><p></c> (paragraph), <c><pre></c>
(preformatted block), <c><codesample></c> (code block),
<c><note></c>, <c><important></c>, <c><warning></c> and
<c><todo></c> tags all can contain one or more lines of text.
Besides the <c><figure></c>, <c><table></c>, <c><ul></c>,
<c><ol></c> and <c><dl></c> elements (which we'll cover in just
a bit), these are the only tags that should appear immediately inside a
<c><body></c> element. Another thing <d/> these tags <e>should not</e>
be stacked <d/> in other words, don't put a <c><note></c> element inside
a <c><p></c> element. As you might guess, the <c><pre></c> and
<c><codesample></c> elements preserve their whitespace exactly, making
them well-suited for code excerpts. Both <c><pre></c> and
<c><codesample></c> can have a <c>caption</c> attribute:
</p>
<codesample lang="sgml" caption="Named <pre>">
<pre caption="Output of uptime">
# uptime
16:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25
</pre>
</codesample>
</body>
<subsection>
<title>Code samples and colour-coding</title>
<body>
<p>
The <c><pre></c> tag does not support any syntax highlighting. When you
need syntax highlighting, use the <c><codesample></c> tag along with a
<c>lang</c> attribute <d/> usually you want this to be set to <c>"ebuild"</c>
to syntax highlight ebuild code snippets. Currently, the following languages
are supported:
</p>
<ul>
<li>c</li>
<li>ebuild</li>
<li>make</li>
<li>m4</li>
<li>sgml</li>
</ul>
<note>
Remember that all leading and trailing spaces, and line breaks in
<c><codesample></c> blocks will appear in the displayed html page.
</note>
<p>
Sample <c><codesample lang="c"></c> block:
</p>
<codesample lang="c">
#include <stdio.h>
main()
{
/* This is a comment */
printf("Hello, world!\n");
}
</codesample>
<p>
You can also specify <c>numbering="lines"</c> to enable line numbering, as in
the following example:
</p>
<codesample lang="ebuild" numbering="lines">
# Copyright 1999-2021 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
EAPI=7
DESCRIPTION="MicroGnuEmacs, a port from the BSDs"
HOMEPAGE="https://homepage.boetes.org/software/mg/"
SRC_URI="https://github.com/hboetes/${PN}/archive/${PV}.tar.gz -> ${P}.tar.gz"
LICENSE="public-domain"
SLOT="0"
KEYWORDS="alpha amd64 arm hppa ppc ~ppc64 sparc x86"
RDEPEND="sys-libs/ncurses:0=
>=dev-libs/libbsd-0.7.0"
DEPEND="${RDEPEND}"
BDEPEND="virtual/pkgconfig"
src_install() {
dobin mg
doman mg.1
dodoc README tutorial
}
</codesample>
</body>
</subsection>
<subsection>
<title>Figures</title>
<body>
<p>
Here's how to insert a figure into a document <d/> <c><figure
link="mygfx.png" short="my picture" caption="my favorite picture of all
time"/></c>. The <c>link</c> attribute points to the actual graphic image,
the <c>short</c> attribute specifies a short description (currently used for
the image's HTML <c>alt</c> attribute), and a caption. Not too difficult
:) We also support the standard HTML-style <img src="foo.gif"/> tag
for adding images without captions, borders, etc.
</p>
</body>
</subsection>
<subsection>
<title>Tables</title>
<body>
<p>
DevBook XML supports a simplified table syntax similar to that of HTML. To start
a table, use a <c><table></c> tag. Start a row with a <c><tr></c>
tag. However, for inserting actual table data, we <e>don't</e> support the HTML
<td> tag; instead, use the <c><th></c> if you are inserting a
header, and <c><ti></c> if you are inserting a normal informational
block. You can use a <c><th></c> anywhere you can use a <c><ti></c>
<d/> there's no requirement that <c><th></c> elements appear only in the
first row.
</p>
<p>
Besides, both table headers (<c><th></c>) and table items
(<c><ti></c>) accept the <c>colspan</c> and <c>rowspan</c> attributes to
span their content across rows, columns or both.
</p>
<p>
Furthermore, table cells (<c><ti></c> & <c><th></c>) can be
right-aligned, left-aligned or centered with the <c>align</c> attribute.
</p>
<table>
<tr>
<th align="center" colspan="4">This title spans 4 columns</th>
</tr>
<tr>
<th rowspan="6">This title spans 6 rows</th>
<ti>Item A1</ti>
<ti>Item A2</ti>
<ti>Item A3</ti>
</tr>
<tr>
<ti align="center">Item B1</ti>
<th colspan="2" rowspan="2" align="right">Blocky 2x2 title</th>
</tr>
<tr>
<ti align="right">Item C1</ti>
</tr>
<tr>
<ti colspan="3" align="center">Item D1..D3</ti>
</tr>
<tr>
<ti rowspan="2">Item E1..F1</ti>
<ti colspan="2" align="right">Item E2..E3</ti>
</tr>
<tr>
<ti colspan="2" align="right">Item F2..F3</ti>
</tr>
</table>
</body>
</subsection>
<subsection>
<title>Lists</title>
<body>
<p>
To create ordered or unordered lists, simply use the XHTML-style
<c><ol></c>, <c><ul></c> and <c><li></c> tags. Lists may only
appear inside the <c><body></c> and <c><li></c> tags which means
that you can have lists inside lists. Don't forget that you are writing XML and
that you must close all tags including list items unlike in HTML.
</p>
<p>
Definition lists (<c><dl></c>) are also supported. Please note that
the definition term tag (<c><dt></c>) does not accept any other block
level tag such as paragraphs or admonitions. A definition list comprises:
</p>
<dl>
<dt><c><dl></c></dt>
<dd>A <b>D</b>efinition <b>L</b>ist Tag containing</dd>
<dt><c><dt></c></dt>
<dd><b>D</b>efinition <b>T</b>erm Tags</dd>
<dt><c><dd></c></dt>
<dd>and <b>D</b>efinition <b>D</b>ata Tags.</dd>
</dl>
<p>
The following example copied from
<uri link="https://www.w3.org/TR/REC-html40/struct/lists.html">w3.org</uri>
shows that lists may also be nested and different list types may be used
together:
</p>
<dl>
<dt>The ingredients:</dt>
<dd>
<ul>
<li>100 g flour</li>
<li>10 g sugar</li>
<li>1 cup water</li>
<li>2 eggs</li>
<li>salt, pepper</li>
</ul>
</dd>
<dt>The procedure:</dt>
<dd>
<ol>
<li>Mix dry ingredients thoroughly.</li>
<li>Pour in wet ingredients.</li>
<li>Mix for 10 minutes.</li>
<li>Bake for one hour at 300 degrees.</li>
</ol>
</dd>
<dt>Notes:</dt>
<dd>The recipe may be improved by adding raisins.</dd>
</dl>
</body>
</subsection>
</section>
<section>
<title>Inline elements</title>
<subsection>
<title><c>, <b>, <e>, <sub> and <sup></title>
<body>
<p>
The <c><c></c> element is used to mark up a <e>command</e> or <e>user
input</e>. Think of <c><c></c> as a way to alert the reader to something
that they can type in that will perform some kind of action. For example,
all the XML tags displayed in this document are enclosed in a <c><c></c>
element because they represent something that the user could type in that is
not a path. By using <c><c></c> elements, you'll help your readers
quickly identify commands that they need to type in. Also, because
<c><c></c> elements are already offset from regular text, <e>it is rarely
necessary to surround user input with double-quotes</e>. For example, don't
refer to a "<c><c></c>" element like I did in this sentence. Avoiding
the use of unnecessary double-quotes makes a document more readable <d/> and
adorable!
</p>
<p>
As you might have guessed, <c><b></c> is used to <b>boldface</b> some
text.
</p>
<p>
<c><e></c> is used to apply emphasis to a word or phrase; for example:
I <e>really</e> should use semicolons more often. As you can see, this text is
offset from the regular paragraph type for emphasis. This helps to give your
prose more <e>punch</e>!
</p>
<p>
The <c><sub></c> and <c><sup></c> elements are used to specify
<sub>subscript</sub> and <sup>superscript</sup>.
</p>
</body>
</subsection>
<subsection>
<title><uri></title>
<body>
<p>
The <c><uri></c> tag is used to point to files/locations on the Internet.
It has two forms <d/> the first can be used when you want to have the actual
URI displayed in the body text, such as this link to
<uri>https://www.gentoo.org/</uri>. To create this link, I typed
<c><uri>https://www.gentoo.org/</uri></c>. The alternate form is
when you want to associate a URI with some other text <d/> for example,
<uri link="https://www.gentoo.org/">the Gentoo Linux website</uri>. To create
<e>this</e> link, I typed <c><uri link="https://www.gentoo.org/">the
Gentoo Linux website</uri></c>.
</p>
<p>
Please avoid the <uri link="https://en.wikipedia.org/wiki/Click_here">click
here syndrome</uri> as recommended by the
<uri link="https://www.w3.org/QA/Tips/noClickHere">W3C</uri>.
</p>
</body>
</subsection>
<subsection>
<title>Intra-document references</title>
<body>
<p>
DevBook XML makes it really easy to reference other parts of the document using
hyperlinks. You can create a link pointing to another chapter, like
<uri link="::ebuild-writing/file-format/">Ebuild file format</uri>, by typing
<c><uri link="::ebuild-writing/file-format/">Ebuild file
format</uri></c>, i.e. two colons followed by the relative path from
the root node. To refer to a section in another chapter, like
<uri link="::quickstart/#First ebuild">First ebuild</uri>, type
<c><uri link="::quickstart/#First ebuild">First ebuild</uri></c>.
</p>
<p>
If the link target's chapter (or section etc.) title is to be used as the link
text, an empty <c><uri></c> element can be used. As a matter of fact,
I could have written the two examples above in more compact form:
<c><uri link="::ebuild-writing/file-format/"/></c> and
<c><uri link="::quickstart/#First ebuild"/></c> render as
<uri link="::ebuild-writing/file-format/"/> and
<uri link="::quickstart/#First ebuild"/>, respectively.
</p>
</body>
</subsection>
</section>
<section>
<title>Coding style</title>
<body>
<p>
Since all Gentoo Documentation is a joint effort and several people will
most likely change existing documentation, a coding style is needed.
A coding style contains two sections. The first one is regarding
internal coding <d/> how the XML-tags are placed. The second one is
regarding the content <d/> how not to confuse the reader.
</p>
<p>
Both sections are described next.
</p>
</body>
<subsection>
<title>Internal coding style</title>
<body>
<p>
<b>Newlines</b> must be placed immediately after <e>every</e> DevBook XML tag
(both opening and closing), except for:
<c><title></c>,
<c><th></c>, <c><ti></c>, <c><li></c>,
<c><dt></c>, <c><dd></c>,
<c><b></c>, <c><c></c>, <c><e></c>, <c><d/></c>,
<c><uri></c>.
</p>
<p>
<b>Blank lines</b> must be placed immediately after <e>every</e>
<c><body></c> (opening tag only) and before <e>every</e>
<c><section></c>, <c><p></c>, <c><pre></c>,
<c><codesample></c>, <c><figure></c>, <c><table></c>,
<c><ul></c>, <c><ol></c>, <c><dl></c>, <c><note></c>,
<c><important></c> and <c><warning></c> (opening tags only).
An exception to this rule applies to tags that are located within list items
or table cells.
</p>
<p>
<b>Word-wrapping</b> must be applied at 80 characters except inside
<c><pre></c> and <c><codesample></c>. You may only deviate from
this rule when there is no other choice (for instance when a URL exceeds the
maximum amount of characters). The editor must then wrap whenever the first
whitespace occurs. You should try to keep the <e>rendered</e> content of
<c><pre></c> and <c><codesample></c> elements within 80 columns
to help console users.
</p>
<p>
<b>Indentation</b> may not be used, except with the XML-constructs of which the
parent XML-tags are <c><tr></c> (from <c><table></c>),
<c><ul></c>, <c><ol></c> and <c><dl></c>. If indentation
is used, it <e>must</e> be two spaces for each indentation. That means
<e>no tabs</e> and <e>not</e> more spaces. Besides, tabs are not allowed in
DevBook XML documents (again, except for <pre> and <codesample>).
</p>
<p>
In case word-wrapping happens in <c><ti></c>, <c><th></c>,
<c><li></c> or <c><dd></c> constructs, indentation must be used for
the content.
</p>
<p>
An example for indentation is:
</p>
<codesample lang="sgml" caption="Indentation example">
<table>
<tr>
<th>Foo</th>
<th>Bar</th>
</tr>
<tr>
<ti>This is an example for indentation</ti>
<ti>
In case text cannot be shown within an 80-character wide line, you
must use indentation if the parent tag allows it
</ti>
</tr>
</table>
<ul>
<li>First option</li>
<li>Second option</li>
</ul>
</codesample>
<p>
<b>Opening tags</b> with a single attribute may not be split between lines.
For example, don't put a newline between <c><uri</c> and its <c>link</c>
attribute. Break the line before the <c><uri></c> tag instead.
</p>
<p>
<b>Attributes</b> may not have spaces in between the attribute, the "=" mark,
and the attribute value. As an example:
</p>
<codesample lang="sgml" caption="Attributes">
Wrong : <uri link = "https://www.gentoo.org/">
Correct: <uri link="https://www.gentoo.org/">
</codesample>
<p>
<b>Dashes</b> used as in-sentence punctuation <d/> like this <d/> should be
written as a <c><d/></c> tag surrounded by spaces. It would be difficult
to distinguish a Unicode em-dash from a hyphen when editing the source using a
fixed-width font.
</p>
</body>
</subsection>
<subsection>
<title>External coding style</title>
<body>
<p>
Inside tables (<c><table></c>) and listings (<c><ul></c>,
<c><ol></c> and <c><dl></c>), periods (".") should not be used
unless multiple sentences are used. In that case, every sentence should end
with a period (or other reading marks).
</p>
<p>
Every sentence, including those inside tables and listings, should start
with a capital letter.
</p>
<codesample lang="sgml" caption="Periods and capital letters">
<ul>
<li>No period</li>
<li>With period. Multiple sentences, remember?</li>
</ul>
</codesample>
<p>
Titles should use sentence case, i.e. their first word should start with a
capital letter, and all other words (except proper nouns) should be in lower
case.
</p>
<p>
Try to use <c><uri></c> with the <c>link</c> attribute as much as
possible. In other words, the
<uri link="https://www.gentoo.org/">Gentoo website</uri> is preferred over
<uri>https://www.gentoo.org/</uri>.
</p>
</body>
</subsection>
</section>
</chapter>
</guide>
|
GitWeb