/[gentoo]/xml/htdocs/doc/en/xml-guide.xml
Gentoo

Diff of /xml/htdocs/doc/en/xml-guide.xml

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.34 Revision 1.35
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.34 2004/10/19 15:23:16 neysx Exp $ --> 2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.35 2004/12/24 11:52:37 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 Linux XML Guide</title> 6<title>Gentoo Linux XML Guide</title>
7 7
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">
18 <mail link="swift@gentoo.org">Sven Vermeulen</mail> 18 <mail link="swift@gentoo.org">Sven Vermeulen</mail>
19</author> 19</author>
20<author title="Editor">
21 <mail link="neysx@gentoo.org">Xavier Neys</mail>
22</author>
20 23
21<abstract> 24<abstract>
22This guide shows you how to compose web documentation using the new lightweight 25This guide shows you how to compose web documentation using the new lightweight
23Gentoo GuideXML syntax. This syntax is the official format for Gentoo Linux 26Gentoo GuideXML syntax. This syntax is the official format for Gentoo Linux
24documentation, and this document itself was created using GuideXML. This guide 27documentation, and this document itself was created using GuideXML. This guide
27 30
28<!-- 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 -->
29<!-- See http://creativecommons.org/licenses/by-sa/2.0 --> 32<!-- See http://creativecommons.org/licenses/by-sa/2.0 -->
30<license/> 33<license/>
31 34
32<version>2.11</version> 35<version>2.12</version>
33<date>August 12, 2004</date> 36<date>2004-12-24</date>
34 37
35<chapter> 38<chapter>
36<title>Guide basics</title> 39<title>Guide basics</title>
37<section> 40<section>
38<title>Guide XML design goals</title> 41<title>Guide XML design goals</title>
81</p> 84</p>
82 85
83<pre caption="The initial part of a guide XML document"> 86<pre caption="The initial part of a guide XML document">
84&lt;?xml version='1.0' encoding="UTF-8"?&gt; 87&lt;?xml version='1.0' encoding="UTF-8"?&gt;
85&lt;!DOCTYPE guide SYSTEM "/dtd/guide.dtd"&gt; 88&lt;!DOCTYPE guide SYSTEM "/dtd/guide.dtd"&gt;
86&lt;guide link="relative_link_to_your_guide"&gt; 89&lt;guide link="<i>relative/link/to/your/guide.xml</i>" lang="<i>en</i>"&gt;
87&lt;title&gt;<i>Gentoo Linux Documentation Guide</i>&lt;/title&gt; 90&lt;title&gt;<i>Gentoo Linux Documentation Guide</i>&lt;/title&gt;
88&lt;author title="<i>Author</i>"&gt; 91&lt;author title="<i>Author</i>"&gt;
89 &lt;mail link="<i>yourname@gentoo.org</i>"&gt;<i>Your Name</i>&lt;/mail&gt; 92 &lt;mail link="<i>yourname@gentoo.org</i>"&gt;<i>Your Name</i>&lt;/mail&gt;
90&lt;/author&gt; 93&lt;/author&gt;
91 94
99&lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt; 102&lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
100&lt;!-- See http://creativecommons.org/licenses/by-sa/2.0 --&gt; 103&lt;!-- See http://creativecommons.org/licenses/by-sa/2.0 --&gt;
101&lt;license/&gt; 104&lt;license/&gt;
102 105
103&lt;version&gt;<i>1.0</i>&lt;/version&gt; 106&lt;version&gt;<i>1.0</i>&lt;/version&gt;
104&lt;date&gt;<i>29 Mar 2001</i>&lt;/date&gt; 107&lt;date&gt;<i>2004-12-25</i>&lt;/date&gt;
105</pre> 108</pre>
106 109
107<p> 110<p>
108On the first, line, we see the requisite tag that identifies this as an XML 111On the first, line, we see the requisite tag that identifies this as an XML
109document. Following it, there's a <c>&lt;guide&gt;</c> tag -- the entire 112document. Following it, there's a <c>&lt;guide&gt;</c> tag -- the entire
110guide document is enclosed within a <c>&lt;guide&gt; &lt;/guide&gt;</c> pair. 113guide document is enclosed within a <c>&lt;guide&gt; &lt;/guide&gt;</c> pair.
114The <c>link</c> attribute is compulsory and should preferably contain the
115relative path to the document even though the file name alone will work. It is
116mainly used to generate a link to a printer-friendly version of your document.
117If you use a wrong value, the link to the printable version will either not
118work or point to a wrong document. The <c>lang</c> attribute can be used to
119specify the language code of your document. It is used to format the date and
120insert strings like "<e>Note</e>", "<e>Content</e>", etc. in the specified
121language. The default is English.
122</p>
123
124<p>
111Next, there's a <c>&lt;title&gt;</c> tag, used to set the title for the entire 125Next, there's a <c>&lt;title&gt;</c> tag, used to set the title for the entire
112guide document. 126guide document.
113</p> 127</p>
114 128
115<p> 129<p>
124</p> 138</p>
125 139
126<p> 140<p>
127Next, we come to the <c>&lt;abstract&gt;</c>, <c>&lt;version&gt;</c> and 141Next, we come to the <c>&lt;abstract&gt;</c>, <c>&lt;version&gt;</c> and
128<c>&lt;date&gt;</c> tags, used to specify a summary of the document, the 142<c>&lt;date&gt;</c> tags, used to specify a summary of the document, the
129current version number, and the current version date (in DD MMM YYYY format) 143current version number, and the current version date (in YYYY-MM-DD format)
144respectively. Dates that are invalid or not in the YYYY-MM-DD format will
145appear verbatim in the rendered document.
146</p>
147
148<p>
130respectively. This rounds out the tags that should appear at the beginning of 149This rounds out the tags that should appear at the beginning of a guide
131a guide document. Besides the <c>&lt;title&gt;</c> and <c>&lt;mail&gt;</c> 150document. Besides the <c>&lt;title&gt;</c> and <c>&lt;mail&gt;</c> tags, these
132tags, these tags shouldn't appear anywhere else except immediately inside the 151tags shouldn't appear anywhere else except immediately inside the
133<c>&lt;guide&gt;</c> tag, and for consistency it's recommended (but not 152<c>&lt;guide&gt;</c> tag, and for consistency it's recommended (but not
134required) that these tags appear before the content of the document. 153required) that these tags appear before the content of the document.
135</p> 154</p>
136 155
137<p> 156<p>
202</p> 221</p>
203 222
204<pre> 223<pre>
205&lt;p&gt; 224&lt;p&gt;
206This is a paragraph. &lt;path&gt;/etc/passwd&lt;/path&gt; is a file. 225This is a paragraph. &lt;path&gt;/etc/passwd&lt;/path&gt; is a file.
207&lt;uri&gt;http://www.gentoo.org&lt;/uri&gt; is my favorite website. 226&lt;uri&gt;http://forums.gentoo.org&lt;/uri&gt; is my favorite website.
208Type &lt;c&gt;ls&lt;/c&gt; if you feel like it. I &lt;e&gt;really&lt;/e&gt; want to go to sleep now. 227Type &lt;c&gt;ls&lt;/c&gt; if you feel like it. I &lt;e&gt;really&lt;/e&gt; want to go to sleep now.
209&lt;/p&gt; 228&lt;/p&gt;
210 229
211&lt;pre&gt; 230&lt;pre&gt;
212This is text output or code. 231This is text output or code.
235Now, here's how this <c>&lt;body&gt;</c> element is rendered: 254Now, here's how this <c>&lt;body&gt;</c> element is rendered:
236</p> 255</p>
237 256
238<p> 257<p>
239This is a paragraph. <path>/etc/passwd</path> is a file. 258This is a paragraph. <path>/etc/passwd</path> is a file.
240<uri>http://www.gentoo.org</uri> is my favorite website. 259<uri>http://forums.gentoo.org</uri> is my favorite website.
241Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now. 260Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now.
242</p> 261</p>
243 262
244<pre> 263<pre>
245This is text output or code. 264This is text output or code.
342some text with a particular email address, and takes the form <c>&lt;mail 361some text with a particular email address, and takes the form <c>&lt;mail
343link="foo@bar.com"&gt;Mr. Foo Bar&lt;/mail&gt;</c>. 362link="foo@bar.com"&gt;Mr. Foo Bar&lt;/mail&gt;</c>.
344</p> 363</p>
345 364
346<p> 365<p>
347The <c>&lt;uri&gt;</c> tag is used to point to files/locations on the 366The <c>&lt;uri&gt;</c> tag is used to point to files/locations on the Internet.
348Internet. It has two forms -- the first can be used when you want to have the 367It has two forms -- the first can be used when you want to have the actual URI
349actual URI displayed in the body text, such as this link to 368displayed in the body text, such as this link to
350<uri>http://www.gentoo.org</uri>. To create this link, I typed 369<uri>http://forums.gentoo.org</uri>. To create this link, I typed
351<c>&lt;uri&gt;http://www.gentoo.org&lt;/uri&gt;</c>. The alternate form is 370<c>&lt;uri&gt;http://forums.gentoo.org&lt;/uri&gt;</c>. The alternate form is
352when you want to associate a URI with some other text -- for example, <uri 371when you want to associate a URI with some other text -- for example, <uri
353link="http://www.gentoo.org">the Gentoo Linux website</uri>. To create 372link="http://forums.gentoo.org">the Gentoo Forums</uri>. To create <e>this</e>
354<e>this</e> link, I typed <c>&lt;uri link="http://www.gentoo.org"&gt;the 373link, I typed <c>&lt;uri link="http://forums.gentoo.org"&gt;the Gentoo
355Gentoo Linux website&lt;/uri&gt;</c>. 374Forums&lt;/uri&gt;</c>. You don't need to write <c>http://www.gentoo.org/</c>
375to link to other parts of the Gentoo website. For instance, a link to the <uri
376link="/doc/en/">documentation main index</uri> should be simply <c>&lt;uri
377link="/doc/en/index.xml"&gt;documentation main index&lt;/uri&gt;</c>. You can
378even omit <c>index.xml</c> when you link to a directory index, e.g. <c>&lt;uri
379link="/doc/en/"&gt;documentation main index&lt;/uri&gt;</c>.
356</p> 380</p>
357 381
358</body> 382</body>
359</section> 383</section>
360<section> 384<section>
563Code Listings should <e>always</e> have a <c>caption</c>. 587Code Listings should <e>always</e> have a <c>caption</c>.
564</p> 588</p>
565 589
566<p> 590<p>
567Try to use <c>&lt;uri&gt;</c> with the <c>link</c> attribute as much as 591Try to use <c>&lt;uri&gt;</c> with the <c>link</c> attribute as much as
568possible. In other words, the <uri link="http://www.gentoo.org">Gentoo 592possible. In other words, the <uri link="http://forums.gentoo.org">Gentoo
569Website</uri> is preferred over <uri>http://www.gentoo.org</uri>. 593Forums</uri> is preferred over <uri>http://forums.gentoo.org</uri>.
570</p> 594</p>
571 595
572<p> 596<p>
573When you comment something inside a <c>&lt;pre&gt;</c> construct, only use 597When you comment something inside a <c>&lt;pre&gt;</c> construct, only use
574<c>&lt;codenote&gt;</c> if the content is a C or C++ code snippet. Otherwise, 598<c>&lt;codenote&gt;</c> if the content is a C or C++ code snippet. Otherwise,
575use <c>&lt;comment&gt;</c> and parantheses. Also place the comment <e>before</e> 599use <c>&lt;comment&gt;</c> and parentheses. Also place the comment <e>before</e>
576the subject of the comment. 600the subject of the comment.
577</p> 601</p>
578 602
579<pre caption="Comment example"> 603<pre caption="Comment example">
580<comment>(Substitute "john" with your user name)</comment> 604<comment>(Substitute "john" with your user name)</comment>
692&lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt; 716&lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
693&lt;!-- See http://creativecommons.org/licenses/by-sa/2.0 --&gt; 717&lt;!-- See http://creativecommons.org/licenses/by-sa/2.0 --&gt;
694 718
695&lt;sections&gt; 719&lt;sections&gt;
696 720
721&lt;version&gt;...&lt;/version&gt;
722&lt;date&gt;...&lt;/date&gt;
723
697<comment>(Define the several &lt;section&gt; and &lt;subsection&gt;)</comment> 724<comment>(Define the several &lt;section&gt; and &lt;subsection&gt;)</comment>
698 725
699&lt;/sections&gt; 726&lt;/sections&gt;
700</pre> 727</pre>
701 728
703Inside each chapter you can define <c>&lt;section&gt;</c>'s (equivalent of 730Inside each chapter you can define <c>&lt;section&gt;</c>'s (equivalent of
704<c>&lt;chapter&gt;</c> in a Guide) and <c>&lt;subsection&gt;</c>'s (equivalent 731<c>&lt;chapter&gt;</c> in a Guide) and <c>&lt;subsection&gt;</c>'s (equivalent
705of <c>&lt;section&gt;</c> in a Guide). 732of <c>&lt;section&gt;</c> in a Guide).
706</p> 733</p>
707 734
735<p>
736Each individual chapter should have its own date and version elements. The
737latest date of all chapters and master document will be displayed when a user
738browses through all parts of the book.
739</p>
740
708</body> 741</body>
709</section> 742</section>
710</chapter> 743</chapter>
711 744
712<chapter> 745<chapter>
714<section> 747<section>
715<title>Start writing</title> 748<title>Start writing</title>
716<body> 749<body>
717 750
718<p> 751<p>
719Guide has been specially designed to be "lean and mean" so that developers 752Guide has been specially designed to be "lean and mean" so that developers can
720can spend more time writing documentation and less time learning the actual XML 753spend more time writing documentation and less time learning the actual XML
721syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy" 754syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy"
722to start writing quality Gentoo Linux documentation. If you'd like to help (or 755to start writing quality Gentoo Linux documentation. You might be interested
756in our <uri link="/proj/en/gdp/doc/doc-tipsntricks.xml">Documentation
757Development Tips &amp; Tricks</uri>. If you'd like to help (or have any
723have any questions about guide), please post a message to the <mail 758questions about guide), please post a message to the <mail
724link="gentoo-doc@gentoo.org">gentoo-doc mailing list</mail> stating what you'd 759link="gentoo-doc@gentoo.org">gentoo-doc mailing list</mail> stating what you'd
725like to tackle. Have fun! 760like to tackle. Have fun!
726</p> 761</p>
727 762
728</body> 763</body>
729</section> 764</section>
730</chapter> 765</chapter>
731</guide> 766</guide>
732

Legend:
Removed from v.1.34  
changed lines
  Added in v.1.35

  ViewVC Help
Powered by ViewVC 1.1.20