doc/source/dtd/readme-dblite.html

   1 <html>
   2 <head>
   3 <title>Using DocBook Lite</title>
   4 <style>
   5 body {
   6   background-color: wheat;
   7   font-family: sans-serif;
   8 }
   9 .section {
  10   margin: 0.5em;
  11   padding: 0.5em;
  12   background-color: wheat;
  13 }
  14 .contents {
  15   margin: 0.5em;
  16   padding: 0.5em;
  17   background-color: silver;
  18 }
  19 </style>
  20 </head>
  21
  22 <body>
  23 <h1 class="doctitle">Using DocBook Lite</h1>
  24 <div class="contents">
  25 <h2 class="ctitle">Contents</h2>
  26 <a href="#section-1">1. Introduction</a>
  27 <br>
  28 <a href="#section-2">2. XML</a>
  29 <br>
  30 <a href="#section-3">3. For best results...</a>
  31 <br>
  32 <a href="#section-4">4. The Physical Structure of a Book</a>
  33 <br>
  34 <a href="#section-5">5. The Logical Structure of a Book</a>
  35 <br>
  36 <a href="#section-6">6. Block elements</a>
  37 <br>
  38 <a href="#section-7">7. Inline elements</a>
  39 <br>
  40 <a href="#section-8">8. Tables</a>
  41 <br>
  42 <a href="#section-9">9. Indexterms</a>
  43 <br>
  44 <a href="#section-10">10. Out-of-flow Text</a>
  45 <br>
  46 <a href="#section-11">11. Reference Pages</a>
  47 <br>
  48 <a href="#section-12">12. See Also...</a>
  49 <br>
  50 </div>
  51
  52
  53
  54
  55
  56
  57   <a name="section-1"></a>
  58 <div class="section">
  59     <h2 class="stitle">1. Introduction</h2>
  60
  61     <p>
  62 This document describes the use of DocBook Lite, a document type
  63 definition (DTD) that defines and shapes the markup of O'Reilly
  64 books. The DTD declares a set of elements (containers of content) and
  65 entities (stand-ins for content). Its notation restricts the kinds of
  66 elements and data that each element can hold. For example, a
  67 <tt>&lt;chapter&gt;</tt> can contain a
  68 <tt>&lt;para&gt;</tt> (paragraph), but cannot contain a
  69 <tt>&lt;book&gt;</tt>.
  70     </p>
  71
  72     <p>
  73 DocBook Lite is an application of the XML markup language rules. XML
  74 doesn't require that you use a DTD, but we find that enforcing
  75 structure is vital to our ability to produce and repurpose books
  76 efficiently. Originally, we used the full DocBook application
  77 maintained by <a href="http://www.oasis-open.org/">the OASIS
  78 SGML/XML standards group</a>, but have since refined it to a small
  79 subset with its own DTD. It has a few additions for some types of
  80 books, but mostly the markup should be compatible with the full
  81 DocBook.
  82     </p>
  83   </div>
  84
  85
  86
  87
  88   <a name="section-2"></a>
  89 <div class="section">
  90     <h2 class="stitle">2. XML</h2>
  91
  92     <p>
  93 The eXtensible Markup Language (XML) is a
  94 specification for how markup should work in a document. Using codes
  95 embedded in text, it defines structure and properties for the parts of
  96 a document. The basic philosophy of XML is that every unique part of a
  97 document should be clearly labelled and its position should be
  98 unambiguous. If a document satisfies the minimal rules of XML, it is
  99 said to be well-formed. A document that is not
 100 well-formed has syntax or other kinds of errors that need to be fixed
 101 before the document can be processed.
 102     </p>
 103
 104
 105       <p>
 106 The rules for a well-formed XML document differ from those of
 107 HTML pages. HTML is less strict with syntax, and most browser will not
 108 complain about poor style or errors. However, XML is much less
 109 forgiving, so be warned.
 110       </p>
 111
 112
 113     <p>
 114 DocBook Lite adds another level of control to the document. It
 115 restricts the kinds of elements and structures that make up a
 116 book. Specially tailored to O'Reilly's style, the DTD ensures that the
 117 book has maximum quality and information value by the time it reaches
 118 production. A document that conforms to our DTD is described as
 119 valid. A document that is not valid has
 120 incorrect markup that needs to be fixed before it can be accurately
 121 processed by our tools.
 122     </p>
 123
 124     <p>
 125 To test the validity of a document, you need to use a program called a
 126 validator. Sometimes this is built-in to the
 127 text editor you're using. For example, Arbortext's Adept editor has a
 128 validation option. Other editors may not include a validating parser
 129 because it's assumed that any document you open is already valid, and
 130 you won't make any mistakes because the editor won't let you (it
 131 constrains your actions). There are also stand-alone validators that
 132 read a document and list errors for you. We use nsgmls to validate
 133 books.
 134     </p>
 135
 136
 137       <p>
 138 <tt>nsgmls</tt> is written and maintained by James Clark
 139 and is available for free from <a href="http://www.jclark.com/sp/nsgmls.htm">his web page</a>.
 140       </p>
 141
 142   </div>
 143
 144
 145
 146
 147   <a name="section-3"></a>
 148 <div class="section">
 149     <h2 class="stitle">3. For best results...</h2>
 150
 151     <p>
 152 Just because you're using XML doesn't mean the document is marked up
 153 as well as it can be. Even a valid document can have mistakes and
 154 problems that lower the quality of the book and slow down
 155 production. For example, you may use the wrong element name, which
 156 will pass the DTD test but not make sense to a human. The following
 157 code fragment shows the correct markup for a term-definition
 158 list:
 159     </p>
 160
 161     <div class="programlisting">
 162 <pre>&lt;variablelist&gt;
 163
 164  &lt;varlistentry&gt;
 165   &lt;term&gt;monkey&lt;/term&gt;
 166   &lt;listitem&gt;&lt;para&gt;A cute, furry mammal that climbs in trees.&lt;/para&gt;&lt;/listitem&gt;
 167  &lt;/varlistentry&gt;
 168
 169  &lt;varlistentry&gt;
 170   &lt;term&gt;koala&lt;/term&gt;
 171   &lt;listitem&gt;&lt;para&gt;A cute, furry mammal that climbs in trees.&lt;/para&gt;&lt;/listitem&gt;
 172  &lt;/varlistentry&gt;
 173
 174 &lt;/variablelist&gt;</pre>
 175 </div>
 176
 177     <p>
 178 Sometimes, people choose to do this with another kind of list:
 179     </p>
 180
 181     <div class="programlisting">
 182 <pre>&lt;itemizedlist&gt;
 183  &lt;listitem&gt;&lt;para&gt;Monkey - A cute, furry mammal that climbs in trees.&lt;/para&gt;&lt;/listitem&gt;
 184  &lt;listitem&gt;&lt;para&gt;Koala - A cute, furry mammal that climbs in trees.&lt;/para&gt;&lt;/listitem&gt;
 185 &lt;/itemizedlist&gt;</pre>
 186 </div>
 187
 188     <p>
 189 It's easier to type it the second way, but then you lose some
 190 information, like the fact that it's supposed to be a mapping of terms
 191 to definitions. Although you may think you're saving time with this
 192 shortcut, it will add delays later when production staff have to
 193 transform the list into its proper markup.
 194     </p>
 195
 196     <p>
 197 Another common mistake authors make is to assume that
 198 presentational markup is just as good as
 199 semantic markup. In other words, saying how
 200 something looks is as good as saying what it is. This is contrary to
 201 the philosophy of XML, and also will cause problems for your book
 202 later on. For example, consider the inline markup for a Web address,
 203 or URL. In print, a URL appears in italic like this:
 204     </p>
 205
 206
 207       <p>
 208 For more information, you <em>really</em> ought to
 209 check out the W3C's website at
 210 <em>http://www.w3.org/</em>.
 211       </p>
 212
 213
 214     <p>
 215 The correct way to mark up this passage is like this:
 216     </p>
 217
 218     <div class="programlisting">
 219 <pre>&lt;para&gt;For more information, you &lt;emphasis&gt;really&lt;/emphasis&gt;
 220 ought to check out the W3C's website at &lt;systemitem
 221 class="url"&gt;http://www.w3.org/&lt;/systemitem&gt;.&lt;/para&gt;</pre>
 222 </div>
 223
 224     <p>
 225 This is called semantic markup because the
 226 "really" and the URL are labelled according to their meaning, not
 227 their appearance. The next snippet shows the incorrect, presentational
 228 markup:
 229     </p>
 230
 231     <div class="programlisting">
 232 <pre>For more information, you &lt;emphasis&gt;really&lt;/emphasis&gt;
 233 ought to check out the W3C's website at
 234 &lt;emphasis&gt;http://www.w3.org/&lt;/emphasis&gt;.</pre>
 235 </div>
 236
 237     <p>
 238 The author thought that because <tt>&lt;emphasis&gt;</tt>
 239 causes its contents to be formatted in italic, it's okay to label
 240 everything that comes out in italic as a
 241 <tt>&lt;emphasis&gt;</tt>. So what? Well, it becomes a
 242 problem when you want to <em>repurpose</em> the document
 243 in HTML. Instead of the URL coming out as a hyperlink, it's merely
 244 formatted in italic. When everything is marked up presentationally,
 245 it's impossible to reuse the content in a different context.
 246     </p>
 247   </div>
 248
 249
 250
 251
 252   <a name="section-4"></a>
 253 <div class="section">
 254     <h2 class="stitle">4. The Physical Structure of a Book</h2>
 255
 256     <p>
 257 By physical structure, we mean the files and
 258 directories used to contain the pieces of an XML document. An O'Reilly
 259 book typically is stored in a single directory. Each chapter, preface,
 260 and appendix exists in a separate file, and there is a
 261 "master" file which contains the top (root) element for
 262 the book. The following table lists the kinds of files and their name
 263 conventions:
 264     </p>
 265
 266     <table border="1">
 267       <h4 class="exampletitle">Table 1. File naming conventions</h4>
 268       <tr>
 269         <th>element</th>
 270         <th>filename</th>
 271         <th>purpose</th>
 272       </tr>
 273
 274       <tr>
 275         <td><tt>&lt;book&gt;</tt></td>
 276         <td>book.xml</td>
 277         <td>
 278           <p>
 279 Contains the DOCTYPE declaration, declares local entities
 280 in the internal subset, holds metadata, contains file reference
 281 entities to chapters and other external elements.
 282           </p>
 283         </td>
 284       </tr>
 285
 286       <tr>
 287         <td><tt>&lt;copyrightpg&gt;</tt></td>
 288         <td>copy.xml</td>
 289         <td>
 290           <p>
 291 Contains the copyright page with legal info.
 292           </p>
 293         </td>
 294       </tr>
 295
 296       <tr>
 297         <td><tt>&lt;preface&gt;</tt></td>
 298         <td>ch00.xml</td>
 299         <td>
 300           <p>
 301 Contains the preface.
 302           </p>
 303         </td>
 304       </tr>
 305
 306       <tr>
 307         <td><tt>&lt;chapter&gt;</tt></td>
 308         <td>
 309           <p>
 310 ch<i>xx</i>.xml, where
 311 <i>xx</i> is the number of the chapter (e.g. 01,
 312 04, 11)
 313           </p>
 314         </td>
 315         <td>
 316           <p>
 317 Contains a chapter.
 318           </p>
 319         </td>
 320       </tr>
 321
 322       <tr>
 323         <td><tt>&lt;appendix&gt;</tt></td>
 324         <td>
 325           <p>
 326 app<i>x</i>.xml, where
 327 <i>x</i> is the letter of the appendix (e.g. a, b,
 328 c)
 329           </p>
 330         </td>
 331         <td>
 332           <p>
 333 Contains an appendix.
 334           </p>
 335         </td>
 336       </tr>
 337
 338       <tr>
 339         <td><tt>&lt;bibliography&gt;</tt></td>
 340         <td>biblio.xml</td>
 341         <td>
 342           <p>
 343 A chapter-level section containing bibliographic citations.
 344           </p>
 345         </td>
 346       </tr>
 347
 348       <tr>
 349         <td><tt>&lt;glossary&gt;</tt></td>
 350         <td>gloss.xml</td>
 351         <td>
 352           <p>
 353 A chapter-level section containing glossary definitions.
 354           </p>
 355         </td>
 356       </tr>
 357
 358       <tr>
 359         <td><tt>&lt;part&gt;</tt></td>
 360         <td>
 361           <p>
 362 part<i>x</i>.xml, where
 363 <i>x</i> is the number of the part (e.g. 1, 2,
 364 3)
 365           </p>
 366         </td>
 367         <td>
 368           <p>
 369 Contains a part (the first page only).
 370           </p>
 371         </td>
 372       </tr>
 373
 374       <tr>
 375         <td><tt>&lt;colophon&gt;</tt></td>
 376         <td>colo.xml</td>
 377         <td>
 378           <p>
 379 A section at the end of the book describing details of the
 380 book's production.
 381           </p>
 382         </td>
 383       </tr>
 384     </table>
 385
 386     <p>
 387 So a typical directory listing for a book would look something like
 388 this:
 389     </p>
 390
 391     <div class="screen">
 392 <pre>$&gt; ls /work/java/java.qref/xml
 393
 394     appa.xml      ch01.xml      ch06.xml      part1.xml
 395     appb.xml      ch02.xml      ch07.xml      part2.xml
 396     appc.xml      ch03.xml      ch08.xml
 397     book.xml      ch04.xml      colo.xml
 398     ch00.xml      ch05.xml      copy.xml</pre>
 399 </div>
 400
 401     <p>
 402 There is one master file for the book (<i>book.xml</i>);
 403 three files for appendixes A, B, and C; one file for the preface;
 404 eight files for chapters 1-8; two files for parts I and II; and a file
 405 each for the copyright page and colophon. Note that the part files do
 406 not contain the chapters, even though the
 407 <tt>&lt;part&gt;</tt> elements logically contain
 408 <tt>&lt;chapter&gt;</tt>s.
 409     </p>
 410   </div>
 411
 412
 413
 414
 415   <a name="section-5"></a>
 416 <div class="section">
 417     <h2 class="stitle">5. The Logical Structure of a Book</h2>
 418
 419     <p>
 420 Logical structure is defined by the book's
 421 markup once the files have been assembled, which is how the parser
 422 sees the document. The hierarchy of the book (chapters, sections,
 423 sub-sections, etc.) is constructed using elements called
 424 divisions. A division is a container that
 425 usually has a <tt>&lt;title&gt;</tt> and contains other
 426 divisions or block elements. We will look at top-level containers
 427 (<tt>&lt;book&gt;</tt>, <tt>&lt;chapter&gt;</tt>,
 428 <tt>&lt;preface&gt;</tt>,
 429 <tt>&lt;appendix&gt;</tt>, and
 430 <tt>&lt;part&gt;</tt>), and intermediate-level divisions
 431 (<tt>&lt;sect1&gt;</tt>, <tt>&lt;sect2&gt;</tt>,
 432 <tt>&lt;sect3&gt;</tt>, <tt>&lt;sect4&gt;</tt>,
 433 <tt>&lt;simplesect&gt;</tt>, and
 434 <tt>&lt;partinfo&gt;</tt>).
 435     </p>
 436
 437     <a name="section-1.1"></a>
 438 <div class="ssection">
 439       <h3 class="sstitle">5.1. ID Attributes</h3>
 440
 441       <p>
 442 To facilitate cross references, you should use IDs in major
 443 hierarchical elements such as sections, chapters, and appendixes.
 444 For example, a chapter might have an ID like this:
 445       </p>
 446
 447       <div class="programlisting">
 448 <pre>&lt;chapter id="intro-chapter"&gt;</pre>
 449 </div>
 450
 451       <p>
 452 Technically, the only requirement for an ID attribute is that it be
 453 unique, since in XML no two elements can have the same ID attribute.
 454 However, we ask that you use attribute names that are easy to read
 455 and indicate the type of element and its subject.  For example,
 456 <tt>id="shapes-section"</tt> is better than
 457 <tt>id="A6-4.2"</tt>.
 458       </p>
 459
 460       <p>
 461 When the book is in production, and the order of elements is
 462 solidified, we will sometimes run a program that inserts ID attributes
 463 where they were previously missing, or to replace those that make
 464 sense only to the author.  These generated IDs follow a pattern that
 465 helps production staff trace links to their targets, even if the
 466 target ID is missing or misspelled.  The following table lists these
 467 ID patterns:
 468       </p>
 469
 470       <table border="1">
 471         <h4 class="exampletitle">Table 1. Autogenerated ID Attributes</h4>
 472         <tr>
 473           <th>element</th>
 474           <th>pattern</th>
 475           <th>example</th>
 476         </tr>
 477
 478         <tr>
 479           <td>appendix</td>
 480           <td><i>prefix</i>-APP-<i>letter</i></td>
 481           <td>MONKEYS-APP-B</td>
 482         </tr>
 483
 484         <tr>
 485           <td>chapter</td>
 486           <td><i>prefix</i>-CH-<i>num</i></td>
 487           <td>MONKEYS-CH-3</td>
 488         </tr>
 489
 490         <tr>
 491           <td>preface</td>
 492           <td><i>prefix</i>-PREF</td>
 493           <td>MONKEYS-PREF</td>
 494         </tr>
 495
 496         <tr>
 497           <td>part</td>
 498           <td><i>prefix</i>-PART-<i>num</i></td>
 499           <td>MONKEYS-PART-2</td>
 500         </tr>
 501
 502         <tr>
 503           <td>sect1 (A-head or section)</td>
 504           <td><i>prefix</i>-<i>CH/APP</i>-<i>num/letter</i>-SECT-<i>num</i></td>
 505           <td>MONKEYS-CH-3-SECT-2</td>
 506         </tr>
 507
 508         <tr>
 509           <td>sect2 (B-head or sub section)</td>
 510           <td><i>prefix</i>-<i>CH/APP</i>-<i>num/letter</i>-SECT-<i>num</i>.<i>num</i></td>
 511           <td>MONKEYS-CH-3-SECT-2.4</td>
 512         </tr>
 513
 514         <tr>
 515           <td>figure</td>
 516           <td><i>prefix</i>-<i>CH/APP</i>-<i>num/letter</i>-FIG-<i>num</i></td>
 517           <td>MONKEYS-PREF-FIG-24</td>
 518         </tr>
 519
 520         <tr>
 521           <td>table</td>
 522           <td><i>prefix</i>-<i>CH/APP</i>-<i>num/letter</i>-TABLE-<i>num</i></td>
 523           <td>MONKEYS-APP-C-TABLE-11</td>
 524         </tr>
 525
 526         <tr>
 527           <td>example</td>
 528           <td><i>prefix</i>-<i>CH/APP</i>-<i>num/letter</i>-EX-<i>num</i></td>
 529           <td>MONKEYS-CH-12-EX-8</td>
 530         </tr>
 531
 532         <tr>
 533           <td>indexterm</td>
 534           <td><i>prefix</i>-<i>terms</i></td>
 535           <td>MONKEYS-perilous-furballs</td>
 536         </tr>
 537       </table>
 538
 539       <p>
 540 The <i>prefix</i> is a short code you pick to
 541 represent your book in <tt>id</tt>s. It's not required, but
 542 we use it to eliminate any confusion when handling files separately,
 543 since there is nothing within each file to indicate which book it came
 544 from.
 545       </p>
 546
 547       <p>
 548 The number for any element type starts at 1.  For elements inside
 549 chapters or appendixes, the numbering is starts within the
 550 chapter/appendix and continues to increment until the very end. An
 551 exception is for sections, whose numbering resets to 1 with each
 552 parent section or chapter.
 553       </p>
 554     </div>
 555
 556
 557     <a name="section-1.2"></a>
 558 <div class="ssection">
 559       <h3 class="sstitle">5.2. The master book file</h3>
 560
 561       <p>
 562 This file is the root of the whole book. Therefore, it contains the
 563 important XML declaration at the top, as well as a directive to
 564 declare the DTD. You would modify the second string value to the
 565 actual location of the DTD on your system. Next are entity
 566 declarations. These can only reside inside the square brackets. First
 567 are the entities that point to the files in your book. Then follow any
 568 special entities you want to define. The
 569 <tt>&lt;bookinfo&gt;</tt> element will later be filled with
 570 metadata, but for now it can be left empty. Finally, the entity
 571 references for book files are listed in order at the bottom.
 572       </p>
 573
 574       <div class="example">
 575         <h4 class="exampletitle">Example 1. Contents of <i>book.xml</i>
 576 </h4>
 577         <div class="programlisting">
 578 <pre>&lt;!DOCTYPE book PUBLIC
 579     "-//ORA//DBLITE 1.1//EN" "/usr/local/prod/sgml/dblite/new.dtd"
 580 [
 581
 582 &lt;!-- Declare external entities --&gt;
 583
 584 &lt;!ENTITY ch00     SYSTEM "ch00.xml"&gt;
 585 &lt;!ENTITY ch01     SYSTEM "ch01.xml"&gt;
 586 &lt;!ENTITY ch02     SYSTEM "ch02.xml"&gt;
 587 &lt;!ENTITY ch03     SYSTEM "ch03.xml"&gt;
 588 &lt;!ENTITY ch04     SYSTEM "ch04.xml"&gt;
 589 &lt;!ENTITY ch05     SYSTEM "ch05.xml"&gt;
 590 &lt;!ENTITY ch06     SYSTEM "ch06.xml"&gt;
 591 &lt;!ENTITY ch07     SYSTEM "ch07.xml"&gt;
 592 &lt;!ENTITY ch08     SYSTEM "ch08.xml"&gt;
 593 &lt;!ENTITY ch09     SYSTEM "ch09.xml"&gt;
 594 &lt;!ENTITY part1    SYSTEM "part1.xml"&gt;
 595 &lt;!ENTITY part2    SYSTEM "part2.xml"&gt;
 596 &lt;!ENTITY appa     SYSTEM "appa.xml"&gt;
 597 &lt;!ENTITY appb     SYSTEM "appb.xml"&gt;
 598 &lt;!ENTITY appc     SYSTEM "appc.xml"&gt;
 599 &lt;!ENTITY copy     SYSTEM "copy.xml"&gt;
 600 &lt;!ENTITY colo     SYSTEM "colo.xml"&gt;
 601
 602 &lt;!-- Declare text entities --&gt;
 603
 604 &lt;!ENTITY ascii    "&lt;acronym&gt;ASCII&lt;/acronym&gt;"&gt;
 605 &lt;!ENTITY html     "&lt;acronym&gt;HTML&lt;/acronym&gt;"&gt;
 606 &lt;!ENTITY sgml     "&lt;acronym&gt;SGML&lt;/acronym&gt;"&gt;
 607 &lt;!ENTITY xml      "&lt;acronym&gt;XML&lt;/acronym&gt;"&gt;
 608 &lt;!ENTITY w3url    "http://www.w3.org/"&gt;
 609
 610 ]&gt;
 611
 612 &lt;book&gt;
 613   &lt;title&gt;Learning &amp;xml;&lt;/title&gt;
 614
 615   &lt;bookinfo&gt;
 616
 617       &lt;!-- Marketing information and metadata,
 618               to be filled out in production. --&gt;
 619
 620   &lt;/bookinfo&gt;
 621
 622   &lt;!-- External entity refs --&gt;
 623
 624   &amp;ch00;
 625   &amp;copy;
 626   &amp;part1;
 627   &amp;part2;
 628   &amp;colo;
 629
 630 &lt;/book&gt;</pre>
 631 </div>
 632       </div>
 633
 634
 635         <p>
 636 In this example, none of the external entity references for chapters
 637 and appendixes appear in <i>book.xml</i>. We will see
 638 later that the chapters and appendixes are references only inside the
 639 files for the parts in which they belong, to maintain the proper
 640 hierarchy.
 641         </p>
 642
 643     </div>
 644
 645     <a name="section-1.3"></a>
 646 <div class="ssection">
 647       <h3 class="sstitle">5.3. The preface</h3>
 648
 649       <p>
 650 The preface is contained entirely within one file called
 651 <i>ch00.xml</i>.  It looks like this:
 652       </p>
 653
 654       <div class="example">
 655         <h4 class="exampletitle">Example 1. Contents of <i>ch00.xml</i>
 656 </h4>
 657         <div class="programlisting">
 658 <pre>&lt;preface id="XML-PREF"&gt;
 659   &lt;title&gt;Preface&lt;/title&gt;
 660
 661           &lt;!-- preamble (no A-head) --&gt;
 662
 663   &lt;simplesect&gt;
 664     &lt;para&gt;Welcome to &amp;xml;. Put on your geek hat, twirl the
 665     propeller, and get ready for a wacky ride!&lt;/para&gt;
 666
 667     &lt;para&gt;Blah blah blah blah blah...&lt;/para&gt;
 668   &lt;/simplesect&gt;
 669
 670           &lt;!-- the first section (A-head) --&gt;
 671
 672   &lt;sect1 id="XML-PREF-SECT-1"&gt;
 673     &lt;title&gt;Why &amp;xml;?&lt;/title&gt;
 674
 675     &lt;para&gt;&amp;xml; is a markup language development kit.  Blah blah
 676     blah...&lt;/para&gt;
 677
 678     &lt;para&gt;Blah blah blah blah blah...&lt;/para&gt;
 679   &lt;/sect1&gt;
 680
 681           &lt;!-- the second section --&gt;
 682
 683   &lt;sect1 id="XML-PREF-SECT-2"&gt;
 684     &lt;title&gt;What's inside&lt;/title&gt;
 685
 686     &lt;para&gt;&lt;xref linkend="XML-PART-1"/&gt; starts off with an
 687     introduction to some basic &amp;xml; areas that any author ought to be
 688     familiar with. Blah blah blah...&lt;/para&gt;
 689   &lt;/sect1&gt;
 690
 691           &lt;!-- Other sections... --&gt;
 692
 693 &lt;/preface&gt;</pre>
 694 </div>
 695       </div>
 696     </div>
 697
 698
 699     <a name="section-1.4"></a>
 700 <div class="ssection">
 701       <h3 class="sstitle">5.4. Part Pages</h3>
 702       <p>
 703 A <tt>&lt;part&gt;</tt> is an element that contains chapters
 704 or appendixes, dividing the book into major categories. At O'Reilly,
 705 we separate chapters into different files by convention, so the part
 706 is spread across several files. The front page of the part doesn't
 707 belong in any particular chapter, so it gets its own file:
 708       </p>
 709
 710       <div class="example">
 711         <h4 class="exampletitle">Example 1. Contents of <i>part1.xml</i>
 712 </h4>
 713         <div class="programlisting">
 714 <pre>&lt;part id="XML-PART-1"&gt;
 715   &lt;title&gt;Basic Concepts&lt;/title&gt;
 716
 717   &lt;partintro&gt;
 718     &lt;para&gt;In this part of the book, we focus on easy material.
 719     Blah blah blah...&lt;/para&gt;
 720   &lt;/partintro&gt;
 721
 722   &lt;!-- External entity references --&gt;
 723
 724   &amp;ch01;
 725   &amp;ch02;
 726   &amp;ch03;
 727   &amp;ch04;
 728
 729 &lt;/part&gt;</pre>
 730 </div>
 731       </div>
 732
 733       <p>
 734 No entity declarations are necessary because they were made in the
 735 <i>book.xml</i> file and carried over. The
 736 <tt>&lt;partinfo&gt;</tt> is an intermediate-level division
 737 that contains all elements between the
 738 <tt>&lt;title&gt;</tt> and the chapter-level children of the
 739 <tt>&lt;part&gt;</tt>.
 740       </p>
 741     </div>
 742
 743
 744     <a name="section-1.5"></a>
 745 <div class="ssection">
 746       <h3 class="sstitle">5.5. The Chapter</h3>
 747
 748       <p>
 749 Chapters follow the same basic pattern as a preface:
 750       </p>
 751
 752       <div class="example">
 753         <h4 class="exampletitle">Example 1. Contents of ch01.xml</h4>
 754         <div class="programlisting">
 755 <pre>&lt;chapter id="XML-CH-1"&gt;
 756   &lt;title&gt;&amp;xml; Basics&lt;/title&gt;
 757
 758           &lt;!-- preamble (no A-head) --&gt;
 759
 760   &lt;simplesect&gt;
 761     &lt;para&gt;In this chapter, we cover the
 762     fundamentals of markup and document structure.  Blah blah blah...&lt;/para&gt;
 763
 764     &lt;para&gt;Blah blah blah blah blah...&lt;/para&gt;
 765   &lt;/simplesect&gt;
 766
 767           &lt;!-- the first section (A-head) --&gt;
 768
 769   &lt;sect1 id="XML-CH-1-SECT-1"&gt;
 770     &lt;title&gt;What is Markup?&lt;/title&gt;
 771
 772     &lt;para&gt;There's a lot of stuff you can
 773     do with markup.  Blah blah blah...&lt;/para&gt;
 774
 775     &lt;para&gt;Blah blah blah blah blah...&lt;/para&gt;
 776   &lt;/sect1&gt;
 777
 778           &lt;!-- the second section --&gt;
 779
 780   &lt;sect1 id="XML-CH-1-SECT-2"&gt;
 781     &lt;title&gt;A historical perspective&lt;/title&gt;
 782
 783     &lt;para&gt;It's useful to see how &amp;xml;
 784     fits in the long line of markup languages. Blah blah blah...&lt;/para&gt;
 785
 786           &lt;!-- a sub-section --&gt;
 787
 788     &lt;sect2 id="XML-CH-1-SECT-2.1&gt;
 789       &lt;title&gt;The earliest days&lt;/title&gt;
 790
 791       &lt;para&gt;Back in the olden days of
 792       digital text, work was very hard. We had to flip knife switches
 793       to program computers and &amp;ascii;
 794       was the only character set in town. Blah blah blah...&lt;/para&gt;
 795
 796       &lt;para&gt;Blah blah blah blah blah...&lt;/para&gt;
 797
 798           &lt;!-- a sub-sub-section --&gt;
 799
 800       &lt;sect3 id="XML-CH-1-SECT-2.1.1&gt;
 801         &lt;title&gt;How I had to walk to work barefoot, uphill
 802         both ways&lt;/title&gt;
 803
 804         &lt;para&gt;Blah blah blah blah blah...&lt;/para&gt;
 805
 806         &lt;figure id="XML-CH-1-FIG-1"&gt;
 807           &lt;title&gt;Picture of my blistered feet&lt;/title&gt;
 808           &lt;graphic fileref="figs/soretoes.gif"/&gt;
 809         &lt;/figure&gt;
 810
 811       &lt;/sect3&gt;
 812     &lt;/sect2&gt;
 813   &lt;/sect1&gt;
 814
 815           &lt;!-- Other sections... --&gt;
 816
 817 &lt;/chapter&gt;</pre>
 818 </div>
 819       </div>
 820
 821       <p>
 822 The hierarchy of sections is important. A
 823 <tt>&lt;sect1&gt;</tt> contains
 824 <tt>&lt;sect2&gt;</tt>s, which can contain
 825 <tt>&lt;sect3&gt;</tt>s, etc. Also important: we now require
 826 that elements after the chapter <tt>&lt;title&gt;</tt>, but
 827 before the first <tt>&lt;sect1&gt;</tt>, be enclosed in a
 828 <tt>&lt;simplesect&gt;</tt>.
 829       </p>
 830
 831       <p>
 832 Appendixes are pretty much the same as chapters, except that they are
 833 contained in an <tt>&lt;appendix&gt;</tt> element instead of
 834 a <tt>&lt;chapter&gt;</tt>, and the <tt>id</tt>
 835 format is different.
 836       </p>
 837     </div>
 838
 839
 840     <a name="section-1.6"></a>
 841 <div class="ssection">
 842       <h3 class="sstitle">5.6. Glossary</h3>
 843
 844       <p>
 845 A glossary is a collection of definitions for terms used in the
 846 book. A <tt>&lt;glossary&gt;</tt> element surrounds the
 847 whole thing, and is usually at the same level as a chapter.  Each
 848 definition is contained in a <tt>&lt;glossentry&gt;</tt>
 849 element with one <tt>&lt;glossentry&gt;</tt>,
 850 containing the term being defined, and an optional (if there is a
 851 see-also, for example) <tt>&lt;glossdef&gt;</tt>, containing
 852 the definition. It can also contain any number of
 853 <tt>&lt;glosssee&gt;</tt> and
 854 <tt>&lt;glossseealso&gt;</tt> elements, which redirect the
 855 reader's attention to another term. Stylistically, a
 856 <tt>&lt;glossentry&gt;</tt> should not contain both a
 857 <tt>&lt;glossdef&gt;</tt> and
 858 <tt>&lt;glosssee&gt;</tt>, but a
 859 <tt>&lt;glossdef&gt;</tt> and
 860 <tt>&lt;glossseealso&gt;</tt> are okay.
 861       </p>
 862
 863       <p>
 864 A glossary looks like this:
 865       </p>
 866
 867       <div class="example">
 868         <h4 class="exampletitle">Example 1. Contents of gloss.xml</h4>
 869         <div class="programlisting">
 870 <pre>&lt;glossary id="the-glossary"&gt;
 871
 872   &lt;!-- SECTION: XML-SPECIFIC TERMS --&gt;
 873
 874   &lt;glossdiv&gt;
 875     &lt;title&gt;XML Terms&lt;/title&gt;
 876     &lt;glossentry&gt;
 877       &lt;glossterm&gt;absolute location term&lt;/glossterm&gt;
 878       &lt;glossdef&gt;
 879         &lt;para&gt;A term that completely identifies the location of a
 880           resource via XPointer. A unique ID attribute assigned to an
 881           element can be used as an absolute location
 882           term.&lt;/para&gt;
 883       &lt;/glossdef&gt;
 884       &lt;glossseealso&gt;relative location term&lt;/glossseealso&gt;
 885       &lt;glossseealso&gt;XPath&lt;/glossseealso&gt;
 886       &lt;glossseealso&gt;XPointer&lt;/glossseealso&gt;
 887     &lt;/glossentry&gt;
 888
 889     &lt;glossentry&gt;
 890       &lt;glossterm&gt;actuation&lt;/glossterm&gt;
 891       &lt;glossdef&gt;
 892         &lt;para&gt;How a link in a document is triggered. For example, a
 893           link to an imported graphic automatically includes a graphic
 894           in the document, and a link to a URL resource requires a
 895           signal from a human.&lt;/para&gt;
 896       &lt;/glossdef&gt;
 897     &lt;/glossentry&gt;
 898   &lt;/glossdiv&gt;
 899
 900   &lt;!-- SECTION: OTHER TERMS --&gt;
 901
 902   &lt;glossdiv&gt;
 903     &lt;title&gt;Other Terms&lt;/title&gt;
 904     &lt;glossentry&gt;
 905       &lt;glossterm&gt;albatross&lt;glossterm&gt;
 906       &lt;glosssee&gt;birds&lt;/glosssee&gt;
 907     &lt;/glossentry&gt;
 908   &lt;/glossdiv&gt;
 909 &lt;/glossary&gt;</pre>
 910 </div>
 911       </div>
 912     </div>
 913
 914
 915     <a name="section-1.7"></a>
 916 <div class="ssection">
 917       <h3 class="sstitle">5.7. Bibliography</h3>
 918
 919       <p>Coming soon...</p>
 920
 921     </div>
 922   </div>
 923
 924
 925
 926
 927   <a name="section-6"></a>
 928 <div class="section">
 929     <h2 class="stitle">6. Block elements</h2>
 930
 931     <p>
 932 A block element is any element that starts a
 933 new line when formatted and contains inline elements. We have seen
 934 three already: <tt>&lt;para&gt;</tt>,
 935 <tt>&lt;title&gt;</tt>, and
 936 <tt>&lt;figure&gt;</tt>. Following is a table of block
 937 elements with examples:
 938     </p>
 939
 940     <table border="1">
 941       <h4 class="exampletitle">Table 1. Common block elements</h4>
 942       <tr>
 943         <th>element</th>
 944         <th>purpose</th>
 945         <th>example</th>
 946       </tr>
 947
 948       <tr>
 949         <td><tt>&lt;para&gt;</tt></td>
 950         <td>Paragraph.</td>
 951         <td>
 952           <div class="programlisting">
 953 <pre>&lt;para&gt;The quick, brown fox jumped over the lazy
 954 dog. The quick, brown fox jumped over the lazy dog.
 955 The quick, brown fox jumped over the lazy dog.&lt;/para&gt;</pre>
 956 </div>
 957         </td>
 958       </tr>
 959
 960       <tr>
 961         <td><tt>&lt;title&gt;</tt></td>
 962         <td>Title.</td>
 963         <td>
 964           <div class="programlisting">
 965 <pre>&lt;title&gt;The Benefits of Laughter&lt;/title&gt;</pre>
 966 </div>
 967         </td>
 968       </tr>
 969
 970       <tr>
 971         <td><tt>&lt;remark&gt;</tt></td>
 972         <td>
 973           <p>
 974 Comment that is not meant for the audience, and outside of the
 975 flow of text. Usually, a communication between the author, editor,
 976 reviewers, copyeditors, etc.
 977           </p>
 978         </td>
 979         <td>
 980           <div class="programlisting">
 981 <pre>&lt;remark&gt;This section is too short
 982 and needs more examples. [Ellen]&lt;/remark&gt;</pre>
 983 </div>
 984         </td>
 985       </tr>
 986
 987       <tr>
 988         <td><tt>&lt;blockquote&gt;</tt></td>
 989         <td>Quotation.</td>
 990         <td>
 991           <div class="programlisting">
 992 <pre>&lt;blockquote&gt;
 993   &lt;para&gt;"They who can give up essential
 994   liberty to purchase a little temporary
 995   safety, deserve neither liberty nor safety,"
 996   spat Ben Franklin.&lt;/para&gt;
 997   &lt;para&gt;"Yes," replied Mark Twain, "but
 998   loyalty to petrified opinion never broke a
 999   chain or freed a human soul."&lt;/para&gt;
