/[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.41 Revision 1.42
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.41 2005/05/12 08:52:42 cam Exp $ --> 2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.42 2005/05/12 16:48:46 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
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>
25This 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
26Gentoo GuideXML syntax. This syntax is the official format for Gentoo Linux 26Gentoo GuideXML syntax. This syntax is the official format for Gentoo Linux
27documentation, and this document itself was created using GuideXML. This guide 27documentation, and this document itself was created using GuideXML. This guide
28assumes a basic working knowledge of XML and HTML. 28assumes 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.18</version> 35<version>2.19</version>
36<date>2005-05-12</date> 36<date>2005-05-12</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>
45The guide XML syntax is lightweight yet expressive, so that it is easy to 45The guide XML syntax is lightweight yet expressive, so that it is easy to
46learn yet also provides all the features we need for the creation of web 46learn yet also provides all the features we need for the creation of web
47documentation. The number of tags is kept to a minimum -- just those we need. 47documentation. The number of tags is kept to a minimum -- just those we need.
48This makes it easy to transform guide into other formats, such as DocBook 48This makes it easy to transform guide into other formats, such as DocBook
49XML/SGML or web-ready HTML. 49XML/SGML or web-ready HTML.
50</p> 50</p>
73 73
74<chapter> 74<chapter>
75<title>Guide XML</title> 75<title>Guide XML</title>
76<section> 76<section>
77<title>Basic structure</title> 77<title>Basic structure</title>
78<body> 78<body>
79 79
80<p> 80<p>
81Let's start learning the GuideXML syntax. We'll start with the the initial 81Let's start learning the GuideXML syntax. We'll start with the the initial
82tags used in a GuideXML document: 82tags used in a GuideXML document:
83</p> 83</p>
84 84
85<pre caption="The initial part of a guide XML document"> 85<pre caption="The initial part of a guide XML document">
86&lt;?xml version="1.0" encoding="UTF-8"?&gt; 86&lt;?xml version="1.0" encoding="UTF-8"?&gt;
87&lt;!DOCTYPE guide SYSTEM "/dtd/guide.dtd"&gt; 87&lt;!DOCTYPE guide SYSTEM "/dtd/guide.dtd"&gt;
88&lt;!-- &#36;Header&#36; --&gt;
89
88&lt;guide link="<i>relative/link/to/your/guide.xml</i>" lang="<i>en</i>"&gt; 90&lt;guide link="<i>relative/link/to/your/guide.xml</i>" lang="<i>en</i>"&gt;
89&lt;title&gt;<i>Gentoo Linux Documentation Guide</i>&lt;/title&gt; 91&lt;title&gt;<i>Gentoo Linux Documentation Guide</i>&lt;/title&gt;
90&lt;author title="<i>Author</i>"&gt; 92&lt;author title="<i>Author</i>"&gt;
91 &lt;mail link="<i>yourname@gentoo.org</i>"&gt;<i>Your Name</i>&lt;/mail&gt; 93 &lt;mail link="<i>yourname@gentoo.org</i>"&gt;<i>Your Name</i>&lt;/mail&gt;
92&lt;/author&gt; 94&lt;/author&gt;
93 95
94&lt;abstract&gt; 96&lt;abstract&gt;
95<i>This guide shows you how to compose web documentation using 97<i>This guide shows you how to compose web documentation using
96our new lightweight Gentoo GuideXML syntax. This syntax is the official 98our new lightweight Gentoo GuideXML syntax. This syntax is the official
97format for Gentoo Linux web documentation, and this document itself was created 99format for Gentoo Linux web documentation, and this document itself was created
98using GuideXML.</i> 100using GuideXML.</i>
99&lt;/abstract&gt; 101&lt;/abstract&gt;
100 102
101&lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt; 103&lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
102&lt;!-- See http://creativecommons.org/licenses/by-sa/2.0 --&gt; 104&lt;!-- See http://creativecommons.org/licenses/by-sa/2.0 --&gt;
103&lt;license/&gt; 105&lt;license/&gt;
104 106
105&lt;version&gt;<i>1.0</i>&lt;/version&gt; 107&lt;version&gt;<i>1.0</i>&lt;/version&gt;
106&lt;date&gt;<i>2004-12-25</i>&lt;/date&gt; 108&lt;date&gt;<i>2004-12-25</i>&lt;/date&gt;
107</pre> 109</pre>
108 110
109<p> 111<p>
110On the first, line, we see the requisite tag that identifies this as an XML 112On the first lines, we see the requisite tag that identifies this as an XML
111document. Following it, there's a <c>&lt;guide&gt;</c> tag -- the entire 113document and specifies its DTD. The <c>&lt;!-- &#36;Header&#36; --&gt;</c> line
114will be automatically modified by the CVS server and helps to track revisions.
115Next, there's a <c>&lt;guide&gt;</c> tag -- the entire guide document
112guide document is enclosed within a <c>&lt;guide&gt; &lt;/guide&gt;</c> pair. 116is enclosed within a <c>&lt;guide&gt; &lt;/guide&gt;</c> pair. The <c>link</c>
113The <c>link</c> attribute is compulsory and should preferably contain the 117attribute is compulsory and should preferably contain the relative path to the
114relative path to the document even though the file name alone will work. It is 118document even though the file name alone will work. It is mainly used to
115mainly used to generate a link to a printer-friendly version of your document. 119generate a link to a printer-friendly version of your document. If you use a
116If you use a wrong value, the link to the printable version will either not 120wrong value, the link to the printable version will either not work or point to
117work or point to a wrong document. The <c>lang</c> attribute can be used to 121a wrong document. The <c>lang</c> attribute can be used to specify the language
118specify the language code of your document. It is used to format the date and 122code of your document. It is used to format the date and insert strings like
119insert strings like "<e>Note</e>", "<e>Content</e>", etc. in the specified 123"<e>Note</e>", "<e>Content</e>", etc. in the specified language. The default
120language. The default is English. 124is English.
121</p> 125</p>
122 126
123<p> 127<p>
124Next, there's a <c>&lt;title&gt;</c> tag, used to set the title for the entire 128Next, there's a <c>&lt;title&gt;</c> tag, used to set the title for the entire
125guide document. 129guide document.
126</p> 130</p>
127 131
128<p> 132<p>
129Then, we come to the <c>&lt;author&gt;</c> tags, which contain information 133Then, we come to the <c>&lt;author&gt;</c> tags, which contain information
130about the various authors of the document. Each <c>&lt;author&gt;</c> tag 134about the various authors of the document. Each <c>&lt;author&gt;</c> tag
131allows for an optional <c>title=</c> element, used to specify the author's 135allows for an optional <c>title=</c> element, used to specify the author's
132relationship to the document (author, co-author, editor, etc.). In this 136relationship to the document (author, co-author, editor, etc.). In this
133particular example, the authors' names are enclosed in another tag -- a 137particular example, the authors' names are enclosed in another tag -- a
134<c>&lt;mail&gt;</c> tag, used to specify an email address for this particular 138<c>&lt;mail&gt;</c> tag, used to specify an email address for this particular
135person. The <c>&lt;mail&gt;</c> tag is optional and can be omitted, and no 139person. The <c>&lt;mail&gt;</c> tag is optional and can be omitted, and no
627</body> 631</body>
628</section> 632</section>
629<section> 633<section>
630<title>Main File</title> 634<title>Main File</title>
631<body> 635<body>
632 636
633<p> 637<p>
634The first change is the need for a "master" document. This document contains no 638The first change is the need for a "master" document. This document contains no
635real content, but links to the individual documentation modules. The syntaxis 639real content, but links to the individual documentation modules. The syntaxis
636doesn't differ much from GuideXML: 640doesn't differ much from GuideXML:
637</p> 641</p>
638 642
639<pre caption="Example book usage"> 643<pre caption="Example book usage">
640&lt;?xml version='1.0' encoding='UTF-8'?&gt; 644&lt;?xml version='1.0' encoding='UTF-8'?&gt;
641&lt;!DOCTYPE book SYSTEM "/dtd/book.dtd"&gt; 645&lt;!DOCTYPE book SYSTEM "/dtd/book.dtd"&gt;
646&lt;!-- &#36;Header&#36; --&gt;
642 647
643&lt;<i>book</i> link="example.xml"&gt; 648&lt;<i>book</i> link="example.xml"&gt;
644&lt;title&gt;Example Book Usage&lt;/title&gt; 649&lt;title&gt;Example Book Usage&lt;/title&gt;
645 650
646&lt;author...&gt; 651&lt;author...&gt;
647 ... 652 ...
648&lt;/author&gt; 653&lt;/author&gt;
649 654
650&lt;abstract&gt; 655&lt;abstract&gt;
651 ... 656 ...
652&lt;/abstract&gt; 657&lt;/abstract&gt;
653 658
654&lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt; 659&lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
655&lt;!-- See http://creativecommons.org/licenses/by-sa/2.0 --&gt; 660&lt;!-- See http://creativecommons.org/licenses/by-sa/2.0 --&gt;
656&lt;license/&gt; 661&lt;license/&gt;
702</pre> 707</pre>
703 708
704</body> 709</body>
705</section> 710</section>
706<section> 711<section>
707<title>Designing the Individual Chapters</title> 712<title>Designing the Individual Chapters</title>
708<body> 713<body>
709 714
710<p> 715<p>
711The content of an individual chapter is structured as follows: 716The content of an individual chapter is structured as follows:
712</p> 717</p>
713 718
714<pre caption="Chapter Syntax"> 719<pre caption="Chapter Syntax">
715&lt;?xml version='1.0' encoding='UTF-8'?&gt; 720&lt;?xml version='1.0' encoding='UTF-8'?&gt;
716&lt;!DOCTYPE sections SYSTEM "/dtd/book.dtd"&gt; 721&lt;!DOCTYPE sections SYSTEM "/dtd/book.dtd"&gt;
722&lt;!-- &#36;Header&#36; --&gt;
717 723
718&lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt; 724&lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
719&lt;!-- See http://creativecommons.org/licenses/by-sa/2.0 --&gt; 725&lt;!-- See http://creativecommons.org/licenses/by-sa/2.0 --&gt;
720 726
721&lt;sections&gt; 727&lt;sections&gt;
722 728
723&lt;version&gt;...&lt;/version&gt; 729&lt;version&gt;...&lt;/version&gt;
724&lt;date&gt;...&lt;/date&gt; 730&lt;date&gt;...&lt;/date&gt;
725 731
726<comment>(Define the several &lt;section&gt; and &lt;subsection&gt;)</comment> 732<comment>(Define the several &lt;section&gt; and &lt;subsection&gt;)</comment>
727 733
728&lt;/sections&gt; 734&lt;/sections&gt;
729</pre> 735</pre>
730 736
731<p> 737<p>

Legend:
Removed from v.1.41  
changed lines
  Added in v.1.42

  ViewVC Help
Powered by ViewVC 1.1.20