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.39 2005/04/16 19:45:35 swift Exp $ --> |
2 | <!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> |
3 | <!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> |
3 | |
4 | |
4 | <guide link="/doc/en/xml-guide.xml"> |
5 | <guide link="/doc/en/xml-guide.xml"> |
5 | <title>Gentoo Linux Documentation Guide</title> |
6 | <title>Gentoo Linux XML Guide</title> |
|
|
7 | |
|
|
8 | <author title="Author"> |
6 | <author title="Author"><mail link="drobbins@gentoo.org">Daniel Robbins</mail></author> |
9 | <mail link="drobbins@gentoo.org">Daniel Robbins</mail> |
7 | <author title="Editor"><mail link="zhen@gentoo.org">John P. Davis</mail></author> |
10 | </author> |
|
|
11 | <author title="Author"><!-- zhen@gentoo.org --> |
|
|
12 | John P. Davis |
|
|
13 | </author> |
|
|
14 | <author title="Editor"> |
|
|
15 | <mail link="peesh@gentoo.org">Jorge Paulo</mail> |
|
|
16 | </author> |
|
|
17 | <author title="Editor"> |
|
|
18 | <mail link="swift@gentoo.org">Sven Vermeulen</mail> |
|
|
19 | </author> |
|
|
20 | <author title="Editor"> |
|
|
21 | <mail link="neysx@gentoo.org">Xavier Neys</mail> |
|
|
22 | </author> |
8 | |
23 | |
|
|
24 | <abstract> |
9 | <abstract>This guide shows you how to compose web documentation using the new lightweight Gentoo guide |
25 | This guide shows you how to compose web documentation using the new lightweight |
10 | XML syntax. This syntax is the official format for Gentoo Linux documentation, and this document |
26 | Gentoo GuideXML syntax. This syntax is the official format for Gentoo Linux |
11 | itself was created using guide XML. This guide assumes a basic working knowledge of XML and HTML. |
27 | documentation, and this document itself was created using GuideXML. This guide |
|
|
28 | assumes a basic working knowledge of XML and HTML. |
12 | </abstract> |
29 | </abstract> |
13 | |
30 | |
|
|
31 | <!-- The content of this document is licensed under the CC-BY-SA license --> |
|
|
32 | <!-- See http://creativecommons.org/licenses/by-sa/2.0 --> |
|
|
33 | <license/> |
|
|
34 | |
14 | <version>1.1</version> |
35 | <version>2.16</version> |
15 | <date>10 January 2002</date> |
36 | <date>2005-04-16</date> |
16 | |
37 | |
17 | <chapter> |
38 | <chapter> |
18 | <title>Guide basics</title> |
39 | <title>Guide basics</title> |
19 | |
|
|
20 | <section> |
40 | <section> |
21 | <title>Guide XML design goals</title> |
41 | <title>Guide XML design goals</title> |
22 | <body> |
42 | <body> |
23 | |
43 | |
|
|
44 | <p> |
24 | <p> 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 |
25 | 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 |
26 | 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. |
27 | 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 |
28 | XML/SGML or web-ready HTML. </p> |
49 | XML/SGML or web-ready HTML. |
|
|
50 | </p> |
29 | |
51 | |
|
|
52 | <p> |
30 | <p>The goal is to make it easy to <e>create</e> and <e>transform</e> guide XML |
53 | The goal is to make it easy to <e>create</e> and <e>transform</e> guide XML |
31 | documents.</p> |
54 | documents. |
|
|
55 | </p> |
32 | |
56 | |
33 | </body> |
57 | </body> |
34 | </section> |
|
|
35 | |
|
|
36 | <section> |
58 | </section> |
37 | <title>How to transform guide XML into HTML</title> |
59 | <section> |
|
|
60 | <title>Further Resources</title> |
38 | <body> |
61 | <body> |
39 | |
62 | |
40 | <p> Before we take a look at the guide syntax itself, it's helpful to know how |
|
|
41 | guide XML is transformed into web-ready HTML. To do this, we use a special |
|
|
42 | file called <path>guide.xsl</path>, along with a command-line XSLT processing |
|
|
43 | tool (also called an "engine"). The <path>guide.xsl</path> file describes |
|
|
44 | exactly how to transform the contents of the source guide XML document to |
|
|
45 | create the target HTML file. Two popular XSLT processors are <c>sabcmd</c> |
|
|
46 | (included in the <path>app-text/sablotron</path> package) and <c>xsltproc</c> |
|
|
47 | (found in the <path>dev-libs/libxslt</path> package). From experience, we've |
|
|
48 | found that <c>xsltproc</c> is the higher-quality and more feature-rich XSLT |
|
|
49 | processor. </p> |
|
|
50 | |
|
|
51 | |
|
|
52 | <p> Once you have either <c>xsltproc</c> or <c>sabcmd</c> installed, you're |
|
|
53 | ready to convert guide XML into web-ready HTML. In order to do this though, |
|
|
54 | it is necessary to get the latest snapshot of our website tree. |
|
|
55 | </p> |
63 | <p> |
56 | |
64 | If you are planning on contributing documentation to Gentoo, or you want to |
57 | <p>The gzipped tarball for the website can be found |
65 | test GuideXML, please read the <uri |
58 | <uri link="http://www.gentoo.org/dyn/arch/xml-guide-latest.tar.gz">here</uri>. |
66 | link="/proj/en/gdp/doc/doc-tipsntricks.xml">Tips and Tricks</uri> which |
59 | </p> |
67 | contains tips and tricks for documentation development. |
60 | |
|
|
61 | <p>Now, extract the tarball. Inside it, you'll find a <path>htdocs</path> |
|
|
62 | directory. Now, find <path>htdocs/doc/<your lang>/gentoo-x86-install.xml</path> |
|
|
63 | (The new user installation guide). This will be our source XML guide document. |
|
|
64 | The easiest way to perform the transformation is to change directories to the location of the |
|
|
65 | <path>guide.xsl</path> file. Then, execute <c>xsltproc</c> as follows: |
|
|
66 | </p> |
|
|
67 | |
|
|
68 | <pre caption="Transforming gentoo-x86-install.xml"> |
|
|
69 | # <c>cd gentoo-web/xsl</c> |
|
|
70 | # <c>xsltproc guide.xsl ../doc/<your lang>/gentoo-x86-install.xml > /tmp/install.html</c> |
|
|
71 | </pre> |
|
|
72 | |
|
|
73 | <p> If all went well, you should have a web-ready version of |
|
|
74 | <path>gentoo-x86-install.xml</path> at <path>/tmp/install.html</path>. For this document |
|
|
75 | to display properly in a web browser, you may have to copy some files from |
|
|
76 | <path>htdocs</path> to <path>/tmp</path>, such |
|
|
77 | as <path>css/main-new.css</path> and (to be safe) the entire <path>images</path> |
|
|
78 | directory. |
|
|
79 | </p> |
68 | </p> |
80 | |
69 | |
81 | </body> |
70 | </body> |
82 | </section> |
71 | </section> |
83 | </chapter> |
72 | </chapter> |
|
|
73 | |
84 | <chapter> |
74 | <chapter> |
85 | <title>Guide XML</title> |
75 | <title>Guide XML</title> |
86 | <section> |
76 | <section> |
87 | <title>Basic structure</title> |
77 | <title>Basic structure</title> |
88 | <body> |
78 | <body> |
89 | |
79 | |
90 | <p>Now that you know how to transform guide XML, you're ready to start learning |
80 | <p> |
91 | the guide XML syntax. We'll start with the the initial tags used in a guide |
81 | Let's start learning the GuideXML syntax. We'll start with the the initial |
92 | XML document: </p> |
82 | tags used in a GuideXML document: |
|
|
83 | </p> |
93 | |
84 | |
94 | <pre caption="The initial part of a guide XML document"> |
85 | <pre caption="The initial part of a guide XML document"> |
95 | <?xml version='1.0' encoding="UTF-8"?> |
86 | <?xml version='1.0' encoding="UTF-8"?> |
96 | <guide link="relative_link_to_your_guide"> |
87 | <!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> |
|
|
88 | <guide link="<i>relative/link/to/your/guide.xml</i>" lang="<i>en</i>"> |
97 | <title><i>Gentoo Linux Documentation Guide</i></title> |
89 | <title><i>Gentoo Linux Documentation Guide</i></title> |
98 | <author title="<i>Chief Architect</i>"><mail link="<i>drobbins@gentoo.org</i>"> |
90 | <author title="<i>Author</i>"> |
99 | <i>Daniel Robbins</i></mail> |
91 | <mail link="<i>yourname@gentoo.org</i>"><i>Your Name</i></mail> |
100 | </author> |
92 | </author> |
101 | <author title="<i>Editor</i>"><mail link="<i>thomasfl@gentoo.org</i>"> |
|
|
102 | <i>Thomas Flavel</i></mail> |
|
|
103 | </author> |
|
|
104 | |
93 | |
105 | <impo>If you are going to be submitting documents, it is necessary to read the |
94 | <abstract> |
106 | <uri link="http://www.gentoo.org/doc/en/doc-developer-guide.xml">Gentoo Documentation Developer's Policy</uri>. |
|
|
107 | </impo> |
|
|
108 | |
|
|
109 | <abstract><i>This guide shows you how to compose web documentation using |
95 | <i>This guide shows you how to compose web documentation using |
110 | our new lightweight Gentoo guide XML syntax. This syntax is the official |
96 | our new lightweight Gentoo GuideXML syntax. This syntax is the official |
111 | format for Gentoo Linux web documentation, and this document itself was created |
97 | format for Gentoo Linux web documentation, and this document itself was created |
112 | using guide XML.</i> </abstract> |
98 | using GuideXML.</i> |
|
|
99 | </abstract> |
|
|
100 | |
|
|
101 | <!-- The content of this document is licensed under the CC-BY-SA license --> |
|
|
102 | <!-- See http://creativecommons.org/licenses/by-sa/2.0 --> |
|
|
103 | <license/> |
113 | |
104 | |
114 | <version><i>1.0</i></version> |
105 | <version><i>1.0</i></version> |
115 | <date><i>29 Mar 2001</i></date> |
106 | <date><i>2004-12-25</i></date> |
116 | </pre> |
107 | </pre> |
117 | |
108 | |
|
|
109 | <p> |
118 | <p>On the first, line, we see the requisite tag that identifies this as an XML |
110 | On the first, line, we see the requisite tag that identifies this as an XML |
119 | document. Following it, there's a <c><guide></c> tag -- the entire |
111 | document. Following it, there's a <c><guide></c> tag -- the entire |
120 | guide document is enclosed within a <c><guide> </guide></c> pair. |
112 | guide document is enclosed within a <c><guide> </guide></c> pair. |
|
|
113 | The <c>link</c> attribute is compulsory and should preferably contain the |
|
|
114 | relative path to the document even though the file name alone will work. It is |
|
|
115 | mainly used to generate a link to a printer-friendly version of your document. |
|
|
116 | If you use a wrong value, the link to the printable version will either not |
|
|
117 | work or point to a wrong document. The <c>lang</c> attribute can be used to |
|
|
118 | specify the language code of your document. It is used to format the date and |
|
|
119 | insert strings like "<e>Note</e>", "<e>Content</e>", etc. in the specified |
|
|
120 | language. The default is English. |
|
|
121 | </p> |
|
|
122 | |
|
|
123 | <p> |
121 | Next, there's a <c><title></c> tag, used to set the title for the entire |
124 | Next, there's a <c><title></c> tag, used to set the title for the entire |
122 | guide document. </p> |
125 | guide document. |
|
|
126 | </p> |
123 | |
127 | |
|
|
128 | <p> |
124 | <p>Then, we come to the <c><author></c> tags, which contain information |
129 | Then, we come to the <c><author></c> tags, which contain information |
125 | about the various authors of the document. Each <c><author></c> tag |
130 | about the various authors of the document. Each <c><author></c> tag |
126 | allows for an optional <c>title=</c> element, used to specify the author's |
131 | allows for an optional <c>title=</c> element, used to specify the author's |
127 | relationship to the document (author, co-author, editor, etc.). In this |
132 | relationship to the document (author, co-author, editor, etc.). In this |
128 | particular example, the authors' names are enclosed in another tag -- a |
133 | particular example, the authors' names are enclosed in another tag -- a |
129 | <c><mail></c> tag, used to specify an email address for this particular |
134 | <c><mail></c> tag, used to specify an email address for this particular |
130 | person. The <c><mail></c> tag is optional and can be omitted, and no |
135 | person. The <c><mail></c> tag is optional and can be omitted, and no |
131 | more than one <c><author></c> element is required per guide document. |
136 | more than one <c><author></c> element is required per guide document. |
132 | </p> |
137 | </p> |
133 | |
138 | |
|
|
139 | <p> |
134 | <p>Next, we come to the <c><abstract></c>, <c><version></c> and |
140 | Next, we come to the <c><abstract></c>, <c><version></c> and |
135 | <c><date></c> tags, used to specify a summary of the document, the |
141 | <c><date></c> tags, used to specify a summary of the document, the |
136 | current version number, and the current version date (in DD MMM YYYY format) |
142 | current version number, and the current version date (in YYYY-MM-DD format) |
|
|
143 | respectively. Dates that are invalid or not in the YYYY-MM-DD format will |
|
|
144 | appear verbatim in the rendered document. |
|
|
145 | </p> |
|
|
146 | |
|
|
147 | <p> |
137 | respectively. This rounds out the tags that should appear at the beginning of |
148 | This rounds out the tags that should appear at the beginning of a guide |
138 | a guide document. Besides the <c><title></c> and <c><mail></c> |
149 | document. Besides the <c><title></c> and <c><mail></c> tags, these |
139 | tags, these tags shouldn't appear anywhere else except immediately inside the |
150 | tags shouldn't appear anywhere else except immediately inside the |
140 | <c><guide></c> tag, and for consistency it's recommended (but not |
151 | <c><guide></c> tag, and for consistency it's recommended (but not |
141 | required) that these tags appear before the content of the document. </p> |
152 | required) that these tags appear before the content of the document. |
|
|
153 | </p> |
142 | |
154 | |
143 | </body> |
155 | <p> |
144 | </section> |
156 | Finally we have the <c><license/></c> tag, used to publish the document |
|
|
157 | under the <uri link="http://creativecommons.org/licenses/by-sa/2.0/">Creative |
|
|
158 | Commons - Attribution / Share Alike</uri> license as required by the <uri |
|
|
159 | link="/proj/en/gdp/doc/doc-policy.xml">Documentation Policy</uri>. |
|
|
160 | </p> |
145 | |
161 | |
|
|
162 | </body> |
|
|
163 | </section> |
146 | <section> |
164 | <section> |
147 | <title>Chapters and sections</title> |
165 | <title>Chapters and sections</title> |
148 | <body> |
166 | <body> |
|
|
167 | |
|
|
168 | <p> |
149 | <p>Once the initial tags have been specified, you're ready to start adding |
169 | Once the initial tags have been specified, you're ready to start adding the |
150 | the structural elements of the document. Guide documents are divided into |
170 | structural elements of the document. Guide documents are divided into |
151 | chapters, and each chapter can hold one or more sections. Every chapter |
171 | chapters, and each chapter can hold one or more sections. Every chapter and |
152 | and section has a title. Here's an example chapter with a single section, |
172 | section has a title. Here's an example chapter with a single section, |
153 | consisting of a paragraph. If you append this XML to the XML in the <uri link="#doc_pre2">previous |
173 | consisting of a paragraph. If you append this XML to the XML in the <uri |
|
|
174 | link="#doc_chap2_pre1">previous excerpt</uri> and append a |
154 | excerpt</uri> and append a <c></guide></c> to the end of the file, you'll have a valid |
175 | <c></guide></c> to the end of the file, you'll have a valid (if minimal) |
155 | (if minimal) guide document: |
176 | guide document: |
156 | </p> |
177 | </p> |
157 | |
178 | |
158 | <pre> |
179 | <pre caption="Minimal guide example"> |
159 | <chapter> |
180 | <chapter> |
160 | <title><i>This is my chapter</i></title> |
181 | <title><i>This is my chapter</i></title> |
161 | <section> |
182 | <section> |
162 | <title><i>This is section one of my chapter</i></title> |
183 | <title><i>This is section one of my chapter</i></title> |
163 | <body> |
184 | <body> |
|
|
185 | |
|
|
186 | <p> |
164 | <p><i>This is the actual text content of my section.</i></p> |
187 | <i>This is the actual text content of my section.</i> |
|
|
188 | </p> |
|
|
189 | |
165 | </body> |
190 | </body> |
166 | </section> |
191 | </section> |
167 | </chapter> |
192 | </chapter> |
168 | </pre> |
193 | </pre> |
169 | |
194 | |
|
|
195 | <p> |
170 | <p>Above, I set the chapter title by adding a child <c><title></c> |
196 | Above, I set the chapter title by adding a child <c><title></c> |
171 | element to the <c><chapter></c> element. Then, I created a section by |
197 | element to the <c><chapter></c> element. Then, I created a section by |
172 | adding a <c><section></c> element. If you look inside the |
198 | adding a <c><section></c> element. If you look inside the |
173 | <c><section></c> element, you'll see that it has two child elements -- a |
199 | <c><section></c> element, you'll see that it has two child elements -- a |
174 | <c><title></c> and a <c><body></c>. While the <c><title></c> |
200 | <c><title></c> and a <c><body></c>. While the <c><title></c> |
175 | is nothing new, the <c><body></c> is -- it contains the actual text |
201 | is nothing new, the <c><body></c> is -- it contains the actual text |
176 | content of this particular section. We'll look at the tags that are allowed |
202 | content of this particular section. We'll look at the tags that are allowed |
177 | inside a <c><body></c> element in a bit. </p> |
203 | inside a <c><body></c> element in a bit. |
|
|
204 | </p> |
178 | |
205 | |
|
|
206 | <note> |
179 | <note>A <c><guide></c> element can contain multiple |
207 | A <c><guide></c> element can contain multiple <c><chapter></c> |
180 | <c><chapter></c> elements, and a <c><chapter></c> can contain |
208 | elements, and a <c><chapter></c> can contain multiple |
181 | multiple <c><section></c> elements. However, a <c><section></c> |
209 | <c><section></c> elements. However, a <c><section></c> |
182 | element can only contain one <c><body></c> element. </note> |
210 | element can only contain one <c><body></c> element. |
|
|
211 | </note> |
183 | |
212 | |
184 | </body> |
213 | </body> |
185 | </section> |
214 | </section> |
186 | |
|
|
187 | <section> |
215 | <section> |
188 | <title>An example <body></title> |
216 | <title>An example <body></title> |
189 | <body> |
217 | <body> |
190 | <p> |
218 | |
191 | Now, it's time to learn how to mark up actual content. Here's the XML code for an example <c><body></c> element: |
|
|
192 | </p> |
219 | <p> |
193 | <pre> |
220 | Now, it's time to learn how to mark up actual content. Here's the XML code for |
|
|
221 | an example <c><body></c> element: |
|
|
222 | </p> |
|
|
223 | |
|
|
224 | <pre caption="Example of a body element"> |
194 | <p> |
225 | <p> |
195 | This is a paragraph. <path>/etc/passwd</path> is a file. |
226 | This is a paragraph. <path>/etc/passwd</path> is a file. |
196 | <uri>http://www.gentoo.org</uri> is my favorite website. |
227 | <uri>http://forums.gentoo.org</uri> is my favorite website. |
197 | Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now. |
228 | Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now. |
198 | </p> |
229 | </p> |
199 | |
230 | |
200 | <pre> |
231 | <pre caption="Code Sample"> |
201 | This is text output or code. |
232 | This is text output or code. |
202 | # <i>this is user input</i> |
233 | # <i>this is user input</i> |
203 | |
234 | |
204 | Make HTML/XML easier to read by using selective emphasis: |
235 | Make HTML/XML easier to read by using selective emphasis: |
205 | <foo><i>bar</i></foo> |
236 | <foo><i>bar</i></foo> |
206 | |
237 | |
207 | <codenote>This is how to insert an inline note into the code block</codenote> |
238 | <comment>(This is how to insert an inline note into the code block)</comment> |
208 | </pre> |
239 | </pre> |
209 | <note>This is a note.</note> |
240 | |
210 | <warn>This is a warning.</warn> |
241 | <note> |
211 | <impo>This is important.</impo> |
242 | This is a note. |
|
|
243 | </note> |
|
|
244 | |
|
|
245 | <warn> |
|
|
246 | This is a warning. |
|
|
247 | </warn> |
|
|
248 | |
|
|
249 | <impo> |
|
|
250 | This is important. |
|
|
251 | </impo> |
212 | </pre> |
252 | </pre> |
|
|
253 | |
|
|
254 | <p> |
213 | <p>Now, here's how this <c><body></c> element is rendered:</p> |
255 | Now, here's how the <c><body></c> element above is rendered: |
|
|
256 | </p> |
214 | |
257 | |
215 | <p> |
258 | <p> |
216 | This is a paragraph. <path>/etc/passwd</path> is a file. |
259 | This is a paragraph. <path>/etc/passwd</path> is a file. |
217 | <uri>http://www.gentoo.org</uri> is my favorite website. |
260 | <uri>http://forums.gentoo.org</uri> is my favorite website. |
218 | Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now. |
261 | Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now. |
219 | </p> |
262 | </p> |
220 | |
263 | |
221 | <pre> |
264 | <pre caption="Code Sample"> |
222 | This is text output or code. |
265 | This is text output or code. |
223 | # <i>this is user input</i> |
266 | # <i>this is user input</i> |
224 | |
267 | |
225 | Make HTML/XML easier to read by using selective emphasis: |
268 | Make HTML/XML easier to read by using selective emphasis: |
226 | <foo><i>bar</i></foo> |
269 | <foo><i>bar</i></foo> |
227 | |
270 | |
228 | <codenote>This is how to insert an inline note into the code block</codenote> |
271 | <comment>(This is how to insert an inline note into the code block)</comment> |
229 | </pre> |
272 | </pre> |
230 | <note>This is a note.</note> |
|
|
231 | <warn>This is a warning.</warn> |
|
|
232 | <impo>This is important.</impo> |
|
|
233 | </body> |
|
|
234 | </section> |
|
|
235 | |
273 | |
|
|
274 | <note> |
|
|
275 | This is a note. |
|
|
276 | </note> |
|
|
277 | |
|
|
278 | <warn> |
|
|
279 | This is a warning. |
|
|
280 | </warn> |
|
|
281 | |
|
|
282 | <impo> |
|
|
283 | This is important. |
|
|
284 | </impo> |
|
|
285 | |
|
|
286 | </body> |
|
|
287 | </section> |
236 | <section> |
288 | <section> |
237 | <title>The <body> tags</title> |
289 | <title>The <body> tags</title> |
238 | <body> |
290 | <body> |
239 | |
291 | |
|
|
292 | <p> |
240 | <p> We introduced a lot of new tags in the previous section -- here's what you |
293 | We introduced a lot of new tags in the previous section -- here's what you |
241 | need to know. The <c><p></c> (paragraph), <c><pre></c> (code |
294 | need to know. The <c><p></c> (paragraph), <c><pre></c> (code |
242 | block), <c><note></c>, <c><warn></c> (warning) and |
295 | block), <c><note></c>, <c><warn></c> (warning) and |
243 | <c><impo></c> (important) tags all can contain one or more lines of text. |
296 | <c><impo></c> (important) tags all can contain one or more lines of text. |
244 | Besides the <c><table></c> element (which we'll cover in just a bit), |
297 | Besides the <c><table></c> element (which we'll cover in just a bit), |
245 | these are the only tags that should appear immediately inside a |
298 | these are the only tags that should appear immediately inside a |
246 | <c><body></c> element. Another thing -- these tags <e>should not</e> be |
299 | <c><body></c> element. Another thing -- these tags <e>should not</e> be |
247 | stacked -- in other words, don't put a <c><note></c> element inside a |
300 | stacked -- in other words, don't put a <c><note></c> element inside a |
248 | <c><p></c> element. As you might guess, the <c><pre></c> element |
301 | <c><p></c> element. As you might guess, the <c><pre></c> element |
249 | preserves its whitespace exactly, making it well-suited for code excerpts.</p> |
302 | preserves its whitespace exactly, making it well-suited for code excerpts. |
|
|
303 | You can also name the <c><pre></c> tag: |
|
|
304 | </p> |
|
|
305 | |
|
|
306 | <pre caption="Named <pre>"> |
|
|
307 | <pre caption = "Output of uptime"> |
|
|
308 | # <i>uptime</i> |
|
|
309 | 16:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25 |
|
|
310 | </pre> |
|
|
311 | </pre> |
250 | |
312 | |
251 | </body> |
313 | </body> |
252 | </section> |
314 | </section> |
253 | <section> |
315 | <section> |
254 | <title><path>, <c> and <e></title> |
316 | <title><path>, <c> and <e></title> |
255 | <body> |
317 | <body> |
256 | |
318 | |
|
|
319 | <p> |
257 | <p>The <c><path></c>, <c><c></c> and <c><e></c> elements can |
320 | The <c><path></c>, <c><c></c> and <c><e></c> elements can |
258 | be used inside any child <c><body></c> tag, except for |
321 | be used inside any child <c><body></c> tag, except for |
259 | <c><pre></c>. </p> |
322 | <c><pre></c>. |
|
|
323 | </p> |
260 | |
324 | |
|
|
325 | <p> |
261 | <p>The <c><path></c> element is used to mark text that refers to an |
326 | The <c><path></c> element is used to mark text that refers to an |
262 | <e>on-disk file</e> -- either an <e>absolute or relative path</e>, or a <e>simple filename</e>. |
327 | <e>on-disk file</e> -- either an <e>absolute or relative path</e>, or a |
263 | This element is generally rendered with a monospaced font to offset it from the |
328 | <e>simple filename</e>. This element is generally rendered with a monospaced |
264 | standard paragraph type. </p> |
329 | font to offset it from the standard paragraph type. |
|
|
330 | </p> |
265 | |
331 | |
|
|
332 | <p> |
266 | <p>The <c><c></c> element is used to mark up a <e>command</e> or <e>user |
333 | The <c><c></c> element is used to mark up a <e>command</e> or <e>user |
267 | input</e>. Think of <c><c></c> as a way to alert the reader to something |
334 | input</e>. Think of <c><c></c> as a way to alert the reader to something |
268 | that they can type in that will perform some kind of action. For example, all |
335 | that they can type in that will perform some kind of action. For example, all |
269 | the XML tags displayed in this document are enclosed in a <c><c></c> |
336 | the XML tags displayed in this document are enclosed in a <c><c></c> |
270 | element because they represent something that the user could type in that is |
337 | element because they represent something that the user could type in that is |
271 | not a path. By using <c><c></c> elements, you'll help your readers |
338 | not a path. By using <c><c></c> elements, you'll help your readers |
272 | quickly identify commands that they need to type in. Also, because |
339 | quickly identify commands that they need to type in. Also, because |
273 | <c><c></c> elements are already offset from regular text, <e>it is rarely |
340 | <c><c></c> elements are already offset from regular text, <e>it is rarely |
274 | necessary to surround user input with double-quotes</e>. For example, don't |
341 | necessary to surround user input with double-quotes</e>. For example, don't |
275 | refer to a "<c><c></c>" element like I did in this sentence. Avoiding |
342 | refer to a "<c><c></c>" element like I did in this sentence. Avoiding |
276 | the use of unnecessary double-quotes makes a document more readable -- and adorable!</p> |
343 | the use of unnecessary double-quotes makes a document more readable -- and |
|
|
344 | adorable! |
|
|
345 | </p> |
277 | |
346 | |
|
|
347 | <p> |
278 | <p><c><e></c> is used to apply emphasis to a word or phrase; for example: |
348 | <c><e></c> is used to apply emphasis to a word or phrase; for example: |
279 | I <e>really</e> should use semicolons more often. As you can see, this text is |
349 | I <e>really</e> should use semicolons more often. As you can see, this text is |
280 | offset from the regular paragraph type for emphasis. This helps to give your |
350 | offset from the regular paragraph type for emphasis. This helps to give your |
281 | prose more <e>punch</e>!</p> |
351 | prose more <e>punch</e>! |
|
|
352 | </p> |
282 | |
353 | |
283 | </body> |
354 | </body> |
284 | </section> |
355 | </section> |
285 | |
|
|
286 | <section> |
356 | <section> |
287 | <title><mail> and <uri></title> |
357 | <title><mail> and <uri></title> |
288 | <body> |
358 | <body> |
289 | |
359 | |
|
|
360 | <p> |
290 | <p>We've taken a look at the <c><mail></c> tag earlier; it's used to link some text |
361 | We've taken a look at the <c><mail></c> tag earlier; it's used to link |
291 | with a particular email address, and takes the form <c><mail link="foo@bar.com">Mr. Foo Bar</mail></c>.</p> |
362 | some text with a particular email address, and takes the form <c><mail |
|
|
363 | link="foo@bar.com">Mr. Foo Bar</mail></c>. |
|
|
364 | </p> |
292 | |
365 | |
|
|
366 | <p> |
293 | <p>The <c><uri></c> tag is used to point to files/locations on the |
367 | The <c><uri></c> tag is used to point to files/locations on the Internet. |
294 | Internet. It has two forms -- the first can be used when you want to have the |
368 | It has two forms -- the first can be used when you want to have the actual URI |
295 | actual URI displayed in the body text, such as this link to |
369 | displayed in the body text, such as this link to |
296 | <uri>http://www.gentoo.org</uri>. To create this link, I typed |
370 | <uri>http://forums.gentoo.org</uri>. To create this link, I typed |
297 | <c><uri>http://www.gentoo.org</uri></c>. The alternate form is |
371 | <c><uri>http://forums.gentoo.org</uri></c>. The alternate form is |
298 | when you want to associate a URI with some other text -- for example, <uri |
372 | when you want to associate a URI with some other text -- for example, <uri |
299 | link="http://www.gentoo.org">the Gentoo Linux website</uri>. To create <e>this</e> |
373 | link="http://forums.gentoo.org">the Gentoo Forums</uri>. To create <e>this</e> |
300 | link, I typed <c><uri link="http://www.gentoo.org">the Gentoo Linux website</uri></c>. |
374 | link, I typed <c><uri link="http://forums.gentoo.org">the Gentoo |
|
|
375 | Forums</uri></c>. You don't need to write <c>http://www.gentoo.org/</c> |
|
|
376 | to link to other parts of the Gentoo website. For instance, a link to the <uri |
|
|
377 | link="/doc/en/">documentation main index</uri> should be simply <c><uri |
|
|
378 | link="/doc/en/index.xml">documentation main index</uri></c>. You can |
|
|
379 | even omit <c>index.xml</c> when you link to a directory index, e.g. <c><uri |
|
|
380 | link="/doc/en/">documentation main index</uri></c>. |
301 | </p> |
381 | </p> |
302 | |
382 | |
303 | </body> |
383 | </body> |
304 | </section> |
384 | </section> |
305 | |
|
|
306 | <section> |
385 | <section> |
307 | <title>Figures</title> |
386 | <title>Figures</title> |
308 | |
|
|
309 | <body> |
387 | <body> |
310 | |
388 | |
|
|
389 | <p> |
311 | <p>Here's how to insert a figure into a document -- <c><figure |
390 | Here's how to insert a figure into a document -- <c><figure |
312 | link="mygfx.png" short="my picture" caption="my favorite picture of all |
391 | link="mygfx.png" short="my picture" caption="my favorite picture of all |
313 | time"/></c>. The <c>link=</c> attribute points to the actual graphic image, |
392 | time"/></c>. The <c>link=</c> attribute points to the actual graphic image, |
314 | the <c>short=</c> attribute specifies a short description (currently used for |
393 | the <c>short=</c> attribute specifies a short description (currently used for |
315 | the image's HTML <c>alt=</c> attribute), and a caption. Not too difficult |
394 | the image's HTML <c>alt=</c> attribute), and a caption. Not too difficult |
316 | :) We also support the standard HTML-style <img src="foo.gif"/> tag |
395 | :) We also support the standard HTML-style <img src="foo.gif"/> tag |
317 | for adding images without captions, borders, etc.</p> |
396 | for adding images without captions, borders, etc. |
|
|
397 | </p> |
318 | |
398 | |
319 | </body> |
399 | </body> |
320 | </section> |
400 | </section> |
321 | <section> |
401 | <section> |
322 | <title>Tables and lists</title> |
402 | <title>Tables and lists</title> |
323 | <body> |
403 | <body> |
324 | |
404 | |
|
|
405 | <p> |
325 | <p>Guide supports a simplified table syntax similar to that of HTML. To start |
406 | Guide supports a simplified table syntax similar to that of HTML. To start |
326 | a table, use a <c><table></c> tag. Start a row with a <c><tr></c> |
407 | a table, use a <c><table></c> tag. Start a row with a <c><tr></c> |
327 | tag. However, for inserting actual table data, we <e>don't</e> support the |
408 | tag. However, for inserting actual table data, we <e>don't</e> support the |
328 | HTML <td> tag; instead, use the <c><th></c> if you are inserting a |
409 | HTML <td> tag; instead, use the <c><th></c> if you are inserting a |
329 | header, and <c><ti></c> if you are inserting a normal informational |
410 | header, and <c><ti></c> if you are inserting a normal informational |
330 | block. You can use a <c><th></c> anywhere you can use a <c><ti></c> -- |
411 | block. You can use a <c><th></c> anywhere you can use a <c><ti></c> |
331 | there's no requirement that <c><th></c> elements appear only in the |
412 | -- there's no requirement that <c><th></c> elements appear only in the |
332 | first row. Currently, these tags don't support any attributes, but some will |
413 | first row. Currently, these tags don't support any attributes, but some will |
333 | be added (such as a <c>caption=</c> attribute for <c><table></c>) soon. |
414 | be added (such as a <c>caption=</c> attribute for <c><table></c>) soon. |
334 | </p> |
415 | </p> |
335 | |
416 | |
|
|
417 | <p> |
336 | <p> To create ordered or unordered lists, simply use the HTML-style |
418 | To create ordered or unordered lists, simply use the XHTML-style |
337 | <c><ol></c>, <c><ul></c> and <c><li></c> tags. List tags |
419 | <c><ol></c>, <c><ul></c> and <c><li></c> tags. List tags |
338 | should only appear inside a <c><p></c>, <c><ti></c>, |
420 | should only appear inside a <c><body></c>, <c><ul></c> or |
339 | <c><note></c>, <c><warn></c> or <c><impo></c> tag. </p> |
421 | <c><ol></c> tag. You need to close the tags as well (which is a general |
|
|
422 | XML requirement). |
|
|
423 | </p> |
340 | |
424 | |
341 | </body> |
425 | </body> |
342 | </section> |
426 | </section> |
343 | |
|
|
344 | <section> |
427 | <section> |
345 | <title>Intra-document references</title> |
428 | <title>Intra-document references</title> |
346 | <body> |
429 | <body> |
347 | |
430 | |
|
|
431 | <p> |
348 | <p>Guide makes it really easy to reference other parts of the document using |
432 | Guide makes it really easy to reference other parts of the document using |
349 | hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter |
433 | hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter |
350 | One</uri> by typing <c><uri link="#doc_chap1">Chapter |
434 | One</uri> by typing <c><uri link="#doc_chap1">Chapter |
351 | One</uri></c>. To point to <uri link="#doc_chap1_sect2">section two of |
435 | One</uri></c>. To point to <uri link="#doc_chap1_sect2">section two of |
352 | Chapter One</uri>, type <c><uri link="#doc_chap1_sect2">section two of |
436 | Chapter One</uri>, type <c><uri link="#doc_chap1_sect2">section two of |
353 | Chapter One</uri></c>. To refer to figure 3 in chapter 1, type <c><uri |
437 | Chapter One</uri></c>. To refer to figure 3 in chapter 1, type <c><uri |
354 | link="doc_chap1_fig3">figure 1.3</uri></c>. Or, to refer to <uri link="#doc_chap2_pre2">code listing 2 in chapter 2</uri>, |
438 | link="doc_chap1_fig3">figure 1.3</uri></c>. Or, to refer to <uri |
|
|
439 | link="#doc_chap2_pre2">code listing 2 in chapter 2</uri>, type <c><uri |
355 | type <c><uri link="doc_chap2_pre2">code listing 2.2</uri></c>. We'll be |
440 | link="doc_chap2_pre2">code listing 2.2</uri></c>. We'll be |
356 | adding other auto-link abilities (such as table support) soon.</p> |
441 | adding other auto-link abilities (such as table support) soon. |
|
|
442 | </p> |
|
|
443 | |
|
|
444 | <p> |
|
|
445 | However, some guides change often and using such "counting" can lead to broken |
|
|
446 | links. In order to cope with this, you can define a name for a |
|
|
447 | <c><chapter></c> or <c><section></c> by using the <c>id</c> |
|
|
448 | attribute, and then point to that attribute, like this: |
|
|
449 | </p> |
|
|
450 | |
|
|
451 | <pre caption="Using the id attribute"> |
|
|
452 | <chapter id="foo"> |
|
|
453 | <title>This is foo!</title> |
|
|
454 | ... |
|
|
455 | <p> |
|
|
456 | More information can be found in the <uri link="#foo">foo chapter</uri> |
|
|
457 | </p> |
|
|
458 | </pre> |
357 | |
459 | |
358 | </body> |
460 | </body> |
359 | </section> |
461 | </section> |
360 | </chapter> |
462 | </chapter> |
|
|
463 | |
|
|
464 | <chapter> |
|
|
465 | <title>Coding Style</title> |
|
|
466 | <section> |
|
|
467 | <title>Introduction</title> |
|
|
468 | <body> |
|
|
469 | |
|
|
470 | <p> |
|
|
471 | Since all Gentoo Documentation is a joint effort and several people will |
|
|
472 | most likely change existing documentation, a coding style is needed. |
|
|
473 | A coding style contains two sections. The first one is regarding |
|
|
474 | internal coding - how the xml-tags are placed. The second one is |
|
|
475 | regarding the content - how not to confuse the reader. |
|
|
476 | </p> |
|
|
477 | |
|
|
478 | <p> |
|
|
479 | Both sections are described next. |
|
|
480 | </p> |
|
|
481 | |
|
|
482 | </body> |
|
|
483 | </section> |
|
|
484 | <section> |
|
|
485 | <title>Internal Coding Style</title> |
|
|
486 | <body> |
|
|
487 | |
|
|
488 | <p> |
|
|
489 | <b>Newlines</b> must be placed immediately after <e>every</e> |
|
|
490 | GuideXML-tag (both opening as closing), except for: |
|
|
491 | <c><version></c>, <c><date></c>, <c><title></c>, |
|
|
492 | <c><th></c>, <c><ti></c>, |
|
|
493 | <c><li></c>, <c><i></c>, <c><e></c>, |
|
|
494 | <c><uri></c>, <c><path></c>, <c><b></c>, |
|
|
495 | <c><comment></c>, <c><mail></c>. |
|
|
496 | </p> |
|
|
497 | |
|
|
498 | <p> |
|
|
499 | <b>Blank lines</b> must be placed immediately after <e>every</e> |
|
|
500 | <c><body></c> (opening tag only) and before <e>every</e> |
|
|
501 | <c><chapter></c>, <c><p></c>, <c><table></c>, |
|
|
502 | <c><author></c> (set), <c><pre></c>, <c><ul></c>, |
|
|
503 | <c><ol></c>, <c><warn></c>, <c><note></c> and |
|
|
504 | <c><impo></c> (opening tags only). |
|
|
505 | </p> |
|
|
506 | |
|
|
507 | <p> |
|
|
508 | <b>Word-wrapping</b> must be applied at 80 characters except inside |
|
|
509 | <c><pre></c>. Only when there is no other choice can be deviated from |
|
|
510 | this rule (for instance when a URL exceeds the maximum amount of characters). |
|
|
511 | The editor must then wrap whenever the first whitespace occurs. |
|
|
512 | </p> |
|
|
513 | |
|
|
514 | <p> |
|
|
515 | <b>Indentation</b> may not be used, except with the XML-constructs of which |
|
|
516 | the parent XML-tags are <c><tr></c> (from <c><table></c>), |
|
|
517 | <c><ul></c>, <c><ol></c> and <c><author></c>. If indentation |
|
|
518 | is used, it <e>must</e> be two spaces for each indentation. That means <e>no</e> |
|
|
519 | tabs and <e>not</e> more spaces. |
|
|
520 | </p> |
|
|
521 | |
|
|
522 | <p> |
|
|
523 | In case word-wrapping happens in <c><ti></c>, <c><th></c> or |
|
|
524 | <c><li></c> constructs, indentation must be used for the content. |
|
|
525 | </p> |
|
|
526 | |
|
|
527 | <p> |
|
|
528 | An example for indentation is: |
|
|
529 | </p> |
|
|
530 | |
|
|
531 | <pre caption="Indentation Example"> |
|
|
532 | <table> |
|
|
533 | <tr> |
|
|
534 | <th>Foo</th> |
|
|
535 | <th>Bar</th> |
|
|
536 | </tr> |
|
|
537 | <tr> |
|
|
538 | <ti>This is an example for indentation.</ti> |
|
|
539 | <ti> |
|
|
540 | In case text cannot be shown within an 80-character wide line, you |
|
|
541 | must use indentation if the parent tag allows it. |
|
|
542 | </ti> |
|
|
543 | </tr> |
|
|
544 | </table> |
|
|
545 | |
|
|
546 | <ul> |
|
|
547 | <li>First option</li> |
|
|
548 | <li>Second option</li> |
|
|
549 | </ul> |
|
|
550 | </pre> |
|
|
551 | |
|
|
552 | <p> |
|
|
553 | <b>Attributes</b> may not have spaces in between the attribute, the |
|
|
554 | "=" mark, and the attribute value. As an example: |
|
|
555 | </p> |
|
|
556 | |
|
|
557 | <pre caption="Attributes"> |
|
|
558 | <comment>Wrong :</comment> <pre caption = "Attributes"> |
|
|
559 | <comment>Correct:</comment> <pre caption="Attributes"> |
|
|
560 | </pre> |
|
|
561 | |
|
|
562 | </body> |
|
|
563 | </section> |
|
|
564 | <section> |
|
|
565 | <title>External Coding Style</title> |
|
|
566 | <body> |
|
|
567 | |
|
|
568 | <p> |
|
|
569 | Inside tables (<c><table></c>) and listings (<c><ul></c> and |
|
|
570 | <c><ol></c>), periods (".") should not be used unless multiple |
|
|
571 | sentences are used. In that case, every sentence should end with a period (or |
|
|
572 | other reading marks). |
|
|
573 | </p> |
|
|
574 | |
|
|
575 | <p> |
|
|
576 | Every sentence, including those inside tables and listings, should start |
|
|
577 | with a capital letter. |
|
|
578 | </p> |
|
|
579 | |
|
|
580 | <pre caption="Periods and capital letters"> |
|
|
581 | <ul> |
|
|
582 | <li>No period</li> |
|
|
583 | <li>With period. Multiple sentences, remember?</li> |
|
|
584 | </ul> |
|
|
585 | </pre> |
|
|
586 | |
|
|
587 | <p> |
|
|
588 | Code Listings should <e>always</e> have a <c>caption</c>. |
|
|
589 | </p> |
|
|
590 | |
|
|
591 | <p> |
|
|
592 | Try to use <c><uri></c> with the <c>link</c> attribute as much as |
|
|
593 | possible. In other words, the <uri link="http://forums.gentoo.org">Gentoo |
|
|
594 | Forums</uri> is preferred over <uri>http://forums.gentoo.org</uri>. |
|
|
595 | </p> |
|
|
596 | |
|
|
597 | <p> |
|
|
598 | When you comment something inside a <c><pre></c> construct, use |
|
|
599 | <c><comment></c> and parentheses or the comment marker for the language |
|
|
600 | that is being used (<c>#</c> for bash scripts and many other things, <c>//</c> |
|
|
601 | for C code, etc.) Also place the comment <e>before</e> the subject of the |
|
|
602 | comment. |
|
|
603 | </p> |
|
|
604 | |
|
|
605 | <pre caption="Comment example"> |
|
|
606 | <comment>(Substitute "john" with your user name)</comment> |
|
|
607 | # <i>id john</i> |
|
|
608 | </pre> |
|
|
609 | |
|
|
610 | </body> |
|
|
611 | </section> |
|
|
612 | </chapter> |
|
|
613 | |
|
|
614 | <chapter> |
|
|
615 | <title>Handbook Format</title> |
|
|
616 | <section> |
|
|
617 | <title>Guide vs Book</title> |
|
|
618 | <body> |
|
|
619 | |
|
|
620 | <p> |
|
|
621 | For high-volume documentation, such as the <uri |
|
|
622 | link="/doc/en/handbook/handbook-x86.xml?part=1">Installation Instructions</uri>, a |
|
|
623 | broader format was needed. We designed a GuideXML-compatible enhancement that |
|
|
624 | allows us to write modular and multi-page documentation. |
|
|
625 | </p> |
|
|
626 | |
|
|
627 | </body> |
|
|
628 | </section> |
|
|
629 | <section> |
|
|
630 | <title>Main File</title> |
|
|
631 | <body> |
|
|
632 | |
|
|
633 | <p> |
|
|
634 | The first change is the need for a "master" document. This document contains no |
|
|
635 | real content, but links to the individual documentation modules. The syntaxis |
|
|
636 | doesn't differ much from GuideXML: |
|
|
637 | </p> |
|
|
638 | |
|
|
639 | <pre caption="Example book usage"> |
|
|
640 | <?xml version='1.0' encoding='UTF-8'?> |
|
|
641 | <!DOCTYPE book SYSTEM "/dtd/book.dtd"> |
|
|
642 | |
|
|
643 | <<i>book</i> link="example.xml"> |
|
|
644 | <title>Example Book Usage</title> |
|
|
645 | |
|
|
646 | <author...> |
|
|
647 | ... |
|
|
648 | </author> |
|
|
649 | |
|
|
650 | <abstract> |
|
|
651 | ... |
|
|
652 | </abstract> |
|
|
653 | |
|
|
654 | <!-- The content of this document is licensed under the CC-BY-SA license --> |
|
|
655 | <!-- See http://creativecommons.org/licenses/by-sa/2.0 --> |
|
|
656 | <license/> |
|
|
657 | |
|
|
658 | <version>...</version> |
|
|
659 | <date>...</date> |
|
|
660 | </pre> |
|
|
661 | |
|
|
662 | <p> |
|
|
663 | So far no real differences (except for the <c><book></c> instead of |
|
|
664 | <c><guide></c> tag). Instead of starting with the individual |
|
|
665 | <c><chapter></c>'s, you define a <c><part></c>, which is the |
|
|
666 | equivalent of a separate part in a book: |
|
|
667 | </p> |
|
|
668 | |
|
|
669 | <pre caption="Defining a part"> |
|
|
670 | <part> |
|
|
671 | <title>Part One</title> |
|
|
672 | <abstract> |
|
|
673 | ... |
|
|
674 | </abstract> |
|
|
675 | |
|
|
676 | <comment>(Defining the several chapters)</comment> |
|
|
677 | </part> |
|
|
678 | </pre> |
|
|
679 | |
|
|
680 | <p> |
|
|
681 | Each part is accompanied by a <c><title></c> and an |
|
|
682 | <c><abstract></c> which gives a small introduction to the part. |
|
|
683 | </p> |
|
|
684 | |
|
|
685 | <p> |
|
|
686 | Inside each part, you define the individual <c><chapter></c>'s. Each |
|
|
687 | chapter <e>must</e> be a separate document. As a result it is no surprise that a |
|
|
688 | special tag (<c><include></c>) is added to allow including the separate |
|
|
689 | document. |
|
|
690 | </p> |
|
|
691 | |
|
|
692 | <pre caption="Defining a chapter"> |
|
|
693 | <chapter> |
|
|
694 | <title>Chapter One</title> |
|
|
695 | <abstract> |
|
|
696 | This is a small explanation on chapter one. |
|
|
697 | </abstract> |
|
|
698 | |
|
|
699 | <include href="path/to/chapter-one.xml"/> |
|
|
700 | |
|
|
701 | </chapter> |
|
|
702 | </pre> |
|
|
703 | |
|
|
704 | </body> |
|
|
705 | </section> |
|
|
706 | <section> |
|
|
707 | <title>Designing the Individual Chapters</title> |
|
|
708 | <body> |
|
|
709 | |
|
|
710 | <p> |
|
|
711 | The content of an individual chapter is structured as follows: |
|
|
712 | </p> |
|
|
713 | |
|
|
714 | <pre caption="Chapter Syntax"> |
|
|
715 | <?xml version='1.0' encoding='UTF-8'?> |
|
|
716 | <!DOCTYPE sections SYSTEM "/dtd/book.dtd"> |
|
|
717 | |
|
|
718 | <!-- The content of this document is licensed under the CC-BY-SA license --> |
|
|
719 | <!-- See http://creativecommons.org/licenses/by-sa/2.0 --> |
|
|
720 | |
|
|
721 | <sections> |
|
|
722 | |
|
|
723 | <version>...</version> |
|
|
724 | <date>...</date> |
|
|
725 | |
|
|
726 | <comment>(Define the several <section> and <subsection>)</comment> |
|
|
727 | |
|
|
728 | </sections> |
|
|
729 | </pre> |
|
|
730 | |
|
|
731 | <p> |
|
|
732 | Inside each chapter you can define <c><section></c>'s (equivalent of |
|
|
733 | <c><chapter></c> in a Guide) and <c><subsection></c>'s (equivalent |
|
|
734 | of <c><section></c> in a Guide). |
|
|
735 | </p> |
|
|
736 | |
|
|
737 | <p> |
|
|
738 | Each individual chapter should have its own date and version elements. The |
|
|
739 | latest date of all chapters and master document will be displayed when a user |
|
|
740 | browses through all parts of the book. |
|
|
741 | </p> |
|
|
742 | |
|
|
743 | </body> |
|
|
744 | </section> |
|
|
745 | </chapter> |
|
|
746 | |
361 | <chapter> |
747 | <chapter> |
362 | <title>Resources</title> |
748 | <title>Resources</title> |
363 | <section> |
749 | <section> |
364 | <title>Start writing</title> |
750 | <title>Start writing</title> |
365 | <body> |
751 | <body> |
|
|
752 | |
|
|
753 | <p> |
366 | <p>Guide has been specially designed to be "lean and mean" so that developers |
754 | Guide has been specially designed to be "lean and mean" so that developers can |
367 | can spend more time writing documentation and less time learning the actual XML |
755 | spend more time writing documentation and less time learning the actual XML |
368 | syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy" |
756 | syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy" |
369 | to start writing quality Gentoo Linux documentation. If you'd like to help (or have any questions about guide), please |
757 | to start writing quality Gentoo Linux documentation. You might be interested |
370 | post a message to <mail link="gentoo-dev@gentoo.org">the gentoo-dev mailing list</mail> |
758 | in our <uri link="/proj/en/gdp/doc/doc-tipsntricks.xml">Documentation |
|
|
759 | Development Tips & Tricks</uri>. If you'd like to help (or have any |
|
|
760 | questions about guide), please post a message to the <mail |
371 | and <mail link="gentoo-doc@gentoo.org">the gentoo-doc mailing list</mail> |
761 | link="gentoo-doc@gentoo.org">gentoo-doc mailing list</mail> stating what you'd |
372 | stating what you'd like to tackle. |
762 | like to tackle. Have fun! |
373 | Have fun!</p> |
763 | </p> |
|
|
764 | |
374 | </body> |
765 | </body> |
375 | </section> |
766 | </section> |
376 | </chapter> |
767 | </chapter> |
377 | </guide> |
768 | </guide> |
378 | |
|
|