/[gentoo]/xml/htdocs/doc/en/xml-guide.xml

Diff of /xml/htdocs/doc/en/xml-guide.xml

Parent Directory | 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>
20	This guide shows you how to compose web documentation using the new lightweight	24	This guide shows you how to compose web documentation using the new lightweight
21	Gentoo GuideXML syntax. This syntax is the official format for Gentoo Linux	25	Gentoo GuideXML syntax. This syntax is the official format for Gentoo Linux
22	documentation, and this document itself was created using GuideXML. This guide	26	documentation, and this document itself was created using GuideXML. This guide
23	assumes a basic working knowledge of XML and HTML.	27	assumes 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>
36	The guide XML syntax is lightweight yet expressive, so that it is easy to	40	The guide XML syntax is lightweight yet expressive, so that it is easy to
37	learn yet also provides all the features we need for the creation of web	41	learn yet also provides all the features we need for the creation of web
38	documentation. The number of tags is kept to a minimum -- just those we need.	42	documentation. The number of tags is kept to a minimum -- just those we need.
39	This makes it easy to transform guide into other formats, such as DocBook	43	This makes it easy to transform guide into other formats, such as DocBook
40	XML/SGML or web-ready HTML.	44	XML/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>
72	Now that you know how to transform guide XML, you're ready to start learning	76	Now that you know how to transform guide XML, you're ready to start learning
73	the GuideXML syntax. We'll start with the the initial tags used in a guide	77	the GuideXML syntax. We'll start with the the initial tags used in a guide
74	XML document:	78	XML 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	<?xml version='1.0' encoding="UTF-8"?>	82	<?xml version='1.0' encoding="UTF-8"?>
		83	<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
