| 1 | <?xml version="1.0" encoding="UTF-8"?> |
1 | <?xml version="1.0" encoding="UTF-8"?> |
| 2 | <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.43 2005/05/12 16:57:02 neysx Exp $ --> |
2 | <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.44 2005/05/23 19:05:33 swift Exp $ --> |
| 3 | <!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> |
3 | <!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> |
| 4 | |
4 | |
| 5 | <guide link="/doc/en/xml-guide.xml"> |
5 | <guide link="/doc/en/xml-guide.xml"> |
| 6 | <title>Gentoo Linux XML Guide</title> |
6 | <title>Gentoo Linux XML Guide</title> |
| 7 | |
7 | |
| 8 | <author title="Author"> |
8 | <author title="Author"> |
| 9 | <mail link="drobbins@gentoo.org">Daniel Robbins</mail> |
9 | <mail link="drobbins@gentoo.org">Daniel Robbins</mail> |
| 10 | </author> |
10 | </author> |
| 11 | <author title="Author"><!-- zhen@gentoo.org --> |
11 | <author title="Author"><!-- zhen@gentoo.org --> |
| 12 | John P. Davis |
12 | John P. Davis |
| 13 | </author> |
13 | </author> |
| 14 | <author title="Editor"> |
14 | <author title="Editor"> |
| 15 | <mail link="peesh@gentoo.org">Jorge Paulo</mail> |
15 | <mail link="peesh@gentoo.org">Jorge Paulo</mail> |
| 16 | </author> |
16 | </author> |
| 17 | <author title="Editor"> |
17 | <author title="Editor"> |
| … | |
… | |
| 20 | <author title="Editor"> |
20 | <author title="Editor"> |
| 21 | <mail link="neysx@gentoo.org">Xavier Neys</mail> |
21 | <mail link="neysx@gentoo.org">Xavier Neys</mail> |
| 22 | </author> |
22 | </author> |
| 23 | |
23 | |
| 24 | <abstract> |
24 | <abstract> |
| 25 | This guide shows you how to compose web documentation using the new lightweight |
25 | This guide shows you how to compose web documentation using the new lightweight |
| 26 | Gentoo GuideXML syntax. This syntax is the official format for Gentoo Linux |
26 | Gentoo GuideXML syntax. This syntax is the official format for Gentoo Linux |
| 27 | documentation, and this document itself was created using GuideXML. This guide |
27 | documentation, and this document itself was created using GuideXML. This guide |
| 28 | assumes a basic working knowledge of XML and HTML. |
28 | assumes a basic working knowledge of XML and HTML. |
| 29 | </abstract> |
29 | </abstract> |
| 30 | |
30 | |
| 31 | <!-- The content of this document is licensed under the CC-BY-SA license --> |
31 | <!-- The content of this document is licensed under the CC-BY-SA license --> |
| 32 | <!-- See http://creativecommons.org/licenses/by-sa/2.0 --> |
32 | <!-- See http://creativecommons.org/licenses/by-sa/2.0 --> |
| 33 | <license/> |
33 | <license/> |
| 34 | |
34 | |
| 35 | <version>2.20</version> |
35 | <version>2.21</version> |
| 36 | <date>2005-05-12</date> |
36 | <date>2005-05-23</date> |
| 37 | |
37 | |
| 38 | <chapter> |
38 | <chapter> |
| 39 | <title>Guide basics</title> |
39 | <title>Guide basics</title> |
| 40 | <section> |
40 | <section> |
| 41 | <title>Guide XML design goals</title> |
41 | <title>Guide XML design goals</title> |
| 42 | <body> |
42 | <body> |
| 43 | |
43 | |
| 44 | <p> |
44 | <p> |
| 45 | The guide XML syntax is lightweight yet expressive, so that it is easy to |
45 | The guide XML syntax is lightweight yet expressive, so that it is easy to |
| 46 | learn yet also provides all the features we need for the creation of web |
46 | learn yet also provides all the features we need for the creation of web |
| 47 | documentation. The number of tags is kept to a minimum -- just those we need. |
47 | documentation. The number of tags is kept to a minimum -- just those we need. |
| 48 | This makes it easy to transform guide into other formats, such as DocBook |
48 | This makes it easy to transform guide into other formats, such as DocBook |
| 49 | XML/SGML or web-ready HTML. |
49 | XML/SGML or web-ready HTML. |
| 50 | </p> |
50 | </p> |
| 51 | |
51 | |
| … | |
… | |
| 305 | <c><p></c> element. As you might guess, the <c><pre></c> element |
305 | <c><p></c> element. As you might guess, the <c><pre></c> element |
| 306 | preserves its whitespace exactly, making it well-suited for code excerpts. |
306 | preserves its whitespace exactly, making it well-suited for code excerpts. |
| 307 | You can also name the <c><pre></c> tag: |
307 | You can also name the <c><pre></c> tag: |
| 308 | </p> |
308 | </p> |
| 309 | |
309 | |
| 310 | <pre caption="Named <pre>"> |
310 | <pre caption="Named <pre>"> |
| 311 | <pre caption = "Output of uptime"> |
311 | <pre caption = "Output of uptime"> |
| 312 | # <i>uptime</i> |
312 | # <i>uptime</i> |
| 313 | 16:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25 |
313 | 16:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25 |
| 314 | </pre> |
314 | </pre> |
| 315 | </pre> |
315 | </pre> |
| 316 | |
316 | |
| 317 | </body> |
317 | </body> |
| 318 | </section> |
318 | </section> |
| 319 | <section> |
319 | <section> |
| 320 | <title><path>, <c> and <e></title> |
320 | <title><path>, <c>, <i> and <e></title> |
| 321 | <body> |
321 | <body> |
| 322 | |
322 | |
| 323 | <p> |
323 | <p> |
| 324 | The <c><path></c>, <c><c></c> and <c><e></c> elements can |
324 | The <c><path></c>, <c><c></c> and <c><e></c> elements can |
| 325 | be used inside any child <c><body></c> tag, except for |
325 | be used inside any child <c><body></c> tag, except for |
|
|
326 | <c><pre></c>. The <c><i></c> element can only be used inside |
| 326 | <c><pre></c>. |
327 | <c><pre></c>. |
| 327 | </p> |
328 | </p> |
| 328 | |
329 | |
| 329 | <p> |
330 | <p> |
| 330 | The <c><path></c> element is used to mark text that refers to an |
331 | The <c><path></c> element is used to mark text that refers to an |
| 331 | <e>on-disk file</e> -- either an <e>absolute or relative path</e>, or a |
332 | <e>on-disk file</e> -- either an <e>absolute or relative path</e>, or a |
| 332 | <e>simple filename</e>. This element is generally rendered with a monospaced |
333 | <e>simple filename</e>. This element is generally rendered with a monospaced |
| 333 | font to offset it from the standard paragraph type. |
334 | font to offset it from the standard paragraph type. |
| 334 | </p> |
335 | </p> |
| 335 | |
336 | |
| 336 | <p> |
337 | <p> |
| 337 | The <c><c></c> element is used to mark up a <e>command</e> or <e>user |
338 | The <c><c></c> element is used to mark up a <e>command</e> or <e>user |
| 338 | input</e>. Think of <c><c></c> as a way to alert the reader to something |
339 | input</e>. Think of <c><c></c> as a way to alert the reader to something |
| 339 | that they can type in that will perform some kind of action. For example, all |
340 | that they can type in that will perform some kind of action. For example, all |
| 340 | the XML tags displayed in this document are enclosed in a <c><c></c> |
341 | the XML tags displayed in this document are enclosed in a <c><c></c> |
| 341 | element because they represent something that the user could type in that is |
342 | element because they represent something that the user could type in that is |
| 342 | not a path. By using <c><c></c> elements, you'll help your readers |
343 | not a path. By using <c><c></c> elements, you'll help your readers |
| 343 | quickly identify commands that they need to type in. Also, because |
344 | quickly identify commands that they need to type in. Also, because |
| 344 | <c><c></c> elements are already offset from regular text, <e>it is rarely |
345 | <c><c></c> elements are already offset from regular text, <e>it is rarely |
| 345 | necessary to surround user input with double-quotes</e>. For example, don't |
346 | necessary to surround user input with double-quotes</e>. For example, don't |
| 346 | refer to a "<c><c></c>" element like I did in this sentence. Avoiding |
347 | refer to a "<c><c></c>" element like I did in this sentence. Avoiding |
| 347 | the use of unnecessary double-quotes makes a document more readable -- and |
348 | the use of unnecessary double-quotes makes a document more readable -- and |
| 348 | adorable! |
349 | adorable! |
|
|
350 | </p> |
|
|
351 | |
|
|
352 | <p> |
|
|
353 | When you want to highlight some text as user input inside a <c><pre></c>, |
|
|
354 | use <c><i></c> instead. |
| 349 | </p> |
355 | </p> |
| 350 | |
356 | |
| 351 | <p> |
357 | <p> |
| 352 | <c><e></c> is used to apply emphasis to a word or phrase; for example: |
358 | <c><e></c> is used to apply emphasis to a word or phrase; for example: |
| 353 | I <e>really</e> should use semicolons more often. As you can see, this text is |
359 | I <e>really</e> should use semicolons more often. As you can see, this text is |
| 354 | offset from the regular paragraph type for emphasis. This helps to give your |
360 | offset from the regular paragraph type for emphasis. This helps to give your |
| 355 | prose more <e>punch</e>! |
361 | prose more <e>punch</e>! |
| 356 | </p> |
362 | </p> |
| 357 | |
363 | |
| 358 | </body> |
364 | </body> |
| 359 | </section> |
365 | </section> |
| 360 | <section> |
366 | <section> |
| 361 | <title><mail> and <uri></title> |
367 | <title><mail> and <uri></title> |
| 362 | <body> |
368 | <body> |
| 363 | |
369 | |
| … | |
… | |
| 483 | Both sections are described next. |
489 | Both sections are described next. |
| 484 | </p> |
490 | </p> |
| 485 | |
491 | |
| 486 | </body> |
492 | </body> |
| 487 | </section> |
493 | </section> |
| 488 | <section> |
494 | <section> |
| 489 | <title>Internal Coding Style</title> |
495 | <title>Internal Coding Style</title> |
| 490 | <body> |
496 | <body> |
| 491 | |
497 | |
| 492 | <p> |
498 | <p> |
| 493 | <b>Newlines</b> must be placed immediately after <e>every</e> |
499 | <b>Newlines</b> must be placed immediately after <e>every</e> |
| 494 | GuideXML-tag (both opening as closing), except for: |
500 | GuideXML-tag (both opening as closing), except for: |
| 495 | <c><version></c>, <c><date></c>, <c><title></c>, |
501 | <c><version></c>, <c><date></c>, <c><title></c>, |
| 496 | <c><th></c>, <c><ti></c>, |
502 | <c><th></c>, <c><ti></c>, |
| 497 | <c><li></c>, <c><i></c>, <c><e></c>, |
503 | <c><li></c>, <c><i></c>, <c><e></c>, |
| 498 | <c><uri></c>, <c><path></c>, <c><b></c>, |
504 | <c><uri></c>, <c><path></c>, <c><b></c>, <c><c></c>, |
| 499 | <c><comment></c>, <c><mail></c>. |
505 | <c><comment></c>, <c><mail></c>. |
| 500 | </p> |
506 | </p> |
| 501 | |
507 | |
| 502 | <p> |
508 | <p> |
| 503 | <b>Blank lines</b> must be placed immediately after <e>every</e> |
509 | <b>Blank lines</b> must be placed immediately after <e>every</e> |
| 504 | <c><body></c> (opening tag only) and before <e>every</e> |
510 | <c><body></c> (opening tag only) and before <e>every</e> |
| 505 | <c><chapter></c>, <c><p></c>, <c><table></c>, |
511 | <c><chapter></c>, <c><p></c>, <c><table></c>, |
| 506 | <c><author></c> (set), <c><pre></c>, <c><ul></c>, |
512 | <c><author></c> (set), <c><pre></c>, <c><ul></c>, |
| 507 | <c><ol></c>, <c><warn></c>, <c><note></c> and |
513 | <c><ol></c>, <c><warn></c>, <c><note></c> and |
| 508 | <c><impo></c> (opening tags only). |
514 | <c><impo></c> (opening tags only). |
| 509 | </p> |
515 | </p> |
| 510 | |
516 | |
| 511 | <p> |
517 | <p> |
| 512 | <b>Word-wrapping</b> must be applied at 80 characters except inside |
518 | <b>Word-wrapping</b> must be applied at 80 characters except inside |
| 513 | <c><pre></c>. Only when there is no other choice can be deviated from |
519 | <c><pre></c>. Only when there is no other choice can be deviated from |
Parent Directory
| 
Revision Log
| 
Patch