/[gentoo]/xml/htdocs/doc/en/xml-guide.xml
Gentoo

Diff of /xml/htdocs/doc/en/xml-guide.xml

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.57 Revision 1.58
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.57 2006/01/09 14:44:14 neysx Exp $ --> 2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.58 2006/02/20 12:17:24 neysx Exp $ -->
3<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> 3<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4 4
5<guide link="/doc/en/xml-guide.xml"> 5<guide link="/doc/en/xml-guide.xml">
6<title>Gentoo XML Guide</title> 6<title>Gentoo XML Guide</title>
7 7
8<author title="Author">
9 <mail link="neysx@gentoo.org">Xavier Neys</mail>
10</author>
8<author title="Author"> 11<author title="Author">
9 <mail link="drobbins@gentoo.org">Daniel Robbins</mail> 12 <mail link="drobbins@gentoo.org">Daniel Robbins</mail>
10</author> 13</author>
11<author title="Author"><!-- zhen@gentoo.org --> 14<author title="Author"><!-- zhen@gentoo.org -->
12 John P. Davis 15 John P. Davis
13</author> 16</author>
14<author title="Editor"> 17<author title="Editor">
15 <mail link="peesh@gentoo.org">Jorge Paulo</mail> 18 <mail link="peesh@gentoo.org">Jorge Paulo</mail>
16</author> 19</author>
17<author title="Editor"> 20<author title="Editor">
18 <mail link="swift@gentoo.org">Sven Vermeulen</mail> 21 <mail link="swift@gentoo.org">Sven Vermeulen</mail>
19</author> 22</author>
20<author title="Editor">
21 <mail link="neysx@gentoo.org">Xavier Neys</mail>
22</author>
23 23
24<abstract> 24<abstract>
25This guide shows you how to compose web documentation using the new lightweight 25This guide shows you how to compose web documentation using the new lightweight
26Gentoo GuideXML syntax. This syntax is the official format for Gentoo 26Gentoo GuideXML syntax. This syntax is the official format for Gentoo
27documentation, and this document itself was created using GuideXML. This guide 27documentation, and this document itself was created using GuideXML. This guide
28assumes a basic working knowledge of XML and HTML. 28assumes a basic working knowledge of XML and HTML.
29</abstract> 29</abstract>
30 30
31<!-- The content of this document is licensed under the CC-BY-SA license --> 31<!-- The content of this document is licensed under the CC-BY-SA license -->
32<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> 32<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
33<license/> 33<license/>
34 34
35<version>2.29</version> 35<version>3</version>
36<date>2005-10-13</date> 36<date>2006-02-18</date>
37 37
38<chapter> 38<chapter>
39<title>Guide basics</title> 39<title>Guide basics</title>
40<section> 40<section>
41<title>Guide XML design goals</title> 41<title>Guide XML design goals</title>
42<body> 42<body>
43 43
44<p> 44<p>
45The guide XML syntax is lightweight yet expressive, so that it is easy to 45The guide XML syntax is lightweight yet expressive, so that it is easy to
46learn yet also provides all the features we need for the creation of web 46learn yet also provides all the features we need for the creation of web
47documentation. The number of tags is kept to a minimum -- just those we need. 47documentation. The number of tags is kept to a minimum -- just those we need.
48This makes it easy to transform guide into other formats, such as DocBook 48This makes it easy to transform guide into other formats, such as DocBook
49XML/SGML or web-ready HTML. 49XML/SGML or web-ready HTML.
50</p> 50</p>
51 51
235 235
236<pre caption="Example of a body element"> 236<pre caption="Example of a body element">
237&lt;p&gt; 237&lt;p&gt;
238This is a paragraph. &lt;path&gt;/etc/passwd&lt;/path&gt; is a file. 238This is a paragraph. &lt;path&gt;/etc/passwd&lt;/path&gt; is a file.
239&lt;uri&gt;http://forums.gentoo.org&lt;/uri&gt; is my favorite website. 239&lt;uri&gt;http://forums.gentoo.org&lt;/uri&gt; is my favorite website.
240Type &lt;c&gt;ls&lt;/c&gt; if you feel like it. I &lt;e&gt;really&lt;/e&gt; want to go to sleep now. 240Type &lt;c&gt;ls&lt;/c&gt; if you feel like it. I &lt;e&gt;really&lt;/e&gt; want to go to sleep now.
241&lt;/p&gt; 241&lt;/p&gt;
242 242
243&lt;pre caption="Code Sample"&gt; 243&lt;pre caption="Code Sample"&gt;
244This is text output or code. 244This is text output or code.
245# &lt;i&gt;this is user input&lt;/i&gt; 245# &lt;i&gt;this is user input&lt;/i&gt;
246 246
247Make HTML/XML easier to read by using selective emphasis: 247Make HTML/XML easier to read by using selective emphasis:
248&lt;foo&gt;&lt;i&gt;bar&lt;/i&gt;&lt;/foo&gt; 248&lt;foo&gt;&lt;i&gt;bar&lt;/i&gt;&lt;/foo&gt;
249 249
250&lt;comment&gt;(This is how to insert an inline note into the code block)&lt;/comment&gt; 250&lt;comment&gt;(This is how to insert a comment into a code block)&lt;/comment&gt;
251&lt;/pre&gt; 251&lt;/pre&gt;
252 252
253&lt;note&gt; 253&lt;note&gt;
254This is a note. 254This is a note.
255&lt;/note&gt; 255&lt;/note&gt;
256 256
257&lt;warn&gt; 257&lt;warn&gt;
258This is a warning. 258This is a warning.
259&lt;/warn&gt; 259&lt;/warn&gt;
260 260
261&lt;impo&gt; 261&lt;impo&gt;
262This is important. 262This is important.
263&lt;/impo&gt; 263&lt;/impo&gt;
264</pre> 264</pre>
265 265
268</p> 268</p>
269 269
270<p> 270<p>
271This is a paragraph. <path>/etc/passwd</path> is a file. 271This is a paragraph. <path>/etc/passwd</path> is a file.
272<uri>http://forums.gentoo.org</uri> is my favorite web site. 272<uri>http://forums.gentoo.org</uri> is my favorite web site.
273Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now. 273Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now.
274</p> 274</p>
275 275
276<pre caption="Code Sample"> 276<pre caption="Code Sample">
277This is text output or code. 277This is text output or code.
278# <i>this is user input</i> 278# <i>this is user input</i>
279 279
280Make HTML/XML easier to read by using selective emphasis: 280Make HTML/XML easier to read by using selective emphasis:
281&lt;foo&gt;<i>bar</i>&lt;/foo&gt; 281&lt;foo&gt;<i>bar</i>&lt;/foo&gt;
282 282
283<comment>(This is how to insert an inline note into the code block)</comment> 283<comment>(This is how to insert a comment into a code block)</comment>
284</pre> 284</pre>
285 285
286<note> 286<note>
287This is a note. 287This is a note.
288</note> 288</note>
289 289
290<warn> 290<warn>
291This is a warning. 291This is a warning.
292</warn> 292</warn>
293 293
294<impo> 294<impo>
295This is important. 295This is important.
296</impo> 296</impo>
297 297
298</body> 298</body>
341Epigraphs are sometimes used at the beginning of chapters to illustrate what is 341Epigraphs are sometimes used at the beginning of chapters to illustrate what is
342to follow. It is simply a paragraph with a <c>by</c> attribute that contains 342to follow. It is simply a paragraph with a <c>by</c> attribute that contains
343the signature. 343the signature.
344</p> 344</p>
345 345
346<pre caption="Short epigraph"> 346<pre caption="Short epigraph">
347&lt;p by="Anonymous student"&gt; 347&lt;p by="Anonymous student"&gt;
348Delegates from the original 13 states formed the... 348Delegates from the original 13 states formed the...
349&lt;/p&gt; 349&lt;/p&gt;
350</pre> 350</pre>
351 351
352</body> 352</body>
353</section> 353</section>
354<section> 354<section>
355<title> 355<title>
356 &lt;path&gt;, &lt;c&gt;, &lt;i&gt;, &lt;b&gt;, &lt;e&gt;, &lt;sub&gt; and &lt;sup&gt; 356 &lt;path&gt;, &lt;c&gt;, &lt;b&gt;, &lt;e&gt;, &lt;sub&gt; and &lt;sup&gt;
357</title> 357</title>
358<body> 358<body>
359 359
360<p> 360<p>
361The <c>&lt;path&gt;</c>, <c>&lt;c&gt;</c>, <c>&lt;b&gt;</c>, <c>&lt;e&gt;</c>, 361The <c>&lt;path&gt;</c>, <c>&lt;c&gt;</c>, <c>&lt;b&gt;</c>, <c>&lt;e&gt;</c>,
362<c>&lt;sub&gt;</c> and <c>&lt;sup&gt;</c> elements can be used inside any child 362<c>&lt;sub&gt;</c> and <c>&lt;sup&gt;</c> elements can be used inside any child
363<c>&lt;body&gt;</c> tag, except for <c>&lt;pre&gt;</c>. The <c>&lt;i&gt;</c> 363<c>&lt;body&gt;</c> tag, except for <c>&lt;pre&gt;</c>.
364element can only be used inside <c>&lt;pre&gt;</c>.
365</p> 364</p>
366 365
367<p> 366<p>
368The <c>&lt;path&gt;</c> element is used to mark text that refers to an 367The <c>&lt;path&gt;</c> element is used to mark text that refers to an
369<e>on-disk file</e> -- either an <e>absolute or relative path</e>, or a 368<e>on-disk file</e> -- either an <e>absolute or relative path</e>, or a
370<e>simple filename</e>. This element is generally rendered with a mono spaced 369<e>simple filename</e>. This element is generally rendered with a mono spaced
371font to offset it from the standard paragraph type. 370font to offset it from the standard paragraph type.
372</p> 371</p>
373 372
374<p> 373<p>
375The <c>&lt;c&gt;</c> element is used to mark up a <e>command</e> or <e>user 374The <c>&lt;c&gt;</c> element is used to mark up a <e>command</e> or <e>user
376input</e>. Think of <c>&lt;c&gt;</c> as a way to alert the reader to something 375input</e>. Think of <c>&lt;c&gt;</c> as a way to alert the reader to something
377that they can type in that will perform some kind of action. For example, all 376that they can type in that will perform some kind of action. For example, all
378the XML tags displayed in this document are enclosed in a <c>&lt;c&gt;</c> 377the XML tags displayed in this document are enclosed in a <c>&lt;c&gt;</c>
379element because they represent something that the user could type in that is 378element because they represent something that the user could type in that is
380not a path. By using <c>&lt;c&gt;</c> elements, you'll help your readers 379not a path. By using <c>&lt;c&gt;</c> elements, you'll help your readers
381quickly identify commands that they need to type in. Also, because 380quickly identify commands that they need to type in. Also, because
382<c>&lt;c&gt;</c> elements are already offset from regular text, <e>it is rarely 381<c>&lt;c&gt;</c> elements are already offset from regular text, <e>it is rarely
383necessary to surround user input with double-quotes</e>. For example, don't 382necessary to surround user input with double-quotes</e>. For example, don't
384refer to a "<c>&lt;c&gt;</c>" element like I did in this sentence. Avoiding 383refer to a "<c>&lt;c&gt;</c>" element like I did in this sentence. Avoiding
385the use of unnecessary double-quotes makes a document more readable -- and 384the use of unnecessary double-quotes makes a document more readable -- and
386adorable! 385adorable!
387</p> 386</p>
388 387
389<p> 388<p>
390When you want to highlight some text as user input inside a <c>&lt;pre&gt;</c>,
391use <c>&lt;i&gt;</c> instead.
392</p>
393
394<p>
395As you might have guessed, <c>&lt;b&gt;</c> is used to <b>boldface</b> some 389As you might have guessed, <c>&lt;b&gt;</c> is used to <b>boldface</b> some
396text. 390text.
397</p> 391</p>
398 392
399<p> 393<p>
400<c>&lt;e&gt;</c> is used to apply emphasis to a word or phrase; for example: 394<c>&lt;e&gt;</c> is used to apply emphasis to a word or phrase; for example:
401I <e>really</e> should use semicolons more often. As you can see, this text is 395I <e>really</e> should use semicolons more often. As you can see, this text is
402offset from the regular paragraph type for emphasis. This helps to give your 396offset from the regular paragraph type for emphasis. This helps to give your
403prose more <e>punch</e>! 397prose more <e>punch</e>!
404</p> 398</p>
405 399
406<p> 400<p>
407The <c>&lt;sub&gt;</c> and <c>&lt;sup&gt;</c> elements are used to specify 401The <c>&lt;sub&gt;</c> and <c>&lt;sup&gt;</c> elements are used to specify
408<sub>subscript</sub> and <sup>superscript</sup>. 402<sub>subscript</sub> and <sup>superscript</sup>.
409</p> 403</p>
404
405</body>
406</section>
407<section>
408<title>Code samples and colour-coding</title>
409<body>
410
411<p>
412To improve the readability of code samples, the following tags are allowed
413inside <c>&lt;pre&gt;</c> blocks:
414</p>
415
416<dl>
417 <dt><c>&lt;i&gt;</c></dt>
418 <dd>Distinguishes user input from displayed text</dd>
419 <dt><c>&lt;comment&gt;</c></dt>
420 <dd>Comments relevant to the action(s) that appear after the comment</dd>
421 <dt><c>&lt;keyword&gt;</c></dt>
422 <dd>Denotes a keyword in the language used in the code sample
423 </dd>
424 <dt><c>&lt;ident&gt;</c></dt>
425 <dd>Used for an identifier
426 </dd>
427 <dt><c>&lt;const&gt;</c></dt>
428 <dd>Used for a constant
429 </dd>
430 <dt><c>&lt;stmt&gt;</c></dt>
431 <dd>Used for a statement
432 </dd>
433 <dt><c>&lt;var&gt;</c></dt>
434 <dd>Used for a variable
435 </dd>
436</dl>
437
438<note>
439Remember that all leading and trailing spaces, and line breaks in
440<c>&lt;pre&gt;</c> blocks will appear in the displayed html page.
441</note>
442
443<p>
444Sample colour-coded <c>&lt;pre&gt;</c> block:
445</p>
446
447<pre caption="My first ebuild">
448<comment># Copyright 1999-2006 <b>Gentoo Foundation</b>
449# Distributed under the terms of the GNU General Public License v2
450# &#36;Header: $</comment>
451
452<ident>DESCRIPTION</ident>=<const>"Exuberant ctags generates tags files for quick source navigation"</const>
453<ident>HOMEPAGE</ident>=<const>"http://ctags.sourceforge.net"</const>
454<ident>SRC_URI</ident>=<const>"mirror://sourceforge/ctags/<var>${P}</var>.tar.gz"</const>
455
456<ident>LICENSE</ident>=<const>"GPL-2"</const>
457<ident>SLOT</ident>=<const>"0"</const>
458<ident>KEYWORDS</ident>=<const>"~mips ~sparc ~x86"</const>
459<ident>IUSE</ident>=<const>""</const>
460
461<stmt>src_compile()</stmt> {
462 <keyword>econf</keyword> --with-posix-regex || <keyword>die</keyword> <const>"econf failed"</const>
463 <keyword>emake</keyword> || <keyword>die</keyword> <const>"emake failed"</const>
464}
465
466<stmt>src_install()</stmt> {
467 <keyword>make</keyword> <ident>DESTDIR</ident>="<var>${D}</var>" install || <keyword>die</keyword> <const>"install failed"</const>
468
469 <keyword>dodoc</keyword> FAQ NEWS README
470 <keyword>dohtml</keyword> EXTENDING.html ctags.html
471}
472</pre>
410 473
411</body> 474</body>
412</section> 475</section>
413<section> 476<section>
414<title>&lt;mail&gt; and &lt;uri&gt;</title> 477<title>&lt;mail&gt; and &lt;uri&gt;</title>
415<body> 478<body>
416 479
417<p> 480<p>
418We've taken a look at the <c>&lt;mail&gt;</c> tag earlier; it's used to link 481We've taken a look at the <c>&lt;mail&gt;</c> tag earlier; it's used to link
419some text with a particular email address, and takes the form <c>&lt;mail 482some text with a particular email address, and takes the form <c>&lt;mail
420link="foo@bar.com"&gt;Mr. Foo Bar&lt;/mail&gt;</c>. If you want to display the 483link="foo@bar.com"&gt;Mr. Foo Bar&lt;/mail&gt;</c>. If you want to display the
421email address, you can use <c>&lt;mail&gt;foo@bar.com&lt;/mail&gt;</c>, this 484email address, you can use <c>&lt;mail&gt;foo@bar.com&lt;/mail&gt;</c>, this
422would be displayed as <mail>foo@bar.com</mail>. 485would be displayed as <mail>foo@bar.com</mail>.
423</p> 486</p>
424 487

Legend:
Removed from v.1.57  
changed lines
  Added in v.1.58

  ViewVC Help
Powered by ViewVC 1.1.20