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
|
<?xml version="1.0" encoding="UTF-8"?>
<guide self="appendices/contributing/devbook-guide/">
<chapter>
<title>Gentoo GuideXML Guide</title>
<section>
<title>GuideXML basics</title>
<subsection>
<title>GuideXML design goals</title>
<body>
<p>
The guideXML 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 -- just those we need.
This makes it easy to transform guide 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> guideXML
documents.
</p>
</body>
</subsection>
</section>
<section>
<title>GuideXML</title>
<subsection>
<title>Basic structure</title>
<body>
<p>
Let's start learning the GuideXML syntax. We'll start with the the initial
tags used in a GuideXML document:
</p>
<codesample lang="sgml"><!-- The initial part of a guide XML document -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<!-- $Header$ -->
<guide lang="<i>en</i>">
<title><i>Gentoo Documentation Guide</i></title>
<author title="<i>Author</i>">
<mail link="<i>yourname@gentoo.org</i>"><i>Your Name</i></mail>
</author>
<abstract>
<i>This guide shows you how to compose web documentation using
our new lightweight Gentoo GuideXML syntax. This syntax is the official
format for Gentoo web documentation, and this document itself was created
using GuideXML.</i>
</abstract>
<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/3.0 -->
<license version="3.0"/>
<version><i>1</i></version>
<date><i>2011-11-29</i></date>
</codesample>
<p>
On the first lines, we see the requisite tag that identifies this as an XML
document and specifies its DTD. The <c><!-- $Header$ --></c> line
will be automatically modified by the CVS server and helps to track revisions.
Next, there's a <c><guide></c> tag -- the entire guide document is
enclosed within a <c><guide> </guide></c> pair.
<br/>
The <c>lang</c> attribute should be used to specify the language code of your
document. It is used to format the date and insert strings like "<e>Note</e>",
"<e>Content</e>", etc. in the specified language. The default is English.
</p>
<p>
Next, there's a <c><title></c> tag, used to set the title for the entire
guide document.
</p>
<p>
Then, we come to the <c><author></c> tags, which contain information
about the various authors of the document. Each <c><author></c> tag
allows for an optional <c>title</c> element, used to specify the author's
relationship to the document (author, co-author, editor, etc.). In this
particular example, the authors' names are enclosed in another tag -- a
<c><mail></c> tag, used to specify an email address for this particular
person. The <c><mail></c> tag is optional and can be omitted, and at
least one <c><author></c> element is required per guide document.
</p>
<p>
Next, we come to the <c><abstract></c>, <c><version></c> and
<c><date></c> tags, used to specify a summary of the document, the
current version number, and the current version date (in YYYY-MM-DD format)
respectively. Dates that are invalid or not in the YYYY-MM-DD format will
appear verbatim in the rendered document.
</p>
<p>
This sums up the tags that should appear at the beginning of a guide document.
Besides the <c><title></c> and <c><mail></c> tags, these tags
shouldn't appear anywhere else except immediately inside the
<c><guide></c> tag, and for consistency it's recommended (but not
required) that these tags appear before the content of the document.
</p>
<p>
Finally we have the <c><license version="3.0"/></c> tag, used to publish
the document under the <uri link="http://creativecommons.org/licenses/by-sa/3.0/">Creative
Commons - Attribution / Share Alike</uri> license as required by the <uri
link="/proj/en/gdp/doc/doc-policy.xml">Documentation Policy</uri>. Historically,
the tag <c><license /></c> was used, which denoted the 2.5 version of the
license. This is still accepted/allowed.
</p>
</body>
</subsection>
<subsection>
<title>Chapters and sections</title>
<body>
<p>
Once the initial tags have been specified, you're ready to start adding the
structural elements of the document. Guide documents are divided into
chapters, and each chapter can hold one or more sections. Every chapter and
section has a title. Here's an example chapter with a single section,
consisting of a paragraph. If you append this XML to the XML in the <uri
link="#doc_chap2_pre1">previous excerpt</uri> and append a
<c></guide></c> to the end of the file, you'll have a valid (if minimal)
guide document:
</p>
<codesample lang="sgml"><!-- Minimal guide example -->
<chapter>
<title><i>This is my chapter</i></title>
<section>
<title><i>This is section one of my chapter</i></title>
<body>
<p>
<i>This is the actual text content of my section.</i>
</p>
</body>
</section>
</chapter>
</codesample>
<p>
Above, I set the chapter title by adding a child <c><title></c>
element to the <c><chapter></c> element. Then, I created a section by
adding a <c><section></c> element. If you look inside the
<c><section></c> element, you'll see that it has two child elements -- a
<c><title></c> and a <c><body></c>. While the <c><title></c>
is nothing new, the <c><body></c> is -- it contains the actual text
content of this particular section. We'll look at the tags that are allowed
inside a <c><body></c> element in a bit.
</p>
<note>
A <c><guide></c> element must contain at least one <c><chapter></c>
elements, a <c><chapter></c> must contain at least one
<c><section></c> elements and a <c><section></c> element must
contain at least one <c><body></c> element.
</note>
</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"><!-- Example of a body element -->
<p>
This is a paragraph. <path>/etc/passwd</path> is a file.
<uri>http://forums.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 caption="Code Sample">
This is text output or code.
# <i>this is user input</i>
Make HTML/XML easier to read by using selective emphasis:
<foo><i>bar</i></foo>
</pre>
<note>
This is a note.
</note>
<warn>
This is a warning.
</warn>
<impo>
This is important.
</impo>
</codesample>
<p>
Now, here's how the <c><body></c> element above is rendered:
</p>
<p>
This is a paragraph. <path>/etc/passwd</path> is a file.
<uri>http://forums.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>
<codesample lang="sgml"><!-- Code Sample -->
This is text output or code.
# <i>this is user input</i>
Make HTML/XML easier to read by using selective emphasis:
<foo><i>bar</i></foo>
</codesample>
<note>
This is a note.
</note>
<warn>
This is a warning.
</warn>
<impo>
This is important.
</impo>
</body>
</subsection>
<subsection>
<title>The <body> tags</title>
<body>
<p>
We introduced a lot of new tags in the previous section -- here's what you need
to know. The <c><p></c> (paragraph), <c><pre></c> (code block),
<c><note></c>, <c><warn></c> (warning) and <c><impo></c>
(important) tags all can contain one or more lines of text. Besides the
<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 -- these tags <e>should not</e> be stacked -- 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> element preserves its whitespace
exactly, making it well-suited for code excerpts. You must name the
<c><pre></c> tag with a <c>caption</c> attribute:
</p>
<codesample lang="sgml"><!-- Named <pre> -->
<pre caption="Output of uptime">
# <i>uptime</i>
16:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25
</pre>
</codesample>
</body>
</subsection>
<subsection>
<title>
<c>, <b>, and <e>
</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 -- 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>
</body>
</subsection>
<subsection>
<title>Code samples and colour-coding</title>
<body>
<todo>
Fill this section with the information about the use of
<codesample/>.
</todo>
</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 -- the first can be used when you want to have the actual URI
displayed in the body text, such as this link to
<uri>http://forums.gentoo.org/</uri>. To create this link, I typed
<c><uri>http://forums.gentoo.org/</uri></c>. The alternate form is
when you want to associate a URI with some other text -- for example, <uri
link="http://forums.gentoo.org/">the Gentoo Forums</uri>. To create
<e>this</e> link, I typed <c><uri link="http://forums.gentoo.org/">the
Gentoo Forums</uri></c>. You don't need to write
<c>http://www.gentoo.org/</c> to link to other parts of the Gentoo web site.
For instance, a link to the <uri link="/doc/en/">documentation main index</uri>
should be simply <c><uri link="/doc/en/index.xml">documentation main
index</uri></c>. You can even omit <c>index.xml</c> when you link to a
directory index, e.g. <c><uri link="/doc/en/">documentation main
index</uri></c>. Leaving the trailing slash saves an extra HTTP request.
</p>
<p>
Please avoid the <uri link="http://en.wikipedia.org/wiki/Click_here">click here
syndrome</uri> as recommended by the <uri
link="http://www.w3.org/QA/Tips/noClickHere">W3C</uri>.
</p>
</body>
</subsection>
<subsection>
<title>Figures</title>
<body>
<p>
Here's how to insert a figure into a document -- <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>
GuideXML 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>
-- 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>
</body>
</subsection>
<subsection>
<title>Intra-document references</title>
<body>
<p>
GuideXML makes it really easy to reference other parts of the document using
hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter
One</uri> by typing <c><uri link="#doc_chap1">Chapter
One</uri></c>. To point to <uri link="#doc_chap1_sect2">section two of
Chapter One</uri>, type <c><uri link="#doc_chap1_sect2">section two of
Chapter One</uri></c>. To refer to figure 3 in chapter 1, type
<c><uri link="#doc_chap1_fig3">figure 1.3</uri></c>. Or, to refer
to <uri link="#doc_chap2_pre2">code listing 2 in chapter 2</uri>, type
<c><uri link="#doc_chap2_pre2">code listing 2.2</uri></c>.
</p>
</body>
</subsection>
</section>
<section>
<title>Coding Style</title>
<subsection>
<title>Introduction</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 - how the XML-tags are placed. The second one is
regarding the content - how not to confuse the reader.
</p>
<p>
Both sections are described next.
</p>
</body>
</subsection>
<subsection>
<title>Internal Coding Style</title>
<body>
<p>
<b>Newlines</b> must be placed immediately after <e>every</e>
GuideXML-tag (both opening as closing), except for:
<c><version></c>, <c><date></c>, <c><title></c>,
<c><th></c>, <c><ti></c>,
<c><li></c>, <c><i></c>, <c><e></c>,
<c><uri></c>, <c><path></c>, <c><b></c>, <c><c></c>,
<c><mail></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><chapter></c>, <c><p></c>, <c><table></c>,
<c><author></c> (set), <c><pre></c>, <c><ul></c>,
<c><ol></c>, <c><warn></c>, <c><note></c> and
<c><impo></c> (opening tags only).
</p>
<p>
<b>Word-wrapping</b> must be applied at 80 characters except inside
<c><pre></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> 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>, <c><dl></c>, and
<c><author></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 GuideXML documents.
</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"><!-- 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>Attributes</b> may not have spaces in between the attribute, the "=" mark,
and the attribute value. As an example:
</p>
<codesample lang="sgml"><!-- Attributes -->
Wrong : <pre caption = "Attributes">
Correct: <pre caption="Attributes">
</codesample>
</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"><!-- Periods and capital letters -->
<ul>
<li>No period</li>
<li>With period. Multiple sentences, remember?</li>
</ul>
</codesample>
<p>
Code Listings should <e>always</e> have a <c>caption</c>.
</p>
<p>
Try to use <c><uri></c> with the <c>link</c> attribute as much as
possible. In other words, the <uri link="http://forums.gentoo.org">Gentoo
Forums</uri> is preferred over <uri>http://forums.gentoo.org</uri>.
</p>
</body>
</subsection>
</section>
<section>
<title>Resources</title>
<subsection>
<title>Start writing</title>
<body>
<p>
GuideXML has been specially designed to be "lean and mean" so that developers
can spend more time writing documentation and less time learning the actual XML
syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy"
to start writing quality Gentoo documentation. You might be interested in our
<uri link="/proj/en/gdp/doc/doc-tipsntricks.xml">Documentation Development Tips
& Tricks</uri>. If you'd like to help (or have any questions about
GuideXML), please post a message to the <uri
link="/main/en/lists.xml">gentoo-doc mailing list</uri> stating what you'd like
to tackle. Have fun!
</p>
</body>
</subsection>
</section>
</chapter>
</guide>
|
GitWeb