/[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.38		Revision 1.68
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.38 2005/04/13 14:12:19 neysx Exp $ -->	2	<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.68 2008/03/09 13:13:15 neysx 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>
6	<title>Gentoo Linux XML Guide</title>	6	<title>Gentoo GuideXML Guide</title>
7		7
		8	<author title="Author">
		9	<mail link="neysx"/>
		10	</author>
8	<author title="Author">	11	<author title="Author">
9	<mail link="drobbins@gentoo.org">Daniel Robbins</mail>	12	<mail link="drobbins@gentoo.org">Daniel Robbins</mail>
10	</author>	13	</author>
11	<author title="Author"><!-- zhen@gentoo.org -->	14	<author title="Author"><!-- zhen@gentoo.org -->
12	John P. Davis	15	John P. Davis
…		…
15	<mail link="peesh@gentoo.org">Jorge Paulo</mail>	18	<mail link="peesh@gentoo.org">Jorge Paulo</mail>
16	</author>	19	</author>
17	<author title="Editor">	20	<author title="Editor">
18	<mail link="swift@gentoo.org">Sven Vermeulen</mail>	21	<mail link="swift@gentoo.org">Sven Vermeulen</mail>
19	</author>	22	</author>
20	<author title="Editor">
21	<mail link="neysx@gentoo.org">Xavier Neys</mail>
22	</author>
23		23
24	<abstract>	24	<abstract>
25	This guide shows you how to compose web documentation using the new lightweight	25	This guide shows you how to compose web documentation using the new lightweight
26	Gentoo GuideXML syntax. This syntax is the official format for Gentoo Linux	26	Gentoo GuideXML syntax. This syntax is the official format for Gentoo
27	documentation, and this document itself was created using GuideXML. This guide	27	documentation, and this document itself was created using GuideXML. This guide
28	assumes a basic working knowledge of XML and HTML.	28	assumes 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.5 -->
33	<license/>	33	<license/>
34		34
35	<version>2.15</version>	35	<version>9</version>
36	<date>2005-04-13</date>	36	<date>2008-03-09</date>
37		37
38	<chapter>	38	<chapter>
39	<title>Guide basics</title>	39	<title>GuideXML basics</title>
40	<section>	40	<section>
41	<title>Guide XML design goals</title>	41	<title>GuideXML design goals</title>
42	<body>	42	<body>
43		43
44	<p>	44	<p>
45	The guide XML syntax is lightweight yet expressive, so that it is easy to	45	The guideXML syntax is lightweight yet expressive, so that it is easy to
46	learn yet also provides all the features we need for the creation of web	46	learn yet also provides all the features we need for the creation of web
47	documentation. The number of tags is kept to a minimum -- just those we need.	47	documentation. The number of tags is kept to a minimum -- just those we need.
48	This makes it easy to transform guide into other formats, such as DocBook	48	This makes it easy to transform guide into other formats, such as DocBook
49	XML/SGML or web-ready HTML.	49	XML/SGML or web-ready HTML.
50	</p>	50	</p>
51		51
52	<p>	52	<p>
53	The goal is to make it easy to <e>create</e> and <e>transform</e> guide XML	53	The goal is to make it easy to <e>create</e> and <e>transform</e> guideXML
54	documents.	54	documents.
55	</p>	55	</p>
56		56
57	</body>	57	</body>
58	</section>	58	</section>
…		…
60	<title>Further Resources</title>	60	<title>Further Resources</title>
61	<body>	61	<body>
62		62
63	<p>	63	<p>
64	If you are planning on contributing documentation to Gentoo, or you want to	64	If you are planning on contributing documentation to Gentoo, or you want to
65	test GuideXML, please read the <uri	65	test GuideXML, please read our <uri
66	link="/proj/en/gdp/doc/doc-tipsntricks.xml">Tips and Tricks</uri> which	66	link="/proj/en/gdp/doc/doc-tipsntricks.xml">Doc Tips 'n' Tricks</uri> guide
67	contains tips and tricks for documentation development.	67	which contains tips and tricks for documentation development.
		68	</p>
		69
		70	<p>
		71	You may want to look at the <uri link="?passthru=1">XML source</uri> of this
		72	document while you read it.
68	</p>	73	</p>
69		74
70	</body>	75	</body>
71	</section>	76	</section>
72	</chapter>	77	</chapter>
73		78
74	<chapter>	79	<chapter>
75	<title>Guide XML</title>	80	<title>GuideXML</title>
76	<section>	81	<section>
77	<title>Basic structure</title>	82	<title>Basic structure</title>
78	<body>	83	<body>
79		84
80	<p>	85	<p>
81	Let's start learning the GuideXML syntax. We'll start with the the initial	86	Let's start learning the GuideXML syntax. We'll start with the the initial
82	tags used in a GuideXML document:	87	tags used in a GuideXML document:
83	</p>	88	</p>
84		89
85	<pre caption="The initial part of a guide XML document">	90	<pre caption="The initial part of a guide XML document">
86	<?xml version='1.0' encoding="UTF-8"?>	91	<?xml version="1.0" encoding="UTF-8"?>
87	<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">	92	<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
		93	<!-- $Header$ -->
		94
88	<guide link="<i>relative/link/to/your/guide.xml</i>" lang="<i>en</i>">	95	<guide link="<i>/doc/en/guide.xml</i>" lang="<i>en</i>">
89	<title><i>Gentoo Linux Documentation Guide</i></title>	96	<title><i>Gentoo Documentation Guide</i></title>
		97
90	<author title="<i>Author</i>">	98	<author title="<i>Author</i>">
91	<mail link="<i>yourname@gentoo.org</i>"><i>Your Name</i></mail>	99	<mail link="<i>yourname@gentoo.org</i>"><i>Your Name</i></mail>
92	</author>	100	</author>
93		101
94	<abstract>	102	<abstract>
95	<i>This guide shows you how to compose web documentation using	103	<i>This guide shows you how to compose web documentation using
96	our new lightweight Gentoo GuideXML syntax. This syntax is the official	104	our new lightweight Gentoo GuideXML syntax. This syntax is the official
97	format for Gentoo Linux web documentation, and this document itself was created	105	format for Gentoo web documentation, and this document itself was created
98	using GuideXML.</i>	106	using GuideXML.</i>
99	</abstract>	107	</abstract>
100		108
101	<!-- The content of this document is licensed under the CC-BY-SA license -->	109	<!-- The content of this document is licensed under the CC-BY-SA license -->
102	<!-- See http://creativecommons.org/licenses/by-sa/2.0 -->	110	<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
103	<license/>	111	<license/>
104		112
105	<version><i>1.0</i></version>	113	<version><i>1.0</i></version>
106	<date><i>2004-12-25</i></date>	114	<date><i>2004-12-25</i></date>
107	</pre>	115	</pre>
108		116
109	<p>	117	<p>
110	On the first, line, we see the requisite tag that identifies this as an XML	118	On the first lines, we see the requisite tag that identifies this as an XML
111	document. Following it, there's a <c><guide></c> tag -- the entire	119	document and specifies its DTD. The <c><!-- $Header$ --></c> line
		120	will be automatically modified by the CVS server and helps to track revisions.
		121	Next, there's a <c><guide></c> tag -- the entire guide document is
112	guide document is enclosed within a <c><guide> </guide></c> pair.	122	enclosed within a <c><guide> </guide></c> pair.
		123	<br/>
113	The <c>link</c> attribute is compulsory and should preferably contain the	124	The <c>link</c> attribute is optional and should preferably contain the
114	relative path to the document even though the file name alone will work. It is	125	absolute path to the document relatively to the document root even though the
115	mainly used to generate a link to a printer-friendly version of your document.	126	file name alone will work. It is only used to generate a link to a
116	If you use a wrong value, the link to the printable version will either not	127	printer-friendly version of your document and check whether a translation is
117	work or point to a wrong document. The <c>lang</c> attribute can be used to	128	up-to-date. Our XSL back-engine passes the actual path to our XSL stylesheet.
118	specify the language code of your document. It is used to format the date and	129	The link attribute is only used as a fall-back value in case the XML is
119	insert strings like "<e>Note</e>", "<e>Content</e>", etc. in the specified	130	processed by other means.
120	language. The default is English.	131	<br/>
		132	The <c>lang</c> attribute should be used to specify the language code of your
		133	document. It is used to format the date and insert strings like "<e>Note</e>",
		134	"<e>Content</e>", etc. in the specified language. The default is English.
121	</p>	135	</p>
122		136
123	<p>	137	<p>
124	Next, there's a <c><title></c> tag, used to set the title for the entire	138	Next, there's a <c><title></c> tag, used to set the title for the entire
125	guide document.	139	guide document.
126	</p>	140	</p>
127		141
128	<p>	142	<p>
129	Then, we come to the <c><author></c> tags, which contain information	143	Then, we come to the <c><author></c> tags, which contain information
130	about the various authors of the document. Each <c><author></c> tag	144	about the various authors of the document. Each <c><author></c> tag
131	allows for an optional <c>title=</c> element, used to specify the author's	145	allows for an optional <c>title</c> element, used to specify the author's
132	relationship to the document (author, co-author, editor, etc.). In this	146	relationship to the document (author, co-author, editor, etc.). In this
133	particular example, the authors' names are enclosed in another tag -- a	147	particular example, the authors' names are enclosed in another tag -- a
134	<c><mail></c> tag, used to specify an email address for this particular	148	<c><mail></c> tag, used to specify an email address for this particular
135	person. The <c><mail></c> tag is optional and can be omitted, and no	149	person. The <c><mail></c> tag is optional and can be omitted, and at
136	more than one <c><author></c> element is required per guide document.	150	least one <c><author></c> element is required per guide document.
137	</p>	151	</p>
138		152
139	<p>	153	<p>
140	Next, we come to the <c><abstract></c>, <c><version></c> and	154	Next, we come to the <c><abstract></c>, <c><version></c> and
141	<c><date></c> tags, used to specify a summary of the document, the	155	<c><date></c> tags, used to specify a summary of the document, the
…		…
143	respectively. Dates that are invalid or not in the YYYY-MM-DD format will	157	respectively. Dates that are invalid or not in the YYYY-MM-DD format will
144	appear verbatim in the rendered document.	158	appear verbatim in the rendered document.
145	</p>	159	</p>
146		160
147	<p>	161	<p>
148	This rounds out the tags that should appear at the beginning of a guide	162	This sums up the tags that should appear at the beginning of a guide document.
149	document. Besides the <c><title></c> and <c><mail></c> tags, these	163	Besides the <c><title></c> and <c><mail></c> tags, these tags
150	tags shouldn't appear anywhere else except immediately inside the	164	shouldn't appear anywhere else except immediately inside the
151	<c><guide></c> tag, and for consistency it's recommended (but not	165	<c><guide></c> tag, and for consistency it's recommended (but not
152	required) that these tags appear before the content of the document.	166	required) that these tags appear before the content of the document.
153	</p>	167	</p>
154		168
155	<p>	169	<p>
156	Finally we have the <c><license/></c> tag, used to publish the document	170	Finally we have the <c><license/></c> tag, used to publish the document
157	under the <uri link="http://creativecommons.org/licenses/by-sa/2.0/">Creative	171	under the <uri link="http://creativecommons.org/licenses/by-sa/2.5/">Creative
158	Commons - Attribution / Share Alike</uri> license as required by the <uri	172	Commons - Attribution / Share Alike</uri> license as required by the <uri
159	link="/proj/en/gdp/doc/doc-policy.xml">Documentation Policy</uri>.	173	link="/proj/en/gdp/doc/doc-policy.xml">Documentation Policy</uri>.
160	</p>	174	</p>
161		175
162	</body>	176	</body>
…		…
202	content of this particular section. We'll look at the tags that are allowed	216	content of this particular section. We'll look at the tags that are allowed
203	inside a <c><body></c> element in a bit.	217	inside a <c><body></c> element in a bit.
204	</p>	218	</p>
205		219
206	<note>	220	<note>
207	A <c><guide></c> element can contain multiple <c><chapter></c>	221	A <c><guide></c> element must contain at least one <c><chapter></c>
208	elements, and a <c><chapter></c> can contain multiple	222	elements, a <c><chapter></c> must contain at least one
209	<c><section></c> elements. However, a <c><section></c>	223	<c><section></c> elements and a <c><section></c> element must
210	element can only contain one <c><body></c> element.	224	contain at least one <c><body></c> element.
211	</note>	225	</note>
212		226
213	</body>	227	</body>
214	</section>	228	</section>
215	<section>	229	<section>
…		…
233	# <i>this is user input</i>	247	# <i>this is user input</i>
234		248
235	Make HTML/XML easier to read by using selective emphasis:	249	Make HTML/XML easier to read by using selective emphasis:
236	<foo><i>bar</i></foo>	250	<foo><i>bar</i></foo>
237		251
238	<comment>(This is how to insert an inline note into the code block)</comment>	252	<comment>(This is how to insert a comment into a code block)</comment>
239	</pre>	253	</pre>
240		254
241	<note>	255	<note>
242	This is a note.	256	This is a note.
243	</note>	257	</note>
…		…
255	Now, here's how the <c><body></c> element above is rendered:	269	Now, here's how the <c><body></c> element above is rendered:
256	</p>	270	</p>
257		271
258	<p>	272	<p>
259	This is a paragraph. <path>/etc/passwd</path> is a file.	273	This is a paragraph. <path>/etc/passwd</path> is a file.
260	<uri>http://forums.gentoo.org</uri> is my favorite website.	274	<uri>http://forums.gentoo.org</uri> is my favorite web site.
261	Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now.	275	Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now.
262	</p>	276	</p>
263		277
264	<pre caption="Code Sample">	278	<pre caption="Code Sample">
265	This is text output or code.	279	This is text output or code.
266	# <i>this is user input</i>	280	# <i>this is user input</i>
267		281
268	Make HTML/XML easier to read by using selective emphasis:	282	Make HTML/XML easier to read by using selective emphasis:
269	<foo><i>bar</i></foo>	283	<foo><i>bar</i></foo>
270		284
271	<comment>(This is how to insert an inline note into the code block)</comment>	285	<comment>(This is how to insert a comment into a code block)</comment>
272	</pre>	286	</pre>
273		287
274	<note>	288	<note>
275	This is a note.	289	This is a note.
276	</note>	290	</note>
…		…
288	<section>	302	<section>
289	<title>The <body> tags</title>	303	<title>The <body> tags</title>
290	<body>	304	<body>
291		305
292	<p>	306	<p>
293	We introduced a lot of new tags in the previous section -- here's what you	307	We introduced a lot of new tags in the previous section -- here's what you need
294	need to know. The <c><p></c> (paragraph), <c><pre></c> (code	308	to know. The <c><p></c> (paragraph), <c><pre></c> (code block),
295	block), <c><note></c>, <c><warn></c> (warning) and	309	<c><note></c>, <c><warn></c> (warning) and <c><impo></c>
296	<c><impo></c> (important) tags all can contain one or more lines of text.	310	(important) tags all can contain one or more lines of text. Besides the
		311	<c><table></c>, <c><ul></c>, <c><ol></c> and