1000 &lt;/blockquote&gt;</pre>
1001 </div>
1002         </td>
1003       </tr>
1004
1005       <tr>
1006         <td><tt>&lt;itemizedlist&gt;</tt></td>
1007         <td>
1008 <p>A list of items where order doesn't matter.</p>
1009 </td>
1010         <td>
1011 <div class="programlisting">
1012 <pre>&lt;itemizedlist&gt;
1013   &lt;listitem&gt;&lt;para&gt;dogsled&lt;/para&gt;&lt;/listitem&gt;
1014   &lt;listitem&gt;&lt;para&gt;hang-glider&lt;/para&gt;&lt;/listitem&gt;
1015   &lt;listitem&gt;&lt;para&gt;roller blades&lt;/para&gt;&lt;/listitem&gt;
1016 &lt;/itemizedlist&gt;</pre>
1017 </div>
1018         </td>
1019       </tr>
1020
1021       <tr>
1022         <td><tt>&lt;orderedlist&gt;</tt></td>
1023         <td>
1024           <p>
1025 A list of items where order is important.
1026           </p>
1027         </td>
1028         <td>
1029           <div class="programlisting">
1030 <pre>&lt;orderedlist&gt;
1031   &lt;listitem&gt;&lt;para&gt;Get a bowl.&lt;/para&gt;&lt;/listitem&gt;
1032   &lt;listitem&gt;&lt;para&gt;Pour the cereal.&lt;/para&gt;&lt;/listitem&gt;
1033   &lt;listitem&gt;&lt;para&gt;Add the milk.&lt;/para&gt;&lt;/listitem&gt;
1034   &lt;listitem&gt;&lt;para&gt;Eat.&lt;/para&gt;&lt;/listitem&gt;
1035 &lt;/orderedlist&gt;</pre>
1036 </div>
1037         </td>
1038       </tr>
1039
1040       <tr>
1041         <td><tt>&lt;variablelist&gt;</tt></td>
1042         <td>
1043           <p>
1044 A list that contains terms and their definitions.
1045           </p>
1046         </td>
1047         <td>
1048           <div class="programlisting">
1049 <pre>&lt;variablelist&gt;
1050   &lt;varlistentry&gt;&lt;term&gt;Snickers&lt;/term&gt;
1051   &lt;listitem&gt;&lt;para&gt;Peanuts in nougat
1052     covered in chocolate.&lt;/para&gt;&lt;/listitem&gt;&lt;/varlistentry&gt;
1053   &lt;varlistentry&gt;&lt;term&gt;Payday&lt;/term&gt;
1054   &lt;listitem&gt;&lt;para&gt;A peanut cluster cemented with caramel and
1055     delicious sticky stuff.&lt;/para&gt;&lt;/listitem&gt;&lt;/varlistentry&gt;
1056 &lt;/variablelist&gt;</pre>
1057 </div>
1058         </td>
1059       </tr>
1060
1061       <tr>
1062         <td><tt>&lt;programlisting&gt;</tt></td>
1063         <td>
1064           <p>
1065 A piece of computer code or example markup where whitespace and
1066 other formatting must be preserved.
1067           </p>
1068         </td>
1069         <td>
1070           <div class="programlisting">
1071 <pre>&lt;programlisting&gt;public void init(ServletConfig config)
1072                                      throws ServletException {
1073   super.init(config);
1074   String greeting = getInitParameter("greeting");
1075 }&lt;/programlisting&gt;</pre>
1076 </div>
1077         </td>
1078       </tr>
1079
1080       <tr>
1081         <td><tt>&lt;screen&gt;</tt></td>
1082         <td>
1083           <p>
1084 A representation of data displayed on a computer
1085 screen. (Whitespace and other formatting are preserved.)
1086           </p>
1087         </td>
1088         <td>
1089           <div class="programlisting">
1090 <pre>&lt;screen&gt;&amp;gt; ls -l
1091 total 6860
1092 -r--r--r-- 1 eray   ora  2570 Mar 27 19:38 BOOKFILES
1093 -rw-rw-r-- 1 eray   ora 13283 Mar 27 19:38 BOOKIDS
1094 -rw-rw-r-- 1 sierra ora  2692 Mar 28 14:43 Makefile
1095 drwxrwxr-x 2 jwizda ora   512 Aug 10 14:22 RCS/
1096 -rw-rw-r-- 1 jwizda ora    39 Jul 26 17:39 README&lt;/screen&gt;</pre>
1097 </div>
1098         </td>
1099       </tr>
1100
1101       <tr>
1102         <td><tt>&lt;literallayout&gt;</tt></td>
1103         <td>
1104           <p>
1105 Traditional text with special linebreaks to be preserved.
1106           </p>
1107         </td>
1108         <td>
1109           <div class="programlisting">
1110 <pre>&lt;literallayout&gt;to be yourself, in a world that
1111      tries,           night and day,       to make you
1112 just like everybody else, is to fight
1113  the greatest battle there ever is
1114  to fight,                and never stop fighting
1115    e. e. cummings&lt;/literallayout&gt;</pre>
1116 </div>
1117         </td>
1118       </tr>
1119
1120       <tr>
1121         <td><tt>&lt;figure&gt;</tt></td>
1122         <td>
1123           <p>
1124 A graphic with a title.
1125           </p>
1126         </td>
1127         <td>
1128           <div class="programlisting">
1129 <pre>&lt;figure id="FOO-APP-E-FIG-19"&gt;
1130   &lt;title&gt;The garden variety eggplant&lt;/title&gt;
1131   &lt;graphic fileref="figs/eggplant.eps"/&gt;
1132 &lt;/figure&gt;</pre>
1133 </div>
1134         </td>
1135       </tr>
1136
1137       <tr>
1138         <td><tt>&lt;example&gt;</tt></td>
1139         <td>
1140           <p>Anything that serves as an example and requires a
1141 title. (Use an &lt;informalexample&gt; if you don't need a
1142 title.)
1143           </p>
1144         </td>
1145         <td>
1146           <div class="programlisting">
1147 <pre>&lt;example id="BAZ-CH-14-EX-5"&gt;
1148   &lt;title&gt;Contents of the file
1149     &lt;filename&gt;blather.cfg&lt;/filename&gt;&lt;/title&gt;
1150   &lt;programlisting&gt;CATS    = -c/usr/local/prod/sgml/CATALOG
1151 DSLCAT  = -c/usr/local/sp/dsssl/catalog
1152 DECL    = /usr/local/sp/pubtext/xml.dcl
1153 SRCHURL = xsrch.htm
1154 STYLE   = dbwrap.dsl
1155 VALOPTS = -sv -wxml&lt;/programlisting&gt;
1156 &lt;/example&gt;</pre>
1157 </div>
1158         </td>
1159       </tr>
1160     </table>
1161   </div>
1162
1163
1164
1165
1166   <a name="section-7"></a>
1167 <div class="section">
1168     <h2 class="stitle">7. Inline elements</h2>
1169
1170     <p>
1171 In contrast to block elements, inline elements
1172 do not force a line break, but coexist peacefully with their siblings
1173 inside a block element. There are two basic types: those that contain
1174 data, and those that don't. The first group is used to label one or
1175 more words as a special kind of object, or deserving of special
1176 processing. Those in the second group function as markers in the text,
1177 anchoring a cross reference or marking some other kind of positional
1178 data. The following table lists inline elements and their
1179 function.
1180     </p>
1181
1182     <table border="1">
1183       <h4 class="exampletitle">Table 1. Inline Elements</h4>
1184       <tr>
1185         <th>element</th>
1186         <th>purpose</th>
1187         <th>example</th>
1188       </tr>
1189
1190       <tr>
1191         <td><tt>&lt;abbrev&gt;</tt></td>
1192         <td>An abbreviated term.</td>
1193         <td>
1194           <div class="programlisting">
1195 <pre>She's in &lt;abbrev&gt;bldg&lt;/abbrev 42.&gt;</pre>
1196 </div>
1197         </td>
1198       </tr>
1199
1200       <tr>
1201         <td><tt>&lt;accel&gt;</tt></td>
1202         <td>A shortcut.</td>
1203         <td>
1204           <div class="programlisting">
1205 <pre>Type &lt;accel&gt;Ctl-s&lt;/accel&gt; to search for
1206 a term.</pre>
1207 </div>
1208         </td>
1209       </tr>
1210
1211       <tr>
1212         <td><tt>&lt;acronym&gt;</tt></td>
1213         <td>
1214           <p>
1215 Mark text as being an acronym.
1216           </p>
1217         </td>
1218         <td>
1219           <div class="programlisting">
1220 <pre>&lt;acronym&gt;ASCII&lt;/acronym&gt;</pre>
1221 </div>
1222         </td>
1223       </tr>
1224
1225       <tr>
1226         <td><tt>&lt;action&gt;</tt></td>
1227         <td>
1228           <p>
1229 A user interface action like a mouse click.
1230           </p>
1231         </td>
1232         <td>
1233           <div class="programlisting">
1234 <pre>Click &lt;action&gt;mouse
1235 button-3&lt;/action&gt; for a pop-up menu.</pre>
1236 </div>
1237         </td>
1238       </tr>
1239
1240       <tr>
1241         <td><tt>&lt;application&gt;</tt></td>
1242         <td>
1243           <p>
1244 The name of a computer software program.</p>
1245 </td>
1246         <td>
1247           <div class="programlisting">
1248 <pre>We can convert any document written in
1249 &lt;application&lt;Microsoft Word&lt;/application&gt;.</pre>
1250 </div>
1251         </td>
1252       </tr>
1253
1254       <tr>
1255         <td><tt>&lt;citation&gt;</tt></td>
1256         <td>
1257           <p>
1258 The source of a quote or piece of information.
1259           </p>
1260         </td>
1261         <td>
1262           <div class="programlisting">
1263 <pre>&lt;citation&gt;Bill Gates&lt;/citation&gt;
1264 once said &lt;quote&gt;256 kB of RAM ought to be good enough
1265 for anybody.&lt;/quote&gt;</pre>
1266 </div>
1267         </td>
1268       </tr>
1269
1270       <tr>
1271         <td><tt>&lt;citetitle&gt;</tt></td>
1272         <td>
1273           <p>
1274 The name of a book or article.
1275           </p>
1276         </td>
1277         <td>
1278           <div class="programlisting">
1279 <pre>&lt;citetitle&gt;The Hobbit&lt;/citetitle&gt;</pre>
1280 </div>
1281         </td>
1282       </tr>
1283
1284       <tr>
1285         <td><tt>&lt;classname&gt;</tt></td>
1286         <td>
1287           <p>
1288 An identifier for a class in some programming
1289 language.
1290           </p>
1291         </td>
1292         <td>
1293           <div class="programlisting">
1294 <pre>The &lt;classname&gt;string&lt;/class&gt;
1295 class has six public methods.</pre>
1296 </div>
1297         </td>
1298       </tr>
1299
1300       <tr>
1301         <td><tt>&lt;classref&gt;</tt></td>
1302         <td>
1303           <p>
1304 A cross reference to a class, with special formatting such as
1305 displaying the class name. (Used mainly in Java books.)
1306           </p>
1307         </td>
1308         <td></td>
1309       </tr>
1310
1311       <tr>
1312         <td><tt>&lt;command&gt;</tt></td>
1313         <td>
1314           <p>
1315 Any command one would type in a computer terminal.
1316           </p>
1317         </td>
1318         <td>
1319           <div class="programlisting">
1320 <pre>To print the file to screen, use the
1321 &lt;command&gt;lpr&lt;/command&gt; command.</pre>
1322 </div>
1323         </td>
1324       </tr>
1325
1326       <tr>
1327         <td><tt>&lt;computeroutput&gt;</tt></td>
1328         <td>
1329           <p>
1330 Text that would be output by a computer program.
1331           </p>
1332         </td>
1333         <td>
1334           <div class="programlisting">
1335 <pre>When we run the script we get the result
1336 &lt;computeroutput&gt;file not found&lt;/computeroutput&gt;.</pre>
1337 </div>
1338         </td>
1339       </tr>
1340
1341       <tr>
1342         <td><tt>&lt;email&gt;</tt></td>
1343         <td>
1344           <p>
1345 An email address. (Note that there may be some conflict
1346 with the &lt;systemitem&gt; element.)
1347           </p>
1348         </td>
1349         <td>
1350           <div class="programlisting">
1351 <pre>Send questions to
1352 &lt;email&gt;tools@oreilly.com&lt;/email&gt;.</pre>
1353 </div>
1354         </td>
1355       </tr>
1356
1357       <tr>
1358         <td><tt>&lt;emphasis&gt;</tt></td>
1359         <td>
1360           <p>
1361 Give special emphasis to a word or phrase. Usually this
1362 formats as italic, but default formatting can be overridden with a
1363 <tt>role</tt> attribute such as
1364 <tt>role="bold"</tt>.
1365           </p>
1366         </td>
1367         <td>
1368 <div class="programlisting">
1369 <pre>This step is &lt;emphasis&gt;very&lt;/emphasis&gt; important</pre>
1370 </div>
1371         </td>
1372       </tr>
1373
1374       <tr>
1375         <td><tt>&lt;envar&gt;</tt></td>
1376         <td>An environment variable.</td>
1377         <td>
1378           <div class="programlisting">
1379 <pre>Set the variable &lt;envar&gt;EDITOR&lt;/envar&gt;
1380 to &lt;literal&gt;emacs&lt;/literal&gt;.</pre>
1381 </div>
1382         </td>
1383       </tr>
1384
1385       <tr>
1386         <td><tt>&lt;filename&gt;</tt></td>
1387         <td>Tags a word as being a filename.</td>
1388         <td>
1389           <div class="programlisting">
1390 <pre>Be sure to read
1391 &lt;filename&gt;readme.txt&lt;/filename&gt;.</pre>
1392 </div>
1393         </td>
1394       </tr>
1395
1396       <tr>
1397         <td><tt>&lt;firstterm&gt;</tt></td>
1398         <td>
1399           <p>
1400 The first time an important term is mentioned.
1401           </p>
1402         </td>
1403         <td>
1404           <div class="programlisting">
1405 <pre>A &lt;firstterm&gt;squib&lt;/firstterm&gt;
1406 is someone born to a wizard family but who can't do magic.</pre>
1407 </div>
1408         </td>
1409       </tr>
1410
1411       <tr>
1412         <td><tt>&lt;foreignphrase&gt;</tt></td>
1413         <td>Words from another language.</td>
1414         <td>
1415           <div class="programlisting">
1416 <pre>There's nothing wrong with borrowing code
1417 &lt;foreignphrase&gt;per se&lt;foreignphrase&gt;.</pre>
1418 </div>
1419         </td>
1420       </tr>
1421
1422       <tr>
1423         <td><tt>&lt;footnoteref&gt;</tt></td>
1424         <td>
1425           <p>
1426 A marker that imports a <tt>&lt;footnote&gt;</tt>
1427 where there would otherwise be a redundant footnote
1428 definition.
1429           </p>
1430         </td>
1431         <td>
1432           <div class="programlisting">
1433 <pre>The Eiffel Tower is huge&lt;footnote id="ABC-CH-4-FN-2"&gt;
1434 &lt;para&gt;Although, compared to a breadbox, any
1435 building is huge.&lt;/para&gt;&lt;/footnote&gt;. So is a redwood
1436 tree&lt;footnoteref linkend="ABC-CH-4-FN-2"&gt;.</pre>
1437 </div>
1438         </td>
1439       </tr>
1440
1441       <tr>
1442         <td><tt>&lt;graphic&gt;</tt></td>
1443         <td>
1444           <p>
1445 An icon or picture to be imported into the document.
1446           </p>
1447         </td>
1448         <td>
1449           <div class="programlisting">
1450 <pre>Examples marked with a disk icon
1451 &lt;graphic fileref="figs/icon.eps"&gt; are on
1452 the companion disk.</pre>
1453 </div>
1454         </td>
1455       </tr>
1456
1457       <tr>
1458         <td><tt>&lt;function&gt;</tt></td>
1459         <td>
1460           <p>
1461 The name of a function, method, or subroutine.
1462           </p>
1463         </td>
1464         <td>
1465 <div class="programlisting">
1466 <pre>The function
1467 &lt;function&gt;alpha_sort&lt;/function&gt; can be made more
1468 efficient.</pre>
1469 </div>
1470         </td>
1471       </tr>
1472
1473       <tr>
1474         <td><tt>&lt;guibutton&gt;</tt></td>
1475         <td>
1476           <p>
1477 A clickable control (e.g. a button) in a graphical interface.
1478           </p>
1479         </td>
1480         <td>
1481 <div class="programlisting">
1482 <pre>Select the
1483 &lt;guibutton&gt;print&lt;guibutton&gt; button to get
1484 hardcopy.</pre>
1485 </div>
1486         </td>
1487       </tr>
1488
1489       <tr>
1490         <td><tt>&lt;guimenu&gt;</tt></td>
1491         <td>
1492           <p>
1493 A menu or submenu in a graphical interface.
1494           </p>
1495         </td>
1496         <td>
1497           <div class="programlisting">
1498 <pre>Close the program by selecting
1499 &lt;guimenuitem&gt;exit&lt;/guimenuitem&gt; from the
1500 &lt;guimenu&gt;file&lt;/guimenu&gt; menu.</pre>
1501 </div>
1502         </td>
1503       </tr>
1504
1505       <tr>
1506         <td><tt>&lt;guimenuitem&gt;</tt></td>
1507         <td>
1508           <p>
1509 An item in a menu or submenu in a graphical interface.
1510           </p>
1511         </td>
1512         <td>
1513           <div class="programlisting">
1514 <pre>Close the program by selecting
1515 &lt;guimenuitem&gt;exit&lt;/guimenuitem&gt; from the
1516 &lt;guimenu&gt;file&lt;/guimenu&gt; menu.</pre>
1517 </div>
1518         </td>
1519       </tr>
1520
1521       <tr>
1522         <td><tt>&lt;keycap&gt;</tt></td>
1523         <td>
1524           <p>
1525 A character to be represented as a key on a keyboard.
1526           </p>
1527         </td>
1528         <td>
1529           <div class="programlisting">
1530 <pre>Pressing &lt;keycap&gt;s&lt;/keycap&gt;
1531 will save the buffer to a file.</pre>
1532 </div>
1533         </td>
1534       </tr>
1535
1536       <tr>
1537         <td><tt>&lt;keysym&gt;</tt></td>
1538         <td></td>
1539         <td></td>
1540       </tr>
1541
1542       <tr>
1543         <td><tt>&lt;lineannotation&gt;</tt></td>
1544         <td>
1545           <p>
1546 An annotation appearing inside a <tt>&lt;screen&gt;</tt> or
1547 <tt>&lt;programlisting&gt;</tt>.
1548           </p>
1549         </td>
1550         <td>
1551           <div class="programlisting">
1552 <pre>for( int $i=0; $i&lt;10; $i++ ) {
1553   &lt;lineannotation&gt;body of loop&lt;/lineannotation&gt;
1554 }</pre>
1555 </div>
1556         </td>
1557       </tr>
1558
1559       <tr>
1560         <td><tt>&lt;literal&gt;</tt></td>
1561         <td>
1562           <p>
1563 A token or string that is part of a computer program or
1564 script, which should be formatted in constant width.
1565           </p>
1566         </td>
1567         <td>
1568           <div class="programlisting">
1569 <pre>If the parameter's value is
1570 &lt;literal&gt;YELLOW&lt;/literal&gt; your subroutine will
1571 explode.</pre>
1572 </div>
1573         </td>
1574       </tr>
1575
1576       <tr>
1577         <td><tt>&lt;option&gt;</tt></td>
1578         <td>
1579           <p>
1580 A code to apply an optional parameter to a command,
1581 program, or function.
1582           </p>
1583         </td>
1584         <td>
1585           <div class="programlisting">
1586 <pre>The command synopsis is
1587 &lt;command&gt;rm &lt;option&gt;-i&lt;/option&gt; *.txt&lt;/command&gt;.</pre>
1588 </div>
1589         </td>
1590       </tr>
1591
1592       <tr>
1593         <td><tt>&lt;optional&gt;</tt></td>
1594         <td>
1595           <p>
1596 Designates some text as an optional item.
1597           </p>
1598         </td>
1599         <td>
1600           <div class="programlisting">
1601 <pre>The stylesheet specification is optional:
1602 &lt;command&gt;formatfiles &lt;optional&gt;stylesheet&lt;/optional&gt;
1603 in.xml&lt;command&gt;.</pre>
1604 </div>
1605         </td>
1606       </tr>
1607
1608       <tr>
1609         <td><tt>&lt;parameter&gt;</tt></td>
1610         <td>
1611           <p>
1612 The name of a parameter for a function, method, or subroutine.
1613           </p>
1614         </td>
1615         <td>
1616           <div class="programlisting">
1617 <pre>In the &lt;function&gt;factorial&lt;/function&gt;
1618 function, there is only one parameter,
1619 &lt;parameter&gt;num&lt;/parameter&gt;.</pre>
1620 </div>
1621         </td>
1622       </tr>
1623
1624       <tr>
1625         <td><tt>&lt;prompt&gt;</tt></td>
1626         <td>
1627           <p>
1628             A word meant to appear as a prompt in a computer display.
1629           </p>
1630         </td>
1631         <td>
1632           <div class="programlisting">
1633 <pre>At the prompt
1634 &lt;prompt&gt;Data?&lt;/prompt&gt;, type in your age in
1635 hexadecimal.</pre>
1636 </div>
1637         </td>
1638       </tr>
1639
1640       <tr>
1641         <td><tt>&lt;quote&gt;</tt></td>
1642         <td>
1643           <p>
1644 Quoted text.
1645           </p>
1646         </td>
1647         <td>
1648           <div class="programlisting">
1649 <pre>Our motto is
1650 &lt;foreignphrase&gt;Caveat Emptor&lt;/foreignphrase&gt;,
1651 which means &lt;quote&gt;we hope you like it!&lt;/quote&gt;</pre>
1652 </div>
1653         </td>
1654       </tr>
1655
1656       <tr>
1657         <td><tt>&lt;replaceable&gt;</tt></td>
1658         <td>
1659           <p>
1660 Marks the data as a replaceable item, a value to be filled in.
1661           </p>
1662         </td>
1663         <td>
1664           <div class="programlisting">
1665 <pre>...where &lt;replaceable&gt;w&lt;/replaceable&gt;
1666 is the width.</pre>
1667 </div>
1668         </td>
1669       </tr>
1670
1671       <tr>
1672         <td><tt>&lt;returnvalue&gt;</tt></td>
1673         <td>
1674           <p>
1675 Data that has been returned from a program or function.
1676           </p>
1677         </td>
1678         <td>
1679           <div class="programlisting">
1680 <pre>The &lt;function&gt;reverse_string&lt;/function&gt;
1681 gives the value &lt;returnvalue&gt;tesolcmoorb&lt;/returnvalue&gt;.</pre>
1682 </div>
1683         </td>
1684       </tr>
1685
1686       <tr>
1687         <td><tt>&lt;sgmltag&gt;</tt></td>
1688         <td>
1689           <p>
1690 The name of an SGML or XML element.
1691           </p>
1692         </td>
1693         <td>
1694           <div class="programlisting">
1695 <pre>The &lt;sgmltag&gt;P&lt;/sgmltag&gt;
1696 element adds space above and below.</pre>
1697 </div>
1698         </td>
1699       </tr>
1700
1701       <tr>
1702         <td><tt>&lt;structfield&gt;</tt></td>
1703         <td>
1704           <p>
1705 The name of a field in a data structure.
1706           </p>
1707         </td>
1708         <td>
1709           <div class="programlisting">
1710 <pre>&lt;structfield&gt;name&lt;/structfield&gt;
1711 is a fixed array of bytes.</pre>
1712 </div>
1713         </td>
1714       </tr>
1715
1716       <tr>
1717         <td><tt>&lt;structname&gt;</tt></td>
1718         <td>
1719           <p>
1720 The name of a data structure.
1721           </p>
1722         </td>
1723         <td>
1724           <div class="programlisting">
1725 <pre>To add a record, we must create a new
1726 &lt;structname&gt;PartStruct&lt;/structname&gt;.</pre>
1727 </div>
1728         </td>
1729       </tr>
1730
1731       <tr>
1732         <td><tt>&lt;subscript&gt;</tt></td>
1733         <td>
1734           <p>
1735 Text that should be rendered in subscript (smaller and
1736 below the baseline).
1737           </p>
1738         </td>
1739         <td>
1740           <div class="programlisting">
1741 <pre>The molecule
1742 H&lt;subscript&gt;2&lt;/subscript&gt;O has many strange
1743 properties.</pre>
1744 </div>
1745         </td>
1746       </tr>
1747
1748       <tr>
1749         <td><tt>&lt;superscript&gt;</tt></td>
1750         <td>
1751           <p>
1752 Text that should be rendered in superscript (smaller and
1753 above the midline).
1754           </p>
1755         </td>
1756         <td>
1757           <div class="programlisting">
1758 <pre>Einstein revolutionized physics with
1759 the simple equation E=MC&lt;superscript&gt;2&lt;/superscript&gt;</pre>
1760 </div>
1761         </td>
1762       </tr>
1763
1764       <tr>
1765         <td><tt>&lt;symbol&gt;</tt></td>
1766         <td>
1767           <p>A special symbol or token.</p>
1768         </td>
1769         <td>
1770           <div class="programlisting">
1771 <pre>The mutant gene &lt;symbol&gt;BLu-6&lt;/symbol&gt;
1772 is responsible for Smurfs' vivid azure hue.</pre>
1773 </div>
1774         </td>
1775       </tr>
1776
1777       <tr>
1778         <td><tt>&lt;systemitem&gt;</tt></td>
1779         <td>
1780           <p>
1781 Designates data as a special item having to do with
1782 computers or networks. Most common use is to encode a
1783 URL.
1784           </p>
1785         </td>
1786         <td>
1787           <div class="programlisting">
1788 <pre>&lt;systemitem class="url"&gt;http://www.oreilly.com&lt;/systemitem&gt;</pre>
1789 </div>
1790         </td>
1791       </tr>
1792
1793       <tr>
1794         <td><tt>&lt;type&gt;</tt></td>
1795         <td>
1796           <p>A variable or constant data type.</p>
1797         </td>
1798         <td>
1799           <div class="programlisting">
1800 <pre>The function returns a value of type
1801 &lt;type&gt;boolean&lt;/type&gt;.</pre>
1802 </div>
1803         </td>
1804       </tr>
1805
1806       <tr>
1807         <td><tt>&lt;userinput&gt;</tt></td>
1808         <td>
1809           <p>
1810 Text entered by a human into a computer terminal.
1811           </p>
1812         </td>
1813         <td>
1814           <div class="programlisting">
1815 <pre>At the command line, type
1816 &lt;userinput&gt;telnet bubba.beerguzzlin.org&lt;/userinput&gt;</pre>
1817 </div>
1818         </td>
1819       </tr>
1820
1821       <tr>
1822         <td><tt>&lt;wordasword&gt;</tt></td>
1823         <td>
1824           <p>A word used as an example.</p>
1825         </td>
1826         <td>
1827           <div class="programlisting">
1828 <pre>By &lt;wordasword&gt;snake&lt;/wordasword&gt;,
1829 I mean &lt;quote&gt;dirty, stinkin' varmint&lt;/quote&gt;.</pre>
1830 </div>
1831         </td>
1832       </tr>
1833
1834       <tr>
1835         <td><tt>&lt;xref&gt;</tt></td>
1836         <td>
1837           <p>
1838 A cross reference to some element in the book. The
1839 required <tt>linkend</tt> attribute contains the
1840 <tt>id</tt> of the element being referenced.
1841           </p>
1842         </td>
1843         <td>
1844           <div class="programlisting">
1845 <pre>For more information, refer to
1846 &lt;xref linkend="XYZ-CH-4"/&gt;.</pre>
1847 </div>
1848         </td>
1849       </tr>
1850     </table>
1851   </div>
1852
1853
1854
1855
1856   <a name="section-8"></a>
1857 <div class="section">
1858     <h2 class="stitle">8. Tables</h2>
1859
1860     <p>
1861 The tables used in DocBook Lite are a slimmed-down version of the CALS
1862 table model, a popular markup format for tables. There are two outer
1863 elements for tables: <tt>&lt;table&gt;</tt>, which requires
1864 a title, and <tt>&lt;informaltable&gt;</tt>, which does not.
1865 These elements contain a <tt>&lt;tgroup&gt;</tt> element
1866 with an attribute <tt>cols</tt> that specifies the number of
1867 columns in the table.
1868     </p>
1869
1870     <p>
1871 The table has a head, body, and foot, contained in
1872 <tt>&lt;thead&gt;</tt>, <tt>&lt;tbody&gt;</tt>,
1873 and <tt>&lt;tfoot&gt;</tt> elements, respectively. Only the
1874 body is required. The head and body contain a set of rows, each a
1875 <tt>&lt;row&gt;</tt> element. The foot contains text that
1876 will appear just below the table, usually within the lines.
1877     </p>
1878
1879     <p>
1880 A <tt>&lt;row&gt;</tt> element contains some number of
1881 <tt>&lt;entry&gt;</tt>s, each corresponding to a table
1882 cell. The entry may either contain mixed content text, or a block
1883 element such as a paragraph. The following is an example of a simple
1884 titled table:
1885     </p>
1886
1887     <div class="programlisting">
1888 <pre>&lt;table id="ABC-CH-1-TABLE-5"&gt;
1889   &lt;title&gt;States and Their Capitals&lt;/title&gt;
1890   &lt;tgroup cols="2"&gt;
1891     &lt;thead&gt;
1892       &lt;row&gt;
1893         &lt;entry&gt;State&lt;/entry&gt;
1894         &lt;entry&gt;Capital&lt;/entry&gt;
1895       &lt;/row&gt;
1896     &lt;/thead&gt;
1897     &lt;tbody&gt;
1898       &lt;row&gt;
1899         &lt;entry&gt;New York&lt;/entry&gt;
1900         &lt;entry&gt;Albany&lt;/entry&gt;
1901       &lt;/row&gt;
1902       &lt;row&gt;
1903         &lt;entry&gt;Massachusetts&lt;/entry&gt;
1904         &lt;entry&gt;Boston&lt;/entry&gt;
1905       &lt;/row&gt;
1906       &lt;row&gt;
1907         &lt;entry&gt;Hawaii&lt;/entry&gt;
1908         &lt;entry&gt;Honalulu&lt;/entry&gt;
1909       &lt;/row&gt;
1910     &lt;/tbody&gt;
1911   &lt;/tgroup&gt;
1912 &lt;/table&gt;</pre>
1913 </div>
1914
1915     <p>
1916 To span a row, add to the <tt>&lt;entry&gt;</tt>
1917 element an attribute <tt>morerows="N"</tt>, where N is the
1918 number of rows to span beyond the current row. For example, to make an
1919 entry that spans 3 rows, use <tt>morerows="2"</tt>. For each
1920 of the following rows that are spanned, leave out an
1921 <tt>&lt;entry&gt;</tt> element, since the spanning cell will
1922 inhabit that space.
1923     </p>
1924
1925     <p>
1926 To span columns, it's a bit more complicated (we didn't try to fix the
1927 weird CALS way of doing it). First, you have to name the columns.
1928 Second, you need to create named spans. Finally, you reference the
1929 spans within the table cells. Here's an example:
1930     </p>
1931
1932     <div class="programlisting">
1933 <pre>&lt;informaltable&gt;
1934   &lt;tgroup cols="3"&gt;
1935     &lt;colspec colnum="1" colname="c1"&gt;
1936     &lt;colspec colnum="3" colname="c3"&gt;
1937     &lt;spanspec spanname="span13" namest="c1" nameend="c3"&gt;
1938     &lt;tbody&gt;
1939       &lt;row&gt;
1940         &lt;entry&gt;A&lt;/entry&gt;
1941         &lt;entry&gt;B&lt;/entry&gt;
1942         &lt;entry&gt;C&lt;/entry&gt;
1943       &lt;/row&gt;
1944       &lt;row&gt;
1945         &lt;entry colspan="span13" &gt;D&lt;/entry&gt;
1946       &lt;/row&gt;
1947       &lt;row&gt;
1948         &lt;entry&gt;E&lt;/entry&gt;
1949         &lt;entry&gt;F&lt;/entry&gt;
1950         &lt;entry&gt;G&lt;/entry&gt;
1951       &lt;/row&gt;
1952     &lt;/tbody&gt;
1953   &lt;/tgroup&gt;
1954 &lt;/table&gt;</pre>
1955 </div>
1956   </div>
1957
1958
1959
1960
1961   <a name="section-9"></a>
1962 <div class="section">
1963     <h2 class="stitle">9. Indexterms</h2>
1964
1965     <p>
1966 We generate indexes for books automatically, with the data originating
1967 in <tt>&lt;indexterm&gt;</tt> elements interspersed
1968 throughout the book. An indexterm holds all the information necessary
1969 for a single entry in an index, including the primary, secondary, and
1970 tertiary terms, references to other entries (see, see also), how to
1971 sort the term, and whether it should cross a range of pages.  An
1972 indexterm typically looks like this:
1973     </p>
1974
1975     <div class="programlisting">
1976 <pre>&lt;indexterm id="ixt-blather-frobozz-zmic"&gt;
1977   &lt;primary&gt;blather&lt;/primary&gt;
1978   &lt;secondary&gt;frobozz&lt;/secondary&gt;
1979   &lt;tertiary sortas="@"&gt;zmic&lt;/tertiary&gt;
1980   &lt;seealso&gt;fuj&lt;/seealso&gt;
1981 &lt;/indexterm&gt;</pre>
1982 </div>
1983
1984     <p>
1985 The term in this example is a tertiary-level term "zmic", which appears
1986 under the secondary term "frobozz", under the primary term
1987 "blather". It will be sorted as if it began with the character "@",
1988 which will pull it to the top of the secondary term's listing. The
1989 term will display "see also fuj".  Here's how the final index entry
1990 might look in an index:
1991     </p>
1992
1993     <div class="screen">
1994 <pre>blaam 24-26
1995 blather
1996   abba 12, 15
1997   crufty 99-105, 411
1998   frobozz 75
1999     zmic 10 (see also fuj)          &lt;-- the term
2000     asca 19, 22
2001     gumm 82-88
2002     splat 470
2003     zingle (see grooby)
2004   gurgle 99, 111
2005 bmm (see kluk)
2006 bravy
2007   scoot 45-48
2008   yodle 91</pre>
2009 </div>
2010
2011     <p>
2012 Indexterms can appear inside a wide variety of elements, but they
2013 typically appear inside paragraphs, lists, tables, or sections.  They
2014 are forbidden from appearing in titles, and should only rarely appear
2015 inside program listings.
2016     </p>
2017
2018     <p>
2019 To create a term that spans a segment of text, you use two
2020 <tt>&lt;indexterm&gt;</tt> elements linked by an
2021 <tt>id</tt>-<tt>startref</tt>
2022 attribute pair and <tt>class</tt> attributes. For
2023 example:
2024     </p>
2025
2026     <div class="programlisting">
2027 <pre>&lt;!-- start of the range --&gt;
2028 &lt;indexterm id="idx-fooby" class="startofrange"&gt;
2029   &lt;primary&gt;fooby&lt;/primary&gt;
2030 &lt;/indexterm&gt;
2031
2032 &lt;!-- content to be indexed --&gt;
2033 &lt;sect1&gt;
2034   &lt;title&gt;Programming Your Fooby&lt;/title&gt;
2035   &lt;para&gt;Blah blah blah...&lt;/para&gt;
2036   ...
2037 &lt;/sect1&gt;
2038
2039 &lt;!-- end of the range --&gt;
2040 &lt;indexterm class="endofrange" startref="idx-fooby"/&gt;</pre>
2041 </div>
2042   </div>
2043
2044
2045
2046
2047   <a name="section-10"></a>
2048 <div class="section">
2049     <h2 class="stitle">10. Out-of-flow Text</h2>
2050
2051     <p>
2052 Out-of-flow text is handled in several ways. Sidebars are for short
2053 discussions that don't belong in the general flow, aren't suitable for
2054 their own section, and can easily be encapsulated as a one-page
2055 aside. Admonitions (e.g. warnings, cautions, tips, etc.) are like
2056 sidebars but attract attention to themselves with more dramatic
2057 formatting and often an icon. Footnotes are shorter notes that have
2058 only a weak connection to the text and should be removed from view to
2059 the bottom of the page.
2060     </p>
2061
2062     <a name="section-1.1"></a>
2063 <div class="ssection">
2064       <h3 class="sstitle">10.1. Sidebars</h3>
2065
2066       <p>
2067 A sidebar functions like a section, but cannot contain sections within
2068 itself. Any other block content is allowed. They can appear at any
2069 level in the document underneath the chapter level. For example:
2070       </p>
2071
2072       <div class="programlisting">
2073 <pre>&lt;section&gt;
2074   &lt;title&gt;Bathyscaph Care and Maintenance&lt;/title&gt;
2075   &lt;para&gt;The hull of your submersible chamber is warranted
2076   for seven years against seal ruptures and corrosion of fittings.
2077   With proper care, you can extend the usable lifetime
2078   considerably. Barnacles are the most common cause of
2079   metal fatigue and gasket deterioration (see the sidebar for
2080   tips in removing these pests).&lt;/para&gt;
2081
2082   &lt;sidebar&gt;
2083     &lt;title&gt;Scraping Barnacles&lt;/title&gt;
2084     &lt;para&gt;You'll need a wire brush and a solution of equal parts
2085     vinegar and water. Pour the solution over the barnacles and let it
2086     sit for several hours. When the barnacle shells are soft, scrub
2087     them vigorously with the brush...&lt;/para&gt;
2088     ...
2089   &lt;/sidebar&gt;
2090   ...
2091 &lt;/sect2&gt;</pre>
2092 </div>
2093     </div>
2094
2095
2096     <a name="section-1.2"></a>
2097 <div class="ssection">
2098       <h3 class="sstitle">10.2. Admonitions</h3>
2099
2100       <p>
2101 To catch a reader's attention about a serious consideration, use an
2102 admonition. DocBook provides a whole bunch: caution, important, note, tip,
2103 and warning. In the absence of a title, either a default will be used
2104 (e.g. "WARNING!") or an icon will catch the reader's attention. Here's
2105 an example:
2106       </p>
2107
2108       <div class="programlisting">
2109 <pre>&lt;caution&gt;
2110   &lt;para&gt;Make sure your craft has reached the surface
2111   before unsealing the hatch. Otherwise, high-pressure
2112   water will flood the compartment.&lt;/para&gt;
2113 &lt;/caution&gt;</pre>
2114 </div>
2115
2116       <p>
2117 An admonition can appear in any section but cannot contain
2118 sections. Try to keep its content simple, using only paragraphs and
2119 lists if possible.
2120       </p>
2121     </div>
2122
2123
2124     <a name="section-1.3"></a>
2125 <div class="ssection">
2126       <h3 class="sstitle">10.3. Footnotes</h3>
2127
2128       <p>
2129 A <tt>&lt;footnote&gt;</tt> is coded as a block that
2130 interrupts a paragraph. It can look a little odd:
2131       </p>
2132
2133       <div class="programlisting">
2134 <pre>&lt;para&gt;When on Mars, be sure to
2135 visit the great volcano Olympus Mons&lt;footnote&gt;
2136   &lt;para&gt;It happens to be the tallest mountain in the Solar
2137   System, so bring your best hiking shoes.&lt;/para&gt;
2138 &lt;/footnote&gt;...</pre>
2139 </div>
2140
2141       <p>
2142 When the same footnote applies to different places in a document, you
2143 can use a <tt>&lt;footnoteref&gt;</tt> element to reference
2144 it. The following example shows how:
2145       </p>
2146
2147       <div class="programlisting">
2148 <pre>&lt;table&gt;
2149   &lt;tgroup cols="2"&gt;
2150     &lt;row&gt;
2151       &lt;entry&gt;apple&lt;/entry&gt;
2152       &lt;entry&gt;red&lt;/entry&gt;
2153     &lt;/row&gt;
2154     &lt;row&gt;
2155       &lt;entry&gt;banana&lt;footnote id="warning"&gt;
2156         &lt;para&gt;Peel it first!&lt;/para&gt;
2157         &lt;/footnote&gt;&lt;/entry&gt;
2158       &lt;entry&gt;yellow&lt;/entry&gt;
2159     &lt;/row&gt;
2160     &lt;row&gt;
2161       &lt;entry&gt;grape&lt;/entry&gt;
2162       &lt;entry&gt;purple&lt;/entry&gt;
2163     &lt;/row&gt;
2164     &lt;row&gt;
2165       &lt;entry&gt;orange&lt;footnoteref
2166         linkend="warning"/&gt;&lt;/entry&gt;
2167       &lt;entry&gt;orange&lt;/entry&gt;
2168     &lt;/row&gt;
2169   &lt;/tgroup&gt;
2170 &lt;/table&gt;</pre>
2171 </div>
2172     </div>
2173
2174
2175     <a name="section-1.4"></a>
2176 <div class="ssection">
2177       <h3 class="sstitle">10.4. Endnotes</h3>
2178
2179       <p>
2180 In some cases, you want a footnote's text to appear in another section
2181 or chapter. The <tt>&lt;endnote&gt;</tt> element serves that
2182 function. It also stores the body of the note elsewhere. For example:
2183       </p>
2184
2185       <div class="programlisting">
2186 <pre>&lt;para&gt;We suspect that lightning often appears in hues other
2187   than white. This hypothesis is supported by
2188   Dr. Indigo Riceway&lt;endnote linkend="note-riceway"/&gt;.&lt;/para&gt;
2189 ...
2190 &lt;endnote id="note-riceway"&gt;
2191   &lt;para&gt;Riceway wrote about green lightning in his
2192   book...&lt;/para&gt;
2193 &lt;/endnote&gt;</pre>
2194 </div>
2195     </div>
2196   </div>
2197
2198
2199
2200
2201   <a name="section-11"></a>
2202 <div class="section">
2203     <h2 class="stitle">11. Reference Pages</h2>
2204
2205     <p>
2206 One of the more complex block elements is
2207 <tt>&lt;refentry&gt;</tt>. It is used to encode a compact set of
2208 information about a command, application, or other technical
2209 entity. There are several different ways to format a reference entry,
2210 so we provide a <tt>role</tt> attribute to let you choose
2211 the one that best fits your book.
2212     </p>
2213
2214     <p>
2215 There are three main types supported:
2216     </p>
2217
2218     <ul>
2219       <li>
2220         <p>
2221 Default
2222         </p>
2223       </li>
2224       <li>
2225         <p>
2226 Nutshell
2227         </p>
2228       </li>
2229       <li>
2230         <p>
2231 Java
2232         </p>
2233       </li>
2234     </ul>
2235
2236
2237     <a name="section-1.1"></a>
2238 <div class="ssection">
2239       <h3 class="sstitle">11.1. Default Reference Pages</h3>
2240
2241       <p>
2242 Here are three examples of common reference pages used in DocBook Lite:
2243       </p>
2244
2245       <div class="figure">
2246         <h4 class="figuretitle">Figure 1.
2247 A refentry from <i>Samba</i>, Appendix C
2248         </h4>
2249         <image src="figs/ref1.gif"></image>
2250       </div>
2251
2252       <div class="example">
2253         <h4 class="exampletitle">Example 1. How the above refentry is coded</h4>
2254         <div class="programlisting">
2255 <pre>&lt;refentry&gt;
2256  &lt;refmeta&gt;
2257   &lt;refmiscinfo class="allowable values"&gt;YES, NO&lt;/refmiscinfo&gt;
2258   &lt;refmiscinfo class="default"&gt;NO&lt;/refmiscinfo&gt;
2259  &lt;/refmeta&gt;
2260  &lt;refnamediv&gt;
2261   &lt;refname&gt;alternate permissions = boolean&lt;/refname&gt;
2262  &lt;/refnamediv&gt;
2263  &lt;refsynopsisdiv&gt;
2264   &lt;para&gt;Obsolete. Has no effect in Samba 2. Files will be shown as
2265    read-only if the owner can't write them. In Samba 1.9 and
2266    earlier, setting this option would set the DOS filesystem read-only
2267    attribute on any file the user couldn't read. This in turn
2268    required the &lt;literal&gt;delete readonly&lt;/literal&gt;
2269    option.&lt;/para&gt;
2270   &lt;/refsynopsisdiv&gt;
2271 &lt;/refentry&gt;</pre>
2272 </div>
2273       </div>
2274
2275       <div class="figure">
2276         <h4 class="figuretitle">Figure 2.
2277 A refentry from <i>MySQL and mSQL</i>, Chapter 21
2278         </h4>
2279         <image src="figs/ref2.gif"></image>
2280       </div>
2281
2282       <div class="example">
2283         <h4 class="exampletitle">Example 2. How the above refentry is coded</h4>
2284         <div class="programlisting">
2285 <pre>&lt;refentry&gt;
2286  &lt;refmeta&gt;
2287   &lt;refentrytitle&gt;DBI::do&lt;/refentrytitle&gt;
2288  &lt;/refmeta&gt;
2289  &lt;refnamediv&gt;
2290   &lt;refname&gt;DBI::do&lt;/refname&gt;
2291  &lt;/refnamediv&gt;
2292  &lt;refsynopsisdiv&gt;
2293   &lt;synopsis&gt;$rows_affected  = $db-&amp;gt;do($statement);
2294 $rows_affected  = $db-&amp;gt;do($statement, \%unused);
2295 $rows_affected  =
2296     $db-&amp;gt;do($statement, \%unused, @bind_values);&lt;/synopsis&gt;
2297   &lt;para&gt;&lt;literal&gt;DBI::do&lt;/literal&gt; directly performs a
2298   non-&lt;literal&gt;SELECT&lt;/literal&gt; SQL statement and
2299   returns the number of rows affected by the statement. This is
2300   faster than a &lt;literal&gt;DBI::prepare/DBI::execute
2301   &lt;/literal&gt;pair which requires two function calls. The
2302   first argument is the SQL statement itself. The
2303   second argument is unused in DBD::mSQL and DBD::mysql,
2304   but can hold a reference to a hash of attributes for other
2305   DBD modules. The final argument is an array of values used
2306   to replace `placeholders,' which are indicated with a
2307   `?' in the statement. The values of the array are
2308   substituted for the placeholders from left to right. As an
2309   additional bonus, &lt;literal&gt;DBI::do&lt;/literal&gt; will
2310   automatically quote string values before substitution.&lt;/para&gt;
2311  &lt;/refsynopsisdiv&gt;
2312  &lt;refsect1&gt;
2313   &lt;title&gt;Example&lt;/title&gt;
2314   &lt;programlisting&gt;use DBI;
2315 my $db = DBI-&amp;gt;connect('DBI:mSQL:mydata',undef,undef);
2316
2317 my $rows_affected =
2318   $db-&amp;gt;do("UPDATE mytable SET name='Joe' WHERE name='Bob'");
2319 print "$rows_affected Joe's were changed to Bob's\n";
2320
2321 my $rows_affected2 =
2322   $db-&amp;gt;do("INSERT INTO mytable (name) VALUES (?)",
2323                                 {}, ("Sheldon's Cycle"));
2324 # After quoting and substitution, the statement:
2325 # INSERT INTO mytable (name) VALUES ('Sheldon's Cycle')
2326 # was sent to the database server.&lt;/programlisting&gt;
2327  &lt;/refsect1&gt;
2328 &lt;/refentry&gt;</pre>
2329 </div>
2330       </div>
2331
2332       <div class="figure">
2333         <h4 class="figuretitle">Figure 3.
2334 A refentry from <i>Apache: The Definitive Guide</i>,
2335 Chapter 14
2336         </h4>
2337         <image src="figs/ref3.gif"></image>
2338       </div>
2339
2340       <div class="example">
2341         <h4 class="exampletitle">Example 3. How the above refentry is coded</h4>
2342         <div class="programlisting">
2343 <pre>&lt;refentry&gt;
2344  &lt;refmeta&gt;
2345   &lt;refentrytitle&gt;ap_pstrndup&lt;/refentrytitle&gt;
2346  &lt;/refmeta&gt;
2347  &lt;refnamediv&gt;
2348   &lt;refname&gt;ap_pstrndup&lt;/refname&gt;
2349   &lt;refpurpose&gt;duplicate a string in a pool with
2350     limited length&lt;/refpurpose&gt;
2351  &lt;/refnamediv&gt;
2352  &lt;refsynopsisdiv&gt;
2353   &lt;synopsis&gt;
2354     char *ap_pstrndup(pool *p, const char *s, int n)&lt;/synopsis&gt;
2355   &lt;para&gt;Allocates &lt;literal&gt;n&lt;/literal&gt;+1 bytes
2356   of memory and copies up to &lt;literal&gt;n&lt;/literal&gt;
2357   characters from &lt;literal&gt;s&lt;/literal&gt;,
2358   &lt;literal&gt;NULL&lt;/literal&gt;- terminating the result.
2359   The memory is destroyed when the pool is destroyed. Returns
2360   a pointer to the new block of memory, or
2361   &lt;literal&gt;NULL&lt;/literal&gt; if &lt;literal&gt;s&lt;/literal&gt;
2362   is &lt;literal&gt;NULL&lt;/literal&gt;.&lt;/para&gt;
2363  &lt;/refsynopsisdiv&gt;
2364 &lt;/refentry&gt;</pre>
2365 </div>
2366       </div>
2367     </div>
2368
2369
2370     <a name="section-1.2"></a>
2371 <div class="ssection">
2372       <h3 class="sstitle">11.2. Nutshell Type Reference Pages</h3>
2373
2374       <p>
2375 Nutshell books use a particular kind of reference structure that
2376 looks like this:
2377       </p>
2378
2379       <div class="figure">
2380         <h4 class="figuretitle">Figure 1.
2381 A refentry from <i>Unix in a Nutshell</i>, Chapter 5
2382         </h4>
2383         <image src="figs/ref4.gif"></image>
2384       </div>
2385
2386       <div class="example">
2387         <h4 class="exampletitle">Example 1. How the above refentry is coded</h4>
2388         <div class="programlisting">
2389 <pre>&lt;nutlist longestterm="unseten"&gt;
2390
2391  &lt;nutentry&gt;&lt;term&gt;alias&lt;/term&gt;
2392   &lt;nutsynopsis&gt;&lt;literal&gt;alias&lt;/literal&gt;
2393   [&lt;replaceable&gt;name&lt;/replaceable&gt;
2394   [&lt;replaceable&gt;command&lt;/replaceable&gt;]]&lt;/nutsynopsis&gt;
2395   &lt;nutentrybody&gt;
2396    &lt;para&gt;Assign &lt;emphasis&gt;name&lt;/emphasis&gt;
2397     as the shorthand name, or alias, for
2398     &lt;emphasis&gt;command&lt;/emphasis&gt;.  If
2399     &lt;emphasis&gt;command&lt;/emphasis&gt; is omitted, print the
2400     alias for &lt;emphasis&gt;name&lt;/emphasis&gt;;
2401     if &lt;emphasis&gt;name&lt;/emphasis&gt; is also
2402     omitted, print all aliases.  Aliases can be defined on the command
2403     line, but they are more often stored in
2404     &lt;literal&gt;.cshrc&lt;/literal&gt;
2405     so that they take effect after login.  (See [cross ref deleted]
2406     earlier in this chapter.)  Alias definitions can reference
2407     command-line arguments, much like the history list.  Use
2408     &lt;literal&gt;\!*&lt;/literal&gt; to refer to all command-line
2409     arguments, &lt;literal&gt;\!^&lt;/literal&gt; for the first argument,
2410     &lt;literal&gt;\!$&lt;/literal&gt; for the last, etc.  An alias
2411     &lt;emphasis&gt;name&lt;/emphasis&gt; can be any valid Unix
2412     command; however, you lose the original command's meaning unless
2413     you type &lt;emphasis&gt;\name&lt;/emphasis&gt;.
2414     See also &lt;emphasis
2415     role="bold"&gt;unalias&lt;/emphasis&gt;.&lt;/para&gt;
2416
2417     &lt;refsect2&gt;&lt;title&gt;Examples&lt;/title&gt;
2418     &lt;para&gt;Set the size for &lt;literal&gt;xterm&lt;/literal&gt;
2419     windows under the X Window System:&lt;/para&gt;
2420     &lt;programlisting&gt;alias R 'set noglob; eval `resize`;
2421       unset noglob'&lt;/programlisting&gt;
2422     &lt;para&gt;Show aliases that contain the string
2423      &lt;emphasis&gt;ls&lt;/emphasis&gt;:&lt;/para&gt;
2424     &lt;programlisting&gt;alias | grep ls&lt;/programlisting&gt;
2425     &lt;para&gt;Run &lt;literal&gt;nroff&lt;/literal&gt;
2426     on all command-line arguments:&lt;/para&gt;
2427     &lt;programlisting&gt;alias ms 'nroff -ms \!*'&lt;/programlisting&gt;
2428     &lt;para&gt;Copy the file that is named as the first argument:&lt;/para&gt;
2429     &lt;programlisting&gt;alias back 'cp \!^ \!^.old'&lt;/programlisting&gt;
2430     &lt;para&gt;Use the regular &lt;literal&gt;ls&lt;/literal&gt;,
2431     not its alias:&lt;/para&gt;
2432     &lt;programlisting&gt;% &lt;userinput&gt;\ls
2433       &lt;/userinput&gt;&lt;/programlisting&gt;
2434    &lt;/refsect2&gt;
2435   &lt;/nutentrybody&gt;
2436  &lt;/nutentry&gt;
2437
2438 &lt;/nutlist&gt;</pre>
2439 </div>
2440       </div>
2441     </div>
2442
2443
2444     <a name="section-1.3"></a>
2445 <div class="ssection">
2446       <h3 class="sstitle">11.3. Java Type Reference Pages</h3>
2447
2448       <p>
2449 This example shows how Java <tt>&lt;refentry&gt;</tt>s
2450 look:
2451       </p>
2452
2453       <div class="figure">
2454         <h4 class="figuretitle">Figure 1.
2455 A refentry from <i>Java Fundamental Classes in a
2456 Nutshell</i>, Chapter 32.
2457         </h4>
2458         <image src="figs/ref5.gif"></image>
2459       </div>
2460
2461       <div class="example">
2462         <h4 class="exampletitle">Example 1. How the above refentry is coded</h4>
2463         <div class="programlisting">
2464 <pre>&lt;refentry role="java"
2465     id="java.io.dataoutputstream"&gt;
2466  &lt;refmeta&gt;
2467   &lt;refmiscinfo class="version"&gt;Java 1.0&lt;/refmiscinfo&gt;
2468   &lt;refmiscinfo class="package"&gt;java.io&lt;/refmiscinfo&gt;
2469   &lt;refmiscinfo class="flags"&gt;PJ1.1&lt;/refmiscinfo&gt;
2470  &lt;/refmeta&gt;
2471  &lt;refnamediv&gt;
2472   &lt;refname&gt;DataOutputStream&lt;/refname&gt;
2473  &lt;/refnamediv&gt;
2474
2475  &lt;refsect1 role="intro"&gt;
2476   &lt;para&gt;This class is a subclass of
2477    &lt;literal&gt;FilterOutputStream&lt;/literal&gt; that allows
2478    you to write Java primitive data types in a portable binary
2479    format. Create a &lt;literal&gt;DataOutputStream&lt;/literal&gt;
2480    by specifying the &lt;literal&gt;OutputStream&lt;/literal&gt;
2481    that is to be filtered in the call to the constructor.
2482    &lt;literal&gt;DataOutputStream&lt;/literal&gt; has methods
2483    that output only primitive types; use
2484    &lt;literal&gt;ObjectOutputStream&lt;/literal&gt; to output object
2485    values. &lt;/para&gt;
2486  &lt;/refsect1&gt;
2487
2488  &lt;refsynopsisdiv&gt;
2489   &lt;classsynopsis keyword="class"&gt;
2490    &lt;modifiers&gt;public&lt;/modifiers&gt;
2491    &lt;classname&gt;DataOutputStream&lt;/classname&gt;
2492    &lt;extends&gt;&lt;classref package="java.io"
2493      class="FilterOutputStream"/&gt;&lt;/extends&gt;
2494    &lt;implements&gt;&lt;classref
2495      package="java.io" class="DataOutput"/&gt;&lt;/implements&gt;
2496
2497    &lt;members&gt;&lt;title&gt;Public Constructors&lt;/title&gt;
2498     &lt;membergroup&gt;
2499      &lt;funcprototype revision="" role="method" flags=""&gt;
2500       &lt;funcdef&gt;&lt;modifiers&gt;public&lt;/modifiers&gt;
2501        &lt;function&gt;DataOutputStream&lt;/function&gt;
2502       &lt;/funcdef&gt;
2503       &lt;paramdef&gt;
2504        &lt;type&gt;&lt;classref role="includePkg"
2505          package="java.io" class="OutputStream"/&gt;&lt;/type&gt;
2506        &lt;parameter&gt;out&lt;/parameter&gt;
2507       &lt;/paramdef&gt;
2508      &lt;/funcprototype&gt;
2509     &lt;/membergroup&gt;
2510    &lt;/members&gt;
2511
2512    &lt;members&gt;&lt;title&gt;Public Instance Methods&lt;/title&gt;
2513     &lt;membergroup&gt;
2514      &lt;funcprototype revision="" role="method" flags=""&gt;
2515       &lt;funcdef&gt;&lt;modifiers&gt;public final&lt;/modifiers&gt;
2516        &lt;type&gt;int&lt;/type&gt;
2517        &lt;function&gt;size&lt;/function&gt;
2518       &lt;/funcdef&gt;
2519      &lt;/funcprototype&gt;
2520     &lt;/membergroup&gt;
2521    &lt;/members&gt;
2522
2523    &lt;members&gt;&lt;title&gt;Methods Implementing
2524      &lt;classref package="java.io" class="DataOutput"/&gt;&lt;/title&gt;
2525     &lt;membergroup&gt;
2526      &lt;funcprototype revision="" role="method" flags=" synchronized"&gt;
2527       &lt;funcdef&gt;&lt;modifiers&gt;public&lt;/modifiers&gt; &lt;type&gt;void&lt;/type&gt;
2528        &lt;function&gt;write&lt;/function&gt;
2529       &lt;/funcdef&gt;
2530       &lt;paramdef&gt;&lt;type&gt;int&lt;/type&gt; &lt;parameter&gt;b&lt;/parameter&gt;&lt;/paramdef&gt;
2531       &lt;throws&gt;&lt;classref package="java.io" class="IOException"/&gt;&lt;/throws&gt;
2532      &lt;/funcprototype&gt;
2533     &lt;/membergroup&gt;
2534     &lt;membergroup&gt;
2535      &lt;funcprototype revision="" role="method" flags=" synchronized"&gt;
2536       &lt;funcdef&gt;&lt;modifiers&gt;public&lt;/modifiers&gt; &lt;type&gt;void&lt;/type&gt;
2537        &lt;function&gt;write&lt;/function&gt;
2538       &lt;/funcdef&gt;
2539       &lt;paramdef&gt;
2540        &lt;type&gt;byte[&amp;thinsp;]&lt;/type&gt; &lt;parameter&gt;b&lt;/parameter&gt;&lt;/paramdef&gt;
2541       &lt;paramdef&gt;&lt;type&gt;int&lt;/type&gt; &lt;parameter&gt;off&lt;/parameter&gt;&lt;/paramdef&gt;
2542       &lt;paramdef&gt;&lt;type&gt;int&lt;/type&gt; &lt;parameter&gt;len&lt;/parameter&gt;&lt;/paramdef&gt;
2543       &lt;throws&gt;&lt;classref package="java.io" class="IOException"/&gt;&lt;/throws&gt;
2544      &lt;/funcprototype&gt;
2545     &lt;/membergroup&gt;
2546     &lt;membergroup&gt;
2547      &lt;funcprototype revision="" role="method" flags=""&gt;
2548       &lt;funcdef&gt;&lt;modifiers&gt;public final&lt;/modifiers&gt; &lt;type&gt;void&lt;/type&gt;
2549        &lt;function&gt;writeBoolean&lt;/function&gt;
2550       &lt;/funcdef&gt;
2551       &lt;paramdef&gt;&lt;type&gt;boolean&lt;/type&gt; &lt;parameter&gt;v&lt;/parameter&gt;&lt;/paramdef&gt;
2552       &lt;throws&gt;&lt;classref package="java.io" class="IOException"/&gt;&lt;/throws&gt;
2553      &lt;/funcprototype&gt;
2554     &lt;/membergroup&gt;
2555     &lt;membergroup&gt;
2556      &lt;funcprototype revision="" role="method" flags=""&gt;
2557       &lt;funcdef&gt;&lt;modifiers&gt;public final&lt;/modifiers&gt; &lt;type&gt;void&lt;/type&gt;
2558        &lt;function&gt;writeByte&lt;/function&gt;
2559       &lt;/funcdef&gt;
2560       &lt;paramdef&gt;&lt;type&gt;int&lt;/type&gt; &lt;parameter&gt;v&lt;/parameter&gt;&lt;/paramdef&gt;
2561       &lt;throws&gt;&lt;classref package="java.io" class="IOException"/&gt;&lt;/throws&gt;
2562      &lt;/funcprototype&gt;
2563     &lt;/membergroup&gt;
2564     &lt;membergroup&gt;
2565      &lt;funcprototype revision="" role="method" flags=""&gt;
2566       &lt;funcdef&gt;&lt;modifiers&gt;public final&lt;/modifiers&gt; &lt;type&gt;void&lt;/type&gt;
2567        &lt;function&gt;writeInt&lt;/function&gt;
2568       &lt;/funcdef&gt;
2569       &lt;paramdef&gt;&lt;type&gt;int&lt;/type&gt; &lt;parameter&gt;v&lt;/parameter&gt;&lt;/paramdef&gt;
2570       &lt;throws&gt;&lt;classref package="java.io" class="IOException"/&gt;&lt;/throws&gt;
2571      &lt;/funcprototype&gt;
2572     &lt;/membergroup&gt;
2573    &lt;/members&gt;
2574
2575    &lt;members&gt;&lt;title&gt;Public Methods Overriding &lt;classref package="java.io"
2576      class="FilterOutputStream"/&gt;&lt;/title&gt;
2577     &lt;membergroup&gt;
2578      &lt;funcprototype revision="" role="method" flags=""&gt;
2579       &lt;funcdef&gt;&lt;modifiers&gt;public&lt;/modifiers&gt; &lt;type&gt;void&lt;/type&gt;
2580        &lt;function&gt;flush&lt;/function&gt;
2581       &lt;/funcdef&gt;
2582       &lt;throws&gt;&lt;classref package="java.io" class="IOException"/&gt;&lt;/throws&gt;
2583      &lt;/funcprototype&gt;
2584     &lt;/membergroup&gt;
2585    &lt;/members&gt;
2586
2587    &lt;members&gt;
2588     &lt;title&gt;Protected Instance Fields&lt;/title&gt;
2589     &lt;membergroup&gt;
2590      &lt;funcprototype revision="" role="field" flags=""&gt;
2591       &lt;funcdef&gt;&lt;modifiers&gt;protected&lt;/modifiers&gt; &lt;type&gt;int&lt;/type&gt;
2592        &lt;function&gt;written&lt;/function&gt;
2593       &lt;/funcdef&gt;
2594      &lt;/funcprototype&gt;
2595     &lt;/membergroup&gt;
2596    &lt;/members&gt;
2597   &lt;/classsynopsis&gt;
2598  &lt;/refsynopsisdiv&gt;
2599
2600  &lt;refsect1&gt;
2601   &lt;title&gt;Hierarchy&lt;/title&gt;
2602   &lt;para&gt;
2603    &lt;literal&gt;&lt;classref package="java.lang" class="Object"/&gt; &amp;rarr;
2604    &lt;classref role="includePkg" package="java.io"
2605    class="OutputStream"/&gt; &amp;rarr; &lt;classref package="java.io"
2606    class="FilterOutputStream"/&gt; &amp;rarr; &lt;classref role="includePkg"
2607    package="java.io" class="DataOutputStream"/&gt; (&lt;classref
2608    package="java.io" class="DataOutput"/&gt;)&lt;/literal&gt;&lt;/para&gt;
2609  &lt;/refsect1&gt;
2610 &lt;/refentry&gt;</pre>
2611 </div>
2612       </div>
2613     </div>
2614   </div>
2615
2616   <a name="section-12"></a>
2617 <hr>
2618 <span class="footertitle">Written by:</span>
2619 <br>
2620 <b>Erik Ray <i><a href="mailto:eray@oreilly.com">eray@oreilly.com</a></i>
2621 <br>
2622 </b>
2623 </body>
2624 </html>