79	<guide link="relative_link_to_your_guide">	84	<guide link="relative_link_to_your_guide">
80	<title><i>Gentoo Linux Documentation Guide</i></title>	85	<title><i>Gentoo Linux Documentation Guide</i></title>
81	<author title="<i>Chief Architect</i>">	86	<author title="<i>Chief Architect</i>">
82	<mail link="<i>drobbins@gentoo.org</i>"><i>Daniel Robbins</i></mail>	87	<mail link="<i>drobbins@gentoo.org</i>"><i>Daniel Robbins</i></mail>
83	</author>	88	</author>
84	<author title="<i>Editor</i>">	89	<author title="<i>Editor</i>">
85	<mail link="<i>thomasfl@gentoo.org</i>"><i>Thomas Flavel</i></mail>	90	<mail link="<i>thomasfl@gentoo.org</i>"><i>Thomas Flavel</i></mail>
86	</author>	91	</author>
87		92
88	<abstract>	93	<abstract>
89	<i>This guide shows you how to compose web documentation using	94	<i>This guide shows you how to compose web documentation using
90	our new lightweight Gentoo GuideXML syntax. This syntax is the official	95	our new lightweight Gentoo GuideXML syntax. This syntax is the official
91	format for Gentoo Linux web documentation, and this document itself was created	96	format for Gentoo Linux web documentation, and this document itself was created
92	using GuideXML.</i>	97	using GuideXML.</i>
93	</abstract>	98	</abstract>
…		…
568	<c><codenote></c> if the content is a C or C++ code snippet. Otherwise,	573	<c><codenote></c> if the content is a C or C++ code snippet. Otherwise,
569	use <c><comment></c> and parantheses. Also place the comment <e>before</e>	574	use <c><comment></c> and parantheses. Also place the comment <e>before</e>
570	the subject of the comment.	575	the 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>
		594	For high-volume documentation, such as the <uri
		595	link="/doc/en/handbook/handbook.xml?part=1">Installation Instructions</uri>, a
		596	broader format was needed. We designed a GuideXML-compatible enhancement that
		597	allows 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>
		607	The first change is the need for a "master" document. This document contains no
		608	real content, but links to the individual documentation modules. The syntaxis
		609	doesn't differ much from GuideXML:
		610	</p>
		611
		612	<pre caption="Example book usage">
		613	<?xml version='1.0' encoding='UTF-8'?>
		614	<!DOCTYPE book SYSTEM "/dtd/book.dtd">
		615
		616	<<i>book</i> link="example.xml">
		617	<title>Example Book Usage</title>
		618
		619	<author...>
		620	...
		621	</author>
		622
		623	<abstract>
		624	...
		625	</abstract>
		626
		627	<!-- The content of this document is licensed under the CC-BY-SA license -->
		628	<!-- See http://creativecommons.org/licenses/by-sa/1.0 -->
		629	<license/>
		630
		631	<version>...</version>
		632	<date>...</date>
		633	</pre>
		634
		635	<p>
		636	So far no real differences (except for the <c><book></c> instead of
		637	<c><guide></c> tag). Instead of starting with the individual
		638	<c><chapter></c>'s, you define a <c><part></c>, which is the
		639	equivalent of a separate part in a book:
		640	</p>
		641
		642	<pre caption="Defining a part">
		643	<part>
		644	<title>Part One</title>
		645	<abstract>
		646	...
		647	</abstract>
		648
		649	<comment>(Defining the several chapters)</comment>
		650	</part>
		651	</pre>
		652
		653	<p>
		654	Each part is accompanied by a <c><title></c> and an
		655	<c><abstract></c> which gives a small introduction to the part.
		656	</p>
		657
		658	<p>
		659	Inside each part, you define the individual <c><chapter></c>'s. Each
		660	chapter <e>must</e> be a separate document. As a result it is no surprise that a
		661	special tag (<c><include></c>) is added to allow including the separate
		662	document.
		663	</p>
		664
		665	<pre caption="Defining a chapter">
		666	<chapter>
		667	<title>Chapter One</title>
		668	<abstract>
		669	This is a small explanation on chapter one.
		670	</abstract>
		671
		672	<include href="path/to/chapter-one.xml"/>
		673
		674	</chapter>
		675	</pre>
		676
		677	</body>
		678	</section>
		679	<section>
		680	<title>Designing the Individual Chapters</title>
		681	<body>
		682
		683	<p>
		684	The content of an individual chapter is structured as follows:
		685	</p>
		686
		687	<pre caption="Chapter Syntax">
		688	<?xml version='1.0' encoding='UTF-8'?>
		689	<!DOCTYPE sections SYSTEM "/dtd/book.dtd">
		690
		691	<!-- The content of this document is licensed under the CC-BY-SA license -->
		692	<!-- See http://creativecommons.org/licenses/by-sa/1.0 -->
		693
		694	<sections>
		695
		696	<comment>(Define the several <section> and <subsection>)</comment>
		697
		698	</sections>
		699	</pre>
		700
		701	<p>
		702	Inside each chapter you can define <c><section></c>'s (equivalent of
		703	<c><chapter></c> in a Guide) and <c><subsection></c>'s (equivalent
		704	of <c><section></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>
589	Guide has been specially designed to be "lean and mean" so that developers	718	Guide has been specially designed to be "lean and mean" so that developers
590	can spend more time writing documentation and less time learning the actual XML	719	can spend more time writing documentation and less time learning the actual XML
591	syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy"	720	syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy"
592	to start writing quality Gentoo Linux documentation. If you'd like to help (or	721	to start writing quality Gentoo Linux documentation. If you'd like to help (or
593	have any questions about guide), please post a message to the <mail	722	have any questions about guide), please post a message to the <mail
594	link="gentoo-doc@gentoo.org">gentoo-doc mailing list</mail> stating what you'd	723	link="gentoo-doc@gentoo.org">gentoo-doc mailing list</mail> stating what you'd
595	like to tackle. Have fun!	724	like to tackle. Have fun!
596	</p>	725	</p>
597		726

 Legend:



Removed from v.1.24
 


changed lines


 
Added in v.1.25
 Legend:



Removed from v.1.24
 


changed lines


 
Added in v.1.25
-Removed from v.1.24
+Added in v.1.25

	ViewVC Help
Powered by ViewVC 1.1.13