297	Besides the <c><table></c> element (which we'll cover in just a bit),	312	<c><dl></c> elements (which we'll cover in just a bit), these are the
298	these are the only tags that should appear immediately inside a	313	only tags that should appear immediately inside a <c><body></c> element.
299	<c><body></c> element. Another thing -- these tags <e>should not</e> be	314	Another thing -- these tags <e>should not</e> be stacked -- in other words,
300	stacked -- in other words, don't put a <c><note></c> element inside a	315	don't put a <c><note></c> element inside a <c><p></c> element. As
301	<c><p></c> element. As you might guess, the <c><pre></c> element	316	you might guess, the <c><pre></c> element preserves its whitespace
302	preserves its whitespace exactly, making it well-suited for code excerpts.	317	exactly, making it well-suited for code excerpts. You must name the
303	You can also name the <c><pre></c> tag:	318	<c><pre></c> tag with a <c>caption</c> attribute:
304	</p>	319	</p>
305		320
306	<pre caption="Named <pre>">	321	<pre caption="Named <pre>">
307	<pre caption = "Output of uptime">	322	<pre caption="Output of uptime">
308	# <i>uptime</i>	323	# <i>uptime</i>
309	16:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25	324	16:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25
310	</pre>	325	</pre>
311	</pre>	326	</pre>
312		327
313	</body>	328	</body>
314	</section>	329	</section>
315	<section>	330	<section>
316	<title><path>, <c> and <e></title>	331	<title>Epigraphs</title>
		332	<body>
		333
		334	<p by="Anonymous student">
		335	Delegates from the original 13 states formed the Contented Congress. Thomas
		336	Jefferson, a Virgin, and Benjamin Franklin were two singers of the Declaration
		337	of Independence. Franklin discovered electricity by rubbing two cats backwards
		338	and declared, "A horse divided against itself cannot stand." Franklin died in
		339	1790 and is still dead.
		340	</p>
		341
		342	<p>
		343	Epigraphs are sometimes used at the beginning of chapters to illustrate what is
		344	to follow. It is simply a paragraph with a <c>by</c> attribute that contains
		345	the signature.
		346	</p>
		347
		348	<pre caption="Short epigraph">
		349	<p by="Anonymous student">
		350	Delegates from the original 13 states formed the...
		351	</p>
		352	</pre>
		353
