/[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
… …
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>
… …
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;
… …
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
Legend:
Removed from v.1.24  
changed lines
  Added in v.1.25
  ViewVC Help
Powered by ViewVC 1.1.13