/[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.43 Revision 1.44
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.43 2005/05/12 16:57:02 neysx Exp $ --> 2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.44 2005/05/23 19:05:33 swift Exp $ -->
3<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> 3<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4 4
5<guide link="/doc/en/xml-guide.xml"> 5<guide link="/doc/en/xml-guide.xml">
6<title>Gentoo Linux XML Guide</title> 6<title>Gentoo Linux XML Guide</title>
7 7
8<author title="Author"> 8<author title="Author">
9 <mail link="drobbins@gentoo.org">Daniel Robbins</mail> 9 <mail link="drobbins@gentoo.org">Daniel Robbins</mail>
10</author> 10</author>
11<author title="Author"><!-- zhen@gentoo.org --> 11<author title="Author"><!-- zhen@gentoo.org -->
12 John P. Davis 12 John P. Davis
13</author> 13</author>
14<author title="Editor"> 14<author title="Editor">
15 <mail link="peesh@gentoo.org">Jorge Paulo</mail> 15 <mail link="peesh@gentoo.org">Jorge Paulo</mail>
16</author> 16</author>
17<author title="Editor"> 17<author title="Editor">
20<author title="Editor"> 20<author title="Editor">
21 <mail link="neysx@gentoo.org">Xavier Neys</mail> 21 <mail link="neysx@gentoo.org">Xavier Neys</mail>
22</author> 22</author>
23 23
24<abstract> 24<abstract>
25This guide shows you how to compose web documentation using the new lightweight 25This guide shows you how to compose web documentation using the new lightweight
26Gentoo GuideXML syntax. This syntax is the official format for Gentoo Linux 26Gentoo GuideXML syntax. This syntax is the official format for Gentoo Linux
27documentation, and this document itself was created using GuideXML. This guide 27documentation, and this document itself was created using GuideXML. This guide
28assumes a basic working knowledge of XML and HTML. 28assumes a basic working knowledge of XML and HTML.
29</abstract> 29</abstract>
30 30
31<!-- The content of this document is licensed under the CC-BY-SA license --> 31<!-- The content of this document is licensed under the CC-BY-SA license -->
32<!-- See http://creativecommons.org/licenses/by-sa/2.0 --> 32<!-- See http://creativecommons.org/licenses/by-sa/2.0 -->
33<license/> 33<license/>
34 34
35<version>2.20</version> 35<version>2.21</version>
36<date>2005-05-12</date> 36<date>2005-05-23</date>
37 37
38<chapter> 38<chapter>
39<title>Guide basics</title> 39<title>Guide basics</title>
40<section> 40<section>
41<title>Guide XML design goals</title> 41<title>Guide XML design goals</title>
42<body> 42<body>
43 43
44<p> 44<p>
45The guide XML syntax is lightweight yet expressive, so that it is easy to 45The guide XML syntax is lightweight yet expressive, so that it is easy to
46learn yet also provides all the features we need for the creation of web 46learn yet also provides all the features we need for the creation of web
47documentation. The number of tags is kept to a minimum -- just those we need. 47documentation. The number of tags is kept to a minimum -- just those we need.
48This makes it easy to transform guide into other formats, such as DocBook 48This makes it easy to transform guide into other formats, such as DocBook
49XML/SGML or web-ready HTML. 49XML/SGML or web-ready HTML.
50</p> 50</p>
51 51
305<c>&lt;p&gt;</c> element. As you might guess, the <c>&lt;pre&gt;</c> element 305<c>&lt;p&gt;</c> element. As you might guess, the <c>&lt;pre&gt;</c> element
306preserves its whitespace exactly, making it well-suited for code excerpts. 306preserves its whitespace exactly, making it well-suited for code excerpts.
307You can also name the <c>&lt;pre&gt;</c> tag: 307You can also name the <c>&lt;pre&gt;</c> tag:
308</p> 308</p>
309 309
310<pre caption="Named &lt;pre&gt;"> 310<pre caption="Named &lt;pre&gt;">
311&lt;pre caption = "Output of uptime"&gt; 311&lt;pre caption = "Output of uptime"&gt;
312# &lt;i&gt;uptime&lt;/i&gt; 312# &lt;i&gt;uptime&lt;/i&gt;
31316:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25 31316:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25
314&lt;/pre&gt; 314&lt;/pre&gt;
315</pre> 315</pre>
316 316
317</body> 317</body>
318</section> 318</section>
319<section> 319<section>
320<title>&lt;path&gt;, &lt;c&gt; and &lt;e&gt;</title> 320<title>&lt;path&gt;, &lt;c&gt;, &lt;i&gt; and &lt;e&gt;</title>
321<body> 321<body>
322 322
323<p> 323<p>
324The <c>&lt;path&gt;</c>, <c>&lt;c&gt;</c> and <c>&lt;e&gt;</c> elements can 324The <c>&lt;path&gt;</c>, <c>&lt;c&gt;</c> and <c>&lt;e&gt;</c> elements can
325be used inside any child <c>&lt;body&gt;</c> tag, except for 325be used inside any child <c>&lt;body&gt;</c> tag, except for
326<c>&lt;pre&gt;</c>. The <c>&lt;i&gt;</c> element can only be used inside
326<c>&lt;pre&gt;</c>. 327<c>&lt;pre&gt;</c>.
327</p> 328</p>
328 329
329<p> 330<p>
330The <c>&lt;path&gt;</c> element is used to mark text that refers to an 331The <c>&lt;path&gt;</c> element is used to mark text that refers to an
331<e>on-disk file</e> -- either an <e>absolute or relative path</e>, or a 332<e>on-disk file</e> -- either an <e>absolute or relative path</e>, or a
332<e>simple filename</e>. This element is generally rendered with a monospaced 333<e>simple filename</e>. This element is generally rendered with a monospaced
333font to offset it from the standard paragraph type. 334font to offset it from the standard paragraph type.
334</p> 335</p>
335 336
336<p> 337<p>
337The <c>&lt;c&gt;</c> element is used to mark up a <e>command</e> or <e>user 338The <c>&lt;c&gt;</c> element is used to mark up a <e>command</e> or <e>user
338input</e>. Think of <c>&lt;c&gt;</c> as a way to alert the reader to something 339input</e>. Think of <c>&lt;c&gt;</c> as a way to alert the reader to something
339that they can type in that will perform some kind of action. For example, all 340that they can type in that will perform some kind of action. For example, all
340the XML tags displayed in this document are enclosed in a <c>&lt;c&gt;</c> 341the XML tags displayed in this document are enclosed in a <c>&lt;c&gt;</c>
341element because they represent something that the user could type in that is 342element because they represent something that the user could type in that is
342not a path. By using <c>&lt;c&gt;</c> elements, you'll help your readers 343not a path. By using <c>&lt;c&gt;</c> elements, you'll help your readers
343quickly identify commands that they need to type in. Also, because 344quickly identify commands that they need to type in. Also, because
344<c>&lt;c&gt;</c> elements are already offset from regular text, <e>it is rarely 345<c>&lt;c&gt;</c> elements are already offset from regular text, <e>it is rarely
345necessary to surround user input with double-quotes</e>. For example, don't 346necessary to surround user input with double-quotes</e>. For example, don't
346refer to a "<c>&lt;c&gt;</c>" element like I did in this sentence. Avoiding 347refer to a "<c>&lt;c&gt;</c>" element like I did in this sentence. Avoiding
347the use of unnecessary double-quotes makes a document more readable -- and 348the use of unnecessary double-quotes makes a document more readable -- and
348adorable! 349adorable!
350</p>
351
352<p>
353When you want to highlight some text as user input inside a <c>&lt;pre&gt;</c>,
354use <c>&lt;i&gt;</c> instead.
349</p> 355</p>
350 356
351<p> 357<p>
352<c>&lt;e&gt;</c> is used to apply emphasis to a word or phrase; for example: 358<c>&lt;e&gt;</c> is used to apply emphasis to a word or phrase; for example:
353I <e>really</e> should use semicolons more often. As you can see, this text is 359I <e>really</e> should use semicolons more often. As you can see, this text is
354offset from the regular paragraph type for emphasis. This helps to give your 360offset from the regular paragraph type for emphasis. This helps to give your
355prose more <e>punch</e>! 361prose more <e>punch</e>!
356</p> 362</p>
357 363
358</body> 364</body>
359</section> 365</section>
360<section> 366<section>
361<title>&lt;mail&gt; and &lt;uri&gt;</title> 367<title>&lt;mail&gt; and &lt;uri&gt;</title>
362<body> 368<body>
363 369
483Both sections are described next. 489Both sections are described next.
484</p> 490</p>
485 491
486</body> 492</body>
487</section> 493</section>
488<section> 494<section>
489<title>Internal Coding Style</title> 495<title>Internal Coding Style</title>
490<body> 496<body>
491 497
492<p> 498<p>
493<b>Newlines</b> must be placed immediately after <e>every</e> 499<b>Newlines</b> must be placed immediately after <e>every</e>
494GuideXML-tag (both opening as closing), except for: 500GuideXML-tag (both opening as closing), except for:
495<c>&lt;version&gt;</c>, <c>&lt;date&gt;</c>, <c>&lt;title&gt;</c>, 501<c>&lt;version&gt;</c>, <c>&lt;date&gt;</c>, <c>&lt;title&gt;</c>,
496<c>&lt;th&gt;</c>, <c>&lt;ti&gt;</c>, 502<c>&lt;th&gt;</c>, <c>&lt;ti&gt;</c>,
497<c>&lt;li&gt;</c>, <c>&lt;i&gt;</c>, <c>&lt;e&gt;</c>, 503<c>&lt;li&gt;</c>, <c>&lt;i&gt;</c>, <c>&lt;e&gt;</c>,
498<c>&lt;uri&gt;</c>, <c>&lt;path&gt;</c>, <c>&lt;b&gt;</c>, 504<c>&lt;uri&gt;</c>, <c>&lt;path&gt;</c>, <c>&lt;b&gt;</c>, <c>&lt;c&gt;</c>,
499<c>&lt;comment&gt;</c>, <c>&lt;mail&gt;</c>. 505<c>&lt;comment&gt;</c>, <c>&lt;mail&gt;</c>.
500</p> 506</p>
501 507
502<p> 508<p>
503<b>Blank lines</b> must be placed immediately after <e>every</e> 509<b>Blank lines</b> must be placed immediately after <e>every</e>
504<c>&lt;body&gt;</c> (opening tag only) and before <e>every</e> 510<c>&lt;body&gt;</c> (opening tag only) and before <e>every</e>
505<c>&lt;chapter&gt;</c>, <c>&lt;p&gt;</c>, <c>&lt;table&gt;</c>, 511<c>&lt;chapter&gt;</c>, <c>&lt;p&gt;</c>, <c>&lt;table&gt;</c>,
506<c>&lt;author&gt;</c> (set), <c>&lt;pre&gt;</c>, <c>&lt;ul&gt;</c>, 512<c>&lt;author&gt;</c> (set), <c>&lt;pre&gt;</c>, <c>&lt;ul&gt;</c>,
507<c>&lt;ol&gt;</c>, <c>&lt;warn&gt;</c>, <c>&lt;note&gt;</c> and 513<c>&lt;ol&gt;</c>, <c>&lt;warn&gt;</c>, <c>&lt;note&gt;</c> and
508<c>&lt;impo&gt;</c> (opening tags only). 514<c>&lt;impo&gt;</c> (opening tags only).
509</p> 515</p>
510 516
511<p> 517<p>
512<b>Word-wrapping</b> must be applied at 80 characters except inside 518<b>Word-wrapping</b> must be applied at 80 characters except inside
513<c>&lt;pre&gt;</c>. Only when there is no other choice can be deviated from 519<c>&lt;pre&gt;</c>. Only when there is no other choice can be deviated from

Legend:
Removed from v.1.43  
changed lines
  Added in v.1.44

  ViewVC Help
Powered by ViewVC 1.1.20