| 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 | <warn> |
249 | <warn> |
| 250 | This is a warning. |
250 | This is a warning. |
| 251 | </warn> |
251 | </warn> |
| 252 | |
252 | |
| 253 | <impo> |
253 | <impo> |
| 254 | This is important. |
254 | This is important. |
| 255 | </impo> |
255 | </impo> |
| 256 | </pre> |
256 | </pre> |
| 257 | |
257 | |
| 258 | <p> |
258 | <p> |
| 259 | Now, here's how the <c><body></c> element above is rendered: |
259 | Now, here's how the <c><body></c> element above is rendered: |
| 260 | </p> |
260 | </p> |
| 261 | |
261 | |
| 262 | <p> |
262 | <p> |
| 263 | This is a paragraph. <path>/etc/passwd</path> is a file. |
263 | This 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. |
| 265 | Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now. |
265 | Type <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"> |
| 269 | This is text output or code. |
269 | This is text output or code. |
| 270 | # <i>this is user input</i> |
270 | # <i>this is user input</i> |
| 271 | |
271 | |
| 272 | Make HTML/XML easier to read by using selective emphasis: |
272 | Make HTML/XML easier to read by using selective emphasis: |
| 273 | <foo><i>bar</i></foo> |
273 | <foo><i>bar</i></foo> |
| 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> |
| 279 | This is a note. |
279 | This is a note. |
| … | |
… | |
| 318 | </section> |
318 | </section> |
| 319 | <section> |
319 | <section> |
| 320 | <title><path>, <c>, <i> and <e></title> |
320 | <title><path>, <c>, <i> and <e></title> |
| 321 | <body> |
321 | <body> |
| 322 | |
322 | |
| 323 | <p> |
323 | <p> |
| 324 | The <c><path></c>, <c><c></c> and <c><e></c> elements can |
324 | The <c><path></c>, <c><c></c> and <c><e></c> elements can |
| 325 | be used inside any child <c><body></c> tag, except for |
325 | be used inside any child <c><body></c> tag, except for |
| 326 | <c><pre></c>. The <c><i></c> element can only be used inside |
326 | <c><pre></c>. The <c><i></c> element can only be used inside |
| 327 | <c><pre></c>. |
327 | <c><pre></c>. |
| 328 | </p> |
328 | </p> |
| 329 | |
329 | |
| 330 | <p> |
330 | <p> |
| 331 | The <c><path></c> element is used to mark text that refers to an |
331 | The <c><path></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 |
| 334 | font to offset it from the standard paragraph type. |
334 | font to offset it from the standard paragraph type. |
| 335 | </p> |
335 | </p> |
| 336 | |
336 | |
| 337 | <p> |
337 | <p> |
| 338 | The <c><c></c> element is used to mark up a <e>command</e> or <e>user |
338 | The <c><c></c> element is used to mark up a <e>command</e> or <e>user |
| 339 | input</e>. Think of <c><c></c> as a way to alert the reader to something |
339 | input</e>. Think of <c><c></c> as a way to alert the reader to something |
| 340 | that they can type in that will perform some kind of action. For example, all |
340 | that they can type in that will perform some kind of action. For example, all |
| 341 | the XML tags displayed in this document are enclosed in a <c><c></c> |
341 | the XML tags displayed in this document are enclosed in a <c><c></c> |
| 342 | element because they represent something that the user could type in that is |
342 | element because they represent something that the user could type in that is |
| 343 | not a path. By using <c><c></c> elements, you'll help your readers |
343 | not a path. By using <c><c></c> elements, you'll help your readers |
| 344 | quickly identify commands that they need to type in. Also, because |
344 | quickly identify commands that they need to type in. Also, because |
| 345 | <c><c></c> elements are already offset from regular text, <e>it is rarely |
345 | <c><c></c> elements are already offset from regular text, <e>it is rarely |
| 346 | necessary to surround user input with double-quotes</e>. For example, don't |
346 | necessary to surround user input with double-quotes</e>. For example, don't |
| 347 | refer to a "<c><c></c>" element like I did in this sentence. Avoiding |
347 | refer to a "<c><c></c>" element like I did in this sentence. Avoiding |
| 348 | the use of unnecessary double-quotes makes a document more readable -- and |
348 | the use of unnecessary double-quotes makes a document more readable -- and |
| … | |
… | |
| 371 | We've taken a look at the <c><mail></c> tag earlier; it's used to link |
371 | We've taken a look at the <c><mail></c> tag earlier; it's used to link |
| 372 | some text with a particular email address, and takes the form <c><mail |
372 | some text with a particular email address, and takes the form <c><mail |
| 373 | link="foo@bar.com">Mr. Foo Bar</mail></c>. |
373 | link="foo@bar.com">Mr. Foo Bar</mail></c>. |
| 374 | </p> |
374 | </p> |
| 375 | |
375 | |
| 376 | <p> |
376 | <p> |
| 377 | The <c><uri></c> tag is used to point to files/locations on the Internet. |
377 | The <c><uri></c> tag is used to point to files/locations on the Internet. |
| 378 | It has two forms -- the first can be used when you want to have the actual URI |
378 | It has two forms -- the first can be used when you want to have the actual URI |
| 379 | displayed in the body text, such as this link to |
379 | displayed 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><uri>http://forums.gentoo.org</uri></c>. The alternate form is |
381 | <c><uri>http://forums.gentoo.org</uri></c>. The alternate form is |
| 382 | when you want to associate a URI with some other text -- for example, <uri |
382 | when you want to associate a URI with some other text -- for example, <uri |
| 383 | link="http://forums.gentoo.org">the Gentoo Forums</uri>. To create <e>this</e> |
383 | link="http://forums.gentoo.org">the Gentoo Forums</uri>. To create <e>this</e> |
| 384 | link, I typed <c><uri link="http://forums.gentoo.org">the Gentoo |
384 | link, I typed <c><uri link="http://forums.gentoo.org">the Gentoo |
| 385 | Forums</uri></c>. You don't need to write <c>http://www.gentoo.org/</c> |
385 | Forums</uri></c>. You don't need to write <c>http://www.gentoo.org/</c> |
| 386 | to link to other parts of the Gentoo website. For instance, a link to the <uri |
386 | to link to other parts of the Gentoo web site. For instance, a link to the <uri |
| 387 | link="/doc/en/">documentation main index</uri> should be simply <c><uri |
387 | link="/doc/en/">documentation main index</uri> should be simply <c><uri |
| 388 | link="/doc/en/index.xml">documentation main index</uri></c>. You can |
388 | link="/doc/en/index.xml">documentation main index</uri></c>. You can |
| 389 | even omit <c>index.xml</c> when you link to a directory index, e.g. <c><uri |
389 | even omit <c>index.xml</c> when you link to a directory index, e.g. <c><uri |
| 390 | link="/doc/en/">documentation main index</uri></c>. |
390 | link="/doc/en/">documentation main index</uri></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> |
| 400 | Here's how to insert a figure into a document -- <c><figure |
400 | Here's how to insert a figure into a document -- <c><figure |
| 401 | link="mygfx.png" short="my picture" caption="my favorite picture of all |
401 | link="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> |
| 481 | Since all Gentoo Documentation is a joint effort and several people will |
481 | Since all Gentoo Documentation is a joint effort and several people will |
| 482 | most likely change existing documentation, a coding style is needed. |
482 | most likely change existing documentation, a coding style is needed. |
| 483 | A coding style contains two sections. The first one is regarding |
483 | A coding style contains two sections. The first one is regarding |
| 484 | internal coding - how the xml-tags are placed. The second one is |
484 | internal coding - how the XML-tags are placed. The second one is |
| 485 | regarding the content - how not to confuse the reader. |
485 | regarding the content - how not to confuse the reader. |
| 486 | </p> |
486 | </p> |
| 487 | |
487 | |
| 488 | <p> |
488 | <p> |
| 489 | Both sections are described next. |
489 | Both 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> |
Parent Directory
| 
Revision Log
| 
Patch