/[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.3		Revision 1.22
1	<?xml version='1.0' encoding="UTF-8"?>	1	<?xml version='1.0' encoding="UTF-8"?>
2	<?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?>	2	<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.22 2003/11/15 00:32:59 neysx Exp $ -->
3
4	<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">	3	<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
5		4
6	<guide link="/doc/en/xml-guide.xml">	5	<guide link="/doc/en/xml-guide.xml">
7	<title>Gentoo Linux Documentation Guide</title>	6	<title>Gentoo Linux XML Guide</title>
8	<author title="Chief Architect"><mail link="drobbins@gentoo.org">Daniel Robbins</mail></author>
9		7
		8	<author title="Author">
		9	<mail link="drobbins@gentoo.org">Daniel Robbins</mail>
		10	</author>
		11	<author title="Author"><!-- zhen@gentoo.org -->
		12	John P. Davis
		13	</author>
		14	<author title="Editor">
		15	<mail link="peesh@gentoo.org">Jorge Paulo</mail>
		16	</author>
		17
		18	<license/>
		19	<abstract>
10	<abstract>This guide shows you how to compose web documentation using the new lightweight Gentoo guide	20	This guide shows you how to compose web documentation using the new lightweight
11	XML syntax. This syntax is the official format for Gentoo Linux documentation, and this document	21	Gentoo GuideXML syntax. This syntax is the official format for Gentoo Linux
12	itself was created using guide XML. This guide assumes a basic working knowledge of XML and HTML.	22	documentation, and this document itself was created using GuideXML. This guide
		23	assumes a basic working knowledge of XML and HTML.
13	</abstract>	24	</abstract>
14		25
15	<version>1.0</version>	26	<version>2.4</version>
16	<date>07 Mar 2002</date>	27	<date>November 5, 2003</date>
17		28
18	<chapter>	29	<chapter>
19	<title>Guide basics</title>	30	<title>Guide basics</title>
20
21	<section>	31	<section>
22	<title>Guide XML design goals</title>	32	<title>Guide XML design goals</title>
23	<body>	33	<body>
24		34
		35	<p>
25	<p> The guide XML syntax is lightweight yet expressive, so that it is easy to	36	The guide XML syntax is lightweight yet expressive, so that it is easy to
26	learn yet also provides all the features we need for the creation of web	37	learn yet also provides all the features we need for the creation of web
27	documentation. The number of tags is kept to a minimum -- just those we need.	38	documentation. The number of tags is kept to a minimum -- just those we need.
28	This makes it easy to transform guide into other formats, such as DocBook	39	This makes it easy to transform guide into other formats, such as DocBook
29	XML/SGML or web-ready HTML. </p>	40	XML/SGML or web-ready HTML.
		41	</p>
30		42
		43	<p>
31	<p>The goal is to make it easy to <e>create</e> and <e>transform</e> guide XML	44	The goal is to make it easy to <e>create</e> and <e>transform</e> guide XML
32	documents.</p>	45	documents.
		46	</p>
33		47
34	</body>	48	</body>
35	</section>
36
37	<section>	49	</section>
38	<title>How to transform guide XML into HTML</title>	50	<section>
		51	<title>Further Resources</title>
39	<body>	52	<body>
40		53
41	<p> Before we take a look at the guide syntax itself, it's helpful to know how
42	guide XML is transformed into web-ready HTML. To do this, we use a special
43	file called <path>guide-main.xsl</path>, along with a command-line XSLT processing
44	tool (also called an "engine"). The <path>guide-main.xsl</path> file describes
45	exactly how to transform the contents of the source guide XML document to
46	create the target HTML file. Two popular XSLT processors are <c>sabcmd</c>
47	(included in the <path>app-text/sablotron</path> package) and <c>xsltproc</c>
48	(found in the <path>dev-libs/libxslt</path> package). From experience, we've
49	found that <c>xsltproc</c> is the higher-quality and more feature-rich XSLT
50	processor. </p>
51
52	<p> Once you have either <c>xsltproc</c> or <c>sabcmd</c> installed, you're
53	ready to convert guide XML into web-ready HTML. Here's how it works. First,
54	download the latest snapshot of our Web site from
55	<uri>http://www.gentoo.org/projects/xml.html</uri>, found in the <uri
56	link="http://www.gentoo.org/projects/guide-xml-latest.tar.gz">xml-guide-latest.tar.gz</uri>
57	file. Extract the tarball. Inside it, you'll find a <path>gentoo-src</path>
58	directory, as well as a <path>gentoo-src/xml</path> directory, etc. Now, find
59	<path>gentoo-src/xml/install.xml</path>. (The new user installation guide).
60	This will be our source XML guide document. The easiest way to perform the
61	transformation is to change directories to the location of the
62	<path>guide-main.xsl</path> file. Then, execute <c>xsltproc</c> as follows:
63	</p>	54	<p>
64		55	If you are planning on contributing documentation to Gentoo, or you want to test
65	<pre>	56	GuideXML, please read the <uri
66	# <i>cd gentoo-web/xsl</i>	57	link="http://www.gentoo.org/proj/en/gdp/doc/en/docdev.xml">Documentation
67	# <i>xsltproc guide-main.xsl ../xml/install.xml > /tmp/install.html</i>	58	Developer Guide</uri> which contains tips and tricks for documentation
68	</pre>	59	development.
69
70	<p> If all went well, you should have a web-ready version of
71	<path>install.xml</path> at <path>/tmp/install.html</path>. For this document
72	to display properly in a web browser, you may have to copy some files from
73	<path>gentoo-web</path> to <path>/tmp</path>, such
74	as <path>css/main-new.css</path> and (to be safe) the entire <path>images</path>
75	directory.
76	</p>	60	</p>
77		61
78	</body>	62	</body>
79	</section>	63	</section>
80	</chapter>	64	</chapter>
		65
81	<chapter>	66	<chapter>
82	<title>Guide XML</title>	67	<title>Guide XML</title>
83	<section>	68	<section>
84	<title>Basic structure</title>	69	<title>Basic structure</title>
85	<body>	70	<body>
86		71
		72	<p>
87	<p>Now that you know how to transform guide XML, you're ready to start learning	73	Now that you know how to transform guide XML, you're ready to start learning
88	the guide XML syntax. We'll start with the the initial tags used in a guide	74	the GuideXML syntax. We'll start with the the initial tags used in a guide
89	XML document: </p>	75	XML document:
		76	</p>
90		77
91	<pre caption="The initial part of a guide XML document">	78	<pre caption="The initial part of a guide XML document">
92	<?xml version='1.0'?>	79	<?xml version='1.0' encoding="UTF-8"?>
93	<guide>	80	<guide link="relative_link_to_your_guide">
94	<title><i>Gentoo Linux Documentation Guide</i></title>	81	<title><i>Gentoo Linux Documentation Guide</i></title>
95	<author title="<i>Chief Architect</i>"><mail link="<i>drobbins@gentoo.org</i>">	82	<author title="<i>Chief Architect</i>">
96	<i>Daniel Robbins</i></mail>	83	<mail link="<i>drobbins@gentoo.org</i>"><i>Daniel Robbins</i></mail>
97	</author>	84	</author>
98	<author title="<i>Editor</i>"><mail link="<i>thomasfl@gentoo.org</i>">	85	<author title="<i>Editor</i>">
99	<i>Thomas Flavel</i></mail>	86	<mail link="<i>thomasfl@gentoo.org</i>"><i>Thomas Flavel</i></mail>
100	</author>	87	</author>
101		88
		89	<abstract>
102	<abstract><i>This guide shows you how to compose web documentation using	90	<i>This guide shows you how to compose web documentation using
103	our new lightweight Gentoo guide XML syntax. This syntax is the official	91	our new lightweight Gentoo GuideXML syntax. This syntax is the official
104	format for Gentoo Linux web documentation, and this document itself was created	92	format for Gentoo Linux web documentation, and this document itself was created
105	using guide XML.</i> </abstract>	93	using GuideXML.</i>
		94	</abstract>
		95
		96	<license/>
106		97
107	<version><i>1.0</i></version>	98	<version><i>1.0</i></version>
108	<date><i>29 Mar 2001</i></date>	99	<date><i>29 Mar 2001</i></date>
109	</pre>	100	</pre>
110		101
		102	<p>
111	<p>On the first, line, we see the requisite tag that identifies this as an XML	103	On the first, line, we see the requisite tag that identifies this as an XML
112	document. Following it, there's a <c><guide></c> tag -- the entire	104	document. Following it, there's a <c><guide></c> tag -- the entire
113	guide document is enclosed within a <c><guide> </guide></c> pair.	105	guide document is enclosed within a <c><guide> </guide></c> pair.
114	Next, there's a <c><title></c> tag, used to set the title for the entire	106	Next, there's a <c><title></c> tag, used to set the title for the entire
115	guide document. </p>	107	guide document.
		108	</p>
116		109
		110	<p>
117	<p>Then, we come to the <c><author></c> tags, which contain information	111	Then, we come to the <c><author></c> tags, which contain information
118	about the various authors of the document. Each <c><author></c> tag	112	about the various authors of the document. Each <c><author></c> tag
119	allows for an optional <c>title=</c> element, used to specify the author's	113	allows for an optional <c>title=</c> element, used to specify the author's
120	relationship to the document (author, co-author, editor, etc.). In this	114	relationship to the document (author, co-author, editor, etc.). In this
121	particular example, the authors' names are enclosed in another tag -- a	115	particular example, the authors' names are enclosed in another tag -- a
122	<c><mail></c> tag, used to specify an email address for this particular	116	<c><mail></c> tag, used to specify an email address for this particular
123	person. The <c><mail></c> tag is optional and can be omitted, and no	117	person. The <c><mail></c> tag is optional and can be omitted, and no
124	more than one <c><author></c> element is required per guide document.	118	more than one <c><author></c> element is required per guide document.
125	</p>	119	</p>
126		120
		121	<p>
127	<p>Next, we come to the <c><abstract></c>, <c><version></c> and	122	Next, we come to the <c><abstract></c>, <c><version></c> and
128	<c><date></c> tags, used to specify a summary of the document, the	123	<c><date></c> tags, used to specify a summary of the document, the
129	current version number, and the current version date (in DD MMM YYYY format)	124	current version number, and the current version date (in DD MMM YYYY format)
130	respectively. This rounds out the tags that should appear at the beginning of	125	respectively. This rounds out the tags that should appear at the beginning of
131	a guide document. Besides the <c><title></c> and <c><mail></c>	126	a guide document. Besides the <c><title></c> and <c><mail></c>
132	tags, these tags shouldn't appear anywhere else except immediately inside the	127	tags, these tags shouldn't appear anywhere else except immediately inside the
133	<c><guide></c> tag, and for consistency it's recommended (but not	128	<c><guide></c> tag, and for consistency it's recommended (but not
134	required) that these tags appear before the content of the document. </p>	129	required) that these tags appear before the content of the document.
		130	</p>