317	<body>	354	</body>
		355	</section>
		356	<section>
		357	<title>
		358	<path>, <c>, <b>, <e>, <sub> and <sup>
		359	</title>
		360	<body>
318		361
319	<p>	362	<p>
320	The <c><path></c>, <c><c></c> and <c><e></c> elements can	363	The <c><path></c>, <c><c></c>, <c><b></c>, <c><e></c>,
321	be used inside any child <c><body></c> tag, except for	364	<c><sub></c> and <c><sup></c> elements can be used inside any child
322	<c><pre></c>.	365	<c><body></c> tag, except for <c><pre></c>.
323	</p>	366	</p>
324		367
325	<p>	368	<p>
326	The <c><path></c> element is used to mark text that refers to an	369	The <c><path></c> element is used to mark text that refers to an
327	<e>on-disk file</e> -- either an <e>absolute or relative path</e>, or a	370	<e>on-disk file</e> -- either an <e>absolute or relative path</e>, or a
328	<e>simple filename</e>. This element is generally rendered with a monospaced	371	<e>simple filename</e>. This element is generally rendered with a mono spaced
329	font to offset it from the standard paragraph type.	372	font to offset it from the standard paragraph type.
330	</p>	373	</p>
331		374
332	<p>	375	<p>
333	The <c><c></c> element is used to mark up a <e>command</e> or <e>user	376	The <c><c></c> element is used to mark up a <e>command</e> or <e>user
…		…
343	the use of unnecessary double-quotes makes a document more readable -- and	386	the use of unnecessary double-quotes makes a document more readable -- and
344	adorable!	387	adorable!
345	</p>	388	</p>
346		389
347	<p>	390	<p>
		391	As you might have guessed, <c><b></c> is used to <b>boldface</b> some
		392	text.
		393	</p>
		394
		395	<p>
348	<c><e></c> is used to apply emphasis to a word or phrase; for example:	396	<c><e></c> is used to apply emphasis to a word or phrase; for example:
349	I <e>really</e> should use semicolons more often. As you can see, this text is	397	I <e>really</e> should use semicolons more often. As you can see, this text is
350	offset from the regular paragraph type for emphasis. This helps to give your	398	offset from the regular paragraph type for emphasis. This helps to give your
351	prose more <e>punch</e>!	399	prose more <e>punch</e>!
352	</p>	400	</p>
353		401
		402	<p>
		403	The <c><sub></c> and <c><sup></c> elements are used to specify
		404	<sub>subscript</sub> and <sup>superscript</sup>.
		405	</p>
		406
		407	</body>
		408	</section>
		409	<section>
		410	<title>Code samples and colour-coding</title>
		411	<body>
		412
		413	<p>
		414	To improve the readability of code samples, the following tags are allowed
		415	inside <c><pre></c> blocks:
		416	</p>
		417
		418	<dl>
		419	<dt><c><i></c></dt>
		420	<dd>Distinguishes user input from displayed text</dd>
		421	<dt><c><comment></c></dt>
		422	<dd>Comments relevant to the action(s) that appear after the comment</dd>
		423	<dt><c><keyword></c></dt>
		424	<dd>Denotes a keyword in the language used in the code sample
		425	</dd>
		426	<dt><c><ident></c></dt>
		427	<dd>Used for an identifier
		428	</dd>
		429	<dt><c><const></c></dt>
		430	<dd>Used for a constant
		431	</dd>
		432	<dt><c><stmt></c></dt>
		433	<dd>Used for a statement
		434	</dd>
		435	<dt><c><var></c></dt>
		436	<dd>Used for a variable
		437	</dd>
		438	</dl>
		439
		440	<note>
		441	Remember that all leading and trailing spaces, and line breaks in
		442	<c><pre></c> blocks will appear in the displayed html page.
		443	</note>
		444
		445	<p>
		446	Sample colour-coded <c><pre></c> block:
		447	</p>
		448
		449	<pre caption="My first ebuild">
		450	<comment># Copyright 1999-2006 <b>Gentoo Foundation</b>
		451	# Distributed under the terms of the GNU General Public License v2
		452	# $Header: $</comment>
		453
		454	<ident>DESCRIPTION</ident>=<const>"Exuberant ctags generates tags files for quick source navigation"</const>
		455	<ident>HOMEPAGE</ident>=<const>"http://ctags.sourceforge.net"</const>
		456	<ident>SRC_URI</ident>=<const>"mirror://sourceforge/ctags/<var>${P}</var>.tar.gz"</const>
		457
		458	<ident>LICENSE</ident>=<const>"GPL-2"</const>
		459	<ident>SLOT</ident>=<const>"0"</const>
		460	<ident>KEYWORDS</ident>=<const>"~mips ~sparc ~x86"</const>
		461	<ident>IUSE</ident>=<const>""</const>
		462
		463	<stmt>src_compile()</stmt> {
		464	<keyword>econf</keyword> --with-posix-regex \|\| <keyword>die</keyword> <const>"econf failed"</const>
		465	<keyword>emake</keyword> \|\| <keyword>die</keyword> <const>"emake failed"</const>
		466	}
		467
		468	<stmt>src_install()</stmt> {
		469	<keyword>make</keyword> <ident>DESTDIR</ident>="<var>${D}</var>" install \|\| <keyword>die</keyword> <const>"install failed"</const>
		470
		471	<keyword>dodoc</keyword> FAQ NEWS README
		472	<keyword>dohtml</keyword> EXTENDING.html ctags.html
		473	}
		474	</pre>
		475
