/[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.16 Revision 1.17
20Gentoo GuideXML syntax. This syntax is the official format for Gentoo Linux 20Gentoo GuideXML syntax. This syntax is the official format for Gentoo Linux
21documentation, and this document itself was created using GuideXML. This guide 21documentation, and this document itself was created using GuideXML. This guide
22assumes a basic working knowledge of XML and HTML. 22assumes a basic working knowledge of XML and HTML.
23</abstract> 23</abstract>
24 24
25<version>2.0</version> 25<version>2.1</version>
26<date>October 9, 2003</date> 26<date>October 14, 2003</date>
27 27
28<chapter> 28<chapter>
29<title>Guide basics</title> 29<title>Guide basics</title>
30
31<section> 30<section>
32<title>Guide XML design goals</title> 31<title>Guide XML design goals</title>
33<body> 32<body>
34 33
35<p> 34<p>
45documents. 44documents.
46</p> 45</p>
47 46
48</body> 47</body>
49</section> 48</section>
50
51<section> 49<section>
52<title>How to transform guide XML into HTML</title> 50<title>How to transform guide XML into HTML</title>
53<body> 51<body>
54 52
55<p> 53<p>
61create the target HTML file. The processing tool that Gentoo Linux uses 59create the target HTML file. The processing tool that Gentoo Linux uses
62is called <c>xsltproc</c>, which is found in the <i>libxslt</i> package. 60is called <c>xsltproc</c>, which is found in the <i>libxslt</i> package.
63</p> 61</p>
64 62
65<pre caption="Installing libxslt"> 63<pre caption="Installing libxslt">
66# <c>emerge libxslt</c> 64# <i>emerge libxslt</i>
67</pre> 65</pre>
68 66
69<p> 67<p>
70Now that we have the way, we need the means, so to speak. In other words, 68Now that we have the way, we need the means, so to speak. In other words,
71we need some Gentoo XML documents to transform. Gentoo has two types of tarballs 69we need some Gentoo XML documents to transform. Gentoo has two types of tarballs
98<path>doc/en/gentoo-x86-install.xml</path>. Now that the locations of the XSL 96<path>doc/en/gentoo-x86-install.xml</path>. Now that the locations of the XSL
99and XML file are known, we can do some transforming with <c>xsltproc</c>. 97and XML file are known, we can do some transforming with <c>xsltproc</c>.
100</p> 98</p>
101 99
102<pre caption="Transforming gentoo-x86-install.xml"> 100<pre caption="Transforming gentoo-x86-install.xml">
103# <c>xsltproc xsl/guide.xsl doc/en/gentoo-x86-install.xml &gt; /tmp/install.html</c> 101# <i>xsltproc xsl/guide.xsl doc/en/gentoo-x86-install.xml &gt; /tmp/install.html</i>
104</pre> 102</pre>
105 103
106<p> 104<p>
107If all went well, you should have a web-ready version of 105If all went well, you should have a web-ready version of
108<path>gentoo-x86-install.xml</path> at <path>/tmp/install.html</path>. For 106<path>gentoo-x86-install.xml</path> at <path>/tmp/install.html</path>. For
189link="/doc/en/doc-policy.xml">Documentation Policy</uri>. 187link="/doc/en/doc-policy.xml">Documentation Policy</uri>.
190</p> 188</p>
191 189
192</body> 190</body>
193</section> 191</section>
194
195<section> 192<section>
196<title>Chapters and sections</title> 193<title>Chapters and sections</title>
197<body> 194<body>
198 195
199<p> 196<p>
240element can only contain one <c>&lt;body&gt;</c> element. 237element can only contain one <c>&lt;body&gt;</c> element.
241</note> 238</note>
242 239
243</body> 240</body>
244</section> 241</section>
245
246<section> 242<section>
247<title>An example &lt;body&gt;</title> 243<title>An example &lt;body&gt;</title>
248<body> 244<body>
249 245
250<p> 246<p>
313This is important. 309This is important.
314</impo> 310</impo>
315 311
316</body> 312</body>
317</section> 313</section>
318
319<section> 314<section>
320<title>The &lt;body&gt; tags</title> 315<title>The &lt;body&gt; tags</title>
321<body> 316<body>
322 317
323<p> 318<p>
382prose more <e>punch</e>! 377prose more <e>punch</e>!
383</p> 378</p>
384 379
385</body> 380</body>
386</section> 381</section>
387
388<section> 382<section>
389<title>&lt;mail&gt; and &lt;uri&gt;</title> 383<title>&lt;mail&gt; and &lt;uri&gt;</title>
390<body> 384<body>
391 385
392<p> 386<p>
407Gentoo Linux website&lt;/uri&gt;</c>. 401Gentoo Linux website&lt;/uri&gt;</c>.
408</p> 402</p>
409 403
410</body> 404</body>
411</section> 405</section>
412
413<section> 406<section>
414<title>Figures</title> 407<title>Figures</title>
415 408
416<body> 409<body>
417 410
450<c>&lt;note&gt;</c>, <c>&lt;warn&gt;</c> or <c>&lt;impo&gt;</c> tag. 443<c>&lt;note&gt;</c>, <c>&lt;warn&gt;</c> or <c>&lt;impo&gt;</c> tag.
451</p> 444</p>
452 445
453</body> 446</body>
454</section> 447</section>
455
456<section> 448<section>
457<title>Intra-document references</title> 449<title>Intra-document references</title>
458<body> 450<body>
459 451
460<p> 452<p>
473</body> 465</body>
474</section> 466</section>
475</chapter> 467</chapter>
476 468
477<chapter> 469<chapter>
470<title>Coding Style</title>
471<section>
472<title>Introduction</title>
473<body>
474
475<p>
476Since all Gentoo Documentation is a joint effort and several people will
477most likely change existing documentation, a coding style is needed.
478A coding style contains two sections. The first one is regarding
479internal coding - how the xml-tags are placed. The second one is
480regarding the content - how not to confuse the reader.
481</p>
482
483<p>
484Both sections are described next.
485</p>
486
487</body>
488</section>
489<section>
490<title>Internal Coding Style</title>
491<body>
492
493<p>
494<b>Newlines</b> must be placed immediately after <e>every</e>
495GuideXML-tag (both opening as closing), except for:
496<c>&lt;version&gt;</c>, <c>&lt;date&gt;</c>, <c>&lt;title&gt;</c>,
497<c>&lt;th&gt;</c>, <c>&lt;ti&gt;</c>,
498<c>&lt;li&gt;</c>, <c>&lt;i&gt;</c>, <c>&lt;e&gt;</c>,
499<c>&lt;uri&gt;</c>, <c>&lt;path&gt;</c>, <c>&lt;b&gt;</c>,
500<c>&lt;comment&gt;</c>, <c>&lt;codenote&gt;</c>, <c>&lt;mail&gt;</c>.
501</p>
502
503<p>
504<b>Blank lines</b> must be placed immediately after <e>every</e>
505<c>&lt;body&gt;</c> (opening tag only) and before <e>every</e>
506<c>&lt;chapter&gt;</c>, <c>&lt;p&gt;</c>, <c>&lt;table&gt;</c>,
507<c>&lt;author&gt;</c>, <c>&lt;pre&gt;</c>, <c>&lt;ul&gt;</c>, <c>&lt;ol&gt;</c>,
508<c>&lt;warn&gt;</c>, <c>&lt;note&gt;</c> and <c>&lt;impo&gt;</c> (opening tags
509only).
510</p>
511
512<p>
513<b>Word-wrapping</b> must be applied at 80 characters except inside
514<c>&lt;pre&gt;</c>. Only when there is no other choice can be deviated from
515this rule (for instance when a URL exceeds the maximum amount of characters).
516The editor must then wrap whenever the first whitespace occurs.
517</p>
518
519<p>
520<b>Indentation</b> may not be used, except with the XML-constructs of which
521the parent XML-tags are <c>&lt;tr&gt;</c> (from <c>&lt;table&gt;</c>),
522<c>&lt;ul&gt;</c> and <c>&lt;ol&gt;</c>. If indentation is used, it
523<e>must</e> be two spaces for each indentation. That means <e>no</e> tabs and
524<e>not</e> more spaces.
525</p>
526
527<p>
528In case word-wrapping happens in <c>&lt;ti&gt;</c>, <c>&lt;th&gt;</c> or
529<c>&lt;li&gt;</c> constructs, indentation must be used for the content.
530</p>
531
532<p>
533An example for indentation is:
534</p>
535
536<pre caption = "Indentation Example">
537&lt;table&gt;
538&lt;tr&gt;
539 &lt;th&gt;Foo&lt;/th&gt;
540 &lt;th&gt;Bar&lt;/th&gt;
541&lt;/tr&gt;
542&lt;tr&gt;
543 &lt;ti&gt;This is an example for indentation.&lt;/ti&gt;
544 &lt;ti&gt;
545 In case text cannot be shown within an 80-character wide line, you
546 must use indentation if the parent tag allows it.
547 &lt;/ti&gt;
548&lt;/tr&gt;
549&lt;/table&gt;
550
551&lt;ul&gt;
552 &lt;li&gt;First option&lt;/li&gt;
553 &lt;li&gt;Second option&lt;/li&gt;
554&lt;/ul&gt;
555</pre>
556
557<p>
558<b>Attributes</b> may not have spaces in between the attribute, the
559&quot;=&quot; mark, and the attribute value. As an example:
560</p>
561
562<pre caption="Attributes">
563<comment>Wrong :</comment> &lt;pre caption = "Attributes"&gt;
564<comment>Correct:</comment> &lt;pre caption="Attributes"&gt;
565</pre>
566
567</body>
568</section>
569<section>
570<title>External Coding Style</title>
571<body>
572
573<p>
574Inside tables (<c>&lt;table&gt;</c>) and listings (<c>&lt;ul&gt;</c> and
575<c>&lt;ol&gt;</c>), periods (&quot;.&quot;) should not be used unless multiple
576sentences are used. In that case, every sentence should end with a period (or
577other reading marks).
578</p>
579
580<p>
581Every sentence, including those inside tables and listings, should start
582with a capital letter.
583</p>
584
585<pre caption="Periods and capital letters">
586&lt;ul&gt;
587 &lt;li&gt;No period&lt;/li&gt;
588 &lt;li&gt;With period. Multiple sentences, remember?&lt;/li&gt;
589&lt;/ul&gt;
590</pre>
591
592<p>
593Code Listings should <e>always</e> have a <c>caption</c>.
594</p>
595
596<p>
597Try to use <c>&lt;uri&gt;</c> with the <c>link</c> attribute as much as
598possible. In other words, the <uri link="http://www.gentoo.org">Gentoo
599Website</uri> is preferred over <uri>http://www.gentoo.org</uri>.
600</p>
601
602</body>
603</section>
604</chapter>
605
606<chapter>
478<title>Resources</title> 607<title>Resources</title>
479<section> 608<section>
480<title>Start writing</title> 609<title>Start writing</title>
481<body> 610<body>
482 611

Legend:
Removed from v.1.16  
changed lines
  Added in v.1.17

  ViewVC Help
Powered by ViewVC 1.1.20