135		131
136	</body>	132	<p>
137	</section>	133	Finally we have the <c><license/></c> tag, used to publish the
		134	document under the <uri link="http://creativecommons.org/licenses/by-sa/1.0/">Creative
		135	Commons - Attribution / Share Alike</uri> license as required by the <uri
		136	link="/doc/en/doc-policy.xml">Documentation Policy</uri>.
		137	</p>
138		138
		139	</body>
		140	</section>
139	<section>	141	<section>
140	<title>Chapters and sections</title>	142	<title>Chapters and sections</title>
141	<body>	143	<body>
		144
		145	<p>
142	<p>Once the initial tags have been specified, you're ready to start adding	146	Once the initial tags have been specified, you're ready to start adding
143	the structural elements of the document. Guide documents are divided into	147	the structural elements of the document. Guide documents are divided into
144	chapters, and each chapter can hold one or more sections. Every chapter	148	chapters, and each chapter can hold one or more sections. Every chapter
145	and section has a title. Here's an example chapter with a single section,	149	and section has a title. Here's an example chapter with a single section,
146	consisting of a paragraph. If you append this XML to the XML in the <uri link="#doc_pre2">previous	150	consisting of a paragraph. If you append this XML to the XML in the <uri link="#doc_chap2_pre1">previous
147	excerpt</uri> and append a <c></guide></c> to the end of the file, you'll have a valid	151	excerpt</uri> and append a <c></guide></c> to the end of the file, you'll have a valid
148	(if minimal) guide document:	152	(if minimal) guide document:
149	</p>	153	</p>
150		154
151	<pre>	155	<pre>
152	<chapter>	156	<chapter>
153	<title><i>This is my chapter</i></title>	157	<title><i>This is my chapter</i></title>
154	<section>	158	<section>
155	<title><i>This is section one of my chapter</i></title>	159	<title><i>This is section one of my chapter</i></title>
156	<body>	160	<body>
		161
		162	<p>