354	</body>	476	</body>
355	</section>	477	</section>
356	<section>	478	<section>
357	<title><mail> and <uri></title>	479	<title><mail> and <uri></title>
358	<body>	480	<body>
359		481
360	<p>	482	<p>
361	We've taken a look at the <c><mail></c> tag earlier; it's used to link	483	We've taken a look at the <c><mail></c> tag earlier; it's used to link
362	some text with a particular email address, and takes the form <c><mail	484	some text with a particular email address, and takes the form <c><mail
363	link="foo@bar.com">Mr. Foo Bar</mail></c>.	485	link="foo.bar@example.com">Mr. Foo Bar</mail></c>. If you want to display the
		486	email address, you can use <c><mail>foo.bar@example.com</mail></c>, this
		487	would be displayed as <mail>foo.bar@example.com</mail>.
		488	</p>
		489
		490	<p>
		491	Shorter forms make it easier to use names and emails of Gentoo developers. Both
		492	<c><mail>neysx</mail></c> and <c><mail link="neysx"/></c>
		493	would appear as <mail>neysx</mail>. If you want to use a Gentoo dev's email
		494	with a different content than his full name, use the second form with some
		495	content. For instance, use a dev's first name: <c><mail
		496	link="neysx">Xavier</mail></c> appears as <mail
		497	link="neysx">Xavier</mail>.
		498	<br/>
		499	This is particularly useful when you want to name a developer whose name
		500	contains "funny" characters that you can't type.
364	</p>	501	</p>
365		502
366	<p>	503	<p>
367	The <c><uri></c> tag is used to point to files/locations on the Internet.	504	The <c><uri></c> tag is used to point to files/locations on the Internet.
368	It has two forms -- the first can be used when you want to have the actual URI	505	It has two forms -- the first can be used when you want to have the actual URI
369	displayed in the body text, such as this link to	506	displayed in the body text, such as this link to
370	<uri>http://forums.gentoo.org</uri>. To create this link, I typed	507	<uri>http://forums.gentoo.org/</uri>. To create this link, I typed
371	<c><uri>http://forums.gentoo.org</uri></c>. The alternate form is	508	<c><uri>http://forums.gentoo.org/</uri></c>. The alternate form is
372	when you want to associate a URI with some other text -- for example, <uri	509	when you want to associate a URI with some other text -- for example, <uri
373	link="http://forums.gentoo.org">the Gentoo Forums</uri>. To create <e>this</e>	510	link="http://forums.gentoo.org/">the Gentoo Forums</uri>. To create
374	link, I typed <c><uri link="http://forums.gentoo.org">the Gentoo	511	<e>this</e> link, I typed <c><uri link="http://forums.gentoo.org/">the
375	Forums</uri></c>. You don't need to write <c>http://www.gentoo.org/</c>	512	Gentoo Forums</uri></c>. You don't need to write
376	to link to other parts of the Gentoo website. For instance, a link to the <uri	513	<c>http://www.gentoo.org/</c> to link to other parts of the Gentoo web site.
377	link="/doc/en/">documentation main index</uri> should be simply <c><uri	514	For instance, a link to the <uri link="/doc/en/">documentation main index</uri>
378	link="/doc/en/index.xml">documentation main index</uri></c>. You can	515	should be simply <c><uri link="/doc/en/index.xml">documentation main
379	even omit <c>index.xml</c> when you link to a directory index, e.g. <c><uri	516	index</uri></c>. You can even omit <c>index.xml</c> when you link to a
380	link="/doc/en/">documentation main index</uri></c>.	517	directory index, e.g. <c><uri link="/doc/en/">documentation main
		518	index</uri></c>. Leaving the trailing slash saves an extra HTTP request.
		519	</p>
		520
		521	<p>
		522	You should not use a <c><uri></c> tag with a <c>link</c> attribute that
		523	starts with <c>mailto:</c>. In this case, use a <c><mail></c> tag.
		524	</p>
		525
		526	<p>
		527	Please avoid the <uri link="http://en.wikipedia.org/wiki/Click_here">click here
		528	syndrome</uri> as recommended by the <uri
		529	link="http://www.w3.org/QA/Tips/noClickHere">W3C</uri>.
381	</p>	530	</p>
382		531
383	</body>	532	</body>
384	</section>	533	</section>
385	<section>	534	<section>
…		…
387	<body>	536	<body>
388		537
389	<p>	538	<p>
390	Here's how to insert a figure into a document -- <c><figure	539	Here's how to insert a figure into a document -- <c><figure
391	link="mygfx.png" short="my picture" caption="my favorite picture of all	540	link="mygfx.png" short="my picture" caption="my favorite picture of all
392	time"/></c>. The <c>link=</c> attribute points to the actual graphic image,	541	time"/></c>. The <c>link</c> attribute points to the actual graphic image,
393	the <c>short=</c> attribute specifies a short description (currently used for	542	the <c>short</c> attribute specifies a short description (currently used for
394	the image's HTML <c>alt=</c> attribute), and a caption. Not too difficult	543	the image's HTML <c>alt</c> attribute), and a caption. Not too difficult
395	:) We also support the standard HTML-style <img src="foo.gif"/> tag	544	:) We also support the standard HTML-style <img src="foo.gif"/> tag
396	for adding images without captions, borders, etc.	545	for adding images without captions, borders, etc.
397	</p>	546	</p>
398		547
399	</body>	548	</body>
400	</section>	549	</section>
401	<section>	550	<section>
402	<title>Tables and lists</title>	551	<title>Tables</title>
403	<body>	552	<body>
404		553
405	<p>	554	<p>
406	Guide supports a simplified table syntax similar to that of HTML. To start	555	GuideXML supports a simplified table syntax similar to that of HTML. To start a
407	a table, use a <c><table></c> tag. Start a row with a <c><tr></c>	556	table, use a <c><table></c> tag. Start a row with a <c><tr></c>
408	tag. However, for inserting actual table data, we <e>don't</e> support the	557	tag. However, for inserting actual table data, we <e>don't</e> support the HTML
409	HTML <td> tag; instead, use the <c><th></c> if you are inserting a	558	<td> tag; instead, use the <c><th></c> if you are inserting a
410	header, and <c><ti></c> if you are inserting a normal informational	559	header, and <c><ti></c> if you are inserting a normal informational
411	block. You can use a <c><th></c> anywhere you can use a <c><ti></c>	560	block. You can use a <c><th></c> anywhere you can use a <c><ti></c>
412	-- there's no requirement that <c><th></c> elements appear only in the	561	-- there's no requirement that <c><th></c> elements appear only in the
413	first row. Currently, these tags don't support any attributes, but some will	562	first row.
414	be added (such as a <c>caption=</c> attribute for <c><table></c>) soon.
415	</p>
416
417	<p>	563	</p>
		564
		565	<p>
		566	Besides, both table headers (<c><th></c>) and table items
		567	(<c><ti></c>) accept the <c>colspan</c> and <c>rowspan</c> attributes to
		568	span their content across rows, columns or both.
		569	</p>
		570
		571	<p>
		572	Furthermore, table cells (<c><ti></c> & <c><th></c>) can be
		573	right-aligned, left-aligned or centered with the <c>align</c> attribute.
		574	</p>
		575
		576	<table>
		577	<tr>
		578	<th align="center" colspan="4">This title spans 4 columns</th>
		579	</tr>
		580	<tr>
		581	<th rowspan="6">This title spans 6 rows</th>
		582	<ti>Item A1</ti>
		583	<ti>Item A2</ti>
		584	<ti>Item A3</ti>
		585	</tr>
		586	<tr>
		587	<ti align="center">Item B1</ti>
		588	<th colspan="2" rowspan="2" align="right">Blocky 2x2 title</th>
		589	</tr>
		590	<tr>
		591	<ti align="right">Item C1</ti>
		592	</tr>
		593	<tr>
		594	<ti colspan="3" align="center">Item D1..D3</ti>
		595	</tr>
		596	<tr>
		597	<ti rowspan="2">Item E1..F1</ti>
		598	<ti colspan="2" align="right">Item E2..E3</ti>
		599	</tr>
		600	<tr>
		601	<ti colspan="2" align="right">Item F2..F3</ti>
		602	</tr>
		603	</table>
		604
		605	</body>
		606	</section>
		607	<section>
		608	<title>Lists</title>
		609	<body>
		610
		611	<p>
