/[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.26
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.26 2004/02/19 14:48:06 swift 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	<author title="Editor">
		18	<mail link="swift@gentoo.org">Sven Vermeulen</mail>
		19	</author>
		20
		21	<abstract>
10	<abstract>This guide shows you how to compose web documentation using the new lightweight Gentoo guide	22	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	23	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.	24	documentation, and this document itself was created using GuideXML. This guide
		25	assumes a basic working knowledge of XML and HTML.
13	</abstract>	26	</abstract>
14		27
		28	<license/>
		29
15	<version>1.0</version>	30	<version>2.7</version>
16	<date>07 Mar 2002</date>	31	<date>February 9, 2004</date>
17		32
18	<chapter>	33	<chapter>
19	<title>Guide basics</title>	34	<title>Guide basics</title>
20
21	<section>	35	<section>
22	<title>Guide XML design goals</title>	36	<title>Guide XML design goals</title>
23	<body>	37	<body>
24		38
		39	<p>
25	<p> The guide XML syntax is lightweight yet expressive, so that it is easy to	40	The guide XML syntax is lightweight yet expressive, so that it is easy to
26	learn yet also provides all the features we need for the creation of web	41	learn yet also provides all the features we need for the creation of web
27	documentation. The number of tags is kept to a minimum -- just those we need.	42	documentation. The number of tags is kept to a minimum -- just those we need.
28	This makes it easy to transform guide into other formats, such as DocBook	43	This makes it easy to transform guide into other formats, such as DocBook
29	XML/SGML or web-ready HTML. </p>	44	XML/SGML or web-ready HTML.
		45	</p>
30		46
		47	<p>
31	<p>The goal is to make it easy to <e>create</e> and <e>transform</e> guide XML	48	The goal is to make it easy to <e>create</e> and <e>transform</e> guide XML
32	documents.</p>	49	documents.
		50	</p>
33		51
34	</body>	52	</body>
35	</section>
36
37	<section>	53	</section>
38	<title>How to transform guide XML into HTML</title>	54	<section>
		55	<title>Further Resources</title>
39	<body>	56	<body>
40		57
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>	58	<p>
64		59	If you are planning on contributing documentation to Gentoo, or you want to test
65	<pre>	60	GuideXML, please read the <uri
66	# <i>cd gentoo-web/xsl</i>	61	link="http://www.gentoo.org/proj/en/gdp/tipsntricks.xml">Tips and Tricks</uri>
67	# <i>xsltproc guide-main.xsl ../xml/install.xml > /tmp/install.html</i>	62	which contains tips and tricks for documentation development.
68	</pre>
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>	63	</p>
77		64
78	</body>	65	</body>
79	</section>	66	</section>
80	</chapter>	67	</chapter>
		68
81	<chapter>	69	<chapter>
82	<title>Guide XML</title>	70	<title>Guide XML</title>
83	<section>	71	<section>
84	<title>Basic structure</title>	72	<title>Basic structure</title>
85	<body>	73	<body>
86		74
		75	<p>
87	<p>Now that you know how to transform guide XML, you're ready to start learning	76	Now that you know how to transform guide XML, you're ready to start learning
88	the guide XML syntax. We'll start with the the initial tags used in a guide	77	the GuideXML syntax. We'll start with the the initial tags used in a guide
89	XML document: </p>	78	XML document:
		79	</p>
90		80
91	<pre caption="The initial part of a guide XML document">	81	<pre caption="The initial part of a guide XML document">
92	<?xml version='1.0'?>	82	<?xml version='1.0' encoding="UTF-8"?>
93	<guide>	83	<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
		84	<guide link="relative_link_to_your_guide">
94	<title><i>Gentoo Linux Documentation Guide</i></title>	85	<title><i>Gentoo Linux Documentation Guide</i></title>
95	<author title="<i>Chief Architect</i>"><mail link="<i>drobbins@gentoo.org</i>">	86	<author title="<i>Chief Architect</i>">
96	<i>Daniel Robbins</i></mail>	87	<mail link="<i>drobbins@gentoo.org</i>"><i>Daniel Robbins</i></mail>
97	</author>	88	</author>
98	<author title="<i>Editor</i>"><mail link="<i>thomasfl@gentoo.org</i>">	89	<author title="<i>Editor</i>">
99	<i>Thomas Flavel</i></mail>	90	<mail link="<i>thomasfl@gentoo.org</i>"><i>Thomas Flavel</i></mail>
100	</author>	91	</author>
101		92
		93	<abstract>
102	<abstract><i>This guide shows you how to compose web documentation using	94	<i>This guide shows you how to compose web documentation using
103	our new lightweight Gentoo guide XML syntax. This syntax is the official	95	our new lightweight Gentoo GuideXML syntax. This syntax is the official
104	format for Gentoo Linux web documentation, and this document itself was created	96	format for Gentoo Linux web documentation, and this document itself was created
105	using guide XML.</i> </abstract>	97	using GuideXML.</i>
		98	</abstract>
		99
		100	<license/>
106		101
107	<version><i>1.0</i></version>	102	<version><i>1.0</i></version>
108	<date><i>29 Mar 2001</i></date>	103	<date><i>29 Mar 2001</i></date>
109	</pre>	104	</pre>
110		105
		106	<p>
111	<p>On the first, line, we see the requisite tag that identifies this as an XML	107	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	108	document. Following it, there's a <c><guide></c> tag -- the entire
113	guide document is enclosed within a <c><guide> </guide></c> pair.	109	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	110	Next, there's a <c><title></c> tag, used to set the title for the entire
115	guide document. </p>	111	guide document.
		112	</p>
116		113
		114	<p>
117	<p>Then, we come to the <c><author></c> tags, which contain information	115	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	116	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	117	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	118	relationship to the document (author, co-author, editor, etc.). In this
121	particular example, the authors' names are enclosed in another tag -- a	119	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	120	<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	121	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.	122	more than one <c><author></c> element is required per guide document.
125	</p>	123	</p>
126		124
		125	<p>
127	<p>Next, we come to the <c><abstract></c>, <c><version></c> and	126	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	127	<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)	128	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	129	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>	130	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	131	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	132	<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>	133	required) that these tags appear before the content of the document.
		134	</p>