157	<p><i>This is the actual text content of my section.</i></p>	163	<i>This is the actual text content of my section.</i>
		164	</p>
		165
158	</body>	166	</body>
159	</section>	167	</section>
160	</chapter>	168	</chapter>
161	</pre>	169	</pre>
162		170
		171	<p>
163	<p>Above, I set the chapter title by adding a child <c><title></c>	172	Above, I set the chapter title by adding a child <c><title></c>
164	element to the <c><chapter></c> element. Then, I created a section by	173	element to the <c><chapter></c> element. Then, I created a section by
165	adding a <c><section></c> element. If you look inside the	174	adding a <c><section></c> element. If you look inside the
166	<c><section></c> element, you'll see that it has two child elements -- a	175	<c><section></c> element, you'll see that it has two child elements -- a
167	<c><title></c> and a <c><body></c>. While the <c><title></c>	176	<c><title></c> and a <c><body></c>. While the <c><title></c>
168	is nothing new, the <c><body></c> is -- it contains the actual text	177	is nothing new, the <c><body></c> is -- it contains the actual text
169	content of this particular section. We'll look at the tags that are allowed	178	content of this particular section. We'll look at the tags that are allowed
170	inside a <c><body></c> element in a bit. </p>	179	inside a <c><body></c> element in a bit.
		180	</p>
