1 | <?xml version='1.0' encoding="UTF-8"?> |
1 | <?xml version='1.0' encoding="UTF-8"?> |
2 | <?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?> |
|
|
3 | |
|
|
4 | <!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> |
2 | <!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> |
5 | |
3 | |
6 | <guide link="/doc/en/xml-guide.xml"> |
4 | <guide link="/doc/en/xml-guide.xml"> |
7 | <title>Gentoo Linux Documentation Guide</title> |
5 | <title>Gentoo Linux XML Guide</title> |
8 | <author title="Chief Architect"><mail link="drobbins@gentoo.org">Daniel Robbins</mail></author> |
|
|
9 | |
6 | |
|
|
7 | <author title="Author"> |
|
|
8 | <mail link="drobbins@gentoo.org">Daniel Robbins</mail> |
|
|
9 | </author> |
|
|
10 | <author title="Author"> |
|
|
11 | <mail link="zhen@gentoo.org">John P. Davis</mail> |
|
|
12 | </author> |
|
|
13 | <author title="Editor"> |
|
|
14 | <mail link="peesh@gentoo.org">Jorge Paulo</mail> |
|
|
15 | </author> |
|
|
16 | |
|
|
17 | <license/> |
|
|
18 | <abstract> |
10 | <abstract>This guide shows you how to compose web documentation using the new lightweight Gentoo guide |
19 | This guide shows you how to compose web documentation using the new lightweight |
11 | XML syntax. This syntax is the official format for Gentoo Linux documentation, and this document |
20 | Gentoo GuideXML syntax. This syntax is the official format for Gentoo Linux |
12 | itself was created using guide XML. This guide assumes a basic working knowledge of XML and HTML. |
21 | documentation, and this document itself was created using GuideXML. This guide |
|
|
22 | assumes a basic working knowledge of XML and HTML. |
13 | </abstract> |
23 | </abstract> |
14 | |
24 | |
15 | <version>1.0</version> |
25 | <version>2.0</version> |
16 | <date>07 Mar 2002</date> |
26 | <date>October 9, 2003</date> |
17 | |
27 | |
18 | <chapter> |
28 | <chapter> |
19 | <title>Guide basics</title> |
29 | <title>Guide basics</title> |
20 | |
30 | |
21 | <section> |
31 | <section> |
22 | <title>Guide XML design goals</title> |
32 | <title>Guide XML design goals</title> |
23 | <body> |
33 | <body> |
24 | |
34 | |
|
|
35 | <p> |
25 | <p> The guide XML syntax is lightweight yet expressive, so that it is easy to |
36 | The guide XML syntax is lightweight yet expressive, so that it is easy to |
26 | learn yet also provides all the features we need for the creation of web |
37 | learn yet also provides all the features we need for the creation of web |
27 | documentation. The number of tags is kept to a minimum -- just those we need. |
38 | documentation. The number of tags is kept to a minimum -- just those we need. |
28 | This makes it easy to transform guide into other formats, such as DocBook |
39 | This makes it easy to transform guide into other formats, such as DocBook |
29 | XML/SGML or web-ready HTML. </p> |
40 | XML/SGML or web-ready HTML. |
|
|
41 | </p> |
30 | |
42 | |
|
|
43 | <p> |
31 | <p>The goal is to make it easy to <e>create</e> and <e>transform</e> guide XML |
44 | The goal is to make it easy to <e>create</e> and <e>transform</e> guide XML |
32 | documents.</p> |
45 | documents. |
|
|
46 | </p> |
33 | |
47 | |
34 | </body> |
48 | </body> |
35 | </section> |
49 | </section> |
36 | |
50 | |
37 | <section> |
51 | <section> |
38 | <title>How to transform guide XML into HTML</title> |
52 | <title>How to transform guide XML into HTML</title> |
39 | <body> |
53 | <body> |
40 | |
54 | |
|
|
55 | <p> |
41 | <p> Before we take a look at the guide syntax itself, it's helpful to know how |
56 | Before we take a look at the guide syntax itself, it's helpful to know how |
42 | guide XML is transformed into web-ready HTML. To do this, we use a special |
57 | guide XML is transformed into web-ready HTML. To do this, we use a special |
43 | file called <path>guide-main.xsl</path>, along with a command-line XSLT processing |
58 | file called <path>guide.xsl</path>, along with a command-line XSLT processing |
44 | tool (also called an "engine"). The <path>guide-main.xsl</path> file describes |
59 | tool (also called an "engine"). The <path>guide.xsl</path> file describes |
45 | exactly how to transform the contents of the source guide XML document to |
60 | exactly how to transform the contents of the source guide XML document to |
46 | create the target HTML file. Two popular XSLT processors are <c>sabcmd</c> |
61 | create the target HTML file. The processing tool that Gentoo Linux uses |
47 | (included in the <path>app-text/sablotron</path> package) and <c>xsltproc</c> |
62 | is called <c>xsltproc</c>, which is found in the <i>libxslt</i> package. |
48 | (found in the <path>dev-libs/libxslt</path> package). From experience, we've |
|
|
49 | found that <c>xsltproc</c> is the higher-quality and more feature-rich XSLT |
|
|
50 | processor. </p> |
|
|
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. Here's how it works. First, |
|
|
54 | download the latest snapshot of our Web site from |
|
|
55 | <uri>http://www.gentoo.org/projects/xml.html</uri>, found in the <uri |
|
|
56 | link="http://www.gentoo.org/projects/guide-xml-latest.tar.gz">xml-guide-latest.tar.gz</uri> |
|
|
57 | file. Extract the tarball. Inside it, you'll find a <path>gentoo-src</path> |
|
|
58 | directory, as well as a <path>gentoo-src/xml</path> directory, etc. Now, find |
|
|
59 | <path>gentoo-src/xml/install.xml</path>. (The new user installation guide). |
|
|
60 | This will be our source XML guide document. The easiest way to perform the |
|
|
61 | transformation is to change directories to the location of the |
|
|
62 | <path>guide-main.xsl</path> file. Then, execute <c>xsltproc</c> as follows: |
|
|
63 | </p> |
63 | </p> |
64 | |
64 | |
|
|
65 | <pre caption="Installing libxslt"> |
|
|
66 | # <c>emerge libxslt</c> |
65 | <pre> |
67 | </pre> |
66 | # <i>cd gentoo-web/xsl</i> |
68 | |
67 | # <i>xsltproc guide-main.xsl ../xml/install.xml > /tmp/install.html</i> |
69 | <p> |
|
|
70 | Now that we have the way, we need the means, so to speak. In other words, |
|
|
71 | we need some Gentoo XML documents to transform. Gentoo has two types of tarballs |
|
|
72 | that are available for download: |
68 | </pre> |
73 | </p> |
69 | |
74 | |
|
|
75 | <p> |
|
|
76 | <b>The first type contains the entire up-to-date Gentoo Linux website</b>. |
|
|
77 | Included are our XSL templates, so if you are planning to transform any |
|
|
78 | documentation, you will need this tarball. The tarball can be found <uri |
|
|
79 | link="http://www.gentoo.org/dyn/arch/xml-guide-latest.tar.gz">here</uri>. |
|
|
80 | </p> |
|
|
81 | |
|
|
82 | <p> |
|
|
83 | <b>The second type contains daily snapshots our XML documentation source</b> |
|
|
84 | in every language that we offer. Please note that it is impossible to transform |
|
|
85 | documentation with this tarball, so please download the web tarball if you want |
|
|
86 | to fully develop your own documentation. These tarballs are especially useful |
|
|
87 | for translators. These tarballs can be found <uri |
|
|
88 | link="http://www.gentoo.org/dyn/doc-snapshots">here</uri>. |
|
|
89 | </p> |
|
|
90 | |
|
|
91 | <p> |
|
|
92 | After the web tarball is downloaded and extracted, go to the directory where |
|
|
93 | the tarball was extracted, and enter the <path>htdocs</path> directory. Browse |
|
|
94 | around and get comfortable with the layout, but note the <path>xsl</path> and |
|
|
95 | <path>doc</path> directories. As you might have guessed, the XSL stylesheets are |
|
|
96 | in <path>xsl</path>, and our documentation is in <path>doc</path>. For testing |
|
|
97 | purposes, we will be using the Gentoo Linux CD Installation Guide, located at |
|
|
98 | <path>doc/en/gentoo-x86-install.xml</path>. Now that the locations of the XSL |
|
|
99 | and XML file are known, we can do some transforming with <c>xsltproc</c>. |
|
|
100 | </p> |
|
|
101 | |
|
|
102 | <pre caption="Transforming gentoo-x86-install.xml"> |
|
|
103 | # <c>xsltproc xsl/guide.xsl doc/en/gentoo-x86-install.xml > /tmp/install.html</c> |
|
|
104 | </pre> |
|
|
105 | |
|
|
106 | <p> |
70 | <p> If all went well, you should have a web-ready version of |
107 | If all went well, you should have a web-ready version of |
71 | <path>install.xml</path> at <path>/tmp/install.html</path>. For this document |
108 | <path>gentoo-x86-install.xml</path> at <path>/tmp/install.html</path>. For |
72 | to display properly in a web browser, you may have to copy some files from |
109 | this document to display properly in a web browser, you may have to copy some |
73 | <path>gentoo-web</path> to <path>/tmp</path>, such |
110 | files from <path>htdocs</path> to <path>/tmp</path>, such as |
74 | as <path>css/main-new.css</path> and (to be safe) the entire <path>images</path> |
111 | <path>css/main.css</path> and (to be safe) the entire <path>images</path> |
75 | directory. |
112 | directory. |
76 | </p> |
113 | </p> |
77 | |
114 | |
78 | </body> |
115 | </body> |
79 | </section> |
116 | </section> |
80 | </chapter> |
117 | </chapter> |
|
|
118 | |
81 | <chapter> |
119 | <chapter> |
82 | <title>Guide XML</title> |
120 | <title>Guide XML</title> |
83 | <section> |
121 | <section> |
84 | <title>Basic structure</title> |
122 | <title>Basic structure</title> |
85 | <body> |
123 | <body> |
86 | |
124 | |
|
|
125 | <p> |
87 | <p>Now that you know how to transform guide XML, you're ready to start learning |
126 | Now that you know how to transform guide XML, you're ready to start learning |
88 | the guide XML syntax. We'll start with the the initial tags used in a guide |
127 | the GuideXML syntax. We'll start with the the initial tags used in a guide |
89 | XML document: </p> |
128 | XML document: |
|
|
129 | </p> |
90 | |
130 | |
91 | <pre caption="The initial part of a guide XML document"> |
131 | <pre caption="The initial part of a guide XML document"> |
92 | <?xml version='1.0'?> |
132 | <?xml version='1.0' encoding="UTF-8"?> |
93 | <guide> |
133 | <guide link="relative_link_to_your_guide"> |
94 | <title><i>Gentoo Linux Documentation Guide</i></title> |
134 | <title><i>Gentoo Linux Documentation Guide</i></title> |
95 | <author title="<i>Chief Architect</i>"><mail link="<i>drobbins@gentoo.org</i>"> |
135 | <author title="<i>Chief Architect</i>"> |
96 | <i>Daniel Robbins</i></mail> |
136 | <mail link="<i>drobbins@gentoo.org</i>"><i>Daniel Robbins</i></mail> |
97 | </author> |
137 | </author> |
98 | <author title="<i>Editor</i>"><mail link="<i>thomasfl@gentoo.org</i>"> |
138 | <author title="<i>Editor</i>"> |
99 | <i>Thomas Flavel</i></mail> |
139 | <mail link="<i>thomasfl@gentoo.org</i>"><i>Thomas Flavel</i></mail> |
100 | </author> |
140 | </author> |
101 | |
141 | |
|
|
142 | <abstract> |
102 | <abstract><i>This guide shows you how to compose web documentation using |
143 | <i>This guide shows you how to compose web documentation using |
103 | our new lightweight Gentoo guide XML syntax. This syntax is the official |
144 | our new lightweight Gentoo GuideXML syntax. This syntax is the official |
104 | format for Gentoo Linux web documentation, and this document itself was created |
145 | format for Gentoo Linux web documentation, and this document itself was created |
105 | using guide XML.</i> </abstract> |
146 | using GuideXML.</i> |
|
|
147 | </abstract> |
|
|
148 | |
|
|
149 | <license/> |
106 | |
150 | |
107 | <version><i>1.0</i></version> |
151 | <version><i>1.0</i></version> |
108 | <date><i>29 Mar 2001</i></date> |
152 | <date><i>29 Mar 2001</i></date> |
109 | </pre> |
153 | </pre> |
110 | |
154 | |
|
|
155 | <p> |
111 | <p>On the first, line, we see the requisite tag that identifies this as an XML |
156 | On the first, line, we see the requisite tag that identifies this as an XML |
112 | document. Following it, there's a <c><guide></c> tag -- the entire |
157 | document. Following it, there's a <c><guide></c> tag -- the entire |
113 | guide document is enclosed within a <c><guide> </guide></c> pair. |
158 | guide document is enclosed within a <c><guide> </guide></c> pair. |
114 | Next, there's a <c><title></c> tag, used to set the title for the entire |
159 | Next, there's a <c><title></c> tag, used to set the title for the entire |
115 | guide document. </p> |
160 | guide document. |
|
|
161 | </p> |
116 | |
162 | |
|
|
163 | <p> |
117 | <p>Then, we come to the <c><author></c> tags, which contain information |
164 | Then, we come to the <c><author></c> tags, which contain information |
118 | about the various authors of the document. Each <c><author></c> tag |
165 | about the various authors of the document. Each <c><author></c> tag |
119 | allows for an optional <c>title=</c> element, used to specify the author's |
166 | allows for an optional <c>title=</c> element, used to specify the author's |
120 | relationship to the document (author, co-author, editor, etc.). In this |
167 | relationship to the document (author, co-author, editor, etc.). In this |
121 | particular example, the authors' names are enclosed in another tag -- a |
168 | particular example, the authors' names are enclosed in another tag -- a |
122 | <c><mail></c> tag, used to specify an email address for this particular |
169 | <c><mail></c> tag, used to specify an email address for this particular |
123 | person. The <c><mail></c> tag is optional and can be omitted, and no |
170 | person. The <c><mail></c> tag is optional and can be omitted, and no |
124 | more than one <c><author></c> element is required per guide document. |
171 | more than one <c><author></c> element is required per guide document. |
125 | </p> |
172 | </p> |
126 | |
173 | |
|
|
174 | <p> |
127 | <p>Next, we come to the <c><abstract></c>, <c><version></c> and |
175 | Next, we come to the <c><abstract></c>, <c><version></c> and |
128 | <c><date></c> tags, used to specify a summary of the document, the |
176 | <c><date></c> tags, used to specify a summary of the document, the |
129 | current version number, and the current version date (in DD MMM YYYY format) |
177 | current version number, and the current version date (in DD MMM YYYY format) |
130 | respectively. This rounds out the tags that should appear at the beginning of |
178 | respectively. This rounds out the tags that should appear at the beginning of |
131 | a guide document. Besides the <c><title></c> and <c><mail></c> |
179 | a guide document. Besides the <c><title></c> and <c><mail></c> |
132 | tags, these tags shouldn't appear anywhere else except immediately inside the |
180 | tags, these tags shouldn't appear anywhere else except immediately inside the |
133 | <c><guide></c> tag, and for consistency it's recommended (but not |
181 | <c><guide></c> tag, and for consistency it's recommended (but not |
134 | required) that these tags appear before the content of the document. </p> |
182 | required) that these tags appear before the content of the document. |
|
|
183 | </p> |
|
|
184 | |
|
|
185 | <p> |
|
|
186 | Finally we have the <c><license/></c> tag, used to publish the |
|
|
187 | document under the <uri link="http://creativecommons.org/licenses/by-sa/1.0/">Creative |
|
|
188 | Commons - Attribution / Share Alike</uri> license as required by the <uri |
|
|
189 | link="/doc/en/doc-policy.xml">Documentation Policy</uri>. |
|
|
190 | </p> |
135 | |
191 | |
136 | </body> |
192 | </body> |
137 | </section> |
193 | </section> |
138 | |
194 | |
139 | <section> |
195 | <section> |
140 | <title>Chapters and sections</title> |
196 | <title>Chapters and sections</title> |
141 | <body> |
197 | <body> |
|
|
198 | |
|
|
199 | <p> |
142 | <p>Once the initial tags have been specified, you're ready to start adding |
200 | Once the initial tags have been specified, you're ready to start adding |
143 | the structural elements of the document. Guide documents are divided into |
201 | the structural elements of the document. Guide documents are divided into |
144 | chapters, and each chapter can hold one or more sections. Every chapter |
202 | chapters, and each chapter can hold one or more sections. Every chapter |
145 | and section has a title. Here's an example chapter with a single section, |
203 | and section has a title. Here's an example chapter with a single section, |
146 | consisting of a paragraph. If you append this XML to the XML in the <uri link="#doc_pre2">previous |
204 | consisting of a paragraph. If you append this XML to the XML in the <uri link="#doc_chap2_pre1">previous |
147 | excerpt</uri> and append a <c></guide></c> to the end of the file, you'll have a valid |
205 | excerpt</uri> and append a <c></guide></c> to the end of the file, you'll have a valid |
148 | (if minimal) guide document: |
206 | (if minimal) guide document: |
149 | </p> |
207 | </p> |
150 | |
208 | |
151 | <pre> |
209 | <pre> |
152 | <chapter> |
210 | <chapter> |
153 | <title><i>This is my chapter</i></title> |
211 | <title><i>This is my chapter</i></title> |
154 | <section> |
212 | <section> |
155 | <title><i>This is section one of my chapter</i></title> |
213 | <title><i>This is section one of my chapter</i></title> |
156 | <body> |
214 | <body> |
|
|
215 | |
|
|
216 | <p> |
157 | <p><i>This is the actual text content of my section.</i></p> |
217 | <i>This is the actual text content of my section.</i> |
|
|
218 | </p> |
|
|
219 | |
158 | </body> |
220 | </body> |
159 | </section> |
221 | </section> |
160 | </chapter> |
222 | </chapter> |
161 | </pre> |
223 | </pre> |
162 | |
224 | |
|
|
225 | <p> |
163 | <p>Above, I set the chapter title by adding a child <c><title></c> |
226 | Above, I set the chapter title by adding a child <c><title></c> |
164 | element to the <c><chapter></c> element. Then, I created a section by |
227 | element to the <c><chapter></c> element. Then, I created a section by |
165 | adding a <c><section></c> element. If you look inside the |
228 | adding a <c><section></c> element. If you look inside the |
166 | <c><section></c> element, you'll see that it has two child elements -- a |
229 | <c><section></c> element, you'll see that it has two child elements -- a |
167 | <c><title></c> and a <c><body></c>. While the <c><title></c> |
230 | <c><title></c> and a <c><body></c>. While the <c><title></c> |
168 | is nothing new, the <c><body></c> is -- it contains the actual text |
231 | is nothing new, the <c><body></c> is -- it contains the actual text |
169 | content of this particular section. We'll look at the tags that are allowed |
232 | content of this particular section. We'll look at the tags that are allowed |
170 | inside a <c><body></c> element in a bit. </p> |
233 | inside a <c><body></c> element in a bit. |
|
|
234 | </p> |
171 | |
235 | |
|
|
236 | <note> |
172 | <note>A <c><guide></c> element can contain multiple |
237 | A <c><guide></c> element can contain multiple <c><chapter></c> |
173 | <c><chapter></c> elements, and a <c><chapter></c> can contain |
238 | elements, and a <c><chapter></c> can contain multiple |
174 | multiple <c><section></c> elements. However, a <c><section></c> |
239 | <c><section></c> elements. However, a <c><section></c> |
175 | element can only contain one <c><body></c> element. </note> |
240 | element can only contain one <c><body></c> element. |
|
|
241 | </note> |
176 | |
242 | |
177 | </body> |
243 | </body> |
178 | </section> |
244 | </section> |
179 | |
245 | |
180 | <section> |
246 | <section> |
181 | <title>An example <body></title> |
247 | <title>An example <body></title> |
182 | <body> |
248 | <body> |
|
|
249 | |
183 | <p> |
250 | <p> |
184 | Now, it's time to learn how to mark up actual content. Here's the XML code for an example <c><body></c> element: |
251 | Now, it's time to learn how to mark up actual content. Here's the XML code for an example <c><body></c> element: |
185 | </p> |
252 | </p> |
|
|
253 | |
186 | <pre> |
254 | <pre> |
187 | <p> |
255 | <p> |
188 | This is a paragraph. <path>/etc/passwd</path> is a file. |
256 | This is a paragraph. <path>/etc/passwd</path> is a file. |
189 | <uri>http://www.gentoo.org</uri> is my favorite website. |
257 | <uri>http://www.gentoo.org</uri> is my favorite website. |
190 | Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now. |
258 | Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now. |
… | |
… | |
197 | Make HTML/XML easier to read by using selective emphasis: |
265 | Make HTML/XML easier to read by using selective emphasis: |
198 | <foo><i>bar</i></foo> |
266 | <foo><i>bar</i></foo> |
199 | |
267 | |
200 | <codenote>This is how to insert an inline note into the code block</codenote> |
268 | <codenote>This is how to insert an inline note into the code block</codenote> |
201 | </pre> |
269 | </pre> |
202 | <note>This is a note.</note> |
270 | |
203 | <warn>This is a warning.</warn> |
271 | <note> |
204 | <impo>This is important.</impo> |
272 | This is a note. |
|
|
273 | </note> |
|
|
274 | |
|
|
275 | <warn> |
|
|
276 | This is a warning. |
|
|
277 | </warn> |
|
|
278 | |
|
|
279 | <impo> |
|
|
280 | This is important. |
|
|
281 | </impo> |
205 | </pre> |
282 | </pre> |
|
|
283 | |
|
|
284 | <p> |
206 | <p>Now, here's how this <c><body></c> element is rendered:</p> |
285 | Now, here's how this <c><body></c> element is rendered: |
|
|
286 | </p> |
207 | |
287 | |
208 | <p> |
288 | <p> |
209 | This is a paragraph. <path>/etc/passwd</path> is a file. |
289 | This is a paragraph. <path>/etc/passwd</path> is a file. |
210 | <uri>http://www.gentoo.org</uri> is my favorite website. |
290 | <uri>http://www.gentoo.org</uri> is my favorite website. |
211 | Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now. |
291 | Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now. |
… | |
… | |
218 | Make HTML/XML easier to read by using selective emphasis: |
298 | Make HTML/XML easier to read by using selective emphasis: |
219 | <foo><i>bar</i></foo> |
299 | <foo><i>bar</i></foo> |
220 | |
300 | |
221 | <codenote>This is how to insert an inline note into the code block</codenote> |
301 | <codenote>This is how to insert an inline note into the code block</codenote> |
222 | </pre> |
302 | </pre> |
223 | <note>This is a note.</note> |
303 | |
224 | <warn>This is a warning.</warn> |
304 | <note> |
225 | <impo>This is important.</impo> |
305 | This is a note. |
|
|
306 | </note> |
|
|
307 | |
|
|
308 | <warn> |
|
|
309 | This is a warning. |
|
|
310 | </warn> |
|
|
311 | |
|
|
312 | <impo> |
|
|
313 | This is important. |
|
|
314 | </impo> |
|
|
315 | |
226 | </body> |
316 | </body> |
227 | </section> |
317 | </section> |
228 | |
318 | |
229 | <section> |
319 | <section> |
230 | <title>The <body> tags</title> |
320 | <title>The <body> tags</title> |
231 | <body> |
321 | <body> |
232 | |
322 | |
|
|
323 | <p> |
233 | <p> We introduced a lot of new tags in the previous section -- here's what you |
324 | We introduced a lot of new tags in the previous section -- here's what you |
234 | need to know. The <c><p></c> (paragraph), <c><pre></c> (code |
325 | need to know. The <c><p></c> (paragraph), <c><pre></c> (code |
235 | block), <c><note></c>, <c><warn></c> (warning) and |
326 | block), <c><note></c>, <c><warn></c> (warning) and |
236 | <c><impo></c> (important) tags all can contain one or more lines of text. |
327 | <c><impo></c> (important) tags all can contain one or more lines of text. |
237 | Besides the <c><table></c> element (which we'll cover in just a bit), |
328 | Besides the <c><table></c> element (which we'll cover in just a bit), |
238 | these are the only tags that should appear immediately inside a |
329 | these are the only tags that should appear immediately inside a |
239 | <c><body></c> element. Another thing -- these tags <e>should not</e> be |
330 | <c><body></c> element. Another thing -- these tags <e>should not</e> be |
240 | stacked -- in other words, don't put a <c><note></c> element inside a |
331 | stacked -- in other words, don't put a <c><note></c> element inside a |
241 | <c><p></c> element. As you might guess, the <c><pre></c> element |
332 | <c><p></c> element. As you might guess, the <c><pre></c> element |
242 | preserves its whitespace exactly, making it well-suited for code excerpts.</p> |
333 | preserves its whitespace exactly, making it well-suited for code excerpts. |
|
|
334 | You can also name the <c><pre></c> tag: |
|
|
335 | </p> |
|
|
336 | |
|
|
337 | <pre caption = "Named <pre>"> |
|
|
338 | <pre caption = "Output of uptime"> |
|
|
339 | # <i>uptime</i> |
|
|
340 | 16:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25 |
|
|
341 | </pre> |
|
|
342 | </pre> |
243 | |
343 | |
244 | </body> |
344 | </body> |
245 | </section> |
345 | </section> |
246 | <section> |
346 | <section> |
247 | <title><path>, <c> and <e></title> |
347 | <title><path>, <c> and <e></title> |
248 | <body> |
348 | <body> |
249 | |
349 | |
|
|
350 | <p> |
250 | <p>The <c><path></c>, <c><c></c> and <c><e></c> elements can |
351 | The <c><path></c>, <c><c></c> and <c><e></c> elements can |
251 | be used inside any child <c><body></c> tag, except for |
352 | be used inside any child <c><body></c> tag, except for |
252 | <c><pre></c>. </p> |
353 | <c><pre></c>. |
|
|
354 | </p> |
253 | |
355 | |
|
|
356 | <p> |
254 | <p>The <c><path></c> element is used to mark text that refers to an |
357 | The <c><path></c> element is used to mark text that refers to an |
255 | <e>on-disk file</e> -- either an <e>absolute or relative path</e>, or a <e>simple filename</e>. |
358 | <e>on-disk file</e> -- either an <e>absolute or relative path</e>, or a |
256 | This element is generally rendered with a monospaced font to offset it from the |
359 | <e>simple filename</e>. This element is generally rendered with a monospaced |
257 | standard paragraph type. </p> |
360 | font to offset it from the standard paragraph type. |
|
|
361 | </p> |
258 | |
362 | |
|
|
363 | <p> |
259 | <p>The <c><c></c> element is used to mark up a <e>command</e> or <e>user |
364 | The <c><c></c> element is used to mark up a <e>command</e> or <e>user |
260 | input</e>. Think of <c><c></c> as a way to alert the reader to something |
365 | input</e>. Think of <c><c></c> as a way to alert the reader to something |
261 | that they can type in that will perform some kind of action. For example, all |
366 | that they can type in that will perform some kind of action. For example, all |
262 | the XML tags displayed in this document are enclosed in a <c><c></c> |
367 | the XML tags displayed in this document are enclosed in a <c><c></c> |
263 | element because they represent something that the user could type in that is |
368 | element because they represent something that the user could type in that is |
264 | not a path. By using <c><c></c> elements, you'll help your readers |
369 | not a path. By using <c><c></c> elements, you'll help your readers |
265 | quickly identify commands that they need to type in. Also, because |
370 | quickly identify commands that they need to type in. Also, because |
266 | <c><c></c> elements are already offset from regular text, <e>it is rarely |
371 | <c><c></c> elements are already offset from regular text, <e>it is rarely |
267 | necessary to surround user input with double-quotes</e>. For example, don't |
372 | necessary to surround user input with double-quotes</e>. For example, don't |
268 | refer to a "<c><c></c>" element like I did in this sentence. Avoiding |
373 | refer to a "<c><c></c>" element like I did in this sentence. Avoiding |
269 | the use of unnecessary double-quotes makes a document more readable -- and adorable!</p> |
374 | the use of unnecessary double-quotes makes a document more readable -- and |
|
|
375 | adorable! |
|
|
376 | </p> |
270 | |
377 | |
|
|
378 | <p> |
271 | <p><c><e></c> is used to apply emphasis to a word or phrase; for example: |
379 | <c><e></c> is used to apply emphasis to a word or phrase; for example: |
272 | I <e>really</e> should use semicolons more often. As you can see, this text is |
380 | I <e>really</e> should use semicolons more often. As you can see, this text is |
273 | offset from the regular paragraph type for emphasis. This helps to give your |
381 | offset from the regular paragraph type for emphasis. This helps to give your |
274 | prose more <e>punch</e>!</p> |
382 | prose more <e>punch</e>! |
|
|
383 | </p> |
275 | |
384 | |
276 | </body> |
385 | </body> |
277 | </section> |
386 | </section> |
278 | |
387 | |
279 | <section> |
388 | <section> |
280 | <title><mail> and <uri></title> |
389 | <title><mail> and <uri></title> |
281 | <body> |
390 | <body> |
282 | |
391 | |
|
|
392 | <p> |
283 | <p>We've taken a look at the <c><mail></c> tag earlier; it's used to link some text |
393 | We've taken a look at the <c><mail></c> tag earlier; it's used to link |
284 | with a particular email address, and takes the form <c><mail link="foo@bar.com">Mr. Foo Bar</mail></c>.</p> |
394 | some text with a particular email address, and takes the form <c><mail |
|
|
395 | link="foo@bar.com">Mr. Foo Bar</mail></c>. |
|
|
396 | </p> |
285 | |
397 | |
|
|
398 | <p> |
286 | <p>The <c><uri></c> tag is used to point to files/locations on the |
399 | The <c><uri></c> tag is used to point to files/locations on the |
287 | Internet. It has two forms -- the first can be used when you want to have the |
400 | Internet. It has two forms -- the first can be used when you want to have the |
288 | actual URI displayed in the body text, such as this link to |
401 | actual URI displayed in the body text, such as this link to |
289 | <uri>http://www.gentoo.org</uri>. To create this link, I typed |
402 | <uri>http://www.gentoo.org</uri>. To create this link, I typed |
290 | <c><uri>http://www.gentoo.org</uri></c>. The alternate form is |
403 | <c><uri>http://www.gentoo.org</uri></c>. The alternate form is |
291 | when you want to associate a URI with some other text -- for example, <uri |
404 | when you want to associate a URI with some other text -- for example, <uri |
292 | link="http://www.gentoo.org">the Gentoo Linux website</uri>. To create <e>this</e> |
405 | link="http://www.gentoo.org">the Gentoo Linux website</uri>. To create |
293 | link, I typed <c><uri link="http://www.gentoo.org">the Gentoo Linux website</uri></c>. |
406 | <e>this</e> link, I typed <c><uri link="http://www.gentoo.org">the |
|
|
407 | Gentoo Linux website</uri></c>. |
294 | </p> |
408 | </p> |
295 | |
409 | |
296 | </body> |
410 | </body> |
297 | </section> |
411 | </section> |
298 | |
412 | |
299 | <section> |
413 | <section> |
300 | <title>Figures</title> |
414 | <title>Figures</title> |
301 | |
415 | |
302 | <body> |
416 | <body> |
303 | |
417 | |
|
|
418 | <p> |
304 | <p>Here's how to insert a figure into a document -- <c><figure |
419 | Here's how to insert a figure into a document -- <c><figure |
305 | link="mygfx.png" short="my picture" caption="my favorite picture of all |
420 | link="mygfx.png" short="my picture" caption="my favorite picture of all |
306 | time"/></c>. The <c>link=</c> attribute points to the actual graphic image, |
421 | time"/></c>. The <c>link=</c> attribute points to the actual graphic image, |
307 | the <c>short=</c> attribute specifies a short description (currently used for |
422 | the <c>short=</c> attribute specifies a short description (currently used for |
308 | the image's HTML <c>alt=</c> attribute), and a caption. Not too difficult |
423 | the image's HTML <c>alt=</c> attribute), and a caption. Not too difficult |
309 | :) We also support the standard HTML-style <img src="foo.gif"/> tag |
424 | :) We also support the standard HTML-style <img src="foo.gif"/> tag |
310 | for adding images without captions, borders, etc.</p> |
425 | for adding images without captions, borders, etc. |
|
|
426 | </p> |
311 | |
427 | |
312 | </body> |
428 | </body> |
313 | </section> |
429 | </section> |
314 | <section> |
430 | <section> |
315 | <title>Tables and lists</title> |
431 | <title>Tables and lists</title> |
316 | <body> |
432 | <body> |
317 | |
433 | |
|
|
434 | <p> |
318 | <p>Guide supports a simplified table syntax similar to that of HTML. To start |
435 | Guide supports a simplified table syntax similar to that of HTML. To start |
319 | a table, use a <c><table></c> tag. Start a row with a <c><tr></c> |
436 | a table, use a <c><table></c> tag. Start a row with a <c><tr></c> |
320 | tag. However, for inserting actual table data, we <e>don't</e> support the |
437 | tag. However, for inserting actual table data, we <e>don't</e> support the |
321 | HTML <td> tag; instead, use the <c><th></c> if you are inserting a |
438 | HTML <td> tag; instead, use the <c><th></c> if you are inserting a |
322 | header, and <c><ti></c> if you are inserting a normal informational |
439 | header, and <c><ti></c> if you are inserting a normal informational |
323 | block. You can use a <c><th></c> anywhere you can use a <c><ti></c> -- |
440 | block. You can use a <c><th></c> anywhere you can use a <c><ti></c> |
324 | there's no requirement that <c><th></c> elements appear only in the |
441 | -- there's no requirement that <c><th></c> elements appear only in the |
325 | first row. Currently, these tags don't support any attributes, but some will |
442 | first row. Currently, these tags don't support any attributes, but some will |
326 | be added (such as a <c>caption=</c> attribute for <c><table></c>) soon. |
443 | be added (such as a <c>caption=</c> attribute for <c><table></c>) soon. |
327 | </p> |
444 | </p> |
328 | |
445 | |
|
|
446 | <p> |
329 | <p> To create ordered or unordered lists, simply use the HTML-style |
447 | To create ordered or unordered lists, simply use the HTML-style |
330 | <c><ol></c>, <c><ul></c> and <c><li></c> tags. List tags |
448 | <c><ol></c>, <c><ul></c> and <c><li></c> tags. List tags |
331 | should only appear inside a <c><p></c>, <c><ti></c>, |
449 | should only appear inside a <c><p></c>, <c><ti></c>, |
332 | <c><note></c>, <c><warn></c> or <c><impo></c> tag. </p> |
450 | <c><note></c>, <c><warn></c> or <c><impo></c> tag. |
|
|
451 | </p> |
333 | |
452 | |
334 | </body> |
453 | </body> |
335 | </section> |
454 | </section> |
336 | |
455 | |
337 | <section> |
456 | <section> |
338 | <title>Intra-document references</title> |
457 | <title>Intra-document references</title> |
339 | <body> |
458 | <body> |
340 | |
459 | |
|
|
460 | <p> |
341 | <p>Guide makes it really easy to reference other parts of the document using |
461 | Guide makes it really easy to reference other parts of the document using |
342 | hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter |
462 | hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter |
343 | One</uri> by typing <c><uri link="#doc_chap1">Chapter |
463 | One</uri> by typing <c><uri link="#doc_chap1">Chapter |
344 | One</uri></c>. To point to <uri link="#doc_chap1_sect2">section two of |
464 | One</uri></c>. To point to <uri link="#doc_chap1_sect2">section two of |
345 | Chapter One</uri>, type <c><uri link="#doc_chap1_sect2">section two of |
465 | Chapter One</uri>, type <c><uri link="#doc_chap1_sect2">section two of |
346 | Chapter One</uri></c>. To refer to figure 3 in chapter 1, type <c><uri |
466 | Chapter One</uri></c>. To refer to figure 3 in chapter 1, type <c><uri |
347 | 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>, |
467 | link="doc_chap1_fig3">figure 1.3</uri></c>. Or, to refer to <uri |
|
|
468 | link="#doc_chap2_pre2">code listing 2 in chapter 2</uri>, type <c><uri |
348 | type <c><uri link="doc_chap2_pre2">code listing 2.2</uri></c>. We'll be |
469 | link="doc_chap2_pre2">code listing 2.2</uri></c>. We'll be |
349 | adding other auto-link abilities (such as table support) soon.</p> |
470 | adding other auto-link abilities (such as table support) soon. |
|
|
471 | </p> |
350 | |
472 | |
351 | </body> |
473 | </body> |
352 | </section> |
474 | </section> |
353 | </chapter> |
475 | </chapter> |
|
|
476 | |
354 | <chapter> |
477 | <chapter> |
355 | <title>Resources</title> |
478 | <title>Resources</title> |
356 | <section> |
479 | <section> |
357 | <title>Start writing</title> |
480 | <title>Start writing</title> |
358 | <body> |
481 | <body> |
|
|
482 | |
|
|
483 | <p> |
359 | <p>Guide has been specially designed to be "lean and mean" so that developers |
484 | Guide has been specially designed to be "lean and mean" so that developers |
360 | can spend more time writing documentation and less time learning the actual XML |
485 | can spend more time writing documentation and less time learning the actual XML |
361 | syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy" |
486 | syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy" |
362 | to start writing quality Gentoo Linux documentation. If you'd like to help (or have any questions about guide), please |
487 | to start writing quality Gentoo Linux documentation. If you'd like to help (or |
363 | post a message to <mail link="gentoo-dev@gentoo.org">the gentoo-dev mailing list</mail> |
488 | have any questions about guide), please post a message to the <mail |
364 | stating what you'd like to tackle. |
489 | link="gentoo-doc@gentoo.org">gentoo-doc mailing list</mail> stating what you'd |
365 | Have fun!</p> |
490 | like to tackle. Have fun! |
|
|
491 | </p> |
|
|
492 | |
366 | </body> |
493 | </body> |
367 | </section> |
494 | </section> |
368 | </chapter> |
495 | </chapter> |
369 | </guide> |
496 | </guide> |
370 | |
497 | |