| 1 |
commit: 8be0d382fb82dc4cfe73b1b85bb7fc3c923a21c7 |
| 2 |
Author: Göktürk Yüksek <gokturk <AT> gentoo <DOT> org> |
| 3 |
AuthorDate: Wed Apr 12 15:37:57 2017 +0000 |
| 4 |
Commit: Göktürk Yüksek <gokturk <AT> gentoo <DOT> org> |
| 5 |
CommitDate: Wed Apr 12 17:19:38 2017 +0000 |
| 6 |
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=8be0d382 |
| 7 |
|
| 8 |
appendices/contributing/devbook-guide: initial commit |
| 9 |
|
| 10 |
Imported from: |
| 11 |
https://sources.gentoo.org/cgi-bin/viewvc.cgi/gentoo/xml/htdocs/doc/en/xml-guide.xml?revision=1.72 |
| 12 |
|
| 13 |
The only modifications that have been made are the removals of DOCTYPE |
| 14 |
and the CVS header, and the addition of self attribute to <guide> |
| 15 |
|
| 16 |
appendices/contributing/devbook-guide/text.xml | 1224 ++++++++++++++++++++++++ |
| 17 |
appendices/contributing/text.xml | 3 +- |
| 18 |
2 files changed, 1226 insertions(+), 1 deletion(-) |
| 19 |
|
| 20 |
diff --git a/appendices/contributing/devbook-guide/text.xml b/appendices/contributing/devbook-guide/text.xml |
| 21 |
new file mode 100644 |
| 22 |
index 0000000..a4a69af |
| 23 |
--- /dev/null |
| 24 |
+++ b/appendices/contributing/devbook-guide/text.xml |
| 25 |
@@ -0,0 +1,1224 @@ |
| 26 |
+<?xml version="1.0" encoding="UTF-8"?> |
| 27 |
+ |
| 28 |
+<guide self="appendices/contributing/devbook-guide/"> |
| 29 |
+<title>Gentoo GuideXML Guide</title> |
| 30 |
+ |
| 31 |
+<author title="Author"> |
| 32 |
+ <mail link="neysx"/> |
| 33 |
+</author> |
| 34 |
+<author title="Author"> |
| 35 |
+ <mail link="drobbins@g.o">Daniel Robbins</mail> |
| 36 |
+</author> |
| 37 |
+<author title="Author"><!-- zhen@g.o --> |
| 38 |
+ John P. Davis |
| 39 |
+</author> |
| 40 |
+<author title="Editor"> |
| 41 |
+ <mail link="peesh@g.o">Jorge Paulo</mail> |
| 42 |
+</author> |
| 43 |
+<author title="Editor"> |
| 44 |
+ <mail link="swift@g.o">Sven Vermeulen</mail> |
| 45 |
+</author> |
| 46 |
+<author title="Editor"> |
| 47 |
+ <mail link="nightmorph"/> |
| 48 |
+</author> |
| 49 |
+ |
| 50 |
+<abstract> |
| 51 |
+This guide shows you how to compose web documentation using the new lightweight |
| 52 |
+Gentoo GuideXML syntax. This syntax is the official format for Gentoo |
| 53 |
+documentation, and this document itself was created using GuideXML. This guide |
| 54 |
+assumes a basic working knowledge of XML and HTML. |
| 55 |
+</abstract> |
| 56 |
+ |
| 57 |
+<!-- The content of this document is licensed under the CC-BY-SA license --> |
| 58 |
+<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> |
| 59 |
+<license/> |
| 60 |
+ |
| 61 |
+<version>13</version> |
| 62 |
+<date>2012-10-07</date> |
| 63 |
+ |
| 64 |
+<chapter> |
| 65 |
+<title>GuideXML basics</title> |
| 66 |
+<section> |
| 67 |
+<title>GuideXML design goals</title> |
| 68 |
+<body> |
| 69 |
+ |
| 70 |
+<p> |
| 71 |
+The guideXML syntax is lightweight yet expressive, so that it is easy to |
| 72 |
+learn yet also provides all the features we need for the creation of web |
| 73 |
+documentation. The number of tags is kept to a minimum -- just those we need. |
| 74 |
+This makes it easy to transform guide into other formats, such as DocBook |
| 75 |
+XML/SGML or web-ready HTML. |
| 76 |
+</p> |
| 77 |
+ |
| 78 |
+<p> |
| 79 |
+The goal is to make it easy to <e>create</e> and <e>transform</e> guideXML |
| 80 |
+documents. |
| 81 |
+</p> |
| 82 |
+ |
| 83 |
+</body> |
| 84 |
+</section> |
| 85 |
+<section> |
| 86 |
+<title>Further Resources</title> |
| 87 |
+<body> |
| 88 |
+ |
| 89 |
+<p> |
| 90 |
+If you are planning on contributing documentation to Gentoo, or you want to |
| 91 |
+test GuideXML, please read our <uri |
| 92 |
+link="/proj/en/gdp/doc/doc-tipsntricks.xml">Doc Tips 'n' Tricks</uri> guide |
| 93 |
+which contains tips and tricks for documentation development. |
| 94 |
+</p> |
| 95 |
+ |
| 96 |
+<p> |
| 97 |
+You may want to look at the <uri link="?passthru=1">XML source</uri> of this |
| 98 |
+document while you read it. |
| 99 |
+</p> |
| 100 |
+ |
| 101 |
+</body> |
| 102 |
+</section> |
| 103 |
+</chapter> |
| 104 |
+ |
| 105 |
+<chapter> |
| 106 |
+<title>GuideXML</title> |
| 107 |
+<section> |
| 108 |
+<title>Basic structure</title> |
| 109 |
+<body> |
| 110 |
+ |
| 111 |
+<p> |
| 112 |
+Let's start learning the GuideXML syntax. We'll start with the the initial |
| 113 |
+tags used in a GuideXML document: |
| 114 |
+</p> |
| 115 |
+ |
| 116 |
+<pre caption="The initial part of a guide XML document"> |
| 117 |
+<?xml version="1.0" encoding="UTF-8"?> |
| 118 |
+<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> |
| 119 |
+<!-- $Header$ --> |
| 120 |
+ |
| 121 |
+<guide lang="<i>en</i>"> |
| 122 |
+<title><i>Gentoo Documentation Guide</i></title> |
| 123 |
+ |
| 124 |
+<author title="<i>Author</i>"> |
| 125 |
+ <mail link="<i>yourname@g.o</i>"><i>Your Name</i></mail> |
| 126 |
+</author> |
| 127 |
+ |
| 128 |
+<abstract> |
| 129 |
+<i>This guide shows you how to compose web documentation using |
| 130 |
+our new lightweight Gentoo GuideXML syntax. This syntax is the official |
| 131 |
+format for Gentoo web documentation, and this document itself was created |
| 132 |
+using GuideXML.</i> |
| 133 |
+</abstract> |
| 134 |
+ |
| 135 |
+<!-- The content of this document is licensed under the CC-BY-SA license --> |
| 136 |
+<!-- See http://creativecommons.org/licenses/by-sa/3.0 --> |
| 137 |
+<license version="3.0"/> |
| 138 |
+ |
| 139 |
+<version><i>1</i></version> |
| 140 |
+<date><i>2011-11-29</i></date> |
| 141 |
+</pre> |
| 142 |
+ |
| 143 |
+<p> |
| 144 |
+On the first lines, we see the requisite tag that identifies this as an XML |
| 145 |
+document and specifies its DTD. The <c><!-- $Header$ --></c> line |
| 146 |
+will be automatically modified by the CVS server and helps to track revisions. |
| 147 |
+Next, there's a <c><guide></c> tag -- the entire guide document is |
| 148 |
+enclosed within a <c><guide> </guide></c> pair. |
| 149 |
+<br/> |
| 150 |
+The <c>lang</c> attribute should be used to specify the language code of your |
| 151 |
+document. It is used to format the date and insert strings like "<e>Note</e>", |
| 152 |
+"<e>Content</e>", etc. in the specified language. The default is English. |
| 153 |
+</p> |
| 154 |
+ |
| 155 |
+<p> |
| 156 |
+Next, there's a <c><title></c> tag, used to set the title for the entire |
| 157 |
+guide document. |
| 158 |
+</p> |
| 159 |
+ |
| 160 |
+<p> |
| 161 |
+Then, we come to the <c><author></c> tags, which contain information |
| 162 |
+about the various authors of the document. Each <c><author></c> tag |
| 163 |
+allows for an optional <c>title</c> element, used to specify the author's |
| 164 |
+relationship to the document (author, co-author, editor, etc.). In this |
| 165 |
+particular example, the authors' names are enclosed in another tag -- a |
| 166 |
+<c><mail></c> tag, used to specify an email address for this particular |
| 167 |
+person. The <c><mail></c> tag is optional and can be omitted, and at |
| 168 |
+least one <c><author></c> element is required per guide document. |
| 169 |
+</p> |
| 170 |
+ |
| 171 |
+<p> |
| 172 |
+Next, we come to the <c><abstract></c>, <c><version></c> and |
| 173 |
+<c><date></c> tags, used to specify a summary of the document, the |
| 174 |
+current version number, and the current version date (in YYYY-MM-DD format) |
| 175 |
+respectively. Dates that are invalid or not in the YYYY-MM-DD format will |
| 176 |
+appear verbatim in the rendered document. |
| 177 |
+</p> |
| 178 |
+ |
| 179 |
+<p> |
| 180 |
+This sums up the tags that should appear at the beginning of a guide document. |
| 181 |
+Besides the <c><title></c> and <c><mail></c> tags, these tags |
| 182 |
+shouldn't appear anywhere else except immediately inside the |
| 183 |
+<c><guide></c> tag, and for consistency it's recommended (but not |
| 184 |
+required) that these tags appear before the content of the document. |
| 185 |
+</p> |
| 186 |
+ |
| 187 |
+<p> |
| 188 |
+Finally we have the <c><license version="3.0"/></c> tag, used to publish |
| 189 |
+the document under the <uri link="http://creativecommons.org/licenses/by-sa/3.0/">Creative |
| 190 |
+Commons - Attribution / Share Alike</uri> license as required by the <uri |
| 191 |
+link="/proj/en/gdp/doc/doc-policy.xml">Documentation Policy</uri>. Historically, |
| 192 |
+the tag <c><license /></c> was used, which denoted the 2.5 version of the |
| 193 |
+license. This is still accepted/allowed. |
| 194 |
+</p> |
| 195 |
+ |
| 196 |
+</body> |
| 197 |
+</section> |
| 198 |
+<section> |
| 199 |
+<title>Chapters and sections</title> |
| 200 |
+<body> |
| 201 |
+ |
| 202 |
+<p> |
| 203 |
+Once the initial tags have been specified, you're ready to start adding the |
| 204 |
+structural elements of the document. Guide documents are divided into |
| 205 |
+chapters, and each chapter can hold one or more sections. Every chapter and |
| 206 |
+section has a title. Here's an example chapter with a single section, |
| 207 |
+consisting of a paragraph. If you append this XML to the XML in the <uri |
| 208 |
+link="#doc_chap2_pre1">previous excerpt</uri> and append a |
| 209 |
+<c></guide></c> to the end of the file, you'll have a valid (if minimal) |
| 210 |
+guide document: |
| 211 |
+</p> |
| 212 |
+ |
| 213 |
+<pre caption="Minimal guide example"> |
| 214 |
+<chapter> |
| 215 |
+<title><i>This is my chapter</i></title> |
| 216 |
+<section> |
| 217 |
+<title><i>This is section one of my chapter</i></title> |
| 218 |
+<body> |
| 219 |
+ |
| 220 |
+<p> |
| 221 |
+<i>This is the actual text content of my section.</i> |
| 222 |
+</p> |
| 223 |
+ |
| 224 |
+</body> |
| 225 |
+</section> |
| 226 |
+</chapter> |
| 227 |
+</pre> |
| 228 |
+ |
| 229 |
+<p> |
| 230 |
+Above, I set the chapter title by adding a child <c><title></c> |
| 231 |
+element to the <c><chapter></c> element. Then, I created a section by |
| 232 |
+adding a <c><section></c> element. If you look inside the |
| 233 |
+<c><section></c> element, you'll see that it has two child elements -- a |
| 234 |
+<c><title></c> and a <c><body></c>. While the <c><title></c> |
| 235 |
+is nothing new, the <c><body></c> is -- it contains the actual text |
| 236 |
+content of this particular section. We'll look at the tags that are allowed |
| 237 |
+inside a <c><body></c> element in a bit. |
| 238 |
+</p> |
| 239 |
+ |
| 240 |
+<note> |
| 241 |
+A <c><guide></c> element must contain at least one <c><chapter></c> |
| 242 |
+elements, a <c><chapter></c> must contain at least one |
| 243 |
+<c><section></c> elements and a <c><section></c> element must |
| 244 |
+contain at least one <c><body></c> element. |
| 245 |
+</note> |
| 246 |
+ |
| 247 |
+</body> |
| 248 |
+</section> |
| 249 |
+<section> |
| 250 |
+<title>An example <body></title> |
| 251 |
+<body> |
| 252 |
+ |
| 253 |
+<p> |
| 254 |
+Now, it's time to learn how to mark up actual content. Here's the XML code for |
| 255 |
+an example <c><body></c> element: |
| 256 |
+</p> |
| 257 |
+ |
| 258 |
+<pre caption="Example of a body element"> |
| 259 |
+<p> |
| 260 |
+This is a paragraph. <path>/etc/passwd</path> is a file. |
| 261 |
+<uri>http://forums.gentoo.org</uri> is my favorite website. |
| 262 |
+Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now. |
| 263 |
+</p> |
| 264 |
+ |
| 265 |
+<pre caption="Code Sample"> |
| 266 |
+This is text output or code. |
| 267 |
+# <i>this is user input</i> |
| 268 |
+ |
| 269 |
+Make HTML/XML easier to read by using selective emphasis: |
| 270 |
+<foo><i>bar</i></foo> |
| 271 |
+ |
| 272 |
+<comment>(This is how to insert a comment into a code block)</comment> |
| 273 |
+</pre> |
| 274 |
+ |
| 275 |
+<note> |
| 276 |
+This is a note. |
| 277 |
+</note> |
| 278 |
+ |
| 279 |
+<warn> |
| 280 |
+This is a warning. |
| 281 |
+</warn> |
| 282 |
+ |
| 283 |
+<impo> |
| 284 |
+This is important. |
| 285 |
+</impo> |
| 286 |
+</pre> |
| 287 |
+ |
| 288 |
+<p> |
| 289 |
+Now, here's how the <c><body></c> element above is rendered: |
| 290 |
+</p> |
| 291 |
+ |
| 292 |
+<p> |
| 293 |
+This is a paragraph. <path>/etc/passwd</path> is a file. |
| 294 |
+<uri>http://forums.gentoo.org</uri> is my favorite web site. |
| 295 |
+Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now. |
| 296 |
+</p> |
| 297 |
+ |
| 298 |
+<pre caption="Code Sample"> |
| 299 |
+This is text output or code. |
| 300 |
+# <i>this is user input</i> |
| 301 |
+ |
| 302 |
+Make HTML/XML easier to read by using selective emphasis: |
| 303 |
+<foo><i>bar</i></foo> |
| 304 |
+ |
| 305 |
+<comment>(This is how to insert a comment into a code block)</comment> |
| 306 |
+</pre> |
| 307 |
+ |
| 308 |
+<note> |
| 309 |
+This is a note. |
| 310 |
+</note> |
| 311 |
+ |
| 312 |
+<warn> |
| 313 |
+This is a warning. |
| 314 |
+</warn> |
| 315 |
+ |
| 316 |
+<impo> |
| 317 |
+This is important. |
| 318 |
+</impo> |
| 319 |
+ |
| 320 |
+</body> |
| 321 |
+</section> |
| 322 |
+<section> |
| 323 |
+<title>The <body> tags</title> |
| 324 |
+<body> |
| 325 |
+ |
| 326 |
+<p> |
| 327 |
+We introduced a lot of new tags in the previous section -- here's what you need |
| 328 |
+to know. The <c><p></c> (paragraph), <c><pre></c> (code block), |
| 329 |
+<c><note></c>, <c><warn></c> (warning) and <c><impo></c> |
| 330 |
+(important) tags all can contain one or more lines of text. Besides the |
| 331 |
+<c><table></c>, <c><ul></c>, <c><ol></c> and |
| 332 |
+<c><dl></c> elements (which we'll cover in just a bit), these are the |
| 333 |
+only tags that should appear immediately inside a <c><body></c> element. |
| 334 |
+Another thing -- these tags <e>should not</e> be stacked -- in other words, |
| 335 |
+don't put a <c><note></c> element inside a <c><p></c> element. As |
| 336 |
+you might guess, the <c><pre></c> element preserves its whitespace |
| 337 |
+exactly, making it well-suited for code excerpts. You must name the |
| 338 |
+<c><pre></c> tag with a <c>caption</c> attribute: |
| 339 |
+</p> |
| 340 |
+ |
| 341 |
+<pre caption="Named <pre>"> |
| 342 |
+<pre caption="Output of uptime"> |
| 343 |
+# <i>uptime</i> |
| 344 |
+16:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25 |
| 345 |
+</pre> |
| 346 |
+</pre> |
| 347 |
+ |
| 348 |
+</body> |
| 349 |
+</section> |
| 350 |
+<section> |
| 351 |
+<title>Epigraphs</title> |
| 352 |
+<body> |
| 353 |
+ |
| 354 |
+<p by="Anonymous student"> |
| 355 |
+Delegates from the original 13 states formed the Contented Congress. Thomas |
| 356 |
+Jefferson, a Virgin, and Benjamin Franklin were two singers of the Declaration |
| 357 |
+of Independence. Franklin discovered electricity by rubbing two cats backwards |
| 358 |
+and declared, "A horse divided against itself cannot stand." Franklin died in |
| 359 |
+1790 and is still dead. |
| 360 |
+</p> |
| 361 |
+ |
| 362 |
+<p> |
| 363 |
+Epigraphs are sometimes used at the beginning of chapters to illustrate what is |
| 364 |
+to follow. It is simply a paragraph with a <c>by</c> attribute that contains |
| 365 |
+the signature. |
| 366 |
+</p> |
| 367 |
+ |
| 368 |
+<pre caption="Short epigraph"> |
| 369 |
+<p by="Anonymous student"> |
| 370 |
+Delegates from the original 13 states formed the... |
| 371 |
+</p> |
| 372 |
+</pre> |
| 373 |
+ |
| 374 |
+</body> |
| 375 |
+</section> |
| 376 |
+<section> |
| 377 |
+<title> |
| 378 |
+ <path>, <c>, <b>, <e>, <sub> and <sup> |
| 379 |
+</title> |
| 380 |
+<body> |
| 381 |
+ |
| 382 |
+<p> |
| 383 |
+The <c><path></c>, <c><c></c>, <c><b></c>, <c><e></c>, |
| 384 |
+<c><sub></c> and <c><sup></c> elements can be used inside any child |
| 385 |
+<c><body></c> tag, except for <c><pre></c>. |
| 386 |
+</p> |
| 387 |
+ |
| 388 |
+<p> |
| 389 |
+The <c><path></c> element is used to mark text that refers to an |
| 390 |
+<e>on-disk file</e> -- either an <e>absolute or relative path</e>, or a |
| 391 |
+<e>simple filename</e>. This element is generally rendered with a mono spaced |
| 392 |
+font to offset it from the standard paragraph type. |
| 393 |
+</p> |
| 394 |
+ |
| 395 |
+<p> |
| 396 |
+The <c><c></c> element is used to mark up a <e>command</e> or <e>user |
| 397 |
+input</e>. Think of <c><c></c> as a way to alert the reader to something |
| 398 |
+that they can type in that will perform some kind of action. For example, all |
| 399 |
+the XML tags displayed in this document are enclosed in a <c><c></c> |
| 400 |
+element because they represent something that the user could type in that is |
| 401 |
+not a path. By using <c><c></c> elements, you'll help your readers |
| 402 |
+quickly identify commands that they need to type in. Also, because |
| 403 |
+<c><c></c> elements are already offset from regular text, <e>it is rarely |
| 404 |
+necessary to surround user input with double-quotes</e>. For example, don't |
| 405 |
+refer to a "<c><c></c>" element like I did in this sentence. Avoiding |
| 406 |
+the use of unnecessary double-quotes makes a document more readable -- and |
| 407 |
+adorable! |
| 408 |
+</p> |
| 409 |
+ |
| 410 |
+<p> |
| 411 |
+As you might have guessed, <c><b></c> is used to <b>boldface</b> some |
| 412 |
+text. |
| 413 |
+</p> |
| 414 |
+ |
| 415 |
+<p> |
| 416 |
+<c><e></c> is used to apply emphasis to a word or phrase; for example: |
| 417 |
+I <e>really</e> should use semicolons more often. As you can see, this text is |
| 418 |
+offset from the regular paragraph type for emphasis. This helps to give your |
| 419 |
+prose more <e>punch</e>! |
| 420 |
+</p> |
| 421 |
+ |
| 422 |
+<p> |
| 423 |
+The <c><sub></c> and <c><sup></c> elements are used to specify |
| 424 |
+<sub>subscript</sub> and <sup>superscript</sup>. |
| 425 |
+</p> |
| 426 |
+ |
| 427 |
+</body> |
| 428 |
+</section> |
| 429 |
+<section> |
| 430 |
+<title>Code samples and colour-coding</title> |
| 431 |
+<body> |
| 432 |
+ |
| 433 |
+<p> |
| 434 |
+To improve the readability of code samples, the following tags are allowed |
| 435 |
+inside <c><pre></c> blocks: |
| 436 |
+</p> |
| 437 |
+ |
| 438 |
+<dl> |
| 439 |
+ <dt><c><i></c></dt> |
| 440 |
+ <dd>Distinguishes user input from displayed text</dd> |
| 441 |
+ <dt><c><comment></c></dt> |
| 442 |
+ <dd>Comments relevant to the action(s) that appear after the comment</dd> |
| 443 |
+ <dt><c><keyword></c></dt> |
| 444 |
+ <dd>Denotes a keyword in the language used in the code sample |
| 445 |
+ </dd> |
| 446 |
+ <dt><c><ident></c></dt> |
| 447 |
+ <dd>Used for an identifier |
| 448 |
+ </dd> |
| 449 |
+ <dt><c><const></c></dt> |
| 450 |
+ <dd>Used for a constant |
| 451 |
+ </dd> |
| 452 |
+ <dt><c><stmt></c></dt> |
| 453 |
+ <dd>Used for a statement |
| 454 |
+ </dd> |
| 455 |
+ <dt><c><var></c></dt> |
| 456 |
+ <dd>Used for a variable |
| 457 |
+ </dd> |
| 458 |
+</dl> |
| 459 |
+ |
| 460 |
+<note> |
| 461 |
+Remember that all leading and trailing spaces, and line breaks in |
| 462 |
+<c><pre></c> blocks will appear in the displayed html page. |
| 463 |
+</note> |
| 464 |
+ |
| 465 |
+<p> |
| 466 |
+Sample colour-coded <c><pre></c> block: |
| 467 |
+</p> |
| 468 |
+ |
| 469 |
+<pre caption="My first ebuild"> |
| 470 |
+<comment># Copyright 1999-2009 <b>Gentoo Foundation</b> |
| 471 |
+# Distributed under the terms of the GNU General Public License v2 |
| 472 |
+# $Header: $</comment> |
| 473 |
+ |
| 474 |
+<ident>DESCRIPTION</ident>=<const>"Exuberant ctags generates tags files for quick source navigation"</const> |
| 475 |
+<ident>HOMEPAGE</ident>=<const>"http://ctags.sourceforge.net"</const> |
| 476 |
+<ident>SRC_URI</ident>=<const>"mirror://sourceforge/ctags/<var>${P}</var>.tar.gz"</const> |
| 477 |
+ |
| 478 |
+<ident>LICENSE</ident>=<const>"GPL-2"</const> |
| 479 |
+<ident>SLOT</ident>=<const>"0"</const> |
| 480 |
+<ident>KEYWORDS</ident>=<const>"~mips ~sparc ~x86"</const> |
| 481 |
+<ident>IUSE</ident>=<const>""</const> |
| 482 |
+ |
| 483 |
+<stmt>src_compile()</stmt> { |
| 484 |
+ <keyword>econf</keyword> --with-posix-regex |
| 485 |
+ <keyword>emake</keyword> || <keyword>die</keyword> <const>"emake failed"</const> |
| 486 |
+} |
| 487 |
+ |
| 488 |
+<stmt>src_install()</stmt> { |
| 489 |
+ <keyword>make</keyword> <ident>DESTDIR</ident>="<var>${D}</var>" install || <keyword>die</keyword> <const>"install failed"</const> |
| 490 |
+ |
| 491 |
+ <keyword>dodoc</keyword> FAQ NEWS README |
| 492 |
+ <keyword>dohtml</keyword> EXTENDING.html ctags.html |
| 493 |
+} |
| 494 |
+</pre> |
| 495 |
+ |
| 496 |
+</body> |
| 497 |
+</section> |
| 498 |
+<section> |
| 499 |
+<title><mail> and <uri></title> |
| 500 |
+<body> |
| 501 |
+ |
| 502 |
+<p> |
| 503 |
+We've taken a look at the <c><mail></c> tag earlier; it's used to link |
| 504 |
+some text with a particular email address, and takes the form <c><mail |
| 505 |
+link="foo.bar@×××××××.com">Mr. Foo Bar</mail></c>. If you want to display the |
| 506 |
+email address, you can use <c><mail>foo.bar@×××××××.com</mail></c>, this |
| 507 |
+would be displayed as <mail>foo.bar@×××××××.com</mail>. |
| 508 |
+</p> |
| 509 |
+ |
| 510 |
+<p> |
| 511 |
+Shorter forms make it easier to use names and emails of Gentoo developers. Both |
| 512 |
+<c><mail>neysx</mail></c> and <c><mail link="neysx"/></c> |
| 513 |
+would appear as <mail>neysx</mail>. If you want to use a Gentoo dev's email |
| 514 |
+with a different content than his full name, use the second form with some |
| 515 |
+content. For instance, use a dev's first name: <c><mail |
| 516 |
+link="neysx">Xavier</mail></c> appears as <mail |
| 517 |
+link="neysx">Xavier</mail>. |
| 518 |
+<br/> |
| 519 |
+This is particularly useful when you want to name a developer whose name |
| 520 |
+contains "funny" characters that you can't type. |
| 521 |
+</p> |
| 522 |
+ |
| 523 |
+<p> |
| 524 |
+The <c><uri></c> tag is used to point to files/locations on the Internet. |
| 525 |
+It has two forms -- the first can be used when you want to have the actual URI |
| 526 |
+displayed in the body text, such as this link to |
| 527 |
+<uri>http://forums.gentoo.org/</uri>. To create this link, I typed |
| 528 |
+<c><uri>http://forums.gentoo.org/</uri></c>. The alternate form is |
| 529 |
+when you want to associate a URI with some other text -- for example, <uri |
| 530 |
+link="http://forums.gentoo.org/">the Gentoo Forums</uri>. To create |
| 531 |
+<e>this</e> link, I typed <c><uri link="http://forums.gentoo.org/">the |
| 532 |
+Gentoo Forums</uri></c>. You don't need to write |
| 533 |
+<c>http://www.gentoo.org/</c> to link to other parts of the Gentoo web site. |
| 534 |
+For instance, a link to the <uri link="/doc/en/">documentation main index</uri> |
| 535 |
+should be simply <c><uri link="/doc/en/index.xml">documentation main |
| 536 |
+index</uri></c>. You can even omit <c>index.xml</c> when you link to a |
| 537 |
+directory index, e.g. <c><uri link="/doc/en/">documentation main |
| 538 |
+index</uri></c>. Leaving the trailing slash saves an extra HTTP request. |
| 539 |
+</p> |
| 540 |
+ |
| 541 |
+<p> |
| 542 |
+You should not use a <c><uri></c> tag with a <c>link</c> attribute that |
| 543 |
+starts with <c>mailto:</c>. In this case, use a <c><mail></c> tag. |
| 544 |
+</p> |
| 545 |
+ |
| 546 |
+<p> |
| 547 |
+Please avoid the <uri link="http://en.wikipedia.org/wiki/Click_here">click here |
| 548 |
+syndrome</uri> as recommended by the <uri |
| 549 |
+link="http://www.w3.org/QA/Tips/noClickHere">W3C</uri>. |
| 550 |
+</p> |
| 551 |
+ |
| 552 |
+</body> |
| 553 |
+</section> |
| 554 |
+<section> |
| 555 |
+<title>Figures</title> |
| 556 |
+<body> |
| 557 |
+ |
| 558 |
+<p> |
| 559 |
+Here's how to insert a figure into a document -- <c><figure |
| 560 |
+link="mygfx.png" short="my picture" caption="my favorite picture of all |
| 561 |
+time"/></c>. The <c>link</c> attribute points to the actual graphic image, |
| 562 |
+the <c>short</c> attribute specifies a short description (currently used for |
| 563 |
+the image's HTML <c>alt</c> attribute), and a caption. Not too difficult |
| 564 |
+:) We also support the standard HTML-style <img src="foo.gif"/> tag |
| 565 |
+for adding images without captions, borders, etc. |
| 566 |
+</p> |
| 567 |
+ |
| 568 |
+</body> |
| 569 |
+</section> |
| 570 |
+<section> |
| 571 |
+<title>Tables</title> |
| 572 |
+<body> |
| 573 |
+ |
| 574 |
+<p> |
| 575 |
+GuideXML supports a simplified table syntax similar to that of HTML. To start a |
| 576 |
+table, use a <c><table></c> tag. Start a row with a <c><tr></c> |
| 577 |
+tag. However, for inserting actual table data, we <e>don't</e> support the HTML |
| 578 |
+<td> tag; instead, use the <c><th></c> if you are inserting a |
| 579 |
+header, and <c><ti></c> if you are inserting a normal informational |
| 580 |
+block. You can use a <c><th></c> anywhere you can use a <c><ti></c> |
| 581 |
+-- there's no requirement that <c><th></c> elements appear only in the |
| 582 |
+first row. |
| 583 |
+</p> |
| 584 |
+ |
| 585 |
+<p> |
| 586 |
+Besides, both table headers (<c><th></c>) and table items |
| 587 |
+(<c><ti></c>) accept the <c>colspan</c> and <c>rowspan</c> attributes to |
| 588 |
+span their content across rows, columns or both. |
| 589 |
+</p> |
| 590 |
+ |
| 591 |
+<p> |
| 592 |
+Furthermore, table cells (<c><ti></c> & <c><th></c>) can be |
| 593 |
+right-aligned, left-aligned or centered with the <c>align</c> attribute. |
| 594 |
+</p> |
| 595 |
+ |
| 596 |
+<table> |
| 597 |
+ <tr> |
| 598 |
+ <th align="center" colspan="4">This title spans 4 columns</th> |
| 599 |
+ </tr> |
| 600 |
+ <tr> |
| 601 |
+ <th rowspan="6">This title spans 6 rows</th> |
| 602 |
+ <ti>Item A1</ti> |
| 603 |
+ <ti>Item A2</ti> |
| 604 |
+ <ti>Item A3</ti> |
| 605 |
+ </tr> |
| 606 |
+ <tr> |
| 607 |
+ <ti align="center">Item B1</ti> |
| 608 |
+ <th colspan="2" rowspan="2" align="right">Blocky 2x2 title</th> |
| 609 |
+ </tr> |
| 610 |
+ <tr> |
| 611 |
+ <ti align="right">Item C1</ti> |
| 612 |
+ </tr> |
| 613 |
+ <tr> |
| 614 |
+ <ti colspan="3" align="center">Item D1..D3</ti> |
| 615 |
+ </tr> |
| 616 |
+ <tr> |
| 617 |
+ <ti rowspan="2">Item E1..F1</ti> |
| 618 |
+ <ti colspan="2" align="right">Item E2..E3</ti> |
| 619 |
+ </tr> |
| 620 |
+ <tr> |
| 621 |
+ <ti colspan="2" align="right">Item F2..F3</ti> |
| 622 |
+ </tr> |
| 623 |
+</table> |
| 624 |
+ |
| 625 |
+</body> |
| 626 |
+</section> |
| 627 |
+<section> |
| 628 |
+<title>Lists</title> |
| 629 |
+<body> |
| 630 |
+ |
| 631 |
+<p> |
| 632 |
+To create ordered or unordered lists, simply use the XHTML-style |
| 633 |
+<c><ol></c>, <c><ul></c> and <c><li></c> tags. Lists may only |
| 634 |
+appear inside the <c><body></c> and <c><li></c> tags which means |
| 635 |
+that you can have lists inside lists. Don't forget that you are writing XML and |
| 636 |
+that you must close all tags including list items unlike in HTML. |
| 637 |
+</p> |
| 638 |
+ |
| 639 |
+<p> |
| 640 |
+Definition lists (<c><dl></c>) are also supported. Please note that |
| 641 |
+neither the definition term tag (<c><dt></c>) nor the definition data tag |
| 642 |
+(<c><dd></c>) accept any other block level tag such as paragraphs or |
| 643 |
+admonitions. A definition list comprises: |
| 644 |
+</p> |
| 645 |
+ |
| 646 |
+<dl> |
| 647 |
+ <dt><c><dl></c></dt> |
| 648 |
+ <dd>A <b>D</b>efinition <b>L</b>ist Tag containing</dd> |
| 649 |
+ <dt><c><dt></c></dt> |
| 650 |
+ <dd>Pairs of <b>D</b>efinition <b>T</b>erm Tags</dd> |
| 651 |
+ <dt><c><dd></c></dt> |
| 652 |
+ <dd>and <b>D</b>efinition <b>D</b>ata Tags</dd> |
| 653 |
+</dl> |
| 654 |
+ |
| 655 |
+<p> |
| 656 |
+The following list copied from <uri |
| 657 |
+link="http://www.w3.org/TR/REC-html40/struct/lists.html">w3.org</uri> shows |
| 658 |
+that a definition list can contain ordered and unordered lists. It may not |
| 659 |
+contain another definition list though. |
| 660 |
+</p> |
| 661 |
+ |
| 662 |
+<dl> |
| 663 |
+ <dt><b>The ingredients:</b></dt> |
| 664 |
+ <dd> |
| 665 |
+ <ul> |
| 666 |
+ <li>100 g. flour</li> |
| 667 |
+ <li>10 g. sugar</li> |
| 668 |
+ <li>1 cup water</li> |
| 669 |
+ <li>2 eggs</li> |
| 670 |
+ <li>salt, pepper</li> |
| 671 |
+ </ul> |
| 672 |
+ </dd> |
| 673 |
+ <dt><b>The procedure:</b></dt> |
| 674 |
+ <dd> |
| 675 |
+ <ol> |
| 676 |
+ <li>Mix dry ingredients thoroughly</li> |
| 677 |
+ <li>Pour in wet ingredients</li> |
| 678 |
+ <li>Mix for 10 minutes</li> |
| 679 |
+ <li>Bake for one hour at 300 degrees</li> |
| 680 |
+ </ol> |
| 681 |
+ </dd> |
| 682 |
+ <dt><b>Notes:</b></dt> |
| 683 |
+ <dd>The recipe may be improved by adding raisins</dd> |
| 684 |
+</dl> |
| 685 |
+ |
| 686 |
+</body> |
| 687 |
+</section> |
| 688 |
+<section> |
| 689 |
+<title>Intra-document references</title> |
| 690 |
+<body> |
| 691 |
+ |
| 692 |
+<p> |
| 693 |
+GuideXML makes it really easy to reference other parts of the document using |
| 694 |
+hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter |
| 695 |
+One</uri> by typing <c><uri link="#doc_chap1">Chapter |
| 696 |
+One</uri></c>. To point to <uri link="#doc_chap1_sect2">section two of |
| 697 |
+Chapter One</uri>, type <c><uri link="#doc_chap1_sect2">section two of |
| 698 |
+Chapter One</uri></c>. To refer to figure 3 in chapter 1, type |
| 699 |
+<c><uri link="#doc_chap1_fig3">figure 1.3</uri></c>. Or, to refer |
| 700 |
+to <uri link="#doc_chap2_pre2">code listing 2 in chapter 2</uri>, type |
| 701 |
+<c><uri link="#doc_chap2_pre2">code listing 2.2</uri></c>. |
| 702 |
+</p> |
| 703 |
+ |
| 704 |
+<p> |
| 705 |
+However, some guides change often and using such "counting" can lead to broken |
| 706 |
+links. In order to cope with this, you can define a name for a |
| 707 |
+<c><chapter></c>, <c><section></c> or a <c><tr></c> by using |
| 708 |
+the <c>id</c> attribute, and then point to that attribute, like this: |
| 709 |
+</p> |
| 710 |
+ |
| 711 |
+<pre caption="Using the id attribute"> |
| 712 |
+<chapter id="foo"> |
| 713 |
+<title>This is foo!</title> |
| 714 |
+... |
| 715 |
+<p> |
| 716 |
+More information can be found in the <uri link="#foo">foo chapter</uri> |
| 717 |
+</p> |
| 718 |
+</pre> |
| 719 |
+ |
| 720 |
+</body> |
| 721 |
+</section> |
| 722 |
+<section> |
| 723 |
+<title>Disclaimers and obsolete documents</title> |
| 724 |
+<body> |
| 725 |
+ |
| 726 |
+<p> |
| 727 |
+A <c>disclaimer</c> attribute can be applied to guides and handbooks to display |
| 728 |
+a predefined disclaimer at the top of the document. The available disclaimers |
| 729 |
+are: |
| 730 |
+</p> |
| 731 |
+ |
| 732 |
+<ul> |
| 733 |
+ <li> |
| 734 |
+ <b>articles</b> is used for <uri link="/doc/en/articles/">republished |
| 735 |
+ articles</uri> |
| 736 |
+ </li> |
| 737 |
+ <li> |
| 738 |
+ <b>draft</b> is used to indicate a document is still being worked on and |
| 739 |
+ should not be considered official |
| 740 |
+ </li> |
| 741 |
+ <li> |
| 742 |
+ <b>oldbook</b> is used on old handbooks to indicate they are not maintained |
| 743 |
+ anymore |
| 744 |
+ </li> |
| 745 |
+ <li><b>obsolete</b> is used to mark a document as obsolete.</li> |
| 746 |
+</ul> |
| 747 |
+ |
| 748 |
+<p> |
| 749 |
+When marking a document as obsolete, you might want to add a link to a new |
| 750 |
+version. The <c>redirect</c> attribute does just that. The user might be |
| 751 |
+automatically redirected to the new page but you should not rely on that |
| 752 |
+behaviour. |
| 753 |
+</p> |
| 754 |
+ |
| 755 |
+<pre caption="Disclaimer sample"> |
| 756 |
+<?xml version="1.0" encoding="UTF-8"?> |
| 757 |
+<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> |
| 758 |
+<!-- $Header$ --> |
| 759 |
+ |
| 760 |
+<guide disclaimer="obsolete" redirect="/doc/en/handbook/handbook-x86.xml"> |
| 761 |
+<title>Gentoo x86 Installation Guide</title> |
| 762 |
+ |
| 763 |
+<author title="Author"> |
| 764 |
+... |
| 765 |
+</pre> |
| 766 |
+ |
| 767 |
+</body> |
| 768 |
+</section> |
| 769 |
+<section> |
| 770 |
+<title>FAQs</title> |
| 771 |
+<body> |
| 772 |
+ |
| 773 |
+<p> |
| 774 |
+FAQ documents need to start with a list of questions with links to their |
| 775 |
+answers. Creating such a list is both time-consuming and error-prone. The list |
| 776 |
+can be created automatically if you use a <c>faqindex</c> element as the first |
| 777 |
+chapter of your document. This element has the same structure as a |
| 778 |
+<c>chapter</c> to allow some introductory text. The structure of the document |
| 779 |
+is expected to be split into chapters (at least one chapter) containing |
| 780 |
+sections, each section containing one question specified in its <c>title</c> |
| 781 |
+element with the answer in its <c>body</c>. The FAQ index will appear as one |
| 782 |
+section per chapter and one link per question. |
| 783 |
+</p> |
| 784 |
+ |
| 785 |
+<p> |
| 786 |
+A quick look at a <uri link="/doc/en/faq.xml">FAQ</uri> and <uri |
| 787 |
+link="/doc/en/faq.xml?passthru=1">its source</uri> should make the above |
| 788 |
+obvious. |
| 789 |
+</p> |
| 790 |
+ |
| 791 |
+</body> |
| 792 |
+</section> |
| 793 |
+</chapter> |
| 794 |
+ |
| 795 |
+<chapter> |
| 796 |
+<title>Handbook Format</title> |
| 797 |
+<section> |
| 798 |
+<title>Guide vs Book</title> |
| 799 |
+<body> |
| 800 |
+ |
| 801 |
+<p> |
| 802 |
+For high-volume documentation, such as the <uri |
| 803 |
+link="/doc/en/handbook/handbook-x86.xml?part=1">Installation Instructions</uri>, a |
| 804 |
+broader format was needed. We designed a GuideXML-compatible enhancement that |
| 805 |
+allows us to write modular and multi-page documentation. |
| 806 |
+</p> |
| 807 |
+ |
| 808 |
+</body> |
| 809 |
+</section> |
| 810 |
+<section> |
| 811 |
+<title>Main File</title> |
| 812 |
+<body> |
| 813 |
+ |
| 814 |
+<p> |
| 815 |
+The first change is the need for a "master" document. This document contains no |
| 816 |
+real content, but links to the individual documentation modules. The syntax |
| 817 |
+doesn't differ much from GuideXML: |
| 818 |
+</p> |
| 819 |
+ |
| 820 |
+<pre caption="Example book usage"> |
| 821 |
+<?xml version='1.0' encoding='UTF-8'?> |
| 822 |
+<!DOCTYPE book SYSTEM "/dtd/book.dtd"> |
| 823 |
+<!-- $Header$ --> |
| 824 |
+ |
| 825 |
+<<i>book</i>> |
| 826 |
+<title>Example Book Usage</title> |
| 827 |
+ |
| 828 |
+<author...> |
| 829 |
+ ... |
| 830 |
+</author> |
| 831 |
+ |
| 832 |
+<abstract> |
| 833 |
+ ... |
| 834 |
+</abstract> |
| 835 |
+ |
| 836 |
+<!-- The content of this document is licensed under the CC-BY-SA license --> |
| 837 |
+<!-- See http://creativecommons.org/licenses/by-sa/3.0 --> |
| 838 |
+<license version="3.0"/> |
| 839 |
+ |
| 840 |
+<version>...</version> |
| 841 |
+<date>...</date> |
| 842 |
+</pre> |
| 843 |
+ |
| 844 |
+<p> |
| 845 |
+So far no real differences (except for the <c><book></c> instead of |
| 846 |
+<c><guide></c> tag). Instead of starting with the individual |
| 847 |
+<c><chapter></c>s, you define a <c><part></c>, which is the |
| 848 |
+equivalent of a separate part in a book: |
| 849 |
+</p> |
| 850 |
+ |
| 851 |
+<pre caption="Defining a part"> |
| 852 |
+<part> |
| 853 |
+<title>Part One</title> |
| 854 |
+<abstract> |
| 855 |
+ ... |
| 856 |
+</abstract> |
| 857 |
+ |
| 858 |
+<comment>(Defining the several chapters)</comment> |
| 859 |
+</part> |
| 860 |
+</pre> |
| 861 |
+ |
| 862 |
+<p> |
| 863 |
+Each part is accompanied by a <c><title></c> and an |
| 864 |
+<c><abstract></c> which gives a small introduction to the part. |
| 865 |
+</p> |
| 866 |
+ |
| 867 |
+<p> |
| 868 |
+Inside each part, you define the individual <c><chapter></c>s. Each |
| 869 |
+chapter <e>must</e> be a separate document. As a result it is no surprise that |
| 870 |
+a special tag (<c><include></c>) is added to allow including the separate |
| 871 |
+document. |
| 872 |
+</p> |
| 873 |
+ |
| 874 |
+<pre caption="Defining a chapter"> |
| 875 |
+<chapter> |
| 876 |
+<title>Chapter One</title> |
| 877 |
+ |
| 878 |
+ <include href="path/to/chapter-one.xml"/> |
| 879 |
+ |
| 880 |
+</chapter> |
| 881 |
+</pre> |
| 882 |
+ |
| 883 |
+</body> |
| 884 |
+</section> |
| 885 |
+<section> |
| 886 |
+<title>Designing the Individual Chapters</title> |
| 887 |
+<body> |
| 888 |
+ |
| 889 |
+<p> |
| 890 |
+The content of an individual chapter is structured as follows: |
| 891 |
+</p> |
| 892 |
+ |
| 893 |
+<pre caption="Chapter Syntax"> |
| 894 |
+<?xml version='1.0' encoding='UTF-8'?> |
| 895 |
+<!DOCTYPE sections SYSTEM "/dtd/book.dtd"> |
| 896 |
+<!-- $Header$ --> |
| 897 |
+ |
| 898 |
+<!-- The content of this document is licensed under the CC-BY-SA license --> |
| 899 |
+<!-- See http://creativecommons.org/licenses/by-sa/3.0 --> |
| 900 |
+ |
| 901 |
+<sections> |
| 902 |
+ |
| 903 |
+<abstract> |
| 904 |
+ This is a small explanation on chapter one. |
| 905 |
+</abstract> |
| 906 |
+ |
| 907 |
+<version>...</version> |
| 908 |
+<date>...</date> |
| 909 |
+ |
| 910 |
+<comment>(Define the several <section> and <subsection>)</comment> |
| 911 |
+ |
| 912 |
+</sections> |
| 913 |
+</pre> |
| 914 |
+ |
| 915 |
+<p> |
| 916 |
+Inside each chapter you can define <c><section></c>s (equivalent of |
| 917 |
+<c><chapter></c> in a Guide) and <c><subsection></c>s (equivalent |
| 918 |
+of <c><section></c> in a Guide). |
| 919 |
+</p> |
| 920 |
+ |
| 921 |
+<p> |
| 922 |
+Each individual chapter should have its own date and version elements. The |
| 923 |
+latest date of all chapters and master document will be displayed when a user |
| 924 |
+browses through all parts of the book. |
| 925 |
+</p> |
| 926 |
+ |
| 927 |
+</body> |
| 928 |
+</section> |
| 929 |
+</chapter> |
| 930 |
+ |
| 931 |
+<chapter> |
| 932 |
+<title>Advanced Handbook Features</title> |
| 933 |
+<section> |
| 934 |
+<title>Global Values</title> |
| 935 |
+<body> |
| 936 |
+ |
| 937 |
+<p> |
| 938 |
+Sometimes, the same values are repeated many times in several parts of a |
| 939 |
+handbook. Global search and replace operations tend to forget some or introduce |
| 940 |
+unwanted changes. Besides, it can be useful to define different values to be |
| 941 |
+used in shared chapters depending on which handbook includes the chapter. |
| 942 |
+</p> |
| 943 |
+ |
| 944 |
+<p> |
| 945 |
+Global values can be defined in a handbook master file and used in all included |
| 946 |
+chapters. |
| 947 |
+</p> |
| 948 |
+ |
| 949 |
+<p> |
| 950 |
+To define global values, add a <c><values></c> element to the handbook |
| 951 |
+master file. Each value is then defined in a <c><key></c> element whose |
| 952 |
+<c>id</c> attribute identifies the value, i.e. it is the name of your variable. |
| 953 |
+The content of the <c><key></c> is its value. |
| 954 |
+</p> |
| 955 |
+ |
| 956 |
+<p> |
| 957 |
+The following example defines three values in a handbook master file: |
| 958 |
+</p> |
| 959 |
+ |
| 960 |
+<pre caption="Define values in a handbook"> |
| 961 |
+<?xml version='1.0' encoding='UTF-8'?> |
| 962 |
+<!DOCTYPE book SYSTEM "/dtd/book.dtd"> |
| 963 |
+<!-- $Header$ --> |
| 964 |
+ |
| 965 |
+<book> |
| 966 |
+<title>Example Book Usage</title> |
| 967 |
+ |
| 968 |
+<i><values> |
| 969 |
+ <key id="arch">x86</key> |
| 970 |
+ <key id="min-cd-name">install-x86-minimal-2007.0-r1.iso</key> |
| 971 |
+ <key id="min-cd-size">57</key> |
| 972 |
+</values></i> |
| 973 |
+ |
| 974 |
+<author...> |
| 975 |
+ ... |
| 976 |
+</author> |
| 977 |
+ |
| 978 |
+... |
| 979 |
+</pre> |
| 980 |
+ |
| 981 |
+<p> |
| 982 |
+The defined values can then be used throughout the handbook with the in-line |
| 983 |
+<c><keyval id="key_id"/></c> element. Specify the name of the key in its |
| 984 |
+<c>id</c> attribute, e.g. <keyval id="min-cd-name"/> would be replaced by |
| 985 |
+"install-x86-minimal-2007.0-r1.iso" in our example. |
| 986 |
+</p> |
| 987 |
+ |
| 988 |
+<pre caption="Using defined values"> |
| 989 |
+<p> |
| 990 |
+The Minimal Installation CD is called <c><i><keyval id="min-cd-name"/></i></c> |
| 991 |
+and takes up only <i><keyval id="min-cd-size"/></i> MB of diskspace. You can use this |
| 992 |
+Installation CD to install Gentoo, but <e>only</e> with a working Internet |
| 993 |
+connection. |
| 994 |
+</p> |
| 995 |
+</pre> |
| 996 |
+ |
| 997 |
+<p> |
| 998 |
+To make life easier on our translators, only use actual values, i.e. content |
| 999 |
+that does not need to be translated. For instance, we defined the |
| 1000 |
+<c>min-cd-size</c> value to <c>57</c> and not <c>57 MB</c>. |
| 1001 |
+</p> |
| 1002 |
+ |
| 1003 |
+</body> |
| 1004 |
+</section> |
| 1005 |
+<section> |
| 1006 |
+<title>Conditional Elements</title> |
| 1007 |
+<body> |
| 1008 |
+ |
| 1009 |
+<p> |
| 1010 |
+Chapters that are shared by several handbooks such as our <uri |
| 1011 |
+link="/doc/en/handbook/">Installation Handbooks</uri> often have small |
| 1012 |
+differences depending on which handbook includes them. Instead of adding |
| 1013 |
+content that is irrelevant to some handbooks, authors can add a condition to |
| 1014 |
+the following elements: <c><section></c>, <c><subsection></c>, |
| 1015 |
+<c><body></c>, <c><note></c>, <c><impo></c>, |
| 1016 |
+<c><warn></c>, <c><pre></c>, <c><p></c>, |
| 1017 |
+<c><table></c>, <c><tr></c>, <c><ul></c>, <c><ol></c> |
| 1018 |
+and <c><li></c>. |
| 1019 |
+</p> |
| 1020 |
+ |
| 1021 |
+<p> |
| 1022 |
+The condition must be an <uri |
| 1023 |
+link="http://en.wikipedia.org/wiki/XPath">XPATH</uri> expression that will be |
| 1024 |
+evaluated when transforming the XML. If it evaluates to <c>true</c>, the |
| 1025 |
+element is processed, if not, it is ignored. The condition is specified in a |
| 1026 |
+<c>test</c> attribute. |
| 1027 |
+</p> |
| 1028 |
+ |
| 1029 |
+<p> |
| 1030 |
+The following example uses the <c>arch</c> value that is defined in each |
| 1031 |
+handbook master file to condition some content: |
| 1032 |
+</p> |
| 1033 |
+ |
| 1034 |
+<pre caption="Using conditional elements"> |
| 1035 |
+<body test="contains('AMD64 x86',func:keyval('arch'))"> |
| 1036 |
+ |
| 1037 |
+<p> |
| 1038 |
+This paragraph applies to both x86 and AMD64 architectures. |
| 1039 |
+</p> |
| 1040 |
+ |
| 1041 |
+<p test="func:keyval('arch')='x86'"> |
| 1042 |
+This paragraph only applies to the x86 architecture. |
| 1043 |
+</p> |
| 1044 |
+ |
| 1045 |
+<p test="func:keyval('arch')='AMD64'"> |
| 1046 |
+This paragraph only applies to the AMD64 architecture. |
| 1047 |
+</p> |
| 1048 |
+ |
| 1049 |
+<p test="func:keyval('arch')='PPC'"> |
| 1050 |
+This paragraph will never be seen! |
| 1051 |
+The whole body is skipped because of the first condition. |
| 1052 |
+</p> |
| 1053 |
+ |
| 1054 |
+</body> |
| 1055 |
+ |
| 1056 |
+<body test="contains('AMD64 PPC64',func:keyval('arch'))"> |
| 1057 |
+ |
| 1058 |
+<p> |
| 1059 |
+This paragraph applies to the AMD64, PPC64 <comment>and PPC</comment> architectures because |
| 1060 |
+the 'AMD64 PPC64' string does contain 'PPC'. |
| 1061 |
+</p> |
| 1062 |
+ |
| 1063 |
+<note test="func:keyval('arch')='AMD64' or func:keyval('arch')='PPC64'"> |
| 1064 |
+This note only applies to the AMD64 and PPC64 architectures. |
| 1065 |
+</note> |
| 1066 |
+ |
| 1067 |
+</body> |
| 1068 |
+</pre> |
| 1069 |
+ |
| 1070 |
+</body> |
| 1071 |
+</section> |
| 1072 |
+</chapter> |
| 1073 |
+ |
| 1074 |
+<chapter id="codingstyle"> |
| 1075 |
+<title>Coding Style</title> |
| 1076 |
+<section> |
| 1077 |
+<title>Introduction</title> |
| 1078 |
+<body> |
| 1079 |
+ |
| 1080 |
+<p> |
| 1081 |
+Since all Gentoo Documentation is a joint effort and several people will |
| 1082 |
+most likely change existing documentation, a coding style is needed. |
| 1083 |
+A coding style contains two sections. The first one is regarding |
| 1084 |
+internal coding - how the XML-tags are placed. The second one is |
| 1085 |
+regarding the content - how not to confuse the reader. |
| 1086 |
+</p> |
| 1087 |
+ |
| 1088 |
+<p> |
| 1089 |
+Both sections are described next. |
| 1090 |
+</p> |
| 1091 |
+ |
| 1092 |
+</body> |
| 1093 |
+</section> |
| 1094 |
+<section> |
| 1095 |
+<title>Internal Coding Style</title> |
| 1096 |
+<body> |
| 1097 |
+ |
| 1098 |
+<p> |
| 1099 |
+<b>Newlines</b> must be placed immediately after <e>every</e> |
| 1100 |
+GuideXML-tag (both opening as closing), except for: |
| 1101 |
+<c><version></c>, <c><date></c>, <c><title></c>, |
| 1102 |
+<c><th></c>, <c><ti></c>, |
| 1103 |
+<c><li></c>, <c><i></c>, <c><e></c>, |
| 1104 |
+<c><uri></c>, <c><path></c>, <c><b></c>, <c><c></c>, |
| 1105 |
+<c><comment></c>, <c><mail></c>. |
| 1106 |
+</p> |
| 1107 |
+ |
| 1108 |
+<p> |
| 1109 |
+<b>Blank lines</b> must be placed immediately after <e>every</e> |
| 1110 |
+<c><body></c> (opening tag only) and before <e>every</e> |
| 1111 |
+<c><chapter></c>, <c><p></c>, <c><table></c>, |
| 1112 |
+<c><author></c> (set), <c><pre></c>, <c><ul></c>, |
| 1113 |
+<c><ol></c>, <c><warn></c>, <c><note></c> and |
| 1114 |
+<c><impo></c> (opening tags only). |
| 1115 |
+</p> |
| 1116 |
+ |
| 1117 |
+<p> |
| 1118 |
+<b>Word-wrapping</b> must be applied at 80 characters except inside |
| 1119 |
+<c><pre></c>. You may only deviate from this rule when there is no other |
| 1120 |
+choice (for instance when a URL exceeds the maximum amount of characters). The |
| 1121 |
+editor must then wrap whenever the first whitespace occurs. You should try to |
| 1122 |
+keep the <e>rendered</e> content of <c><pre></c> elements within 80 |
| 1123 |
+columns to help console users. |
| 1124 |
+</p> |
| 1125 |
+ |
| 1126 |
+<p> |
| 1127 |
+<b>Indentation</b> may not be used, except with the XML-constructs of which the |
| 1128 |
+parent XML-tags are <c><tr></c> (from <c><table></c>), |
| 1129 |
+<c><ul></c>, <c><ol></c>, <c><dl></c>, and |
| 1130 |
+<c><author></c>. If indentation is used, it <e>must</e> be two spaces for |
| 1131 |
+each indentation. That means <e>no tabs</e> and <e>not</e> more spaces. |
| 1132 |
+Besides, tabs are not allowed in GuideXML documents. |
| 1133 |
+</p> |
| 1134 |
+ |
| 1135 |
+<p> |
| 1136 |
+In case word-wrapping happens in <c><ti></c>, <c><th></c>, |
| 1137 |
+<c><li></c> or <c><dd></c> constructs, indentation must be used for |
| 1138 |
+the content. |
| 1139 |
+</p> |
| 1140 |
+ |
| 1141 |
+<p> |
| 1142 |
+An example for indentation is: |
| 1143 |
+</p> |
| 1144 |
+ |
| 1145 |
+<pre caption="Indentation Example"> |
| 1146 |
+<table> |
| 1147 |
+<tr> |
| 1148 |
+ <th>Foo</th> |
| 1149 |
+ <th>Bar</th> |
| 1150 |
+</tr> |
| 1151 |
+<tr> |
| 1152 |
+ <ti>This is an example for indentation</ti> |
| 1153 |
+ <ti> |
| 1154 |
+ In case text cannot be shown within an 80-character wide line, you |
| 1155 |
+ must use indentation if the parent tag allows it |
| 1156 |
+ </ti> |
| 1157 |
+</tr> |
| 1158 |
+</table> |
| 1159 |
+ |
| 1160 |
+<ul> |
| 1161 |
+ <li>First option</li> |
| 1162 |
+ <li>Second option</li> |
| 1163 |
+</ul> |
| 1164 |
+</pre> |
| 1165 |
+ |
| 1166 |
+<p> |
| 1167 |
+<b>Attributes</b> may not have spaces in between the attribute, the "=" mark, |
| 1168 |
+and the attribute value. As an example: |
| 1169 |
+</p> |
| 1170 |
+ |
| 1171 |
+<pre caption="Attributes"> |
| 1172 |
+<comment>Wrong :</comment> <pre caption = "Attributes"> |
| 1173 |
+<comment>Correct:</comment> <pre caption="Attributes"> |
| 1174 |
+</pre> |
| 1175 |
+ |
| 1176 |
+</body> |
| 1177 |
+</section> |
| 1178 |
+<section> |
| 1179 |
+<title>External Coding Style</title> |
| 1180 |
+<body> |
| 1181 |
+ |
| 1182 |
+<p> |
| 1183 |
+Inside tables (<c><table></c>) and listings (<c><ul></c>, |
| 1184 |
+<c><ol></c>) and <c><dl></c>, periods (".") should not be used |
| 1185 |
+unless multiple sentences are used. In that case, every sentence should end |
| 1186 |
+with a period (or other reading marks). |
| 1187 |
+</p> |
| 1188 |
+ |
| 1189 |
+<p> |
| 1190 |
+Every sentence, including those inside tables and listings, should start |
| 1191 |
+with a capital letter. |
| 1192 |
+</p> |
| 1193 |
+ |
| 1194 |
+<pre caption="Periods and capital letters"> |
| 1195 |
+<ul> |
| 1196 |
+ <li>No period</li> |
| 1197 |
+ <li>With period. Multiple sentences, remember?</li> |
| 1198 |
+</ul> |
| 1199 |
+</pre> |
| 1200 |
+ |
| 1201 |
+<p> |
| 1202 |
+Code Listings should <e>always</e> have a <c>caption</c>. |
| 1203 |
+</p> |
| 1204 |
+ |
| 1205 |
+<p> |
| 1206 |
+Try to use <c><uri></c> with the <c>link</c> attribute as much as |
| 1207 |
+possible. In other words, the <uri link="http://forums.gentoo.org">Gentoo |
| 1208 |
+Forums</uri> is preferred over <uri>http://forums.gentoo.org</uri>. |
| 1209 |
+</p> |
| 1210 |
+ |
| 1211 |
+<p> |
| 1212 |
+When you comment something inside a <c><pre></c> construct, use |
| 1213 |
+<c><comment></c> and parentheses or the comment marker for the language |
| 1214 |
+that is being used (<c>#</c> for bash scripts and many other things, <c>//</c> |
| 1215 |
+for C code, etc.) Also place the comment <e>before</e> the subject of the |
| 1216 |
+comment. |
| 1217 |
+</p> |
| 1218 |
+ |
| 1219 |
+<pre caption="Comment example"> |
| 1220 |
+<comment>(Substitute "john" with your user name)</comment> |
| 1221 |
+# <i>id john</i> |
| 1222 |
+</pre> |
| 1223 |
+ |
| 1224 |
+</body> |
| 1225 |
+</section> |
| 1226 |
+</chapter> |
| 1227 |
+ |
| 1228 |
+<chapter> |
| 1229 |
+<title>Resources</title> |
| 1230 |
+<section> |
| 1231 |
+<title>Start writing</title> |
| 1232 |
+<body> |
| 1233 |
+ |
| 1234 |
+<p> |
| 1235 |
+GuideXML has been specially designed to be "lean and mean" so that developers |
| 1236 |
+can spend more time writing documentation and less time learning the actual XML |
| 1237 |
+syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy" |
| 1238 |
+to start writing quality Gentoo documentation. You might be interested in our |
| 1239 |
+<uri link="/proj/en/gdp/doc/doc-tipsntricks.xml">Documentation Development Tips |
| 1240 |
+& Tricks</uri>. If you'd like to help (or have any questions about |
| 1241 |
+GuideXML), please post a message to the <uri |
| 1242 |
+link="/main/en/lists.xml">gentoo-doc mailing list</uri> stating what you'd like |
| 1243 |
+to tackle. Have fun! |
| 1244 |
+</p> |
| 1245 |
+ |
| 1246 |
+</body> |
| 1247 |
+</section> |
| 1248 |
+</chapter> |
| 1249 |
+</guide> |
| 1250 |
|
| 1251 |
diff --git a/appendices/contributing/text.xml b/appendices/contributing/text.xml |
| 1252 |
index 5550aef..04fc9a8 100644 |
| 1253 |
--- a/appendices/contributing/text.xml |
| 1254 |
+++ b/appendices/contributing/text.xml |
| 1255 |
@@ -143,5 +143,6 @@ really should first examine the GuideXML guide in a reasonable amount of depth. |
| 1256 |
</section> |
| 1257 |
</chapter> |
| 1258 |
|
| 1259 |
-</guide> |
| 1260 |
+<include href="devbook-guide/"/> |
| 1261 |
|
| 1262 |
+</guide> |
Archives