171		181
		182	<note>
172	<note>A <c><guide></c> element can contain multiple	183	A <c><guide></c> element can contain multiple <c><chapter></c>
173	<c><chapter></c> elements, and a <c><chapter></c> can contain	184	elements, and a <c><chapter></c> can contain multiple
174	multiple <c><section></c> elements. However, a <c><section></c>	185	<c><section></c> elements. However, a <c><section></c>
175	element can only contain one <c><body></c> element. </note>	186	element can only contain one <c><body></c> element.
		187	</note>
176		188
177	</body>	189	</body>
178	</section>	190	</section>
179
180	<section>	191	<section>
181	<title>An example <body></title>	192	<title>An example <body></title>
182	<body>	193	<body>
		194
183	<p>	195	<p>
184	Now, it's time to learn how to mark up actual content. Here's the XML code for an example <c><body></c> element:	196	Now, it's time to learn how to mark up actual content. Here's the XML code for an example <c><body></c> element:
185	</p>	197	</p>
		198
186	<pre>	199	<pre>
187	<p>	200	<p>
188	This is a paragraph. <path>/etc/passwd</path> is a file.	201	This is a paragraph. <path>/etc/passwd</path> is a file.
189	<uri>http://www.gentoo.org</uri> is my favorite website.	202	<uri>http://www.gentoo.org</uri> is my favorite website.
190	Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now.	203	Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now.
…		…
197	Make HTML/XML easier to read by using selective emphasis:	210	Make HTML/XML easier to read by using selective emphasis:
198	<foo><i>bar</i></foo>	211	<foo><i>bar</i></foo>
199		212
200	<codenote>This is how to insert an inline note into the code block</codenote>	213	<codenote>This is how to insert an inline note into the code block</codenote>
201	</pre>	214	</pre>
202	<note>This is a note.</note>	215
203	<warn>This is a warning.</warn>	216	<note>
204	<impo>This is important.</impo>	217	This is a note.
		218	</note>
		219
		220	<warn>
		221	This is a warning.
		222	</warn>
		223
		224	<impo>
		225	This is important.
		226	</impo>
205	</pre>	227	</pre>
		228
		229	<p>
206	<p>Now, here's how this <c><body></c> element is rendered:</p>	230	Now, here's how this <c><body></c> element is rendered:
		231	</p>
207		232
208	<p>	233	<p>
209	This is a paragraph. <path>/etc/passwd</path> is a file.	234	This is a paragraph. <path>/etc/passwd</path> is a file.
210	<uri>http://www.gentoo.org</uri> is my favorite website.	235	<uri>http://www.gentoo.org</uri> is my favorite website.
211	Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now.	236	Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now.
…		…
218	Make HTML/XML easier to read by using selective emphasis:	243	Make HTML/XML easier to read by using selective emphasis:
219	<foo><i>bar</i></foo>	244	<foo><i>bar</i></foo>
220		245
221	<codenote>This is how to insert an inline note into the code block</codenote>	246	<codenote>This is how to insert an inline note into the code block</codenote>
222	</pre>	247	</pre>
223	<note>This is a note.</note>
224	<warn>This is a warning.</warn>
225	<impo>This is important.</impo>
226	</body>
227	</section>
228		248
		249	<note>
		250	This is a note.
		251	</note>
		252
		253	<warn>
		254	This is a warning.
		255	</warn>
		256
		257	<impo>
		258	This is important.
		259	</impo>
		260
		261	</body>
		262	</section>
229	<section>	263	<section>
230	<title>The <body> tags</title>	264	<title>The <body> tags</title>
231	<body>	265	<body>
232		266
		267	<p>
