/[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.44 Revision 1.45
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.44 2005/05/23 19:05:33 swift Exp $ --> 2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.45 2005/05/23 19:08:16 swift 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 Linux XML Guide</title> 6<title>Gentoo Linux XML Guide</title>
7 7
8<author title="Author"> 8<author title="Author">
9 <mail link="drobbins@gentoo.org">Daniel Robbins</mail> 9 <mail link="drobbins@gentoo.org">Daniel Robbins</mail>
10</author> 10</author>
11<author title="Author"><!-- zhen@gentoo.org --> 11<author title="Author"><!-- zhen@gentoo.org -->
12 John P. Davis 12 John P. Davis
13</author> 13</author>
14<author title="Editor"> 14<author title="Editor">
15 <mail link="peesh@gentoo.org">Jorge Paulo</mail> 15 <mail link="peesh@gentoo.org">Jorge Paulo</mail>
16</author> 16</author>
17<author title="Editor"> 17<author title="Editor">
249&lt;warn&gt; 249&lt;warn&gt;
250This is a warning. 250This is a warning.
251&lt;/warn&gt; 251&lt;/warn&gt;
252 252
253&lt;impo&gt; 253&lt;impo&gt;
254This is important. 254This is important.
255&lt;/impo&gt; 255&lt;/impo&gt;
256</pre> 256</pre>
257 257
258<p> 258<p>
259Now, here's how the <c>&lt;body&gt;</c> element above is rendered: 259Now, here's how the <c>&lt;body&gt;</c> element above is rendered:
260</p> 260</p>
261 261
262<p> 262<p>
263This is a paragraph. <path>/etc/passwd</path> is a file. 263This is a paragraph. <path>/etc/passwd</path> is a file.
264<uri>http://forums.gentoo.org</uri> is my favorite website. 264<uri>http://forums.gentoo.org</uri> is my favorite web site.
265Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now. 265Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now.
266</p> 266</p>
267 267
268<pre caption="Code Sample"> 268<pre caption="Code Sample">
269This is text output or code. 269This is text output or code.
270# <i>this is user input</i> 270# <i>this is user input</i>
271 271
272Make HTML/XML easier to read by using selective emphasis: 272Make HTML/XML easier to read by using selective emphasis:
273&lt;foo&gt;<i>bar</i>&lt;/foo&gt; 273&lt;foo&gt;<i>bar</i>&lt;/foo&gt;
274 274
275<comment>(This is how to insert an inline note into the code block)</comment> 275<comment>(This is how to insert an inline note into the code block)</comment>
276</pre> 276</pre>
277 277
278<note> 278<note>
279This is a note. 279This is a note.
318</section> 318</section>
319<section> 319<section>
320<title>&lt;path&gt;, &lt;c&gt;, &lt;i&gt; and &lt;e&gt;</title> 320<title>&lt;path&gt;, &lt;c&gt;, &lt;i&gt; and &lt;e&gt;</title>
321<body> 321<body>
322 322
323<p> 323<p>
324The <c>&lt;path&gt;</c>, <c>&lt;c&gt;</c> and <c>&lt;e&gt;</c> elements can 324The <c>&lt;path&gt;</c>, <c>&lt;c&gt;</c> and <c>&lt;e&gt;</c> elements can
325be used inside any child <c>&lt;body&gt;</c> tag, except for 325be used inside any child <c>&lt;body&gt;</c> tag, except for
326<c>&lt;pre&gt;</c>. The <c>&lt;i&gt;</c> element can only be used inside 326<c>&lt;pre&gt;</c>. The <c>&lt;i&gt;</c> element can only be used inside
327<c>&lt;pre&gt;</c>. 327<c>&lt;pre&gt;</c>.
328</p> 328</p>
329 329
330<p> 330<p>
331The <c>&lt;path&gt;</c> element is used to mark text that refers to an 331The <c>&lt;path&gt;</c> element is used to mark text that refers to an
332<e>on-disk file</e> -- either an <e>absolute or relative path</e>, or a 332<e>on-disk file</e> -- either an <e>absolute or relative path</e>, or a
333<e>simple filename</e>. This element is generally rendered with a monospaced 333<e>simple filename</e>. This element is generally rendered with a mono spaced
334font to offset it from the standard paragraph type. 334font to offset it from the standard paragraph type.
335</p> 335</p>
336 336
337<p> 337<p>
338The <c>&lt;c&gt;</c> element is used to mark up a <e>command</e> or <e>user 338The <c>&lt;c&gt;</c> element is used to mark up a <e>command</e> or <e>user
339input</e>. Think of <c>&lt;c&gt;</c> as a way to alert the reader to something 339input</e>. Think of <c>&lt;c&gt;</c> as a way to alert the reader to something
340that they can type in that will perform some kind of action. For example, all 340that they can type in that will perform some kind of action. For example, all
341the XML tags displayed in this document are enclosed in a <c>&lt;c&gt;</c> 341the XML tags displayed in this document are enclosed in a <c>&lt;c&gt;</c>
342element because they represent something that the user could type in that is 342element because they represent something that the user could type in that is
343not a path. By using <c>&lt;c&gt;</c> elements, you'll help your readers 343not a path. By using <c>&lt;c&gt;</c> elements, you'll help your readers
344quickly identify commands that they need to type in. Also, because 344quickly identify commands that they need to type in. Also, because
345<c>&lt;c&gt;</c> elements are already offset from regular text, <e>it is rarely 345<c>&lt;c&gt;</c> elements are already offset from regular text, <e>it is rarely
346necessary to surround user input with double-quotes</e>. For example, don't 346necessary to surround user input with double-quotes</e>. For example, don't
347refer to a "<c>&lt;c&gt;</c>" element like I did in this sentence. Avoiding 347refer to a "<c>&lt;c&gt;</c>" element like I did in this sentence. Avoiding
348the use of unnecessary double-quotes makes a document more readable -- and 348the use of unnecessary double-quotes makes a document more readable -- and
371We've taken a look at the <c>&lt;mail&gt;</c> tag earlier; it's used to link 371We've taken a look at the <c>&lt;mail&gt;</c> tag earlier; it's used to link
372some text with a particular email address, and takes the form <c>&lt;mail 372some text with a particular email address, and takes the form <c>&lt;mail
373link="foo@bar.com"&gt;Mr. Foo Bar&lt;/mail&gt;</c>. 373link="foo@bar.com"&gt;Mr. Foo Bar&lt;/mail&gt;</c>.
374</p> 374</p>
375 375
376<p> 376<p>
377The <c>&lt;uri&gt;</c> tag is used to point to files/locations on the Internet. 377The <c>&lt;uri&gt;</c> tag is used to point to files/locations on the Internet.
378It has two forms -- the first can be used when you want to have the actual URI 378It has two forms -- the first can be used when you want to have the actual URI
379displayed in the body text, such as this link to 379displayed in the body text, such as this link to
380<uri>http://forums.gentoo.org</uri>. To create this link, I typed 380<uri>http://forums.gentoo.org</uri>. To create this link, I typed
381<c>&lt;uri&gt;http://forums.gentoo.org&lt;/uri&gt;</c>. The alternate form is 381<c>&lt;uri&gt;http://forums.gentoo.org&lt;/uri&gt;</c>. The alternate form is
382when you want to associate a URI with some other text -- for example, <uri 382when you want to associate a URI with some other text -- for example, <uri
383link="http://forums.gentoo.org">the Gentoo Forums</uri>. To create <e>this</e> 383link="http://forums.gentoo.org">the Gentoo Forums</uri>. To create <e>this</e>
384link, I typed <c>&lt;uri link="http://forums.gentoo.org"&gt;the Gentoo 384link, I typed <c>&lt;uri link="http://forums.gentoo.org"&gt;the Gentoo
385Forums&lt;/uri&gt;</c>. You don't need to write <c>http://www.gentoo.org/</c> 385Forums&lt;/uri&gt;</c>. You don't need to write <c>http://www.gentoo.org/</c>
386to link to other parts of the Gentoo website. For instance, a link to the <uri 386to link to other parts of the Gentoo web site. For instance, a link to the <uri
387link="/doc/en/">documentation main index</uri> should be simply <c>&lt;uri 387link="/doc/en/">documentation main index</uri> should be simply <c>&lt;uri
388link="/doc/en/index.xml"&gt;documentation main index&lt;/uri&gt;</c>. You can 388link="/doc/en/index.xml"&gt;documentation main index&lt;/uri&gt;</c>. You can
389even omit <c>index.xml</c> when you link to a directory index, e.g. <c>&lt;uri 389even omit <c>index.xml</c> when you link to a directory index, e.g. <c>&lt;uri
390link="/doc/en/"&gt;documentation main index&lt;/uri&gt;</c>. 390link="/doc/en/"&gt;documentation main index&lt;/uri&gt;</c>.
391</p> 391</p>
392 392
393</body> 393</body>
394</section> 394</section>
395<section> 395<section>
396<title>Figures</title> 396<title>Figures</title>
397<body> 397<body>
398 398
399<p> 399<p>
400Here's how to insert a figure into a document -- <c>&lt;figure 400Here's how to insert a figure into a document -- <c>&lt;figure
401link="mygfx.png" short="my picture" caption="my favorite picture of all 401link="mygfx.png" short="my picture" caption="my favorite picture of all
469 469
470</body> 470</body>
471</section> 471</section>
472</chapter> 472</chapter>
473 473
474<chapter> 474<chapter>
475<title>Coding Style</title> 475<title>Coding Style</title>
476<section> 476<section>
477<title>Introduction</title> 477<title>Introduction</title>
478<body> 478<body>
479 479
480<p> 480<p>
481Since all Gentoo Documentation is a joint effort and several people will 481Since all Gentoo Documentation is a joint effort and several people will
482most likely change existing documentation, a coding style is needed. 482most likely change existing documentation, a coding style is needed.
483A coding style contains two sections. The first one is regarding 483A coding style contains two sections. The first one is regarding
484internal coding - how the xml-tags are placed. The second one is 484internal coding - how the XML-tags are placed. The second one is
485regarding the content - how not to confuse the reader. 485regarding the content - how not to confuse the reader.
486</p> 486</p>
487 487
488<p> 488<p>
489Both sections are described next. 489Both sections are described next.
490</p> 490</p>
491 491
492</body> 492</body>
493</section> 493</section>
494<section> 494<section>
495<title>Internal Coding Style</title> 495<title>Internal Coding Style</title>
496<body> 496<body>
497 497
498<p> 498<p>
499<b>Newlines</b> must be placed immediately after <e>every</e> 499<b>Newlines</b> must be placed immediately after <e>every</e>

Legend:
Removed from v.1.44  
changed lines
  Added in v.1.45

  ViewVC Help
Powered by ViewVC 1.1.20