| 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 | |
| 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 |
26 | Gentoo GuideXML syntax. This syntax is the official format for Gentoo |
| 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.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> |
| 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 | |
| … | |
… | |
| 301 | <title>The <body> tags</title> |
301 | <title>The <body> tags</title> |
| 302 | <body> |
302 | <body> |
| 303 | |
303 | |
| 304 | <p> |
304 | <p> |
| 305 | We introduced a lot of new tags in the previous section -- here's what you need |
305 | We introduced a lot of new tags in the previous section -- here's what you need |
| 306 | to know. The <c><p></c> (paragraph), <c><pre></c> (code block), |
306 | to know. The <c><p></c> (paragraph), <c><pre></c> (code block), |
| 307 | <c><note></c>, <c><warn></c> (warning) and <c><impo></c> |
307 | <c><note></c>, <c><warn></c> (warning) and <c><impo></c> |
| 308 | (important) tags all can contain one or more lines of text. Besides the |
308 | (important) tags all can contain one or more lines of text. Besides the |
| 309 | <c><table></c>, <c><ul></c>, <c><ol></c> and |
309 | <c><table></c>, <c><ul></c>, <c><ol></c> and |
| 310 | <c><dl></c> elements (which we'll cover in just a bit), these are the |
310 | <c><dl></c> elements (which we'll cover in just a bit), these are the |
| 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> |
| 322 | 16:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25 |
322 | 16:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25 |
| 323 | </pre> |
323 | </pre> |
| 324 | </pre> |
324 | </pre> |
| 325 | |
325 | |
| 326 | </body> |
326 | </body> |
| 327 | </section> |
327 | </section> |
| 328 | <section> |
328 | <section> |
| 329 | <title>Epigraphs</title> |
329 | <title>Epigraphs</title> |
| 330 | <body> |
330 | <body> |
| 331 | |
331 | |
| … | |
… | |
| 503 | <title>Lists</title> |
503 | <title>Lists</title> |
| 504 | <body> |
504 | <body> |
| 505 | |
505 | |
| 506 | <p> |
506 | <p> |
| 507 | To create ordered or unordered lists, simply use the XHTML-style |
507 | To create ordered or unordered lists, simply use the XHTML-style |
| 508 | <c><ol></c>, <c><ul></c> and <c><li></c> tags. Lists may only |
508 | <c><ol></c>, <c><ul></c> and <c><li></c> tags. Lists may only |
| 509 | appear inside the <c><body></c> and <c><li></c> tags which means |
509 | appear inside the <c><body></c> and <c><li></c> tags which means |
| 510 | that you can have lists inside lists. Don't forget that you are writing XML and |
510 | that you can have lists inside lists. Don't forget that you are writing XML and |
| 511 | that you must close all tags including list items unlike in HTML. |
511 | that you must close all tags including list items unlike in HTML. |
| 512 | </p> |
512 | </p> |
| 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> |
| 524 | <dt><c><dt></c></dt> |
524 | <dt><c><dt></c></dt> |
| 525 | <dd>Pairs of <b>D</b>efinition <b>T</b>erm Tags</dd> |
525 | <dd>Pairs of <b>D</b>efinition <b>T</b>erm Tags</dd> |
| 526 | <dt><c><dd></c></dt> |
526 | <dt><c><dd></c></dt> |
| 527 | <dd>and <b>D</b>efinition <b>D</b>ata Tags</dd> |
527 | <dd>and <b>D</b>efinition <b>D</b>ata Tags</dd> |
| 528 | </dl> |
528 | </dl> |
| 529 | |
529 | |
| 530 | <p> |
530 | <p> |
| 531 | The following list copied from <uri |
531 | The following list copied from <uri |
| 532 | link="http://www.w3.org/TR/REC-html40/struct/lists.html">w3.org</uri> shows |
532 | link="http://www.w3.org/TR/REC-html40/struct/lists.html">w3.org</uri> shows |
| 533 | that a definition list can contain ordered and unordered lists. It may not |
533 | that a definition list can contain ordered and unordered lists. It may not |
| … | |
… | |
| 536 | |
536 | |
| 537 | <dl> |
537 | <dl> |
| 538 | <dt><b>The ingredients:</b></dt> |
538 | <dt><b>The ingredients:</b></dt> |
| 539 | <dd> |
539 | <dd> |
| 540 | <ul> |
540 | <ul> |
| 541 | <li>100 g. flour</li> |
541 | <li>100 g. flour</li> |
| 542 | <li>10 g. sugar</li> |
542 | <li>10 g. sugar</li> |
| 543 | <li>1 cup water</li> |
543 | <li>1 cup water</li> |
| 544 | <li>2 eggs</li> |
544 | <li>2 eggs</li> |
| 545 | <li>salt, pepper</li> |
545 | <li>salt, pepper</li> |
| 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> |
| 564 | <title>Intra-document references</title> |
564 | <title>Intra-document references</title> |
| 565 | <body> |
565 | <body> |
| 566 | |
566 | |
| 567 | <p> |
567 | <p> |
| 568 | Guide makes it really easy to reference other parts of the document using |
568 | Guide makes it really easy to reference other parts of the document using |
| 569 | hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter |
569 | hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter |
| 570 | One</uri> by typing <c><uri link="#doc_chap1">Chapter |
570 | One</uri> by typing <c><uri link="#doc_chap1">Chapter |
| 571 | One</uri></c>. To point to <uri link="#doc_chap1_sect2">section two of |
571 | One</uri></c>. To point to <uri link="#doc_chap1_sect2">section two of |
| 572 | Chapter One</uri>, type <c><uri link="#doc_chap1_sect2">section two of |
572 | Chapter One</uri>, type <c><uri link="#doc_chap1_sect2">section two of |
| 573 | Chapter One</uri></c>. To refer to figure 3 in chapter 1, type <c><uri |
573 | Chapter One</uri></c>. To refer to figure 3 in chapter 1, type <c><uri |
| … | |
… | |
| 684 | <c><impo></c> (opening tags only). |
684 | <c><impo></c> (opening tags only). |
| 685 | </p> |
685 | </p> |
| 686 | |
686 | |
| 687 | <p> |
687 | <p> |
| 688 | <b>Word-wrapping</b> must be applied at 80 characters except inside |
688 | <b>Word-wrapping</b> must be applied at 80 characters except inside |
| 689 | <c><pre></c>. You may only deviate from this rule when there is no other |
689 | <c><pre></c>. You may only deviate from this rule when there is no other |
| 690 | choice (for instance when a URL exceeds the maximum amount of characters). The |
690 | choice (for instance when a URL exceeds the maximum amount of characters). The |
| 691 | editor must then wrap whenever the first whitespace occurs. You should try to |
691 | editor must then wrap whenever the first whitespace occurs. You should try to |
| 692 | keep the <e>rendered</e> content of <c><pre></c> elements within 80 |
692 | keep the <e>rendered</e> content of <c><pre></c> elements within 80 |
| 693 | columns to help console users. |
693 | columns to help console users. |
| 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> |
| 713 | |
714 | |
| 714 | <pre caption="Indentation Example"> |
715 | <pre caption="Indentation Example"> |
| 715 | <table> |
716 | <table> |
| 716 | <tr> |
717 | <tr> |
| 717 | <th>Foo</th> |
718 | <th>Foo</th> |
| 718 | <th>Bar</th> |
719 | <th>Bar</th> |
| 719 | </tr> |
720 | </tr> |
| 720 | <tr> |
721 | <tr> |
| 721 | <ti>This is an example for indentation</ti> |
722 | <ti>This is an example for indentation</ti> |
| 722 | <ti> |
723 | <ti> |
| 723 | In case text cannot be shown within an 80-character wide line, you |
724 | In case text cannot be shown within an 80-character wide line, you |
| 724 | must use indentation if the parent tag allows it |
725 | must use indentation if the parent tag allows it |
| 725 | </ti> |
726 | </ti> |
| 726 | </tr> |
727 | </tr> |
| 727 | </table> |
728 | </table> |
| 728 | |
729 | |
| 729 | <ul> |
730 | <ul> |
| 730 | <li>First option</li> |
731 | <li>First option</li> |
| 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"> |
| 743 | </pre> |
744 | </pre> |
| 744 | |
745 | |
| 745 | </body> |
746 | </body> |
| 746 | </section> |
747 | </section> |
| 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. |
| 761 | </p> |
762 | </p> |
| 762 | |
763 | |
| 763 | <pre caption="Periods and capital letters"> |
764 | <pre caption="Periods and capital letters"> |
| 764 | <ul> |
765 | <ul> |
| 765 | <li>No period</li> |
766 | <li>No period</li> |
| 766 | <li>With period. Multiple sentences, remember?</li> |
767 | <li>With period. Multiple sentences, remember?</li> |
| 767 | </ul> |
768 | </ul> |
| 768 | </pre> |
769 | </pre> |
| 769 | |
770 | |
| 770 | <p> |
771 | <p> |
Parent Directory
| 
Revision Log
| 
Patch