233	<p> We introduced a lot of new tags in the previous section -- here's what you	268	We introduced a lot of new tags in the previous section -- here's what you
234	need to know. The <c><p></c> (paragraph), <c><pre></c> (code	269	need to know. The <c><p></c> (paragraph), <c><pre></c> (code
235	block), <c><note></c>, <c><warn></c> (warning) and	270	block), <c><note></c>, <c><warn></c> (warning) and
236	<c><impo></c> (important) tags all can contain one or more lines of text.	271	<c><impo></c> (important) tags all can contain one or more lines of text.
237	Besides the <c><table></c> element (which we'll cover in just a bit),	272	Besides the <c><table></c> element (which we'll cover in just a bit),
238	these are the only tags that should appear immediately inside a	273	these are the only tags that should appear immediately inside a
239	<c><body></c> element. Another thing -- these tags <e>should not</e> be	274	<c><body></c> element. Another thing -- these tags <e>should not</e> be
240	stacked -- in other words, don't put a <c><note></c> element inside a	275	stacked -- in other words, don't put a <c><note></c> element inside a
241	<c><p></c> element. As you might guess, the <c><pre></c> element	276	<c><p></c> element. As you might guess, the <c><pre></c> element
242	preserves its whitespace exactly, making it well-suited for code excerpts.</p>	277	preserves its whitespace exactly, making it well-suited for code excerpts.
		278	You can also name the <c><pre></c> tag:
		279	</p>
		280
		281	<pre caption = "Named <pre>">
		282	<pre caption = "Output of uptime">
		283	# <i>uptime</i>
		284	16:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25
		285	</pre>
		286	</pre>
243		287
244	</body>	288	</body>
245	</section>	289	</section>
246	<section>	290	<section>
247	<title><path>, <c> and <e></title>	291	<title><path>, <c> and <e></title>
248	<body>	292	<body>
249		293
		294	<p>
250	<p>The <c><path></c>, <c><c></c> and <c><e></c> elements can	295	The <c><path></c>, <c><c></c> and <c><e></c> elements can
251	be used inside any child <c><body></c> tag, except for	296	be used inside any child <c><body></c> tag, except for
252	<c><pre></c>. </p>	297	<c><pre></c>.
		298	</p>
253		299
		300	<p>
254	<p>The <c><path></c> element is used to mark text that refers to an	301	The <c><path></c> element is used to mark text that refers to an
255	<e>on-disk file</e> -- either an <e>absolute or relative path</e>, or a <e>simple filename</e>.	302	<e>on-disk file</e> -- either an <e>absolute or relative path</e>, or a
256	This element is generally rendered with a monospaced font to offset it from the	303	<e>simple filename</e>. This element is generally rendered with a monospaced
257	standard paragraph type. </p>	304	font to offset it from the standard paragraph type.
		305	</p>
258		306
		307	<p>
259	<p>The <c><c></c> element is used to mark up a <e>command</e> or <e>user	308	The <c><c></c> element is used to mark up a <e>command</e> or <e>user
260	input</e>. Think of <c><c></c> as a way to alert the reader to something	309	input</e>. Think of <c><c></c> as a way to alert the reader to something
261	that they can type in that will perform some kind of action. For example, all	310	that they can type in that will perform some kind of action. For example, all
262	the XML tags displayed in this document are enclosed in a <c><c></c>	311	the XML tags displayed in this document are enclosed in a <c><c></c>
263	element because they represent something that the user could type in that is	312	element because they represent something that the user could type in that is
264	not a path. By using <c><c></c> elements, you'll help your readers	313	not a path. By using <c><c></c> elements, you'll help your readers
265	quickly identify commands that they need to type in. Also, because	314	quickly identify commands that they need to type in. Also, because
266	<c><c></c> elements are already offset from regular text, <e>it is rarely	315	<c><c></c> elements are already offset from regular text, <e>it is rarely
267	necessary to surround user input with double-quotes</e>. For example, don't	316	necessary to surround user input with double-quotes</e>. For example, don't
268	refer to a "<c><c></c>" element like I did in this sentence. Avoiding	317	refer to a "<c><c></c>" element like I did in this sentence. Avoiding
269	the use of unnecessary double-quotes makes a document more readable -- and adorable!</p>	318	the use of unnecessary double-quotes makes a document more readable -- and
		319	adorable!
		320	</p>
270		321
		322	<p>
271	<p><c><e></c> is used to apply emphasis to a word or phrase; for example:	323	<c><e></c> is used to apply emphasis to a word or phrase; for example:
272	I <e>really</e> should use semicolons more often. As you can see, this text is	324	I <e>really</e> should use semicolons more often. As you can see, this text is
273	offset from the regular paragraph type for emphasis. This helps to give your	325	offset from the regular paragraph type for emphasis. This helps to give your
274	prose more <e>punch</e>!</p>	326	prose more <e>punch</e>!
		327	</p>
275		328
276	</body>	329	</body>
277	</section>	330	</section>
278
279	<section>	331	<section>
280	<title><mail> and <uri></title>	332	<title><mail> and <uri></title>
281	<body>	333	<body>
282		334
		335	<p>
