/[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.24 Revision 1.25
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.24 2003/12/12 14:24:49 swift Exp $ --> 2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.25 2004/02/09 19:25:39 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">
18 <mail link="swift@gentoo.org">Sven Vermeulen</mail>
19</author>
17 20
18<license/> 21<license/>
22
19<abstract> 23<abstract>
20This guide shows you how to compose web documentation using the new lightweight 24This guide shows you how to compose web documentation using the new lightweight
21Gentoo GuideXML syntax. This syntax is the official format for Gentoo Linux 25Gentoo GuideXML syntax. This syntax is the official format for Gentoo Linux
22documentation, and this document itself was created using GuideXML. This guide 26documentation, and this document itself was created using GuideXML. This guide
23assumes a basic working knowledge of XML and HTML. 27assumes a basic working knowledge of XML and HTML.
24</abstract> 28</abstract>
25 29
26<version>2.6</version> 30<version>2.7</version>
27<date>December 12, 2003</date> 31<date>February 9, 2004</date>
28 32
29<chapter> 33<chapter>
30<title>Guide basics</title> 34<title>Guide basics</title>
31<section> 35<section>
32<title>Guide XML design goals</title> 36<title>Guide XML design goals</title>
33<body> 37<body>
34 38
35<p> 39<p>
36The guide XML syntax is lightweight yet expressive, so that it is easy to 40The guide XML syntax is lightweight yet expressive, so that it is easy to
37learn yet also provides all the features we need for the creation of web 41learn yet also provides all the features we need for the creation of web
38documentation. The number of tags is kept to a minimum -- just those we need. 42documentation. The number of tags is kept to a minimum -- just those we need.
39This makes it easy to transform guide into other formats, such as DocBook 43This makes it easy to transform guide into other formats, such as DocBook
40XML/SGML or web-ready HTML. 44XML/SGML or web-ready HTML.
41</p> 45</p>
42 46
64 68
65<chapter> 69<chapter>
66<title>Guide XML</title> 70<title>Guide XML</title>
67<section> 71<section>
68<title>Basic structure</title> 72<title>Basic structure</title>
69<body> 73<body>
70 74
71<p> 75<p>
72Now that you know how to transform guide XML, you're ready to start learning 76Now that you know how to transform guide XML, you're ready to start learning
73the GuideXML syntax. We'll start with the the initial tags used in a guide 77the GuideXML syntax. We'll start with the the initial tags used in a guide
74XML document: 78XML document:
75</p> 79</p>
76 80
77<pre caption="The initial part of a guide XML document"> 81<pre caption="The initial part of a guide XML document">
78&lt;?xml version='1.0' encoding="UTF-8"?&gt; 82&lt;?xml version='1.0' encoding="UTF-8"?&gt;
83&lt;!DOCTYPE guide SYSTEM "/dtd/guide.dtd"&gt;
79&lt;guide link="relative_link_to_your_guide"&gt; 84&lt;guide link="relative_link_to_your_guide"&gt;
80&lt;title&gt;<i>Gentoo Linux Documentation Guide</i>&lt;/title&gt; 85&lt;title&gt;<i>Gentoo Linux Documentation Guide</i>&lt;/title&gt;
81&lt;author title="<i>Chief Architect</i>"&gt; 86&lt;author title="<i>Chief Architect</i>"&gt;
82 &lt;mail link="<i>drobbins@gentoo.org</i>"&gt;<i>Daniel Robbins</i>&lt;/mail&gt; 87 &lt;mail link="<i>drobbins@gentoo.org</i>"&gt;<i>Daniel Robbins</i>&lt;/mail&gt;
83&lt;/author&gt; 88&lt;/author&gt;
84&lt;author title="<i>Editor</i>"&gt; 89&lt;author title="<i>Editor</i>"&gt;
85 &lt;mail link="<i>thomasfl@gentoo.org</i>"&gt;<i>Thomas Flavel</i>&lt;/mail&gt; 90 &lt;mail link="<i>thomasfl@gentoo.org</i>"&gt;<i>Thomas Flavel</i>&lt;/mail&gt;
86&lt;/author&gt; 91&lt;/author&gt;
87 92
88&lt;abstract&gt; 93&lt;abstract&gt;
89<i>This guide shows you how to compose web documentation using 94<i>This guide shows you how to compose web documentation using
90our new lightweight Gentoo GuideXML syntax. This syntax is the official 95our new lightweight Gentoo GuideXML syntax. This syntax is the official
91format for Gentoo Linux web documentation, and this document itself was created 96format for Gentoo Linux web documentation, and this document itself was created
92using GuideXML.</i> 97using GuideXML.</i>
93&lt;/abstract&gt; 98&lt;/abstract&gt;
568<c>&lt;codenote&gt;</c> if the content is a C or C++ code snippet. Otherwise, 573<c>&lt;codenote&gt;</c> if the content is a C or C++ code snippet. Otherwise,
569use <c>&lt;comment&gt;</c> and parantheses. Also place the comment <e>before</e> 574use <c>&lt;comment&gt;</c> and parantheses. Also place the comment <e>before</e>
570the subject of the comment. 575the subject of the comment.
571</p> 576</p>
572 577
573<pre caption="Comment example"> 578<pre caption="Comment example">
574<comment>(Substitute "john" with your user name)</comment> 579<comment>(Substitute "john" with your user name)</comment>
575# <i>id john</i> 580# <i>id john</i>
576</pre> 581</pre>
577 582
578</body> 583</body>
579</section> 584</section>
580</chapter> 585</chapter>
581 586
582<chapter> 587<chapter>
588<title>Handbook Format</title>
589<section>
590<title>Guide vs Book</title>
591<body>
592
593<p>
594For high-volume documentation, such as the <uri
595link="/doc/en/handbook/handbook.xml?part=1">Installation Instructions</uri>, a
596broader format was needed. We designed a GuideXML-compatible enhancement that
597allows us to write modular and multi-page documentation.
598</p>
599
600</body>
601</section>
602<section>
603<title>Main File</title>
604<body>
605
606<p>
607The first change is the need for a "master" document. This document contains no
608real content, but links to the individual documentation modules. The syntaxis
609doesn't differ much from GuideXML:
610</p>
611
612<pre caption="Example book usage">
613&lt;?xml version='1.0' encoding='UTF-8'?&gt;
614&lt;!DOCTYPE book SYSTEM "/dtd/book.dtd"&gt;
615
616&lt;<i>book</i> link="example.xml"&gt;
617&lt;title&gt;Example Book Usage&lt;/title&gt;
618
619&lt;author...&gt;
620 ...
621&lt;/author&gt;
622
623&lt;abstract&gt;
624 ...
625&lt;/abstract&gt;
626
627&lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
628&lt;!-- See http://creativecommons.org/licenses/by-sa/1.0 --&gt;
629&lt;license/&gt;
630
631&lt;version&gt;...&lt;/version&gt;
632&lt;date&gt;...&lt;/date&gt;
633</pre>
634
635<p>
636So far no real differences (except for the <c>&lt;book&gt;</c> instead of
637<c>&lt;guide&gt;</c> tag). Instead of starting with the individual
638<c>&lt;chapter&gt;</c>'s, you define a <c>&lt;part&gt;</c>, which is the
639equivalent of a separate part in a book:
640</p>
641
642<pre caption="Defining a part">
643&lt;part&gt;
644&lt;title&gt;Part One&lt;/title&gt;
645&lt;abstract&gt;
646 ...
647&lt;/abstract&gt;
648
649<comment>(Defining the several chapters)</comment>
650&lt;/part&gt;
651</pre>
652
653<p>
654Each part is accompanied by a <c>&lt;title&gt;</c> and an
655<c>&lt;abstract&gt;</c> which gives a small introduction to the part.
656</p>
657
658<p>
659Inside each part, you define the individual <c>&lt;chapter&gt;</c>'s. Each
660chapter <e>must</e> be a separate document. As a result it is no surprise that a
661special tag (<c>&lt;include&gt;</c>) is added to allow including the separate
662document.
663</p>
664
665<pre caption="Defining a chapter">
666&lt;chapter&gt;
667&lt;title&gt;Chapter One&lt;/title&gt;
668&lt;abstract&gt;
669 This is a small explanation on chapter one.
670&lt;/abstract&gt;
671
672 &lt;include href="path/to/chapter-one.xml"/&gt;
673
674&lt;/chapter&gt;
675</pre>
676
677</body>
678</section>
679<section>
680<title>Designing the Individual Chapters</title>
681<body>
682
683<p>
684The content of an individual chapter is structured as follows:
685</p>
686
687<pre caption="Chapter Syntax">
688&lt;?xml version='1.0' encoding='UTF-8'?&gt;
689&lt;!DOCTYPE sections SYSTEM "/dtd/book.dtd"&gt;
690
691&lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
692&lt;!-- See http://creativecommons.org/licenses/by-sa/1.0 --&gt;
693
694&lt;sections&gt;
695
696<comment>(Define the several &lt;section&gt; and &lt;subsection&gt;)</comment>
697
698&lt;/sections&gt;
699</pre>
700
701<p>
702Inside each chapter you can define <c>&lt;section&gt;</c>'s (equivalent of
703<c>&lt;chapter&gt;</c> in a Guide) and <c>&lt;subsection&gt;</c>'s (equivalent
704of <c>&lt;section&gt;</c> in a Guide).
705</p>
706
707</body>
708</section>
709</chapter>
710
711<chapter>
583<title>Resources</title> 712<title>Resources</title>
584<section> 713<section>
585<title>Start writing</title> 714<title>Start writing</title>
586<body> 715<body>
587 716
588<p> 717<p>
589Guide has been specially designed to be "lean and mean" so that developers 718Guide has been specially designed to be "lean and mean" so that developers
590can spend more time writing documentation and less time learning the actual XML 719can spend more time writing documentation and less time learning the actual XML
591syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy" 720syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy"
592to start writing quality Gentoo Linux documentation. If you'd like to help (or 721to start writing quality Gentoo Linux documentation. If you'd like to help (or
593have any questions about guide), please post a message to the <mail 722have any questions about guide), please post a message to the <mail
594link="gentoo-doc@gentoo.org">gentoo-doc mailing list</mail> stating what you'd 723link="gentoo-doc@gentoo.org">gentoo-doc mailing list</mail> stating what you'd
595like to tackle. Have fun! 724like to tackle. Have fun!
596</p> 725</p>
597 726

Legend:
Removed from v.1.24  
changed lines
  Added in v.1.25

  ViewVC Help
Powered by ViewVC 1.1.20