/[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.36 Revision 1.37
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.36 2005/02/14 16:14:46 swift Exp $ --> 2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.37 2005/04/06 10:59:55 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
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.13</version> 35<version>2.14</version>
36<date>2005-02-14</date> 36<date>2005-04-06</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>
164<section> 164<section>
165<title>Chapters and sections</title> 165<title>Chapters and sections</title>
166<body> 166<body>
167 167
168<p> 168<p>
169Once the initial tags have been specified, you're ready to start adding 169Once the initial tags have been specified, you're ready to start adding the
170the structural elements of the document. Guide documents are divided into 170structural elements of the document. Guide documents are divided into
171chapters, and each chapter can hold one or more sections. Every chapter 171chapters, and each chapter can hold one or more sections. Every chapter and
172and section has a title. Here's an example chapter with a single section, 172section has a title. Here's an example chapter with a single section,
173consisting of a paragraph. If you append this XML to the XML in the <uri link="#doc_chap2_pre1">previous 173consisting of a paragraph. If you append this XML to the XML in the <uri
174link="#doc_chap2_pre1">previous excerpt</uri> and append a
174excerpt</uri> and append a <c>&lt;/guide&gt;</c> to the end of the file, you'll have a valid 175<c>&lt;/guide&gt;</c> to the end of the file, you'll have a valid (if minimal)
175(if minimal) guide document: 176guide document:
176</p> 177</p>
177 178
178<pre> 179<pre caption="Minimal guide example">
179&lt;chapter&gt; 180&lt;chapter&gt;
180&lt;title&gt;<i>This is my chapter</i>&lt;/title&gt; 181&lt;title&gt;<i>This is my chapter</i>&lt;/title&gt;
181&lt;section&gt; 182&lt;section&gt;
182&lt;title&gt;<i>This is section one of my chapter</i>&lt;/title&gt; 183&lt;title&gt;<i>This is section one of my chapter</i>&lt;/title&gt;
183&lt;body&gt; 184&lt;body&gt;
214<section> 215<section>
215<title>An example &lt;body&gt;</title> 216<title>An example &lt;body&gt;</title>
216<body> 217<body>
217 218
218<p> 219<p>
219Now, it's time to learn how to mark up actual content. Here's the XML code for an example <c>&lt;body&gt;</c> element: 220Now, it's time to learn how to mark up actual content. Here's the XML code for
221an example <c>&lt;body&gt;</c> element:
220</p> 222</p>
221 223
222<pre> 224<pre caption="Example of a body element">
223&lt;p&gt; 225&lt;p&gt;
224This is a paragraph. &lt;path&gt;/etc/passwd&lt;/path&gt; is a file. 226This is a paragraph. &lt;path&gt;/etc/passwd&lt;/path&gt; is a file.
225&lt;uri&gt;http://forums.gentoo.org&lt;/uri&gt; is my favorite website. 227&lt;uri&gt;http://forums.gentoo.org&lt;/uri&gt; is my favorite website.
226Type &lt;c&gt;ls&lt;/c&gt; if you feel like it. I &lt;e&gt;really&lt;/e&gt; want to go to sleep now. 228Type &lt;c&gt;ls&lt;/c&gt; if you feel like it. I &lt;e&gt;really&lt;/e&gt; want to go to sleep now.
227&lt;/p&gt; 229&lt;/p&gt;
228 230
229&lt;pre&gt; 231&lt;pre caption="Code Sample"&gt;
230This is text output or code. 232This is text output or code.
231# &lt;i&gt;this is user input&lt;/i&gt; 233# &lt;i&gt;this is user input&lt;/i&gt;
232 234
233Make HTML/XML easier to read by using selective emphasis: 235Make HTML/XML easier to read by using selective emphasis:
234&lt;foo&gt;&lt;i&gt;bar&lt;/i&gt;&lt;/foo&gt; 236&lt;foo&gt;&lt;i&gt;bar&lt;/i&gt;&lt;/foo&gt;
235 237
236&lt;codenote&gt;This is how to insert an inline note into the code block&lt;/codenote&gt; 238&lt;comment&gt;(This is how to insert an inline note into the code block)&lt;/comment&gt;
237&lt;/pre&gt; 239&lt;/pre&gt;
238 240
239&lt;note&gt; 241&lt;note&gt;
240This is a note. 242This is a note.
241&lt;/note&gt; 243&lt;/note&gt;
248This is important. 250This is important.
249&lt;/impo&gt; 251&lt;/impo&gt;
250</pre> 252</pre>
251 253
252<p> 254<p>
253Now, here's how this <c>&lt;body&gt;</c> element is rendered: 255Now, here's how the <c>&lt;body&gt;</c> element above is rendered:
254</p> 256</p>
255 257
256<p> 258<p>
257This is a paragraph. <path>/etc/passwd</path> is a file. 259This is a paragraph. <path>/etc/passwd</path> is a file.
258<uri>http://forums.gentoo.org</uri> is my favorite website. 260<uri>http://forums.gentoo.org</uri> is my favorite website.
259Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now. 261Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now.
260</p> 262</p>
261 263
262<pre> 264<pre caption="Code Sample">
263This is text output or code. 265This is text output or code.
264# <i>this is user input</i> 266# <i>this is user input</i>
265 267
266Make HTML/XML easier to read by using selective emphasis: 268Make HTML/XML easier to read by using selective emphasis:
267&lt;foo&gt;<i>bar</i>&lt;/foo&gt; 269&lt;foo&gt;<i>bar</i>&lt;/foo&gt;
268 270
269<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>
270</pre> 272</pre>
271 273
272<note> 274<note>
273This is a note. 275This is a note.
274</note> 276</note>
299<c>&lt;p&gt;</c> element. As you might guess, the <c>&lt;pre&gt;</c> element 301<c>&lt;p&gt;</c> element. As you might guess, the <c>&lt;pre&gt;</c> element
300preserves its whitespace exactly, making it well-suited for code excerpts. 302preserves its whitespace exactly, making it well-suited for code excerpts.
301You can also name the <c>&lt;pre&gt;</c> tag: 303You can also name the <c>&lt;pre&gt;</c> tag:
302</p> 304</p>
303 305
304<pre caption = "Named &lt;pre&gt;"> 306<pre caption="Named &lt;pre&gt;">
305&lt;pre caption = "Output of uptime"&gt; 307&lt;pre caption = "Output of uptime"&gt;
306# &lt;i&gt;uptime&lt;/i&gt; 308# &lt;i&gt;uptime&lt;/i&gt;
30716:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25 30916:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25
308&lt;/pre&gt; 310&lt;/pre&gt;
309</pre> 311</pre>
380 382
381</body> 383</body>
382</section> 384</section>
383<section> 385<section>
384<title>Figures</title> 386<title>Figures</title>
385
386<body> 387<body>
387 388
388<p> 389<p>
389Here's how to insert a figure into a document -- <c>&lt;figure 390Here's how to insert a figure into a document -- <c>&lt;figure
390link="mygfx.png" short="my picture" caption="my favorite picture of all 391link="mygfx.png" short="my picture" caption="my favorite picture of all
488GuideXML-tag (both opening as closing), except for: 489GuideXML-tag (both opening as closing), except for:
489<c>&lt;version&gt;</c>, <c>&lt;date&gt;</c>, <c>&lt;title&gt;</c>, 490<c>&lt;version&gt;</c>, <c>&lt;date&gt;</c>, <c>&lt;title&gt;</c>,
490<c>&lt;th&gt;</c>, <c>&lt;ti&gt;</c>, 491<c>&lt;th&gt;</c>, <c>&lt;ti&gt;</c>,
491<c>&lt;li&gt;</c>, <c>&lt;i&gt;</c>, <c>&lt;e&gt;</c>, 492<c>&lt;li&gt;</c>, <c>&lt;i&gt;</c>, <c>&lt;e&gt;</c>,
492<c>&lt;uri&gt;</c>, <c>&lt;path&gt;</c>, <c>&lt;b&gt;</c>, 493<c>&lt;uri&gt;</c>, <c>&lt;path&gt;</c>, <c>&lt;b&gt;</c>,
493<c>&lt;comment&gt;</c>, <c>&lt;codenote&gt;</c>, <c>&lt;mail&gt;</c>. 494<c>&lt;comment&gt;</c>, <c>&lt;mail&gt;</c>.
494</p> 495</p>
495 496
496<p> 497<p>
497<b>Blank lines</b> must be placed immediately after <e>every</e> 498<b>Blank lines</b> must be placed immediately after <e>every</e>
498<c>&lt;body&gt;</c> (opening tag only) and before <e>every</e> 499<c>&lt;body&gt;</c> (opening tag only) and before <e>every</e>
524 525
525<p> 526<p>
526An example for indentation is: 527An example for indentation is:
527</p> 528</p>
528 529
529<pre caption = "Indentation Example"> 530<pre caption="Indentation Example">
530&lt;table&gt; 531&lt;table&gt;
531&lt;tr&gt; 532&lt;tr&gt;
532 &lt;th&gt;Foo&lt;/th&gt; 533 &lt;th&gt;Foo&lt;/th&gt;
533 &lt;th&gt;Bar&lt;/th&gt; 534 &lt;th&gt;Bar&lt;/th&gt;
534&lt;/tr&gt; 535&lt;/tr&gt;
591possible. In other words, the <uri link="http://forums.gentoo.org">Gentoo 592possible. In other words, the <uri link="http://forums.gentoo.org">Gentoo
592Forums</uri> is preferred over <uri>http://forums.gentoo.org</uri>. 593Forums</uri> is preferred over <uri>http://forums.gentoo.org</uri>.
593</p> 594</p>
594 595
595<p> 596<p>
596When you comment something inside a <c>&lt;pre&gt;</c> construct, only use 597When you comment something inside a <c>&lt;pre&gt;</c> construct, use
597<c>&lt;codenote&gt;</c> if the content is a C or C++ code snippet. Otherwise, 598<c>&lt;comment&gt;</c> and parentheses or the comment marker for the language
598use <c>&lt;comment&gt;</c> and parentheses. Also place the comment <e>before</e> 599that is being used (<c>#</c> for bash scripts and many other things, <c>//</c>
599the subject of the comment. 600for C code, etc.) Also place the comment <e>before</e> the subject of the
601comment.
600</p> 602</p>
601 603
602<pre caption="Comment example"> 604<pre caption="Comment example">
603<comment>(Substitute "john" with your user name)</comment> 605<comment>(Substitute "john" with your user name)</comment>
604# <i>id john</i> 606# <i>id john</i>

Legend:
Removed from v.1.36  
changed lines
  Added in v.1.37

  ViewVC Help
Powered by ViewVC 1.1.20