135		135
136	</body>	136	<p>
137	</section>	137	Finally we have the <c><license/></c> tag, used to publish the
		138	document under the <uri link="http://creativecommons.org/licenses/by-sa/1.0/">Creative
		139	Commons - Attribution / Share Alike</uri> license as required by the <uri
		140	link="/doc/en/doc-policy.xml">Documentation Policy</uri>.
		141	</p>
138		142
		143	</body>
		144	</section>
139	<section>	145	<section>
140	<title>Chapters and sections</title>	146	<title>Chapters and sections</title>
141	<body>	147	<body>
		148
		149	<p>
142	<p>Once the initial tags have been specified, you're ready to start adding	150	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	151	the structural elements of the document. Guide documents are divided into
144	chapters, and each chapter can hold one or more sections. Every chapter	152	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,	153	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	154	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	155	excerpt</uri> and append a <c></guide></c> to the end of the file, you'll have a valid
148	(if minimal) guide document:	156	(if minimal) guide document:
149	</p>	157	</p>
150		158
151	<pre>	159	<pre>
152	<chapter>	160	<chapter>
153	<title><i>This is my chapter</i></title>	161	<title><i>This is my chapter</i></title>
154	<section>	162	<section>
155	<title><i>This is section one of my chapter</i></title>	163	<title><i>This is section one of my chapter</i></title>
156	<body>	164	<body>
		165
		166	<p>
157	<p><i>This is the actual text content of my section.</i></p>	167	<i>This is the actual text content of my section.</i>
		168	</p>
		169