418	To create ordered or unordered lists, simply use the HTML-style	612	To create ordered or unordered lists, simply use the XHTML-style
419	<c><ol></c>, <c><ul></c> and <c><li></c> tags. List tags	613	<c><ol></c>, <c><ul></c> and <c><li></c> tags. Lists may only
420	should only appear inside a <c><body></c>, <c><ul></c> or	614	appear inside the <c><body></c> and <c><li></c> tags which means
421	<c><ol></c> tag.	615	that you can have lists inside lists. Don't forget that you are writing XML and
		616	that you must close all tags including list items unlike in HTML.
		617	</p>
		618
422	</p>	619	<p>
		620	Definition lists (<c><dl></c>) are also supported. Please note that
		621	neither the definition term tag (<c><dt></c>) nor the definition data tag
		622	(<c><dd></c>) accept any other block level tag such as paragraphs or
		623	admonitions. A definition list comprises:
		624	</p>
		625
		626	<dl>
		627	<dt><c><dl></c></dt>
		628	<dd>A <b>D</b>efinition <b>L</b>ist Tag containing</dd>
		629	<dt><c><dt></c></dt>
		630	<dd>Pairs of <b>D</b>efinition <b>T</b>erm Tags</dd>
		631	<dt><c><dd></c></dt>
		632	<dd>and <b>D</b>efinition <b>D</b>ata Tags</dd>
		633	</dl>
		634
		635	<p>
		636	The following list copied from <uri
		637	link="http://www.w3.org/TR/REC-html40/struct/lists.html">w3.org</uri> shows
		638	that a definition list can contain ordered and unordered lists. It may not
		639	contain another definition list though.
		640	</p>
		641
		642	<dl>
		643	<dt><b>The ingredients:</b></dt>
		644	<dd>
		645	<ul>
		646	<li>100 g. flour</li>
		647	<li>10 g. sugar</li>
		648	<li>1 cup water</li>
		649	<li>2 eggs</li>
		650	<li>salt, pepper</li>
		651	</ul>
		652	</dd>
		653	<dt><b>The procedure:</b></dt>
		654	<dd>
		655	<ol>
		656	<li>Mix dry ingredients thoroughly</li>
		657	<li>Pour in wet ingredients</li>
		658	<li>Mix for 10 minutes</li>
		659	<li>Bake for one hour at 300 degrees</li>
		660	</ol>
		661	</dd>
		662	<dt><b>Notes:</b></dt>
		663	<dd>The recipe may be improved by adding raisins</dd>
		664	</dl>
423		665
424	</body>	666	</body>
425	</section>	667	</section>
426	<section>	668	<section>
427	<title>Intra-document references</title>	669	<title>Intra-document references</title>
428	<body>	670	<body>
429		671
430	<p>	672	<p>
431	Guide makes it really easy to reference other parts of the document using	673	GuideXML makes it really easy to reference other parts of the document using
432	hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter	674	hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter
433	One</uri> by typing <c><uri link="#doc_chap1">Chapter	675	One</uri> by typing <c><uri link="#doc_chap1">Chapter
434	One</uri></c>. To point to <uri link="#doc_chap1_sect2">section two of	676	One</uri></c>. To point to <uri link="#doc_chap1_sect2">section two of
435	Chapter One</uri>, type <c><uri link="#doc_chap1_sect2">section two of	677	Chapter One</uri>, type <c><uri link="#doc_chap1_sect2">section two of
436	Chapter One</uri></c>. To refer to figure 3 in chapter 1, type <c><uri	678	Chapter One</uri></c>. To refer to figure 3 in chapter 1, type
437	link="doc_chap1_fig3">figure 1.3</uri></c>. Or, to refer to <uri	679	<c><uri link="#doc_chap1_fig3">figure 1.3</uri></c>. Or, to refer
438	link="#doc_chap2_pre2">code listing 2 in chapter 2</uri>, type <c><uri	680	to <uri link="#doc_chap2_pre2">code listing 2 in chapter 2</uri>, type
439	link="doc_chap2_pre2">code listing 2.2</uri></c>. We'll be	681	<c><uri link="#doc_chap2_pre2">code listing 2.2</uri></c>.
440	adding other auto-link abilities (such as table support) soon.
441	</p>	682	</p>
442		683
443	<p>	684	<p>
444	However, some guides change often and using such "counting" can lead to broken	685	However, some guides change often and using such "counting" can lead to broken
445	links. In order to cope with this, you can define a name for a	686	links. In order to cope with this, you can define a name for a
446	<c><chapter></c> or <c><section></c> by using the <c>id</c>	687	<c><chapter></c>, <c><section></c> or a <c><tr></c> by using
447	attribute, and then point to that attribute, like this:	688	the <c>id</c> attribute, and then point to that attribute, like this:
448	</p>	689	</p>
449		690
450	<pre caption="Using the id attribute">	691	<pre caption="Using the id attribute">
451	<chapter id="foo">	692	<chapter id="foo">
452	<title>This is foo!</title>	693	<title>This is foo!</title>
…		…
456	</p>	697	</p>
457	</pre>	698	</pre>
458		699
459	</body>	700	</body>
460	</section>	701	</section>
		702	<section>
		703	<title>Disclaimers and obsolete documents</title>
		704	<body>
		705
		706	<p>
		707	A <c>disclaimer</c> attribute can be applied to guides and handbooks to display
		708	a predefined disclaimer at the top of the document. The available disclaimers
		709	are:
		710	</p>
		711
		712	<ul>
		713	<li>
		714	<b>articles</b> is used for <uri link="/doc/en/articles/">republished
		715	articles</uri>
		716	</li>
		717	<li>
		718	<b>draft</b> is used to indicate a document is still being worked on and
		719	should not be considered official
		720	</li>
		721	<li>
		722	<b>oldbook</b> is used on old handbooks to indicate they are not maintained
		723	anymore
		724	</li>
		725	<li><b>obsolete</b> is used to mark a document as obsolete.</li>
		726	</ul>
		727
		728	<p>
		729	When marking a document as obsolete, you might want to add a link to a new
		730	version. The <c>redirect</c> attribute does just that. The user might be
		731	automatically redirected to the new page but you should not rely on that
		732	behaviour.
		733	</p>
		734
		735	<pre caption="Disclaimer sample">
		736	<?xml version="1.0" encoding="UTF-8"?>
		737	<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
		738	<!-- $Header$ -->
		739
		740	<guide disclaimer="obsolete" redirect="/doc/en/handbook/handbook-x86.xml">
		741	<title>Gentoo x86 Installation Guide</title>
		742
		743	<author title="Author">
		744	...
		745	</pre>
		746
		747	</body>
		748	</section>
		749	<section>
		750	<title>FAQs</title>
		751	<body>
		752
		753	<p>
		754	FAQ documents need to start with a list of questions with links to their
		755	answers. Creating such a list is both time-consuming and error-prone. The list
		756	can be created automatically if you use a <c>faqindex</c> element as the first
		757	chapter of your document. This element has the same structure as a
		758	<c>chapter</c> to allow some introductory text. The structure of the document
		759	is expected to be split into chapters (at least one chapter) containing
		760	sections, each section containing one question specified in its <c>title</c>
		761	element with the answer in its <c>body</c>. The FAQ index will appear as one
		762	section per chapter and one link per question.
		763	</p>
		764
		765	<p>
		766	A quick look at a <uri link="/doc/en/faq.xml">FAQ</uri> and <uri
		767	link="/doc/en/faq.xml?passthru=1">its source</uri> should make the above
		768	obvious.
		769	</p>
		770
		771	</body>
		772	</section>
