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

 Legend:



Removed from v.1.6
 


changed lines


 
Added in v.1.39
 Legend:



Removed from v.1.6
 


changed lines


 
Added in v.1.39
-Removed from v.1.6
+Added in v.1.39

	ViewVC Help
Powered by ViewVC 1.1.20