| 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.52 2005/10/13 15:57:42 neysx Exp $ --> |
2 | <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.53 2005/10/13 20:33:40 neysx 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 XML Guide</title> |
6 | <title>Gentoo XML Guide</title> |
| 7 | |
7 | |
| … | |
… | |
| 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.5 --> |
32 | <!-- See http://creativecommons.org/licenses/by-sa/2.5 --> |
| 33 | <license/> |
33 | <license/> |
| 34 | |
34 | |
| 35 | <version>2.27</version> |
35 | <version>2.28</version> |
| 36 | <date>2005-10-11</date> |
36 | <date>2005-10-13</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> |
| … | |
… | |
| 311 | only tags that should appear immediately inside a <c><body></c> element. |
311 | only tags that should appear immediately inside a <c><body></c> element. |
| 312 | Another thing -- these tags <e>should not</e> be stacked -- in other words, |
312 | Another thing -- these tags <e>should not</e> be stacked -- in other words, |
| 313 | don't put a <c><note></c> element inside a <c><p></c> element. As |
313 | don't put a <c><note></c> element inside a <c><p></c> element. As |
| 314 | you might guess, the <c><pre></c> element preserves its whitespace |
314 | you might guess, the <c><pre></c> element preserves its whitespace |
| 315 | exactly, making it well-suited for code excerpts. You must name the |
315 | exactly, making it well-suited for code excerpts. You must name the |
| 316 | <c><pre></c> tag with a caption attribute: |
316 | <c><pre></c> tag with a <c>caption</c> attribute: |
| 317 | </p> |
317 | </p> |
| 318 | |
318 | |
| 319 | <pre caption="Named <pre>"> |
319 | <pre caption="Named <pre>"> |
| 320 | <pre caption="Output of uptime"> |
320 | <pre caption="Output of uptime"> |
| 321 | # <i>uptime</i> |
321 | # <i>uptime</i> |
| … | |
… | |
| 513 | |
513 | |
| 514 | <p> |
514 | <p> |
| 515 | Definition lists (<c><dl></c>) are also supported. Please note that |
515 | Definition lists (<c><dl></c>) are also supported. Please note that |
| 516 | neither the definition term tag (<c><dt></c>) nor the definition data tag |
516 | neither the definition term tag (<c><dt></c>) nor the definition data tag |
| 517 | (<c><dd></c>) accept any other block level tag such as paragraphs or |
517 | (<c><dd></c>) accept any other block level tag such as paragraphs or |
| 518 | admonitions. A definition list comprises |
518 | admonitions. A definition list comprises: |
| 519 | </p> |
519 | </p> |
| 520 | |
520 | |
| 521 | <dl> |
521 | <dl> |
| 522 | <dt><c><dl></c></dt> |
522 | <dt><c><dl></c></dt> |
| 523 | <dd>A <b>D</b>efinition <b>L</b>ist Tag containing</dd> |
523 | <dd>A <b>D</b>efinition <b>L</b>ist Tag containing</dd> |
| … | |
… | |
| 546 | </ul> |
546 | </ul> |
| 547 | </dd> |
547 | </dd> |
| 548 | <dt><b>The procedure:</b></dt> |
548 | <dt><b>The procedure:</b></dt> |
| 549 | <dd> |
549 | <dd> |
| 550 | <ol> |
550 | <ol> |
| 551 | <li>Mix dry ingredients thoroughly.</li> |
551 | <li>Mix dry ingredients thoroughly</li> |
| 552 | <li>Pour in wet ingredients.</li> |
552 | <li>Pour in wet ingredients</li> |
| 553 | <li>Mix for 10 minutes.</li> |
553 | <li>Mix for 10 minutes</li> |
| 554 | <li>Bake for one hour at 300 degrees.</li> |
554 | <li>Bake for one hour at 300 degrees</li> |
| 555 | </ol> |
555 | </ol> |
| 556 | </dd> |
556 | </dd> |
| 557 | <dt><b>Notes:</b></dt> |
557 | <dt><b>Notes:</b></dt> |
| 558 | <dd>The recipe may be improved by adding raisins.</dd> |
558 | <dd>The recipe may be improved by adding raisins</dd> |
| 559 | </dl> |
559 | </dl> |
| 560 | |
560 | |
| 561 | </body> |
561 | </body> |
| 562 | </section> |
562 | </section> |
| 563 | <section> |
563 | <section> |
| … | |
… | |
| 694 | </p> |
694 | </p> |
| 695 | |
695 | |
| 696 | <p> |
696 | <p> |
| 697 | <b>Indentation</b> may not be used, except with the XML-constructs of which the |
697 | <b>Indentation</b> may not be used, except with the XML-constructs of which the |
| 698 | parent XML-tags are <c><tr></c> (from <c><table></c>), |
698 | parent XML-tags are <c><tr></c> (from <c><table></c>), |
| 699 | <c><ul></c>, <c><ol></c> and <c><author></c>. If indentation |
699 | <c><ul></c>, <c><ol></c>, <c><dl></c>, and |
| 700 | is used, it <e>must</e> be two spaces for each indentation. That means <e>no |
700 | <c><author></c>. If indentation is used, it <e>must</e> be two spaces for |
| 701 | tabs</e> and <e>not</e> more spaces. Besides, tabs are not allowed in GuideXML |
701 | each indentation. That means <e>no tabs</e> and <e>not</e> more spaces. |
| 702 | documents. |
702 | Besides, tabs are not allowed in GuideXML documents. |
| 703 | </p> |
|
|
| 704 | |
|
|
| 705 | <p> |
703 | </p> |
|
|
704 | |
|
|
705 | <p> |
| 706 | In case word-wrapping happens in <c><ti></c>, <c><th></c> or |
706 | In case word-wrapping happens in <c><ti></c>, <c><th></c>, |
| 707 | <c><li></c> constructs, indentation must be used for the content. |
707 | <c><li></c> or <c><dd></c>constructs, indentation must be used for |
|
|
708 | the content. |
| 708 | </p> |
709 | </p> |
| 709 | |
710 | |
| 710 | <p> |
711 | <p> |
| 711 | An example for indentation is: |
712 | An example for indentation is: |
| 712 | </p> |
713 | </p> |
| … | |
… | |
| 731 | <li>Second option</li> |
732 | <li>Second option</li> |
| 732 | </ul> |
733 | </ul> |
| 733 | </pre> |
734 | </pre> |
| 734 | |
735 | |
| 735 | <p> |
736 | <p> |
| 736 | <b>Attributes</b> may not have spaces in between the attribute, the |
737 | <b>Attributes</b> may not have spaces in between the attribute, the "=" mark, |
| 737 | "=" mark, and the attribute value. As an example: |
738 | and the attribute value. As an example: |
| 738 | </p> |
739 | </p> |
| 739 | |
740 | |
| 740 | <pre caption="Attributes"> |
741 | <pre caption="Attributes"> |
| 741 | <comment>Wrong :</comment> <pre caption = "Attributes"> |
742 | <comment>Wrong :</comment> <pre caption = "Attributes"> |
| 742 | <comment>Correct:</comment> <pre caption="Attributes"> |
743 | <comment>Correct:</comment> <pre caption="Attributes"> |
| … | |
… | |
| 747 | <section> |
748 | <section> |
| 748 | <title>External Coding Style</title> |
749 | <title>External Coding Style</title> |
| 749 | <body> |
750 | <body> |
| 750 | |
751 | |
| 751 | <p> |
752 | <p> |
| 752 | Inside tables (<c><table></c>) and listings (<c><ul></c> and |
753 | Inside tables (<c><table></c>) and listings (<c><ul></c>, |
| 753 | <c><ol></c>), periods (".") should not be used unless multiple |
754 | <c><ol></c>) and <c><dl></c>, periods (".") should not be used |
| 754 | sentences are used. In that case, every sentence should end with a period (or |
755 | unless multiple sentences are used. In that case, every sentence should end |
| 755 | other reading marks). |
756 | with a period (or other reading marks). |
| 756 | </p> |
757 | </p> |
| 757 | |
758 | |
| 758 | <p> |
759 | <p> |
| 759 | Every sentence, including those inside tables and listings, should start |
760 | Every sentence, including those inside tables and listings, should start |
| 760 | with a capital letter. |
761 | with a capital letter. |
Parent Directory
| 
Revision Log
| 
Patch