461	</chapter>	773	</chapter>
462		774
463	<chapter>	775	<chapter>
		776	<title>Handbook Format</title>
		777	<section>
		778	<title>Guide vs Book</title>
		779	<body>
		780
		781	<p>
		782	For high-volume documentation, such as the <uri
		783	link="/doc/en/handbook/handbook-x86.xml?part=1">Installation Instructions</uri>, a
		784	broader format was needed. We designed a GuideXML-compatible enhancement that
		785	allows us to write modular and multi-page documentation.
		786	</p>
		787
		788	</body>
		789	</section>
		790	<section>
		791	<title>Main File</title>
		792	<body>
		793
		794	<p>
		795	The first change is the need for a "master" document. This document contains no
		796	real content, but links to the individual documentation modules. The syntax
		797	doesn't differ much from GuideXML:
		798	</p>
		799
		800	<pre caption="Example book usage">
		801	<?xml version='1.0' encoding='UTF-8'?>
		802	<!DOCTYPE book SYSTEM "/dtd/book.dtd">
		803	<!-- $Header$ -->
		804
		805	<<i>book</i>>
		806	<title>Example Book Usage</title>
		807
		808	<author...>
		809	...
		810	</author>
		811
		812	<abstract>
		813	...
		814	</abstract>
		815
		816	<!-- The content of this document is licensed under the CC-BY-SA license -->
		817	<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
		818	<license/>
		819
		820	<version>...</version>
		821	<date>...</date>
		822	</pre>
		823
		824	<p>
		825	So far no real differences (except for the <c><book></c> instead of
		826	<c><guide></c> tag). Instead of starting with the individual
		827	<c><chapter></c>s, you define a <c><part></c>, which is the
		828	equivalent of a separate part in a book:
		829	</p>
		830
		831	<pre caption="Defining a part">
		832	<part>
		833	<title>Part One</title>
		834	<abstract>
		835	...
		836	</abstract>
		837
		838	<comment>(Defining the several chapters)</comment>
		839	</part>
		840	</pre>
		841
		842	<p>
		843	Each part is accompanied by a <c><title></c> and an
		844	<c><abstract></c> which gives a small introduction to the part.
		845	</p>
		846
		847	<p>
		848	Inside each part, you define the individual <c><chapter></c>s. Each
		849	chapter <e>must</e> be a separate document. As a result it is no surprise that
		850	a special tag (<c><include></c>) is added to allow including the separate
		851	document.
		852	</p>
		853
		854	<pre caption="Defining a chapter">
		855	<chapter>
		856	<title>Chapter One</title>
		857
		858	<include href="path/to/chapter-one.xml"/>
		859
		860	</chapter>
		861	</pre>
		862
		863	</body>
		864	</section>
		865	<section>
		866	<title>Designing the Individual Chapters</title>
		867	<body>
		868
		869	<p>
		870	The content of an individual chapter is structured as follows:
		871	</p>
		872
		873	<pre caption="Chapter Syntax">
		874	<?xml version='1.0' encoding='UTF-8'?>
		875	<!DOCTYPE sections SYSTEM "/dtd/book.dtd">
		876	<!-- $Header$ -->
		877
		878	<!-- The content of this document is licensed under the CC-BY-SA license -->
		879	<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
		880
		881	<sections>
		882
		883	<abstract>
		884	This is a small explanation on chapter one.
		885	</abstract>
		886
		887	<version>...</version>
		888	<date>...</date>
		889
		890	<comment>(Define the several <section> and <subsection>)</comment>
		891
		892	</sections>
		893	</pre>
		894
		895	<p>
		896	Inside each chapter you can define <c><section></c>s (equivalent of
		897	<c><chapter></c> in a Guide) and <c><subsection></c>s (equivalent
		898	of <c><section></c> in a Guide).
		899	</p>
		900
		901	<p>
		902	Each individual chapter should have its own date and version elements. The
		903	latest date of all chapters and master document will be displayed when a user
		904	browses through all parts of the book.
		905	</p>
		906
		907	</body>
		908	</section>
		909	</chapter>
		910
		911	<chapter>
		912	<title>Advanced Handbook Features</title>
		913	<section>
		914	<title>Global Values</title>
		915	<body>
		916
		917	<p>
		918	Sometimes, the same values are repeated many times in several parts of a
		919	handbook. Global search and replace operations tend to forget some or introduce
		920	unwanted changes. Besides, it can be useful to define different values to be
		921	used in shared chapters depending on which handbook includes the chapter.
		922	</p>
		923
		924	<p>
		925	Global values can be defined in a handbook master file and used in all included
		926	chapters.
		927	</p>
		928
		929	<p>
		930	To define global values, add a <c><values></c> element to the handbook
		931	master file. Each value is then defined in a <c><key></c> element whose
		932	<c>id</c> attribute identifies the value, i.e. it is the name of your variable.
		933	The content of the <c><key></c> is its value.
		934	</p>
		935
		936	<p>
		937	The following example defines three values in a handbook master file:
		938	</p>
		939
		940	<pre caption="Define values in a handbook">
		941	<?xml version='1.0' encoding='UTF-8'?>
		942	<!DOCTYPE book SYSTEM "/dtd/book.dtd">
		943	<!-- $Header$ -->
		944
		945	<book>
		946	<title>Example Book Usage</title>
		947
		948	<i><values>
		949	<key id="arch">x86</key>
		950	<key id="min-cd-name">install-x86-minimal-2007.0-r1.iso</key>
		951	<key id="min-cd-size">57</key>
		952	</values></i>
		953
		954	<author...>
		955	...
		956	</author>
		957
		958	...
		959	</pre>
		960
		961	<p>
		962	The defined values can then be used throughout the handbook with the in-line
		963	<c><keyval id="key_id"/></c> element. Specify the name of the key in its
		964	<c>id</c> attribute, e.g. <keyval id="min-cd-name"/> would be replaced by
		965	"install-x86-minimal-2007.0-r1.iso" in our example.
		966	</p>
		967
		968	<pre caption="Using defined values">
		969	<p>
		970	The Minimal Installation CD is called <c><i><keyval id="min-cd-name"/></i></c>
		971	and takes up only <i><keyval id="min-cd-size"/></i> MB of diskspace. You can use this
		972	Installation CD to install Gentoo, but <e>only</e> with a working Internet
		973	connection.
		974	</p>
		975	</pre>
		976
		977	<p>
		978	To make life easier on our translators, only use actual values, i.e. content
		979	that does not need to be translated. For instance, we defined the
		980	<c>min-cd-size</c> value to <c>57</c> and not <c>57 MB</c>.
		981	</p>
		982
		983	</body>
		984	</section>
		985	<section>
		986	<title>Conditional Elements</title>
		987	<body>
		988
		989	<p>
		990	Chapters that are shared by several handbooks such as our <uri
		991	link="/doc/en/handbook/">Installation Handbooks</uri> often have small
		992	differences depending on which handbook includes them. Instead of adding
		993	content that is irrelevant to some handbooks, authors can add a condition to
		994	the following elements: <c><section></c>, <c><subsection></c>,
		995	<c><body></c>, <c><note></c>, <c><impo></c>,
		996	<c><warn></c>, <c><pre></c>, <c><p></c>,
		997	<c><table></c>, <c><tr></c>, <c><ul></c>, <c><ol></c>
		998	and <c><li></c>.
		999	</p>
		1000
		1001	<p>
		1002	The condition must be an <uri
		1003	link="http://en.wikipedia.org/wiki/XPath">XPATH</uri> expression that will be
		1004	evaluated when transforming the XML. If it evaluates to <c>true</c>, the
		1005	element is processed, if not, it is ignored. The condition is specified in a
		1006	<c>test</c> attribute.
		1007	</p>
		1008
		1009	<p>
		1010	The following example uses the <c>arch</c> value that is defined in each
		1011	handbook master file to condition some content:
		1012	</p>
		1013
		1014	<pre caption="Using conditional elements">
		1015	<body test="contains('AMD64 x86',func:keyval('arch'))">
		1016
		1017	<p>
		1018	This paragraph applies to both x86 and AMD64 architectures.
		1019	</p>
		1020
		1021	<p test="func:keyval('arch')='x86'">
		1022	This paragraph only applies to the x86 architecture.
		1023	</p>
		1024
		1025	<p test="func:keyval('arch')='AMD64'">
		1026	This paragraph only applies to the AMD64 architecture.
		1027	</p>
		1028
		1029	<p test="func:keyval('arch')='PPC'">
		1030	This paragraph will never be seen!
		1031	The whole body is skipped because of the first condition.
		1032	</p>
		1033
		1034	</body>
		1035
		1036	<body test="contains('AMD64 PPC64',func:keyval('arch'))">
		1037
		1038	<p>
		1039	This paragraph applies to the AMD64, PPC64 <comment>and PPC</comment> architectures because
		1040	the 'AMD64 PPC64' string does contain 'PPC'.
		1041	</p>
		1042
		1043	<note test="func:keyval('arch')='AMD64' or func:keyval('arch')='PPC64'">
		1044	This note only applies to the AMD64 and PPC64 architectures.
		1045	</note>
		1046
		1047	</body>
		1048	</pre>
		1049
		1050	</body>
		1051	</section>
		1052	</chapter>
		1053
		1054	<chapter id="codingstyle">