283	<p>We've taken a look at the <c><mail></c> tag earlier; it's used to link some text	336	We've taken a look at the <c><mail></c> tag earlier; it's used to link
284	with a particular email address, and takes the form <c><mail link="foo@bar.com">Mr. Foo Bar</mail></c>.</p>	337	some text with a particular email address, and takes the form <c><mail
		338	link="foo@bar.com">Mr. Foo Bar</mail></c>.
		339	</p>
285		340
		341	<p>
286	<p>The <c><uri></c> tag is used to point to files/locations on the	342	The <c><uri></c> tag is used to point to files/locations on the
287	Internet. It has two forms -- the first can be used when you want to have the	343	Internet. It has two forms -- the first can be used when you want to have the
288	actual URI displayed in the body text, such as this link to	344	actual URI displayed in the body text, such as this link to
289	<uri>http://www.gentoo.org</uri>. To create this link, I typed	345	<uri>http://www.gentoo.org</uri>. To create this link, I typed
290	<c><uri>http://www.gentoo.org</uri></c>. The alternate form is	346	<c><uri>http://www.gentoo.org</uri></c>. The alternate form is
291	when you want to associate a URI with some other text -- for example, <uri	347	when you want to associate a URI with some other text -- for example, <uri
292	link="http://www.gentoo.org">the Gentoo Linux website</uri>. To create <e>this</e>	348	link="http://www.gentoo.org">the Gentoo Linux website</uri>. To create
293	link, I typed <c><uri link="http://www.gentoo.org">the Gentoo Linux website</uri></c>.	349	<e>this</e> link, I typed <c><uri link="http://www.gentoo.org">the
		350	Gentoo Linux website</uri></c>.
294	</p>	351	</p>
295		352
296	</body>	353	</body>
297	</section>	354	</section>
298
299	<section>	355	<section>
300	<title>Figures</title>	356	<title>Figures</title>
301		357
302	<body>	358	<body>
303		359
		360	<p>
304	<p>Here's how to insert a figure into a document -- <c><figure	361	Here's how to insert a figure into a document -- <c><figure
305	link="mygfx.png" short="my picture" caption="my favorite picture of all	362	link="mygfx.png" short="my picture" caption="my favorite picture of all
306	time"/></c>. The <c>link=</c> attribute points to the actual graphic image,	363	time"/></c>. The <c>link=</c> attribute points to the actual graphic image,
307	the <c>short=</c> attribute specifies a short description (currently used for	364	the <c>short=</c> attribute specifies a short description (currently used for
308	the image's HTML <c>alt=</c> attribute), and a caption. Not too difficult	365	the image's HTML <c>alt=</c> attribute), and a caption. Not too difficult
309	:) We also support the standard HTML-style <img src="foo.gif"/> tag	366	:) We also support the standard HTML-style <img src="foo.gif"/> tag
310	for adding images without captions, borders, etc.</p>	367	for adding images without captions, borders, etc.
		368	</p>
311		369
312	</body>	370	</body>
313	</section>	371	</section>
314	<section>	372	<section>
315	<title>Tables and lists</title>	373	<title>Tables and lists</title>
316	<body>	374	<body>
317		375
		376	<p>
318	<p>Guide supports a simplified table syntax similar to that of HTML. To start	377	Guide supports a simplified table syntax similar to that of HTML. To start
319	a table, use a <c><table></c> tag. Start a row with a <c><tr></c>	378	a table, use a <c><table></c> tag. Start a row with a <c><tr></c>
320	tag. However, for inserting actual table data, we <e>don't</e> support the	379	tag. However, for inserting actual table data, we <e>don't</e> support the
321	HTML <td> tag; instead, use the <c><th></c> if you are inserting a	380	HTML <td> tag; instead, use the <c><th></c> if you are inserting a
322	header, and <c><ti></c> if you are inserting a normal informational	381	header, and <c><ti></c> if you are inserting a normal informational
323	block. You can use a <c><th></c> anywhere you can use a <c><ti></c> --	382	block. You can use a <c><th></c> anywhere you can use a <c><ti></c>
324	there's no requirement that <c><th></c> elements appear only in the	383	-- there's no requirement that <c><th></c> elements appear only in the
325	first row. Currently, these tags don't support any attributes, but some will	384	first row. Currently, these tags don't support any attributes, but some will
326	be added (such as a <c>caption=</c> attribute for <c><table></c>) soon.	385	be added (such as a <c>caption=</c> attribute for <c><table></c>) soon.
327	</p>	386	</p>
328		387
		388	<p>