158	</body>	170	</body>
159	</section>	171	</section>
160	</chapter>	172	</chapter>
161	</pre>	173	</pre>
162		174
		175	<p>
163	<p>Above, I set the chapter title by adding a child <c><title></c>	176	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	177	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	178	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	179	<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>	180	<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	181	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	182	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>	183	inside a <c><body></c> element in a bit.
		184	</p>
171		185
		186	<note>
172	<note>A <c><guide></c> element can contain multiple	187	A <c><guide></c> element can contain multiple <c><chapter></c>
173	<c><chapter></c> elements, and a <c><chapter></c> can contain	188	elements, and a <c><chapter></c> can contain multiple
174	multiple <c><section></c> elements. However, a <c><section></c>	189	<c><section></c> elements. However, a <c><section></c>
175	element can only contain one <c><body></c> element. </note>	190	element can only contain one <c><body></c> element.
		191	</note>
176		192
177	</body>	193	</body>
178	</section>	194	</section>
179
180	<section>	195	<section>
181	<title>An example <body></title>	196	<title>An example <body></title>
182	<body>	197	<body>
		198
183	<p>	199	<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:	200	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>	201	</p>
		202
186	<pre>	203	<pre>
187	<p>	204	<p>
188	This is a paragraph. <path>/etc/passwd</path> is a file.	205	This is a paragraph. <path>/etc/passwd</path> is a file.
189	<uri>http://www.gentoo.org</uri> is my favorite website.	206	<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.	207	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:	214	Make HTML/XML easier to read by using selective emphasis:
198	<foo><i>bar</i></foo>	215	<foo><i>bar</i></foo>
199		216
200	<codenote>This is how to insert an inline note into the code block</codenote>	217	<codenote>This is how to insert an inline note into the code block</codenote>
201	</pre>	218	</pre>
202	<note>This is a note.</note>	219
203	<warn>This is a warning.</warn>	220	<note>
204	<impo>This is important.</impo>	221	This is a note.
		222	</note>
		223
		224	<warn>
		225	This is a warning.
		226	</warn>
		227
		228	<impo>
		229	This is important.
		230	</impo>
205	</pre>	231	</pre>
		232
		233	<p>
206	<p>Now, here's how this <c><body></c> element is rendered:</p>	234	Now, here's how this <c><body></c> element is rendered:
		235	</p>
207		236
208	<p>	237	<p>
209	This is a paragraph. <path>/etc/passwd</path> is a file.	238	This is a paragraph. <path>/etc/passwd</path> is a file.
210	<uri>http://www.gentoo.org</uri> is my favorite website.	239	<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.	240	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:	247	Make HTML/XML easier to read by using selective emphasis:
219	<foo><i>bar</i></foo>	248	<foo><i>bar</i></foo>
220		249
221	<codenote>This is how to insert an inline note into the code block</codenote>	250	<codenote>This is how to insert an inline note into the code block</codenote>
222	</pre>	251	</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		252
		253	<note>
		254	This is a note.
		255	</note>
		256
		257	<warn>
		258	This is a warning.
		259	</warn>
		260
		261	<impo>
		262	This is important.
		263	</impo>
		264
		265	</body>
		266	</section>
229	<section>	267	<section>
230	<title>The <body> tags</title>	268	<title>The <body> tags</title>
231	<body>	269	<body>
232		270
		271	<p>
233	<p> We introduced a lot of new tags in the previous section -- here's what you	272	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	273	need to know. The <c><p></c> (paragraph), <c><pre></c> (code
235	block), <c><note></c>, <c><warn></c> (warning) and	274	block), <c><note></c>, <c><warn></c> (warning) and
236	<c><impo></c> (important) tags all can contain one or more lines of text.	275	<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),	276	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	277	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	278	<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	279	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	280	<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>	281	preserves its whitespace exactly, making it well-suited for code excerpts.
		282	You can also name the <c><pre></c> tag:
		283	</p>
		284
		285	<pre caption = "Named <pre>">
		286	<pre caption = "Output of uptime">
		287	# <i>uptime</i>
		288	16:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25
		289	</pre>
		290	</pre>
