/[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.16		Revision 1.17
…		…
10	<author title="Author">	10	<author title="Author">
11	<mail link="zhen@gentoo.org">John P. Davis</mail>	11	<mail link="zhen@gentoo.org">John P. Davis</mail>
12	</author>	12	</author>
13	<author title="Editor">	13	<author title="Editor">
14	<mail link="peesh@gentoo.org">Jorge Paulo</mail>	14	<mail link="peesh@gentoo.org">Jorge Paulo</mail>
15	</author>	15	</author>
16		16
17	<license/>	17	<license/>
18	<abstract>	18	<abstract>
19	This guide shows you how to compose web documentation using the new lightweight	19	This guide shows you how to compose web documentation using the new lightweight
20	Gentoo GuideXML syntax. This syntax is the official format for Gentoo Linux	20	Gentoo GuideXML syntax. This syntax is the official format for Gentoo Linux
21	documentation, and this document itself was created using GuideXML. This guide	21	documentation, and this document itself was created using GuideXML. This guide
22	assumes a basic working knowledge of XML and HTML.	22	assumes 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>
36	The guide XML syntax is lightweight yet expressive, so that it is easy to	35	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	36	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.	37	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	38	This makes it easy to transform guide into other formats, such as DocBook
40	XML/SGML or web-ready HTML.	39	XML/SGML or web-ready HTML.
41	</p>	40	</p>
42		41
43	<p>	42	<p>
44	The goal is to make it easy to <e>create</e> and <e>transform</e> guide XML	43	The goal is to make it easy to <e>create</e> and <e>transform</e> guide XML
45	documents.	44	documents.
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>
56	Before we take a look at the guide syntax itself, it's helpful to know how	54	Before we take a look at the guide syntax itself, it's helpful to know how
57	guide XML is transformed into web-ready HTML. To do this, we use a special	55	guide XML is transformed into web-ready HTML. To do this, we use a special
58	file called <path>guide.xsl</path>, along with a command-line XSLT processing	56	file called <path>guide.xsl</path>, along with a command-line XSLT processing
59	tool (also called an "engine"). The <path>guide.xsl</path> file describes	57	tool (also called an "engine"). The <path>guide.xsl</path> file describes
60	exactly how to transform the contents of the source guide XML document to	58	exactly how to transform the contents of the source guide XML document to
61	create the target HTML file. The processing tool that Gentoo Linux uses	59	create the target HTML file. The processing tool that Gentoo Linux uses
62	is called <c>xsltproc</c>, which is found in the <i>libxslt</i> package.	60	is 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>
70	Now that we have the way, we need the means, so to speak. In other words,	68	Now that we have the way, we need the means, so to speak. In other words,
71	we need some Gentoo XML documents to transform. Gentoo has two types of tarballs	69	we need some Gentoo XML documents to transform. Gentoo has two types of tarballs
72	that are available for download:	70	that are available for download:
73	</p>	71	</p>
74		72
75	<p>	73	<p>
76	<b>The first type contains the entire up-to-date Gentoo Linux website</b>.	74	<b>The first type contains the entire up-to-date Gentoo Linux website</b>.
77	Included are our XSL templates, so if you are planning to transform any	75	Included are our XSL templates, so if you are planning to transform any
78	documentation, you will need this tarball. The tarball can be found <uri	76	documentation, you will need this tarball. The tarball can be found <uri
79	link="http://www.gentoo.org/dyn/arch/xml-guide-latest.tar.gz">here</uri>.	77	link="http://www.gentoo.org/dyn/arch/xml-guide-latest.tar.gz">here</uri>.
80	</p>	78	</p>
81		79
…		…
88	link="http://www.gentoo.org/dyn/doc-snapshots">here</uri>.	86	link="http://www.gentoo.org/dyn/doc-snapshots">here</uri>.
89	</p>	87	</p>
90		88
91	<p>	89	<p>
92	After the web tarball is downloaded and extracted, go to the directory where	90	After the web tarball is downloaded and extracted, go to the directory where
93	the tarball was extracted, and enter the <path>htdocs</path> directory. Browse	91	the tarball was extracted, and enter the <path>htdocs</path> directory. Browse
94	around and get comfortable with the layout, but note the <path>xsl</path> and	92	around and get comfortable with the layout, but note the <path>xsl</path> and
95	<path>doc</path> directories. As you might have guessed, the XSL stylesheets are	93	<path>doc</path> directories. As you might have guessed, the XSL stylesheets are
96	in <path>xsl</path>, and our documentation is in <path>doc</path>. For testing	94	in <path>xsl</path>, and our documentation is in <path>doc</path>. For testing
97	purposes, we will be using the Gentoo Linux CD Installation Guide, located at	95	purposes, we will be using the Gentoo Linux CD Installation Guide, located at
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
99	and XML file are known, we can do some transforming with <c>xsltproc</c>.	97	and 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 > /tmp/install.html</c>	101	# <i>xsltproc xsl/guide.xsl doc/en/gentoo-x86-install.xml > /tmp/install.html</i>
104	</pre>	102	</pre>
105		103
106	<p>	104	<p>
107	If all went well, you should have a web-ready version of	105	If 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
109	this document to display properly in a web browser, you may have to copy some	107	this document to display properly in a web browser, you may have to copy some
110	files from <path>htdocs</path> to <path>/tmp</path>, such as	108	files from <path>htdocs</path> to <path>/tmp</path>, such as
111	<path>css/main.css</path> and (to be safe) the entire <path>images</path>	109	<path>css/main.css</path> and (to be safe) the entire <path>images</path>
112	directory.	110	directory.
113	</p>	111	</p>
114		112
115	</body>	113	</body>
116	</section>	114	</section>
117	</chapter>	115	</chapter>
118		116
…		…
179	a guide document. Besides the <c><title></c> and <c><mail></c>	177	a guide document. Besides the <c><title></c> and <c><mail></c>
180	tags, these tags shouldn't appear anywhere else except immediately inside the	178	tags, these tags shouldn't appear anywhere else except immediately inside the
181	<c><guide></c> tag, and for consistency it's recommended (but not	179	<c><guide></c> tag, and for consistency it's recommended (but not
182	required) that these tags appear before the content of the document.	180	required) that these tags appear before the content of the document.
183	</p>	181	</p>
184		182
185	<p>	183	<p>
186	Finally we have the <c><license/></c> tag, used to publish the	184	Finally we have the <c><license/></c> tag, used to publish the
187	document under the <uri link="http://creativecommons.org/licenses/by-sa/1.0/">Creative	185	document under the <uri link="http://creativecommons.org/licenses/by-sa/1.0/">Creative
188	Commons - Attribution / Share Alike</uri> license as required by the <uri	186	Commons - Attribution / Share Alike</uri> license as required by the <uri
189	link="/doc/en/doc-policy.xml">Documentation Policy</uri>.	187	link="/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>
200	Once the initial tags have been specified, you're ready to start adding	197	Once the initial tags have been specified, you're ready to start adding
201	the structural elements of the document. Guide documents are divided into	198	the structural elements of the document. Guide documents are divided into
202	chapters, and each chapter can hold one or more sections. Every chapter	199	chapters, and each chapter can hold one or more sections. Every chapter
203	and section has a title. Here's an example chapter with a single section,	200	and section has a title. Here's an example chapter with a single section,
204	consisting of a paragraph. If you append this XML to the XML in the <uri link="#doc_chap2_pre1">previous	201	consisting of a paragraph. If you append this XML to the XML in the <uri link="#doc_chap2_pre1">previous
205	excerpt</uri> and append a <c></guide></c> to the end of the file, you'll have a valid	202	excerpt</uri> and append a <c></guide></c> to the end of the file, you'll have a valid
206	(if minimal) guide document:	203	(if minimal) guide document:
207	</p>	204	</p>
208		205
209	<pre>	206	<pre>
…		…
230	<c><title></c> and a <c><body></c>. While the <c><title></c>	227	<c><title></c> and a <c><body></c>. While the <c><title></c>
231	is nothing new, the <c><body></c> is -- it contains the actual text	228	is nothing new, the <c><body></c> is -- it contains the actual text
232	content of this particular section. We'll look at the tags that are allowed	229	content of this particular section. We'll look at the tags that are allowed
233	inside a <c><body></c> element in a bit.	230	inside a <c><body></c> element in a bit.
234	</p>	231	</p>
235		232
236	<note>	233	<note>
237	A <c><guide></c> element can contain multiple <c><chapter></c>	234	A <c><guide></c> element can contain multiple <c><chapter></c>
238	elements, and a <c><chapter></c> can contain multiple	235	elements, and a <c><chapter></c> can contain multiple
239	<c><section></c> elements. However, a <c><section></c>	236	<c><section></c> elements. However, a <c><section></c>
240	element can only contain one <c><body></c> element.	237	element can only contain one <c><body></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 <body></title>	243	<title>An example <body></title>
248	<body>	244	<body>
249		245
250	<p>	246	<p>
251	Now, it's time to learn how to mark up actual content. Here's the XML code for an example <c><body></c> element:	247	Now, it's time to learn how to mark up actual content. Here's the XML code for an example <c><body></c> element:
252	</p>	248	</p>
253		249
254	<pre>	250	<pre>
255	<p>	251	<p>
256	This is a paragraph. <path>/etc/passwd</path> is a file.	252	This is a paragraph. <path>/etc/passwd</path> is a file.
257	<uri>http://www.gentoo.org</uri> is my favorite website.	253	<uri>http://www.gentoo.org</uri> is my favorite website.
258	Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now.	254	Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now.
259	</p>	255	</p>
260		256
…		…
303		299
304	<note>	300	<note>
305	This is a note.	301	This is a note.
306	</note>	302	</note>
307		303
308	<warn>	304	<warn>
309	This is a warning.	305	This is a warning.
310	</warn>	306	</warn>
311		307
312	<impo>	308	<impo>
313	This is important.	309	This is important.
314	</impo>	310	</impo>
315		311
316	</body>	312	</body>
317	</section>	313	</section>
318
319	<section>	314	<section>
320	<title>The <body> tags</title>	315	<title>The <body> tags</title>
321	<body>	316	<body>
322		317
323	<p>	318	<p>
324	We introduced a lot of new tags in the previous section -- here's what you	319	We introduced a lot of new tags in the previous section -- here's what you
325	need to know. The <c><p></c> (paragraph), <c><pre></c> (code	320	need to know. The <c><p></c> (paragraph), <c><pre></c> (code
326	block), <c><note></c>, <c><warn></c> (warning) and	321	block), <c><note></c>, <c><warn></c> (warning) and
327	<c><impo></c> (important) tags all can contain one or more lines of text.	322	<c><impo></c> (important) tags all can contain one or more lines of text.
328	Besides the <c><table></c> element (which we'll cover in just a bit),	323	Besides the <c><table></c> element (which we'll cover in just a bit),
329	these are the only tags that should appear immediately inside a	324	these are the only tags that should appear immediately inside a
330	<c><body></c> element. Another thing -- these tags <e>should not</e> be	325	<c><body></c> element. Another thing -- these tags <e>should not</e> be
331	stacked -- in other words, don't put a <c><note></c> element inside a	326	stacked -- in other words, don't put a <c><note></c> element inside a
332	<c><p></c> element. As you might guess, the <c><pre></c> element	327	<c><p></c> element. As you might guess, the <c><pre></c> element
333	preserves its whitespace exactly, making it well-suited for code excerpts.	328	preserves its whitespace exactly, making it well-suited for code excerpts.
…		…
372	necessary to surround user input with double-quotes</e>. For example, don't	367	necessary to surround user input with double-quotes</e>. For example, don't
373	refer to a "<c><c></c>" element like I did in this sentence. Avoiding	368	refer to a "<c><c></c>" element like I did in this sentence. Avoiding
374	the use of unnecessary double-quotes makes a document more readable -- and	369	the use of unnecessary double-quotes makes a document more readable -- and
375	adorable!	370	adorable!
376	</p>	371	</p>
377		372
378	<p>	373	<p>
379	<c><e></c> is used to apply emphasis to a word or phrase; for example:	374	<c><e></c> is used to apply emphasis to a word or phrase; for example:
380	I <e>really</e> should use semicolons more often. As you can see, this text is	375	I <e>really</e> should use semicolons more often. As you can see, this text is
381	offset from the regular paragraph type for emphasis. This helps to give your	376	offset from the regular paragraph type for emphasis. This helps to give your
382	prose more <e>punch</e>!	377	prose 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><mail> and <uri></title>	383	<title><mail> and <uri></title>
390	<body>	384	<body>
391		385
392	<p>	386	<p>
393	We've taken a look at the <c><mail></c> tag earlier; it's used to link	387	We've taken a look at the <c><mail></c> tag earlier; it's used to link
394	some text with a particular email address, and takes the form <c><mail	388	some text with a particular email address, and takes the form <c><mail
395	link="foo@bar.com">Mr. Foo Bar</mail></c>.	389	link="foo@bar.com">Mr. Foo Bar</mail></c>.
396	</p>	390	</p>
397		391
398	<p>	392	<p>
399	The <c><uri></c> tag is used to point to files/locations on the	393	The <c><uri></c> tag is used to point to files/locations on the
400	Internet. It has two forms -- the first can be used when you want to have the	394	Internet. It has two forms -- the first can be used when you want to have the
401	actual URI displayed in the body text, such as this link to	395	actual URI displayed in the body text, such as this link to
402	<uri>http://www.gentoo.org</uri>. To create this link, I typed	396	<uri>http://www.gentoo.org</uri>. To create this link, I typed
403	<c><uri>http://www.gentoo.org</uri></c>. The alternate form is	397	<c><uri>http://www.gentoo.org</uri></c>. The alternate form is
404	when you want to associate a URI with some other text -- for example, <uri	398	when you want to associate a URI with some other text -- for example, <uri
405	link="http://www.gentoo.org">the Gentoo Linux website</uri>. To create	399	link="http://www.gentoo.org">the Gentoo Linux website</uri>. To create
406	<e>this</e> link, I typed <c><uri link="http://www.gentoo.org">the	400	<e>this</e> link, I typed <c><uri link="http://www.gentoo.org">the
407	Gentoo Linux website</uri></c>.	401	Gentoo Linux website</uri></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
418	<p>	411	<p>
419	Here's how to insert a figure into a document -- <c><figure	412	Here's how to insert a figure into a document -- <c><figure
420	link="mygfx.png" short="my picture" caption="my favorite picture of all	413	link="mygfx.png" short="my picture" caption="my favorite picture of all
421	time"/></c>. The <c>link=</c> attribute points to the actual graphic image,	414	time"/></c>. The <c>link=</c> attribute points to the actual graphic image,
422	the <c>short=</c> attribute specifies a short description (currently used for	415	the <c>short=</c> attribute specifies a short description (currently used for
423	the image's HTML <c>alt=</c> attribute), and a caption. Not too difficult	416	the image's HTML <c>alt=</c> attribute), and a caption. Not too difficult
424	:) We also support the standard HTML-style <img src="foo.gif"/> tag	417	:) We also support the standard HTML-style <img src="foo.gif"/> tag
425	for adding images without captions, borders, etc.	418	for adding images without captions, borders, etc.
426	</p>	419	</p>
427		420
…		…
440	block. You can use a <c><th></c> anywhere you can use a <c><ti></c>	433	block. You can use a <c><th></c> anywhere you can use a <c><ti></c>
441	-- there's no requirement that <c><th></c> elements appear only in the	434	-- there's no requirement that <c><th></c> elements appear only in the
442	first row. Currently, these tags don't support any attributes, but some will	435	first row. Currently, these tags don't support any attributes, but some will
443	be added (such as a <c>caption=</c> attribute for <c><table></c>) soon.	436	be added (such as a <c>caption=</c> attribute for <c><table></c>) soon.
444	</p>	437	</p>
445		438
446	<p>	439	<p>
447	To create ordered or unordered lists, simply use the HTML-style	440	To create ordered or unordered lists, simply use the HTML-style
448	<c><ol></c>, <c><ul></c> and <c><li></c> tags. List tags	441	<c><ol></c>, <c><ul></c> and <c><li></c> tags. List tags
449	should only appear inside a <c><p></c>, <c><ti></c>,	442	should only appear inside a <c><p></c>, <c><ti></c>,
450	<c><note></c>, <c><warn></c> or <c><impo></c> tag.	443	<c><note></c>, <c><warn></c> or <c><impo></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>
461	Guide makes it really easy to reference other parts of the document using	453	Guide makes it really easy to reference other parts of the document using
462	hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter	454	hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter
463	One</uri> by typing <c><uri link="#doc_chap1">Chapter	455	One</uri> by typing <c><uri link="#doc_chap1">Chapter
464	One</uri></c>. To point to <uri link="#doc_chap1_sect2">section two of	456	One</uri></c>. To point to <uri link="#doc_chap1_sect2">section two of
465	Chapter One</uri>, type <c><uri link="#doc_chap1_sect2">section two of	457	Chapter One</uri>, type <c><uri link="#doc_chap1_sect2">section two of
466	Chapter One</uri></c>. To refer to figure 3 in chapter 1, type <c><uri	458	Chapter One</uri></c>. To refer to figure 3 in chapter 1, type <c><uri
467	link="doc_chap1_fig3">figure 1.3</uri></c>. Or, to refer to <uri	459	link="doc_chap1_fig3">figure 1.3</uri></c>. Or, to refer to <uri
468	link="#doc_chap2_pre2">code listing 2 in chapter 2</uri>, type <c><uri	460	link="#doc_chap2_pre2">code listing 2 in chapter 2</uri>, type <c><uri
469	link="doc_chap2_pre2">code listing 2.2</uri></c>. We'll be	461	link="doc_chap2_pre2">code listing 2.2</uri></c>. We'll be
470	adding other auto-link abilities (such as table support) soon.	462	adding other auto-link abilities (such as table support) soon.
471	</p>	463	</p>
472		464
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>
		476	Since all Gentoo Documentation is a joint effort and several people will
		477	most likely change existing documentation, a coding style is needed.
		478	A coding style contains two sections. The first one is regarding
		479	internal coding - how the xml-tags are placed. The second one is
		480	regarding the content - how not to confuse the reader.
		481	</p>
		482
		483	<p>
		484	Both 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>
		495	GuideXML-tag (both opening as closing), except for:
		496	<c><version></c>, <c><date></c>, <c><title></c>,
		497	<c><th></c>, <c><ti></c>,
		498	<c><li></c>, <c><i></c>, <c><e></c>,
		499	<c><uri></c>, <c><path></c>, <c><b></c>,
		500	<c><comment></c>, <c><codenote></c>, <c><mail></c>.
		501	</p>
		502
		503	<p>
		504	<b>Blank lines</b> must be placed immediately after <e>every</e>
		505	<c><body></c> (opening tag only) and before <e>every</e>
		506	<c><chapter></c>, <c><p></c>, <c><table></c>,
		507	<c><author></c>, <c><pre></c>, <c><ul></c>, <c><ol></c>,
		508	<c><warn></c>, <c><note></c> and <c><impo></c> (opening tags
		509	only).
		510	</p>
		511
		512	<p>
		513	<b>Word-wrapping</b> must be applied at 80 characters except inside
		514	<c><pre></c>. Only when there is no other choice can be deviated from
		515	this rule (for instance when a URL exceeds the maximum amount of characters).
		516	The 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
		521	the parent XML-tags are <c><tr></c> (from <c><table></c>),
		522	<c><ul></c> and <c><ol></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>
		528	In case word-wrapping happens in <c><ti></c>, <c><th></c> or
		529	<c><li></c> constructs, indentation must be used for the content.
		530	</p>
		531
		532	<p>
		533	An example for indentation is:
		534	</p>
		535
		536	<pre caption = "Indentation Example">
		537	<table>
		538	<tr>
		539	<th>Foo</th>
		540	<th>Bar</th>
		541	</tr>
		542	<tr>
		543	<ti>This is an example for indentation.</ti>
		544	<ti>
		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	</ti>
		548	</tr>
		549	</table>
		550
		551	<ul>
		552	<li>First option</li>
		553	<li>Second option</li>
		554	</ul>
		555	</pre>
		556
		557	<p>
		558	<b>Attributes</b> may not have spaces in between the attribute, the
		559	"=" mark, and the attribute value. As an example:
		560	</p>
		561
		562	<pre caption="Attributes">
		563	<comment>Wrong :</comment> <pre caption = "Attributes">
		564	<comment>Correct:</comment> <pre caption="Attributes">
		565	</pre>
		566
		567	</body>
		568	</section>
		569	<section>
		570	<title>External Coding Style</title>
		571	<body>
		572
		573	<p>
		574	Inside tables (<c><table></c>) and listings (<c><ul></c> and
		575	<c><ol></c>), periods (".") should not be used unless multiple
		576	sentences are used. In that case, every sentence should end with a period (or
		577	other reading marks).
		578	</p>
		579
		580	<p>
		581	Every sentence, including those inside tables and listings, should start
		582	with a capital letter.
		583	</p>
		584
		585	<pre caption="Periods and capital letters">
		586	<ul>
		587	<li>No period</li>
		588	<li>With period. Multiple sentences, remember?</li>
		589	</ul>
		590	</pre>
		591
		592	<p>
		593	Code Listings should <e>always</e> have a <c>caption</c>.
		594	</p>
		595
		596	<p>
		597	Try to use <c><uri></c> with the <c>link</c> attribute as much as
		598	possible. In other words, the <uri link="http://www.gentoo.org">Gentoo
		599	Website</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
483	<p>	612	<p>
484	Guide has been specially designed to be "lean and mean" so that developers	613	Guide has been specially designed to be "lean and mean" so that developers
485	can spend more time writing documentation and less time learning the actual XML	614	can spend more time writing documentation and less time learning the actual XML
486	syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy"	615	syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy"
487	to start writing quality Gentoo Linux documentation. If you'd like to help (or	616	to start writing quality Gentoo Linux documentation. If you'd like to help (or
488	have any questions about guide), please post a message to the <mail	617	have any questions about guide), please post a message to the <mail
489	link="gentoo-doc@gentoo.org">gentoo-doc mailing list</mail> stating what you'd	618	link="gentoo-doc@gentoo.org">gentoo-doc mailing list</mail> stating what you'd
490	like to tackle. Have fun!	619	like to tackle. Have fun!
491	</p>	620	</p>
492		621

 Legend:



Removed from v.1.16
 


changed lines


 
Added in v.1.17
 Legend:



Removed from v.1.16
 


changed lines


 
Added in v.1.17
-Removed from v.1.16
+Added in v.1.17

	ViewVC Help
Powered by ViewVC 1.1.13