| 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> |
| 25 | This guide shows you how to compose web documentation using the new lightweight |
25 | This guide shows you how to compose web documentation using the new lightweight |
| 26 | Gentoo GuideXML syntax. This syntax is the official format for Gentoo |
26 | Gentoo GuideXML syntax. This syntax is the official format for Gentoo |
| 27 | documentation, and this document itself was created using GuideXML. This guide |
27 | documentation, and this document itself was created using GuideXML. This guide |
| 28 | assumes a basic working knowledge of XML and HTML. |
28 | assumes 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> |
| 45 | The guide XML syntax is lightweight yet expressive, so that it is easy to |
45 | The guide XML syntax is lightweight yet expressive, so that it is easy to |
| 46 | learn yet also provides all the features we need for the creation of web |
46 | learn yet also provides all the features we need for the creation of web |
| 47 | documentation. The number of tags is kept to a minimum -- just those we need. |
47 | documentation. The number of tags is kept to a minimum -- just those we need. |
| 48 | This makes it easy to transform guide into other formats, such as DocBook |
48 | This makes it easy to transform guide into other formats, such as DocBook |
| 49 | XML/SGML or web-ready HTML. |
49 | XML/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 | <p> |
237 | <p> |
| 238 | This is a paragraph. <path>/etc/passwd</path> is a file. |
238 | This is a paragraph. <path>/etc/passwd</path> is a file. |
| 239 | <uri>http://forums.gentoo.org</uri> is my favorite website. |
239 | <uri>http://forums.gentoo.org</uri> is my favorite website. |
| 240 | Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now. |
240 | Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now. |
| 241 | </p> |
241 | </p> |
| 242 | |
242 | |
| 243 | <pre caption="Code Sample"> |
243 | <pre caption="Code Sample"> |
| 244 | This is text output or code. |
244 | This is text output or code. |
| 245 | # <i>this is user input</i> |
245 | # <i>this is user input</i> |
| 246 | |
246 | |
| 247 | Make HTML/XML easier to read by using selective emphasis: |
247 | Make HTML/XML easier to read by using selective emphasis: |
| 248 | <foo><i>bar</i></foo> |
248 | <foo><i>bar</i></foo> |
| 249 | |
249 | |
| 250 | <comment>(This is how to insert an inline note into the code block)</comment> |
250 | <comment>(This is how to insert a comment into a code block)</comment> |
| 251 | </pre> |
251 | </pre> |
| 252 | |
252 | |
| 253 | <note> |
253 | <note> |
| 254 | This is a note. |
254 | This is a note. |
| 255 | </note> |
255 | </note> |
| 256 | |
256 | |
| 257 | <warn> |
257 | <warn> |
| 258 | This is a warning. |
258 | This is a warning. |
| 259 | </warn> |
259 | </warn> |
| 260 | |
260 | |
| 261 | <impo> |
261 | <impo> |
| 262 | This is important. |
262 | This is important. |
| 263 | </impo> |
263 | </impo> |
| 264 | </pre> |
264 | </pre> |
| 265 | |
265 | |
| … | |
… | |
| 268 | </p> |
268 | </p> |
| 269 | |
269 | |
| 270 | <p> |
270 | <p> |
| 271 | This is a paragraph. <path>/etc/passwd</path> is a file. |
271 | This 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. |
| 273 | Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now. |
273 | Type <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"> |
| 277 | This is text output or code. |
277 | This is text output or code. |
| 278 | # <i>this is user input</i> |
278 | # <i>this is user input</i> |
| 279 | |
279 | |
| 280 | Make HTML/XML easier to read by using selective emphasis: |
280 | Make HTML/XML easier to read by using selective emphasis: |
| 281 | <foo><i>bar</i></foo> |
281 | <foo><i>bar</i></foo> |
| 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> |
| 287 | This is a note. |
287 | This is a note. |
| 288 | </note> |
288 | </note> |
| 289 | |
289 | |
| 290 | <warn> |
290 | <warn> |
| 291 | This is a warning. |
291 | This is a warning. |
| 292 | </warn> |
292 | </warn> |
| 293 | |
293 | |
| 294 | <impo> |
294 | <impo> |
| 295 | This is important. |
295 | This is important. |
| 296 | </impo> |
296 | </impo> |
| 297 | |
297 | |
| 298 | </body> |
298 | </body> |
| … | |
… | |
| 341 | Epigraphs are sometimes used at the beginning of chapters to illustrate what is |
341 | Epigraphs are sometimes used at the beginning of chapters to illustrate what is |
| 342 | to follow. It is simply a paragraph with a <c>by</c> attribute that contains |
342 | to follow. It is simply a paragraph with a <c>by</c> attribute that contains |
| 343 | the signature. |
343 | the signature. |
| 344 | </p> |
344 | </p> |
| 345 | |
345 | |
| 346 | <pre caption="Short epigraph"> |
346 | <pre caption="Short epigraph"> |
| 347 | <p by="Anonymous student"> |
347 | <p by="Anonymous student"> |
| 348 | Delegates from the original 13 states formed the... |
348 | Delegates from the original 13 states formed the... |
| 349 | </p> |
349 | </p> |
| 350 | </pre> |
350 | </pre> |
| 351 | |
351 | |
| 352 | </body> |
352 | </body> |
| 353 | </section> |
353 | </section> |
| 354 | <section> |
354 | <section> |
| 355 | <title> |
355 | <title> |
| 356 | <path>, <c>, <i>, <b>, <e>, <sub> and <sup> |
356 | <path>, <c>, <b>, <e>, <sub> and <sup> |
| 357 | </title> |
357 | </title> |
| 358 | <body> |
358 | <body> |
| 359 | |
359 | |
| 360 | <p> |
360 | <p> |
| 361 | The <c><path></c>, <c><c></c>, <c><b></c>, <c><e></c>, |
361 | The <c><path></c>, <c><c></c>, <c><b></c>, <c><e></c>, |
| 362 | <c><sub></c> and <c><sup></c> elements can be used inside any child |
362 | <c><sub></c> and <c><sup></c> elements can be used inside any child |
| 363 | <c><body></c> tag, except for <c><pre></c>. The <c><i></c> |
363 | <c><body></c> tag, except for <c><pre></c>. |
| 364 | element can only be used inside <c><pre></c>. |
|
|
| 365 | </p> |
364 | </p> |
| 366 | |
365 | |
| 367 | <p> |
366 | <p> |
| 368 | The <c><path></c> element is used to mark text that refers to an |
367 | The <c><path></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 |
| 371 | font to offset it from the standard paragraph type. |
370 | font to offset it from the standard paragraph type. |
| 372 | </p> |
371 | </p> |
| 373 | |
372 | |
| 374 | <p> |
373 | <p> |
| 375 | The <c><c></c> element is used to mark up a <e>command</e> or <e>user |
374 | The <c><c></c> element is used to mark up a <e>command</e> or <e>user |
| 376 | input</e>. Think of <c><c></c> as a way to alert the reader to something |
375 | input</e>. Think of <c><c></c> as a way to alert the reader to something |
| 377 | that they can type in that will perform some kind of action. For example, all |
376 | that they can type in that will perform some kind of action. For example, all |
| 378 | the XML tags displayed in this document are enclosed in a <c><c></c> |
377 | the XML tags displayed in this document are enclosed in a <c><c></c> |
| 379 | element because they represent something that the user could type in that is |
378 | element because they represent something that the user could type in that is |
| 380 | not a path. By using <c><c></c> elements, you'll help your readers |
379 | not a path. By using <c><c></c> elements, you'll help your readers |
| 381 | quickly identify commands that they need to type in. Also, because |
380 | quickly identify commands that they need to type in. Also, because |
| 382 | <c><c></c> elements are already offset from regular text, <e>it is rarely |
381 | <c><c></c> elements are already offset from regular text, <e>it is rarely |
| 383 | necessary to surround user input with double-quotes</e>. For example, don't |
382 | necessary to surround user input with double-quotes</e>. For example, don't |
| 384 | refer to a "<c><c></c>" element like I did in this sentence. Avoiding |
383 | refer to a "<c><c></c>" element like I did in this sentence. Avoiding |
| 385 | the use of unnecessary double-quotes makes a document more readable -- and |
384 | the use of unnecessary double-quotes makes a document more readable -- and |
| 386 | adorable! |
385 | adorable! |
| 387 | </p> |
386 | </p> |
| 388 | |
387 | |
| 389 | <p> |
388 | <p> |
| 390 | When you want to highlight some text as user input inside a <c><pre></c>, |
|
|
| 391 | use <c><i></c> instead. |
|
|
| 392 | </p> |
|
|
| 393 | |
|
|
| 394 | <p> |
|
|
| 395 | As you might have guessed, <c><b></c> is used to <b>boldface</b> some |
389 | As you might have guessed, <c><b></c> is used to <b>boldface</b> some |
| 396 | text. |
390 | text. |
| 397 | </p> |
391 | </p> |
| 398 | |
392 | |
| 399 | <p> |
393 | <p> |
| 400 | <c><e></c> is used to apply emphasis to a word or phrase; for example: |
394 | <c><e></c> is used to apply emphasis to a word or phrase; for example: |
| 401 | I <e>really</e> should use semicolons more often. As you can see, this text is |
395 | I <e>really</e> should use semicolons more often. As you can see, this text is |
| 402 | offset from the regular paragraph type for emphasis. This helps to give your |
396 | offset from the regular paragraph type for emphasis. This helps to give your |
| 403 | prose more <e>punch</e>! |
397 | prose more <e>punch</e>! |
| 404 | </p> |
398 | </p> |
| 405 | |
399 | |
| 406 | <p> |
400 | <p> |
| 407 | The <c><sub></c> and <c><sup></c> elements are used to specify |
401 | The <c><sub></c> and <c><sup></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> |
|
|
412 | To improve the readability of code samples, the following tags are allowed |
|
|
413 | inside <c><pre></c> blocks: |
|
|
414 | </p> |
|
|
415 | |
|
|
416 | <dl> |
|
|
417 | <dt><c><i></c></dt> |
|
|
418 | <dd>Distinguishes user input from displayed text</dd> |
|
|
419 | <dt><c><comment></c></dt> |
|
|
420 | <dd>Comments relevant to the action(s) that appear after the comment</dd> |
|
|
421 | <dt><c><keyword></c></dt> |
|
|
422 | <dd>Denotes a keyword in the language used in the code sample |
|
|
423 | </dd> |
|
|
424 | <dt><c><ident></c></dt> |
|
|
425 | <dd>Used for an identifier |
|
|
426 | </dd> |
|
|
427 | <dt><c><const></c></dt> |
|
|
428 | <dd>Used for a constant |
|
|
429 | </dd> |
|
|
430 | <dt><c><stmt></c></dt> |
|
|
431 | <dd>Used for a statement |
|
|
432 | </dd> |
|
|
433 | <dt><c><var></c></dt> |
|
|
434 | <dd>Used for a variable |
|
|
435 | </dd> |
|
|
436 | </dl> |
|
|
437 | |
|
|
438 | <note> |
|
|
439 | Remember that all leading and trailing spaces, and line breaks in |
|
|
440 | <c><pre></c> blocks will appear in the displayed html page. |
|
|
441 | </note> |
|
|
442 | |
|
|
443 | <p> |
|
|
444 | Sample colour-coded <c><pre></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 | # $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><mail> and <uri></title> |
477 | <title><mail> and <uri></title> |
| 415 | <body> |
478 | <body> |
| 416 | |
479 | |
| 417 | <p> |
480 | <p> |
| 418 | We've taken a look at the <c><mail></c> tag earlier; it's used to link |
481 | We've taken a look at the <c><mail></c> tag earlier; it's used to link |
| 419 | some text with a particular email address, and takes the form <c><mail |
482 | some text with a particular email address, and takes the form <c><mail |
| 420 | link="foo@bar.com">Mr. Foo Bar</mail></c>. If you want to display the |
483 | link="foo@bar.com">Mr. Foo Bar</mail></c>. If you want to display the |
| 421 | email address, you can use <c><mail>foo@bar.com</mail></c>, this |
484 | email address, you can use <c><mail>foo@bar.com</mail></c>, this |
| 422 | would be displayed as <mail>foo@bar.com</mail>. |
485 | would be displayed as <mail>foo@bar.com</mail>. |
| 423 | </p> |
486 | </p> |
| 424 | |
487 | |
Parent Directory
| 
Revision Log
| 
Patch