329	<p> To create ordered or unordered lists, simply use the HTML-style	389	To create ordered or unordered lists, simply use the HTML-style
330	<c><ol></c>, <c><ul></c> and <c><li></c> tags. List tags	390	<c><ol></c>, <c><ul></c> and <c><li></c> tags. List tags
331	should only appear inside a <c><p></c>, <c><ti></c>,	391	should only appear inside a <c><p></c>, <c><ti></c>,
332	<c><note></c>, <c><warn></c> or <c><impo></c> tag. </p>	392	<c><note></c>, <c><warn></c> or <c><impo></c> tag.
		393	</p>
333		394
334	</body>	395	</body>
335	</section>	396	</section>
336
337	<section>	397	<section>
338	<title>Intra-document references</title>	398	<title>Intra-document references</title>
339	<body>	399	<body>
340		400
		401	<p>
341	<p>Guide makes it really easy to reference other parts of the document using	402	Guide makes it really easy to reference other parts of the document using
342	hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter	403	hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter
343	One</uri> by typing <c><uri link="#doc_chap1">Chapter	404	One</uri> by typing <c><uri link="#doc_chap1">Chapter
344	One</uri></c>. To point to <uri link="#doc_chap1_sect2">section two of	405	One</uri></c>. To point to <uri link="#doc_chap1_sect2">section two of
345	Chapter One</uri>, type <c><uri link="#doc_chap1_sect2">section two of	406	Chapter One</uri>, type <c><uri link="#doc_chap1_sect2">section two of
346	Chapter One</uri></c>. To refer to figure 3 in chapter 1, type <c><uri	407	Chapter One</uri></c>. To refer to figure 3 in chapter 1, type <c><uri
347	link="doc_chap1_fig3">figure 1.3</uri></c>. Or, to refer to <uri link="#doc_chap2_pre2">code listing 2 in chapter 2</uri>,	408	link="doc_chap1_fig3">figure 1.3</uri></c>. Or, to refer to <uri
		409	link="#doc_chap2_pre2">code listing 2 in chapter 2</uri>, type <c><uri
348	type <c><uri link="doc_chap2_pre2">code listing 2.2</uri></c>. We'll be	410	link="doc_chap2_pre2">code listing 2.2</uri></c>. We'll be
349	adding other auto-link abilities (such as table support) soon.</p>	411	adding other auto-link abilities (such as table support) soon.
		412	</p>
