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 | |