243		291
244	</body>	292	</body>
245	</section>	293	</section>
246	<section>	294	<section>
247	<title><path>, <c> and <e></title>	295	<title><path>, <c> and <e></title>
248	<body>	296	<body>
249		297
		298	<p>
250	<p>The <c><path></c>, <c><c></c> and <c><e></c> elements can	299	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	300	be used inside any child <c><body></c> tag, except for
252	<c><pre></c>. </p>	301	<c><pre></c>.
		302	</p>
253		303
		304	<p>
254	<p>The <c><path></c> element is used to mark text that refers to an	305	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>.	306	<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	307	<e>simple filename</e>. This element is generally rendered with a monospaced
257	standard paragraph type. </p>	308	font to offset it from the standard paragraph type.
		309	</p>
258		310
		311	<p>
259	<p>The <c><c></c> element is used to mark up a <e>command</e> or <e>user	312	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	313	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	314	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>	315	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	316	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	317	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	318	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	319	<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	320	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	321	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>	322	the use of unnecessary double-quotes makes a document more readable -- and
		323	adorable!
		324	</p>
270		325
		326	<p>
271	<p><c><e></c> is used to apply emphasis to a word or phrase; for example:	327	<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	328	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	329	offset from the regular paragraph type for emphasis. This helps to give your
274	prose more <e>punch</e>!</p>	330	prose more <e>punch</e>!
		331	</p>
275		332
276	</body>	333	</body>
277	</section>	334	</section>
278
279	<section>	335	<section>
280	<title><mail> and <uri></title>	336	<title><mail> and <uri></title>
281	<body>	337	<body>
282		338
		339	<p>
283	<p>We've taken a look at the <c><mail></c> tag earlier; it's used to link some text	340	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>	341	some text with a particular email address, and takes the form <c><mail
		342	link="foo@bar.com">Mr. Foo Bar</mail></c>.
		343	</p>
285		344
		345	<p>
286	<p>The <c><uri></c> tag is used to point to files/locations on the	346	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	347	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	348	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	349	<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	350	<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	351	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>	352	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>.	353	<e>this</e> link, I typed <c><uri link="http://www.gentoo.org">the
		354	Gentoo Linux website</uri></c>.
294	</p>	355	</p>
295		356
296	</body>	357	</body>
297	</section>	358	</section>
298
299	<section>	359	<section>
300	<title>Figures</title>	360	<title>Figures</title>
301		361
302	<body>	362	<body>
303		363
		364	<p>
304	<p>Here's how to insert a figure into a document -- <c><figure	365	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	366	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,	367	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	368	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	369	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	370	:) We also support the standard HTML-style <img src="foo.gif"/> tag
310	for adding images without captions, borders, etc.</p>	371	for adding images without captions, borders, etc.
		372	</p>
311		373
312	</body>	374	</body>
313	</section>	375	</section>
314	<section>	376	<section>
315	<title>Tables and lists</title>	377	<title>Tables and lists</title>
316	<body>	378	<body>
317		379
		380	<p>
318	<p>Guide supports a simplified table syntax similar to that of HTML. To start	381	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>	382	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	383	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	384	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	385	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> --	386	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	387	-- 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	388	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.	389	be added (such as a <c>caption=</c> attribute for <c><table></c>) soon.
327	</p>	390	</p>
328		391
		392	<p>
329	<p> To create ordered or unordered lists, simply use the HTML-style	393	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	394	<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>,	395	should only appear inside a <c><p></c>, <c><ti></c>,
332	<c><note></c>, <c><warn></c> or <c><impo></c> tag. </p>	396	<c><note></c>, <c><warn></c> or <c><impo></c> tag.
		397	</p>