464	<title>Coding Style</title>	1055	<title>Coding Style</title>
465	<section>	1056	<section>
466	<title>Introduction</title>	1057	<title>Introduction</title>
467	<body>	1058	<body>
468		1059
469	<p>	1060	<p>
470	Since all Gentoo Documentation is a joint effort and several people will	1061	Since all Gentoo Documentation is a joint effort and several people will
471	most likely change existing documentation, a coding style is needed.	1062	most likely change existing documentation, a coding style is needed.
472	A coding style contains two sections. The first one is regarding	1063	A coding style contains two sections. The first one is regarding
473	internal coding - how the xml-tags are placed. The second one is	1064	internal coding - how the XML-tags are placed. The second one is
474	regarding the content - how not to confuse the reader.	1065	regarding the content - how not to confuse the reader.
475	</p>	1066	</p>
476		1067
477	<p>	1068	<p>
478	Both sections are described next.	1069	Both sections are described next.
…		…
488	<b>Newlines</b> must be placed immediately after <e>every</e>	1079	<b>Newlines</b> must be placed immediately after <e>every</e>
489	GuideXML-tag (both opening as closing), except for:	1080	GuideXML-tag (both opening as closing), except for:
490	<c><version></c>, <c><date></c>, <c><title></c>,	1081	<c><version></c>, <c><date></c>, <c><title></c>,
491	<c><th></c>, <c><ti></c>,	1082	<c><th></c>, <c><ti></c>,
492	<c><li></c>, <c><i></c>, <c><e></c>,	1083	<c><li></c>, <c><i></c>, <c><e></c>,
493	<c><uri></c>, <c><path></c>, <c><b></c>,	1084	<c><uri></c>, <c><path></c>, <c><b></c>, <c><c></c>,
494	<c><comment></c>, <c><mail></c>.	1085	<c><comment></c>, <c><mail></c>.
495	</p>	1086	</p>
496		1087
497	<p>	1088	<p>
498	<b>Blank lines</b> must be placed immediately after <e>every</e>	1089	<b>Blank lines</b> must be placed immediately after <e>every</e>
…		…
503	<c><impo></c> (opening tags only).	1094	<c><impo></c> (opening tags only).
504	</p>	1095	</p>
505		1096
506	<p>	1097	<p>
507	<b>Word-wrapping</b> must be applied at 80 characters except inside	1098	<b>Word-wrapping</b> must be applied at 80 characters except inside
508	<c><pre></c>. Only when there is no other choice can be deviated from	1099	<c><pre></c>. You may only deviate from this rule when there is no other
509	this rule (for instance when a URL exceeds the maximum amount of characters).	1100	choice (for instance when a URL exceeds the maximum amount of characters). The
510	The editor must then wrap whenever the first whitespace occurs.	1101	editor must then wrap whenever the first whitespace occurs. You should try to
511	</p>	1102	keep the <e>rendered</e> content of <c><pre></c> elements within 80
512		1103	columns to help console users.
513	<p>	1104	</p>
		1105
		1106	<p>
514	<b>Indentation</b> may not be used, except with the XML-constructs of which	1107	<b>Indentation</b> may not be used, except with the XML-constructs of which the
515	the parent XML-tags are <c><tr></c> (from <c><table></c>),	1108	parent XML-tags are <c><tr></c> (from <c><table></c>),
516	<c><ul></c>, <c><ol></c> and <c><author></c>. If indentation	1109	<c><ul></c>, <c><ol></c>, <c><dl></c>, and
517	is used, it <e>must</e> be two spaces for each indentation. That means <e>no</e>	1110	<c><author></c>. If indentation is used, it <e>must</e> be two spaces for
518	tabs and <e>not</e> more spaces.	1111	each indentation. That means <e>no tabs</e> and <e>not</e> more spaces.
519	</p>	1112	Besides, tabs are not allowed in GuideXML documents.
520
521	<p>	1113	</p>
		1114
		1115	<p>
522	In case word-wrapping happens in <c><ti></c>, <c><th></c> or	1116	In case word-wrapping happens in <c><ti></c>, <c><th></c>,
523	<c><li></c> constructs, indentation must be used for the content.	1117	<c><li></c> or <c><dd></c> constructs, indentation must be used for
		1118	the content.
