/[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.50 Revision 1.51
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.50 2005/10/09 06:07:09 vapier Exp $ --> 2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.51 2005/10/09 11:00:20 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
111 111
112<p> 112<p>
113On the first lines, we see the requisite tag that identifies this as an XML 113On the first lines, we see the requisite tag that identifies this as an XML
114document and specifies its DTD. The <c>&lt;!-- &#36;Header&#36; --&gt;</c> line 114document and specifies its DTD. The <c>&lt;!-- &#36;Header&#36; --&gt;</c> line
115will be automatically modified by the CVS server and helps to track revisions. 115will be automatically modified by the CVS server and helps to track revisions.
116Next, there's a <c>&lt;guide&gt;</c> tag -- the entire guide document is 116Next, there's a <c>&lt;guide&gt;</c> tag -- the entire guide document is
117enclosed within a <c>&lt;guide&gt; &lt;/guide&gt;</c> pair. The <c>link</c> 117enclosed within a <c>&lt;guide&gt; &lt;/guide&gt;</c> pair. The <c>link</c>
118attribute is compulsory and should preferably contain the absolute path to the 118attribute is compulsory and should preferably contain the absolute path to the
119document relatively to the document root even though the file name alone will 119document relatively to the document root even though the file name alone will
120work. It is mainly used to generate a link to a printer-friendly version of 120work. It is mainly used to generate a link to a printer-friendly version of
121your document. If you use a wrong value, the link to the printable version 121your document. If you use a wrong value, the link to the printable version will
122will either not work or point to a wrong document. The <c>lang</c> attribute 122either not work or point to a wrong document. Translated documents <e>must</e>
123can be used to specify the language code of your document. It is used to format 123specify the full path because it is also used to check whether a more recent
124the date and insert strings like "<e>Note</e>", "<e>Content</e>", etc. in the 124original document exists. The <c>lang</c> attribute should be used to specify
125specified language. The default is English. 125the language code of your document. It is used to format the date and insert
126strings like "<e>Note</e>", "<e>Content</e>", etc. in the specified language.
127The default is English.
126</p> 128</p>
127 129
128<p> 130<p>
129Next, there's a <c>&lt;title&gt;</c> tag, used to set the title for the entire 131Next, there's a <c>&lt;title&gt;</c> tag, used to set the title for the entire
130guide document. 132guide document.
303these are the only tags that should appear immediately inside a 305these are the only tags that should appear immediately inside a
304<c>&lt;body&gt;</c> element. Another thing -- these tags <e>should not</e> be 306<c>&lt;body&gt;</c> element. Another thing -- these tags <e>should not</e> be
305stacked -- in other words, don't put a <c>&lt;note&gt;</c> element inside a 307stacked -- in other words, don't put a <c>&lt;note&gt;</c> element inside a
306<c>&lt;p&gt;</c> element. As you might guess, the <c>&lt;pre&gt;</c> element 308<c>&lt;p&gt;</c> element. As you might guess, the <c>&lt;pre&gt;</c> element
307preserves its whitespace exactly, making it well-suited for code excerpts. 309preserves its whitespace exactly, making it well-suited for code excerpts.
308You can also name the <c>&lt;pre&gt;</c> tag: 310You must name the <c>&lt;pre&gt;</c> tag with a caption attribute:
309</p> 311</p>
310 312
311<pre caption="Named &lt;pre&gt;"> 313<pre caption="Named &lt;pre&gt;">
312&lt;pre caption = "Output of uptime"&gt; 314&lt;pre caption="Output of uptime"&gt;
313# &lt;i&gt;uptime&lt;/i&gt; 315# &lt;i&gt;uptime&lt;/i&gt;
31416:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25 31616:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25
315&lt;/pre&gt; 317&lt;/pre&gt;
316</pre> 318</pre>
317 319
318</body> 320</body>
319</section> 321</section>
320<section> 322<section>
321<title>&lt;path&gt;, &lt;c&gt;, &lt;i&gt; and &lt;e&gt;</title> 323<title>&lt;path&gt;, &lt;c&gt;, &lt;i&gt;, &lt;b&gt; and &lt;e&gt;</title>
322<body> 324<body>
323 325
324<p> 326<p>
325The <c>&lt;path&gt;</c>, <c>&lt;c&gt;</c> and <c>&lt;e&gt;</c> elements can 327The <c>&lt;path&gt;</c>, <c>&lt;c&gt;</c>, <c>&lt;b&gt;</c> and <c>&lt;e&gt;</c> elements can
326be used inside any child <c>&lt;body&gt;</c> tag, except for 328be used inside any child <c>&lt;body&gt;</c> tag, except for
327<c>&lt;pre&gt;</c>. The <c>&lt;i&gt;</c> element can only be used inside 329<c>&lt;pre&gt;</c>. The <c>&lt;i&gt;</c> element can only be used inside
328<c>&lt;pre&gt;</c>. 330<c>&lt;pre&gt;</c>.
329</p> 331</p>
330 332
354When you want to highlight some text as user input inside a <c>&lt;pre&gt;</c>, 356When you want to highlight some text as user input inside a <c>&lt;pre&gt;</c>,
355use <c>&lt;i&gt;</c> instead. 357use <c>&lt;i&gt;</c> instead.
356</p> 358</p>
357 359
358<p> 360<p>
361As you might have guessed, <c>&lt;b&gt;</c> is used to <b>boldface</b> some
362text.
363</p>
364
365<p>
359<c>&lt;e&gt;</c> is used to apply emphasis to a word or phrase; for example: 366<c>&lt;e&gt;</c> is used to apply emphasis to a word or phrase; for example:
360I <e>really</e> should use semicolons more often. As you can see, this text is 367I <e>really</e> should use semicolons more often. As you can see, this text is
361offset from the regular paragraph type for emphasis. This helps to give your 368offset from the regular paragraph type for emphasis. This helps to give your
362prose more <e>punch</e>! 369prose more <e>punch</e>!
363</p> 370</p>
367<section> 374<section>
368<title>&lt;mail&gt; and &lt;uri&gt;</title> 375<title>&lt;mail&gt; and &lt;uri&gt;</title>
369<body> 376<body>
370 377
371<p> 378<p>
372We've taken a look at the <c>&lt;mail&gt;</c> tag earlier; it's used to link 379We've taken a look at the <c>&lt;mail&gt;</c> tag earlier; it's used to link
373some text with a particular email address, and takes the form <c>&lt;mail 380some text with a particular email address, and takes the form <c>&lt;mail
374link="foo@bar.com"&gt;Mr. Foo Bar&lt;/mail&gt;</c>. 381link="foo@bar.com"&gt;Mr. Foo Bar&lt;/mail&gt;</c>. If you want to display the
382email address, you can use <c>&lt;mail&gt;foo@bar.com&lt;/mail&gt;</c>, this
383would be displayed as <mail>foo@bar.com</mail>.
375</p> 384</p>
376 385
377<p> 386<p>
378The <c>&lt;uri&gt;</c> tag is used to point to files/locations on the Internet. 387The <c>&lt;uri&gt;</c> tag is used to point to files/locations on the Internet.
379It has two forms -- the first can be used when you want to have the actual URI 388It has two forms -- the first can be used when you want to have the actual URI
412<section> 421<section>
413<title>Tables and lists</title> 422<title>Tables and lists</title>
414<body> 423<body>
415 424
416<p> 425<p>
417Guide supports a simplified table syntax similar to that of HTML. To start 426Guide supports a simplified table syntax similar to that of HTML. To start a
418a table, use a <c>&lt;table&gt;</c> tag. Start a row with a <c>&lt;tr&gt;</c> 427table, use a <c>&lt;table&gt;</c> tag. Start a row with a <c>&lt;tr&gt;</c>
419tag. However, for inserting actual table data, we <e>don't</e> support the 428tag. However, for inserting actual table data, we <e>don't</e> support the
420HTML &lt;td&gt; tag; instead, use the <c>&lt;th&gt;</c> if you are inserting a 429HTML &lt;td&gt; tag; instead, use the <c>&lt;th&gt;</c> if you are inserting a
421header, and <c>&lt;ti&gt;</c> if you are inserting a normal informational 430header, and <c>&lt;ti&gt;</c> if you are inserting a normal informational
422block. You can use a <c>&lt;th&gt;</c> anywhere you can use a <c>&lt;ti&gt;</c> 431block. You can use a <c>&lt;th&gt;</c> anywhere you can use a <c>&lt;ti&gt;</c>
423-- there's no requirement that <c>&lt;th&gt;</c> elements appear only in the 432-- there's no requirement that <c>&lt;th&gt;</c> elements appear only in the
424first row. Currently, these tags don't support any attributes, but some might 433first row.
425be added (such as a <c>caption=</c> attribute for <c>&lt;table&gt;</c>) later.
426</p> 434</p>
427 435
428<p> 436<p>
429To create ordered or unordered lists, simply use the XHTML-style 437To create ordered or unordered lists, simply use the XHTML-style
430<c>&lt;ol&gt;</c>, <c>&lt;ul&gt;</c> and <c>&lt;li&gt;</c> tags. List tags 438<c>&lt;ol&gt;</c>, <c>&lt;ul&gt;</c> and <c>&lt;li&gt;</c> tags. List tags
468&lt;/p&gt; 476&lt;/p&gt;
469</pre> 477</pre>
470 478
471</body> 479</body>
472</section> 480</section>
481<section>
482<title>Disclaimers and obsolete documents</title>
483<body>
484
485<p>
486A disclaimer attribute can be applied to guides and handbooks to display a predefined disclaimer at the top of the document. The available disclaimers are:
487</p>
488
489<ul>
490 <li>
491 <b>articles</b> is used for <uri link="/doc/en/articles/">republished
492 articles</uri>
493 </li>
494 <li>
495 <b>draft</b> is used to indicate a document is still being worked on and
496 should not be considered official
497 </li>
498 <li>
499 <b>oldbook</b> is used on old handbooks to indicate they are not maintained
500 anymore
501 </li>
502 <li><b>obsolete</b> is used to mark a document as obsolete.</li>
503</ul>
504
505<p>
506When marking a document as obsolete, you might want to add a link to a new
507version. The <c>redirect</c> attribute does just that. The user might be
508automatically redirected to the new page but you should not rely on that
509behaviour.
510</p>
511
512<pre caption="Disclaimer sample">
513&lt;?xml version="1.0" encoding="UTF-8"?&gt;
514&lt;!DOCTYPE guide SYSTEM "/dtd/guide.dtd"&gt;
515&lt;!-- &#36;Header&#36; --&gt;
516
517&lt;guide link="/doc/en/gentoo-x86-install.xml" disclaimer="obsolete" redirect="/doc/en/handbook/handbook-x86.xml"&gt;
518&lt;title>Gentoo x86 Installation Guide&lt;/title&gt;
519
520&lt;author title="Author"&gt;
521...
522</pre>
523
524</body>
525</section>
473</chapter> 526</chapter>
474 527
475<chapter> 528<chapter>
476<title>Coding Style</title> 529<title>Coding Style</title>
477<section> 530<section>
515<c>&lt;impo&gt;</c> (opening tags only). 568<c>&lt;impo&gt;</c> (opening tags only).
516</p> 569</p>
517 570
518<p> 571<p>
519<b>Word-wrapping</b> must be applied at 80 characters except inside 572<b>Word-wrapping</b> must be applied at 80 characters except inside
520<c>&lt;pre&gt;</c>. Only when there is no other choice can be deviated from 573<c>&lt;pre&gt;</c>. You may only deviate from this rule when there is no other
521this rule (for instance when a URL exceeds the maximum amount of characters). 574choice (for instance when a URL exceeds the maximum amount of characters). The
522The editor must then wrap whenever the first whitespace occurs. 575editor must then wrap whenever the first whitespace occurs. You should try to
523</p> 576keep the <e>rendered</e> content of <c>&lt;pre&gt;</c> elements within 80
524 577columns to help console users.
525<p> 578</p>
579
580<p>
526<b>Indentation</b> may not be used, except with the XML-constructs of which 581<b>Indentation</b> may not be used, except with the XML-constructs of which the
527the parent XML-tags are <c>&lt;tr&gt;</c> (from <c>&lt;table&gt;</c>), 582parent XML-tags are <c>&lt;tr&gt;</c> (from <c>&lt;table&gt;</c>),
528<c>&lt;ul&gt;</c>, <c>&lt;ol&gt;</c> and <c>&lt;author&gt;</c>. If indentation 583<c>&lt;ul&gt;</c>, <c>&lt;ol&gt;</c> and <c>&lt;author&gt;</c>. If indentation
529is used, it <e>must</e> be two spaces for each indentation. That means <e>no</e> 584is used, it <e>must</e> be two spaces for each indentation. That means <e>no
530tabs and <e>not</e> more spaces. 585tabs</e> and <e>not</e> more spaces. Besides, tabs are not allowed in GuideXML
586documents.
531</p> 587</p>
532 588
533<p> 589<p>
534In case word-wrapping happens in <c>&lt;ti&gt;</c>, <c>&lt;th&gt;</c> or 590In case word-wrapping happens in <c>&lt;ti&gt;</c>, <c>&lt;th&gt;</c> or
535<c>&lt;li&gt;</c> constructs, indentation must be used for the content. 591<c>&lt;li&gt;</c> constructs, indentation must be used for the content.

Legend:
Removed from v.1.50  
changed lines
  Added in v.1.51

  ViewVC Help
Powered by ViewVC 1.1.20