333		398
334	</body>	399	</body>
335	</section>	400	</section>
336
337	<section>	401	<section>
338	<title>Intra-document references</title>	402	<title>Intra-document references</title>
339	<body>	403	<body>
340		404
		405	<p>
341	<p>Guide makes it really easy to reference other parts of the document using	406	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	407	hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter
343	One</uri> by typing <c><uri link="#doc_chap1">Chapter	408	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	409	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	410	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	411	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>,	412	link="doc_chap1_fig3">figure 1.3</uri></c>. Or, to refer to <uri
		413	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	414	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>	415	adding other auto-link abilities (such as table support) soon.
		416	</p>
		417
		418	<p>
		419	However, some guides change often and using such "counting" can lead to broken
		420	links. In order to cope with this, you can define a name for a
		421	<c><chapter></c> or <c><section></c> by using the <c>id</c>
		422	attribute, and then point to that attribute, like this:
		423	</p>
		424
		425	<pre caption="Using the id attribute">
		426	<chapter id="foo">
		427	<title>This is foo!</title>
		428	...
		429	<p>
		430	More information can be found in the <uri link="#foo">foo chapter</uri>
		431	</p>
		432	</pre>
350		433
351	</body>	434	</body>
352	</section>	435	</section>
353	</chapter>	436	</chapter>
		437
		438	<chapter>
		439	<title>Coding Style</title>
		440	<section>
		441	<title>Introduction</title>
		442	<body>
		443
		444	<p>
		445	Since all Gentoo Documentation is a joint effort and several people will
		446	most likely change existing documentation, a coding style is needed.
		447	A coding style contains two sections. The first one is regarding
		448	internal coding - how the xml-tags are placed. The second one is
		449	regarding the content - how not to confuse the reader.
		450	</p>
		451
		452	<p>
		453	Both sections are described next.
		454	</p>
		455
		456	</body>
		457	</section>
		458	<section>
		459	<title>Internal Coding Style</title>
		460	<body>
		461
		462	<p>
		463	<b>Newlines</b> must be placed immediately after <e>every</e>
		464	GuideXML-tag (both opening as closing), except for:
		465	<c><version></c>, <c><date></c>, <c><title></c>,
		466	<c><th></c>, <c><ti></c>,
		467	<c><li></c>, <c><i></c>, <c><e></c>,
		468	<c><uri></c>, <c><path></c>, <c><b></c>,
		469	<c><comment></c>, <c><codenote></c>, <c><mail></c>.
		470	</p>
		471
		472	<p>
		473	<b>Blank lines</b> must be placed immediately after <e>every</e>
		474	<c><body></c> (opening tag only) and before <e>every</e>
		475	<c><chapter></c>, <c><p></c>, <c><table></c>,
		476	<c><author></c> (set), <c><pre></c>, <c><ul></c>,
		477	<c><ol></c>, <c><warn></c>, <c><note></c> and
		478	<c><impo></c> (opening tags only).
		479	</p>
		480
		481	<p>
		482	<b>Word-wrapping</b> must be applied at 80 characters except inside
		483	<c><pre></c>. Only when there is no other choice can be deviated from
		484	this rule (for instance when a URL exceeds the maximum amount of characters).
		485	The editor must then wrap whenever the first whitespace occurs.
		486	</p>
		487
		488	<p>
		489	<b>Indentation</b> may not be used, except with the XML-constructs of which
		490	the parent XML-tags are <c><tr></c> (from <c><table></c>),
		491	<c><ul></c>, <c><ol></c> and <c><author></c>. If indentation
		492	is used, it <e>must</e> be two spaces for each indentation. That means <e>no</e>
		493	tabs and <e>not</e> more spaces.
		494	</p>
		495
		496	<p>
		497	In case word-wrapping happens in <c><ti></c>, <c><th></c> or
		498	<c><li></c> constructs, indentation must be used for the content.
		499	</p>
		500
		501	<p>
		502	An example for indentation is:
		503	</p>
		504
		505	<pre caption = "Indentation Example">
		506	<table>
		507	<tr>
		508	<th>Foo</th>
		509	<th>Bar</th>
		510	</tr>
		511	<tr>
		512	<ti>This is an example for indentation.</ti>
		513	<ti>
		514	In case text cannot be shown within an 80-character wide line, you
		515	must use indentation if the parent tag allows it.
		516	</ti>
		517	</tr>
		518	</table>
		519
		520	<ul>
		521	<li>First option</li>
		522	<li>Second option</li>
		523	</ul>
		524	</pre>
		525
		526	<p>
		527	<b>Attributes</b> may not have spaces in between the attribute, the
		528	"=" mark, and the attribute value. As an example:
		529	</p>
		530
		531	<pre caption="Attributes">
		532	<comment>Wrong :</comment> <pre caption = "Attributes">
		533	<comment>Correct:</comment> <pre caption="Attributes">
		534	</pre>
		535
		536	</body>
		537	</section>
		538	<section>
		539	<title>External Coding Style</title>
		540	<body>
		541
		542	<p>
		543	Inside tables (<c><table></c>) and listings (<c><ul></c> and
		544	<c><ol></c>), periods (".") should not be used unless multiple
		545	sentences are used. In that case, every sentence should end with a period (or
		546	other reading marks).
		547	</p>
		548
		549	<p>
		550	Every sentence, including those inside tables and listings, should start
		551	with a capital letter.
		552	</p>
		553
		554	<pre caption="Periods and capital letters">
		555	<ul>
		556	<li>No period</li>
		557	<li>With period. Multiple sentences, remember?</li>
		558	</ul>
		559	</pre>
		560
		561	<p>
		562	Code Listings should <e>always</e> have a <c>caption</c>.
		563	</p>
		564
		565	<p>
		566	Try to use <c><uri></c> with the <c>link</c> attribute as much as
		567	possible. In other words, the <uri link="http://www.gentoo.org">Gentoo
		568	Website</uri> is preferred over <uri>http://www.gentoo.org</uri>.
		569	</p>
		570
		571	<p>
		572	When you comment something inside a <c><pre></c> construct, only use
		573	<c><codenote></c> if the content is a C or C++ code snippet. Otherwise,
		574	use <c><comment></c> and parantheses. Also place the comment <e>before</e>
		575	the subject of the comment.
		576	</p>
		577
		578	<pre caption="Comment example">
		579	<comment>(Substitute "john" with your user name)</comment>
		580	# <i>id john</i>
		581	</pre>
		582
		583	</body>
		584	</section>
		585	</chapter>
		586
		587	<chapter>
		588	<title>Handbook Format</title>
		589	<section>
		590	<title>Guide vs Book</title>
		591	<body>
		592
		593	<p>
		594	For high-volume documentation, such as the <uri
		595	link="/doc/en/handbook/handbook.xml?part=1">Installation Instructions</uri>, a
		596	broader format was needed. We designed a GuideXML-compatible enhancement that
		597	allows us to write modular and multi-page documentation.
		598	</p>
		599
		600	</body>
		601	</section>
		602	<section>
		603	<title>Main File</title>
		604	<body>
		605
		606	<p>
		607	The first change is the need for a "master" document. This document contains no
		608	real content, but links to the individual documentation modules. The syntaxis
		609	doesn't differ much from GuideXML:
		610	</p>
		611
		612	<pre caption="Example book usage">
		613	<?xml version='1.0' encoding='UTF-8'?>
		614	<!DOCTYPE book SYSTEM "/dtd/book.dtd">
		615
		616	<<i>book</i> link="example.xml">
		617	<title>Example Book Usage</title>
		618
		619	<author...>
		620	...
		621	</author>
		622
		623	<abstract>
		624	...
		625	</abstract>
		626
		627	<!-- The content of this document is licensed under the CC-BY-SA license -->
		628	<!-- See http://creativecommons.org/licenses/by-sa/1.0 -->
		629	<license/>
		630
		631	<version>...</version>
		632	<date>...</date>
		633	</pre>
		634
		635	<p>
		636	So far no real differences (except for the <c><book></c> instead of
		637	<c><guide></c> tag). Instead of starting with the individual
		638	<c><chapter></c>'s, you define a <c><part></c>, which is the
		639	equivalent of a separate part in a book:
		640	</p>
		641
		642	<pre caption="Defining a part">
		643	<part>
		644	<title>Part One</title>
		645	<abstract>
		646	...
		647	</abstract>
		648
		649	<comment>(Defining the several chapters)</comment>
		650	</part>
		651	</pre>
		652
		653	<p>
		654	Each part is accompanied by a <c><title></c> and an
		655	<c><abstract></c> which gives a small introduction to the part.
		656	</p>
		657
		658	<p>
		659	Inside each part, you define the individual <c><chapter></c>'s. Each
		660	chapter <e>must</e> be a separate document. As a result it is no surprise that a
		661	special tag (<c><include></c>) is added to allow including the separate
		662	document.
		663	</p>
		664
		665	<pre caption="Defining a chapter">
		666	<chapter>
		667	<title>Chapter One</title>
		668	<abstract>
		669	This is a small explanation on chapter one.
		670	</abstract>
		671
		672	<include href="path/to/chapter-one.xml"/>
		673
		674	</chapter>
		675	</pre>
		676
		677	</body>
		678	</section>
		679	<section>
		680	<title>Designing the Individual Chapters</title>
		681	<body>
		682
		683	<p>
		684	The content of an individual chapter is structured as follows:
		685	</p>
		686
		687	<pre caption="Chapter Syntax">
		688	<?xml version='1.0' encoding='UTF-8'?>
		689	<!DOCTYPE sections SYSTEM "/dtd/book.dtd">
		690
		691	<!-- The content of this document is licensed under the CC-BY-SA license -->
		692	<!-- See http://creativecommons.org/licenses/by-sa/1.0 -->
		693
		694	<sections>
		695
		696	<comment>(Define the several <section> and <subsection>)</comment>
		697
		698	</sections>
		699	</pre>
		700
		701	<p>
		702	Inside each chapter you can define <c><section></c>'s (equivalent of
		703	<c><chapter></c> in a Guide) and <c><subsection></c>'s (equivalent
		704	of <c><section></c> in a Guide).
		705	</p>
		706
		707	</body>
		708	</section>
		709	</chapter>
		710
354	<chapter>	711	<chapter>
355	<title>Resources</title>	712	<title>Resources</title>
356	<section>	713	<section>
357	<title>Start writing</title>	714	<title>Start writing</title>
358	<body>	715	<body>
		716
		717	<p>
359	<p>Guide has been specially designed to be "lean and mean" so that developers	718	Guide has been specially designed to be "lean and mean" so that developers
360	can spend more time writing documentation and less time learning the actual XML	719	can spend more time writing documentation and less time learning the actual XML
361	syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy"	720	syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy"
362	to start writing quality Gentoo Linux documentation. If you'd like to help (or have any questions about guide), please	721	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>	722	have any questions about guide), please post a message to the <mail
364	stating what you'd like to tackle.	723	link="gentoo-doc@gentoo.org">gentoo-doc mailing list</mail> stating what you'd
365	Have fun!</p>	724	like to tackle. Have fun!
		725	</p>
		726
366	</body>	727	</body>
367	</section>	728	</section>
368	</chapter>	729	</chapter>
369	</guide>	730	</guide>
370		731

 Legend:



Removed from v.1.3
 


changed lines


 
Added in v.1.26
 Legend:



Removed from v.1.3
 


changed lines


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

	ViewVC Help
Powered by ViewVC 1.1.13