/[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
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
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>
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;
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>
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
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>
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>

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

  ViewVC Help
Powered by ViewVC 1.1.20