524	</p>	1119	</p>
525		1120
526	<p>	1121	<p>
527	An example for indentation is:	1122	An example for indentation is:
528	</p>	1123	</p>
…		…
532	<tr>	1127	<tr>
533	<th>Foo</th>	1128	<th>Foo</th>
534	<th>Bar</th>	1129	<th>Bar</th>
535	</tr>	1130	</tr>
536	<tr>	1131	<tr>
537	<ti>This is an example for indentation.</ti>	1132	<ti>This is an example for indentation</ti>
538	<ti>	1133	<ti>
539	In case text cannot be shown within an 80-character wide line, you	1134	In case text cannot be shown within an 80-character wide line, you
540	must use indentation if the parent tag allows it.	1135	must use indentation if the parent tag allows it
541	</ti>	1136	</ti>
542	</tr>	1137	</tr>
543	</table>	1138	</table>
544		1139
545	<ul>	1140	<ul>
…		…
547	<li>Second option</li>	1142	<li>Second option</li>
548	</ul>	1143	</ul>
549	</pre>	1144	</pre>
550		1145
551	<p>	1146	<p>
552	<b>Attributes</b> may not have spaces in between the attribute, the	1147	<b>Attributes</b> may not have spaces in between the attribute, the "=" mark,
553	"=" mark, and the attribute value. As an example:	1148	and the attribute value. As an example:
554	</p>	1149	</p>
555		1150
556	<pre caption="Attributes">	1151	<pre caption="Attributes">
557	<comment>Wrong :</comment> <pre caption = "Attributes">	1152	<comment>Wrong :</comment> <pre caption = "Attributes">
558	<comment>Correct:</comment> <pre caption="Attributes">	1153	<comment>Correct:</comment> <pre caption="Attributes">
…		…
563	<section>	1158	<section>
564	<title>External Coding Style</title>	1159	<title>External Coding Style</title>
565	<body>	1160	<body>
566		1161
567	<p>	1162	<p>
568	Inside tables (<c><table></c>) and listings (<c><ul></c> and	1163	Inside tables (<c><table></c>) and listings (<c><ul></c>,
569	<c><ol></c>), periods (".") should not be used unless multiple	1164	<c><ol></c>) and <c><dl></c>, periods (".") should not be used
570	sentences are used. In that case, every sentence should end with a period (or	1165	unless multiple sentences are used. In that case, every sentence should end
571	other reading marks).	1166	with a period (or other reading marks).
572	</p>	1167	</p>
573		1168
574	<p>	1169	<p>
575	Every sentence, including those inside tables and listings, should start	1170	Every sentence, including those inside tables and listings, should start
576	with a capital letter.	1171	with a capital letter.
…		…
609	</body>	1204	</body>
610	</section>	1205	</section>
611	</chapter>	1206	</chapter>
612		1207
613	<chapter>	1208	<chapter>
614	<title>Handbook Format</title>
615	<section>
616	<title>Guide vs Book</title>
617	<body>
618
619	<p>
620	For high-volume documentation, such as the <uri
621	link="/doc/en/handbook/handbook-x86.xml?part=1">Installation Instructions</uri>, a
622	broader format was needed. We designed a GuideXML-compatible enhancement that
623	allows us to write modular and multi-page documentation.
624	</p>
625
626	</body>
627	</section>
628	<section>
629	<title>Main File</title>
630	<body>
631
632	<p>
633	The first change is the need for a "master" document. This document contains no
634	real content, but links to the individual documentation modules. The syntaxis
635	doesn't differ much from GuideXML:
636	</p>
637
638	<pre caption="Example book usage">
639	<?xml version='1.0' encoding='UTF-8'?>
640	<!DOCTYPE book SYSTEM "/dtd/book.dtd">
641
642	<<i>book</i> link="example.xml">
643	<title>Example Book Usage</title>
644
645	<author...>
646	...
647	</author>
648
649	<abstract>
650	...
651	</abstract>
652
653	<!-- The content of this document is licensed under the CC-BY-SA license -->
654	<!-- See http://creativecommons.org/licenses/by-sa/2.0 -->
655	<license/>
656
657	<version>...</version>
658	<date>...</date>
659	</pre>
660
661	<p>
662	So far no real differences (except for the <c><book></c> instead of
663	<c><guide></c> tag). Instead of starting with the individual
664	<c><chapter></c>'s, you define a <c><part></c>, which is the
665	equivalent of a separate part in a book:
666	</p>
667
668	<pre caption="Defining a part">
669	<part>
670	<title>Part One</title>
671	<abstract>
672	...
673	</abstract>
674
675	<comment>(Defining the several chapters)</comment>
676	</part>
677	</pre>
678
679	<p>
680	Each part is accompanied by a <c><title></c> and an
681	<c><abstract></c> which gives a small introduction to the part.
682	</p>
683
684	<p>
685	Inside each part, you define the individual <c><chapter></c>'s. Each
686	chapter <e>must</e> be a separate document. As a result it is no surprise that a
687	special tag (<c><include></c>) is added to allow including the separate
688	document.
689	</p>
690
691	<pre caption="Defining a chapter">
692	<chapter>
693	<title>Chapter One</title>
694	<abstract>
695	This is a small explanation on chapter one.
696	</abstract>
697
698	<include href="path/to/chapter-one.xml"/>
699
700	</chapter>
701	</pre>
702
703	</body>
704	</section>
705	<section>
706	<title>Designing the Individual Chapters</title>
707	<body>
708
709	<p>
710	The content of an individual chapter is structured as follows:
711	</p>
712
713	<pre caption="Chapter Syntax">
714	<?xml version='1.0' encoding='UTF-8'?>
715	<!DOCTYPE sections SYSTEM "/dtd/book.dtd">
716
717	<!-- The content of this document is licensed under the CC-BY-SA license -->
718	<!-- See http://creativecommons.org/licenses/by-sa/2.0 -->
719
720	<sections>
721
722	<version>...</version>
723	<date>...</date>
724
725	<comment>(Define the several <section> and <subsection>)</comment>
726
727	</sections>
728	</pre>
729
730	<p>
731	Inside each chapter you can define <c><section></c>'s (equivalent of
732	<c><chapter></c> in a Guide) and <c><subsection></c>'s (equivalent
733	of <c><section></c> in a Guide).
734	</p>
735
736	<p>
737	Each individual chapter should have its own date and version elements. The
738	latest date of all chapters and master document will be displayed when a user
739	browses through all parts of the book.
740	</p>
741
742	</body>
743	</section>
744	</chapter>
745
746	<chapter>
747	<title>Resources</title>	1209	<title>Resources</title>
748	<section>	1210	<section>
749	<title>Start writing</title>	1211	<title>Start writing</title>
750	<body>	1212	<body>
751		1213
752	<p>	1214	<p>
753	Guide has been specially designed to be "lean and mean" so that developers can	1215	GuideXML has been specially designed to be "lean and mean" so that developers
754	spend more time writing documentation and less time learning the actual XML	1216	can spend more time writing documentation and less time learning the actual XML
755	syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy"	1217	syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy"
756	to start writing quality Gentoo Linux documentation. You might be interested	1218	to start writing quality Gentoo documentation. You might be interested in our
757	in our <uri link="/proj/en/gdp/doc/doc-tipsntricks.xml">Documentation	1219	<uri link="/proj/en/gdp/doc/doc-tipsntricks.xml">Documentation Development Tips
758	Development Tips & Tricks</uri>. If you'd like to help (or have any	1220	& Tricks</uri>. If you'd like to help (or have any questions about
759	questions about guide), please post a message to the <mail	1221	GuideXML), please post a message to the <uri
760	link="gentoo-doc@gentoo.org">gentoo-doc mailing list</mail> stating what you'd	1222	link="/main/en/lists.xml">gentoo-doc mailing list</uri> stating what you'd like
761	like to tackle. Have fun!	1223	to tackle. Have fun!
762	</p>	1224	</p>
763		1225
764	</body>	1226	</body>
765	</section>	1227	</section>
766	</chapter>	1228	</chapter>

 Legend:



Removed from v.1.38
 


changed lines


 
Added in v.1.68
 Legend:



Removed from v.1.38
 


changed lines


 
Added in v.1.68
-Removed from v.1.38
+Added in v.1.68

	ViewVC Help
Powered by ViewVC 1.1.13