350		413
351	</body>	414	</body>
352	</section>	415	</section>
353	</chapter>	416	</chapter>
		417
		418	<chapter>
		419	<title>Coding Style</title>
		420	<section>
		421	<title>Introduction</title>
		422	<body>
		423
		424	<p>
		425	Since all Gentoo Documentation is a joint effort and several people will
		426	most likely change existing documentation, a coding style is needed.
		427	A coding style contains two sections. The first one is regarding
		428	internal coding - how the xml-tags are placed. The second one is
		429	regarding the content - how not to confuse the reader.
		430	</p>
		431
		432	<p>
		433	Both sections are described next.
		434	</p>
		435
		436	</body>
		437	</section>
		438	<section>
		439	<title>Internal Coding Style</title>
		440	<body>
		441
		442	<p>
		443	<b>Newlines</b> must be placed immediately after <e>every</e>
		444	GuideXML-tag (both opening as closing), except for:
		445	<c><version></c>, <c><date></c>, <c><title></c>,
		446	<c><th></c>, <c><ti></c>,
		447	<c><li></c>, <c><i></c>, <c><e></c>,
		448	<c><uri></c>, <c><path></c>, <c><b></c>,
		449	<c><comment></c>, <c><codenote></c>, <c><mail></c>.
		450	</p>
		451
		452	<p>
		453	<b>Blank lines</b> must be placed immediately after <e>every</e>
		454	<c><body></c> (opening tag only) and before <e>every</e>
		455	<c><chapter></c>, <c><p></c>, <c><table></c>,
		456	<c><author></c> (set), <c><pre></c>, <c><ul></c>,
		457	<c><ol></c>, <c><warn></c>, <c><note></c> and
		458	<c><impo></c> (opening tags only).
		459	</p>
		460
		461	<p>
		462	<b>Word-wrapping</b> must be applied at 80 characters except inside
		463	<c><pre></c>. Only when there is no other choice can be deviated from
		464	this rule (for instance when a URL exceeds the maximum amount of characters).
		465	The editor must then wrap whenever the first whitespace occurs.
		466	</p>
		467
		468	<p>
		469	<b>Indentation</b> may not be used, except with the XML-constructs of which
		470	the parent XML-tags are <c><tr></c> (from <c><table></c>),
		471	<c><ul></c>, <c><ol></c> and <c><author></c>. If indentation
		472	is used, it <e>must</e> be two spaces for each indentation. That means <e>no</e>
		473	tabs and <e>not</e> more spaces.
		474	</p>
		475
		476	<p>
		477	In case word-wrapping happens in <c><ti></c>, <c><th></c> or
		478	<c><li></c> constructs, indentation must be used for the content.
		479	</p>
		480
		481	<p>
		482	An example for indentation is:
		483	</p>
		484
		485	<pre caption = "Indentation Example">
		486	<table>
		487	<tr>
		488	<th>Foo</th>
		489	<th>Bar</th>
		490	</tr>
		491	<tr>
		492	<ti>This is an example for indentation.</ti>
		493	<ti>
		494	In case text cannot be shown within an 80-character wide line, you
		495	must use indentation if the parent tag allows it.
		496	</ti>
		497	</tr>
		498	</table>
		499
		500	<ul>
		501	<li>First option</li>
		502	<li>Second option</li>
		503	</ul>
		504	</pre>
		505
		506	<p>
		507	<b>Attributes</b> may not have spaces in between the attribute, the
		508	"=" mark, and the attribute value. As an example:
		509	</p>
		510
		511	<pre caption="Attributes">
		512	<comment>Wrong :</comment> <pre caption = "Attributes">
		513	<comment>Correct:</comment> <pre caption="Attributes">
		514	</pre>
		515
		516	</body>
		517	</section>
		518	<section>
		519	<title>External Coding Style</title>
		520	<body>
		521
		522	<p>
		523	Inside tables (<c><table></c>) and listings (<c><ul></c> and
		524	<c><ol></c>), periods (".") should not be used unless multiple
		525	sentences are used. In that case, every sentence should end with a period (or
		526	other reading marks).
		527	</p>
		528
		529	<p>
		530	Every sentence, including those inside tables and listings, should start
		531	with a capital letter.
		532	</p>
		533
		534	<pre caption="Periods and capital letters">
		535	<ul>
		536	<li>No period</li>
		537	<li>With period. Multiple sentences, remember?</li>
		538	</ul>
		539	</pre>
		540
		541	<p>
		542	Code Listings should <e>always</e> have a <c>caption</c>.
		543	</p>
		544
		545	<p>
		546	Try to use <c><uri></c> with the <c>link</c> attribute as much as
		547	possible. In other words, the <uri link="http://www.gentoo.org">Gentoo
		548	Website</uri> is preferred over <uri>http://www.gentoo.org</uri>.
		549	</p>
		550
		551	<p>
		552	When you comment something inside a <c><pre></c> construct, only use
		553	<c><codenote></c> if the content is a C or C++ code snippet. Otherwise,
		554	use <c><comment></c> and parantheses. Also place the comment <e>before</e>
		555	the subject of the comment.
		556	</p>
		557
		558	<pre caption="Comment example">
		559	<comment>(Substitute "john" with your user name)</comment>
		560	# <i>id john</i>
		561	</pre>
		562
		563	</body>
		564	</section>
		565	</chapter>
		566
354	<chapter>	567	<chapter>
355	<title>Resources</title>	568	<title>Resources</title>
356	<section>	569	<section>
357	<title>Start writing</title>	570	<title>Start writing</title>
358	<body>	571	<body>
		572
		573	<p>
359	<p>Guide has been specially designed to be "lean and mean" so that developers	574	Guide has been specially designed to be "lean and mean" so that developers
360	can spend more time writing documentation and less time learning the actual XML	575	can spend more time writing documentation and less time learning the actual XML
361	syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy"	576	syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy"
362	to start writing quality Gentoo Linux documentation. If you'd like to help (or have any questions about guide), please	577	to start writing quality Gentoo Linux documentation. If you'd like to help (or
363	post a message to <mail link="gentoo-dev@gentoo.org">the gentoo-dev mailing list</mail>	578	have any questions about guide), please post a message to the <mail
364	stating what you'd like to tackle.	579	link="gentoo-doc@gentoo.org">gentoo-doc mailing list</mail> stating what you'd
365	Have fun!</p>	580	like to tackle. Have fun!
		581	</p>
		582
366	</body>	583	</body>
367	</section>	584	</section>
368	</chapter>	585	</chapter>
369	</guide>	586	</guide>
370		587

 Legend:



Removed from v.1.3
 


changed lines


 
Added in v.1.22
 Legend:



Removed from v.1.3
 


changed lines


 
Added in v.1.22
-Removed from v.1.3
+Added in v.1.22

	ViewVC Help
Powered by ViewVC 1.1.20