libstdc++-v3/doc/xml/manual/documentation_hacking.xml

   1 <section xmlns="http://docbook.org/ns/docbook" version="5.0"
   2          xml:id="appendix.porting.doc" xreflabel="Documentation Hacking">
   3 <?dbhtml filename="documentation_hacking.html"?>
   4
   5 <info><title>Writing and Generating Documentation</title>
   6   <keywordset>
   7     <keyword>ISO C++</keyword>
   8     <keyword>documentation</keyword>
   9     <keyword>style</keyword>
  10     <keyword>docbook</keyword>
  11     <keyword>doxygen</keyword>
  12   </keywordset>
  13 </info>
  14
  15   <section xml:id="doc.intro">
  16     <info>
  17     <title>Introduction</title>
  18     </info>
  19     <para>
  20       Documentation for the GNU C++ Library is created from three
  21       independent sources: a manual, a FAQ, and an API reference.
  22     </para>
  23     <para>
  24       The sub-directory <filename class="directory">doc</filename>
  25       within the main source directory contains
  26       <filename>Makefile.am</filename> and
  27       <filename>Makefile.in</filename>, which provide rules for
  28       generating documentation, described in excruciating detail
  29       below. The <filename class="directory">doc</filename>
  30       sub-directory also contains three directories: <filename
  31       class="directory">doxygen</filename>, which contains scripts and
  32       fragments for <command>doxygen</command>, <filename
  33       class="directory">html</filename>, which contains an html
  34       version of the manual, and <filename
  35       class="directory">xml</filename>, which contains an xml version
  36       of the manual.
  37     </para>
  38     <para>
  39       Diverging from established documentation conventions in the rest
  40       of the GCC project, libstdc++ does not use Texinfo as a markup
  41       language. Instead, Docbook is used to create the manual and the
  42       FAQ, and Doxygen is used to construct the API
  43       reference. Although divergent, this conforms to the GNU Project
  44       recommendations as long as the output is of sufficient quality,
  45       as per
  46       <link xmlns:xlink="http://www.w3.org/1999/xlink"
  47       xlink:href="http://www.gnu.org/prep/standards/standards.html#Documentation">
  48       GNU Manuals</link>.
  49     </para>
  50   </section>
  51
  52   <section xml:id="doc.generation">
  53     <info>
  54     <title>Generating Documentation</title>
  55     </info>
  56
  57     <para>
  58       Certain Makefile rules are required by the GNU Coding
  59       Standards. These standard rules generate HTML, PDF, XML, or man
  60       files. For each of the generative rules, there is an additional
  61       install rule that is used to install any generated documentation
  62       files into the prescribed installation directory. Files are
  63       installed into <filename class="directory">share/doc</filename>
  64       or <filename class="directory">share/man</filename> directories.
  65     </para>
  66
  67     <para>
  68       The standard Makefile rules are conditionally supported, based
  69       on the results of examining the host environment for
  70       prerequisites at configuration time. If requirements are not
  71       found, the rule is aliased to a dummy rule that does nothing,
  72       and produces no documentation. If the requirements are found,
  73       the rule forwards to a private rule that produces the requested
  74       documentation.
  75     </para>
  76
  77     <para>
  78       For more details on what prerequisites were found and where,
  79       please consult the file <filename>config.log</filename> in the
  80       libstdc++ build directory. Compare this log to what is expected
  81       for the relevant Makefile conditionals:
  82       <literal>BUILD_INFO</literal>, <literal>BUILD_XML</literal>,
  83       <literal>BUILD_HTML</literal>, <literal>BUILD_MAN</literal>,
  84       <literal>BUILD_PDF</literal>, and <literal>BUILD_EPUB</literal>.
  85     </para>
  86
  87     <para>
  88       Supported Makefile rules:
  89     </para>
  90
  91     <variablelist>
  92       <varlistentry>
  93         <term>
  94           <emphasis>make html</emphasis>
  95         </term>
  96         <term>
  97           <emphasis>make install-html</emphasis>
  98         </term>
  99         <listitem>
 100           <para>
 101             Generates multi-page HTML documentation, and installs it
 102             in the following directories:
 103           </para>
 104           <para>
 105             <filename class="directory">
 106               doc/libstdc++/libstdc++-api.html
 107             </filename>
 108           </para>
 109           <para>
 110             <filename class="directory">
 111               doc/libstdc++/libstdc++-manual.html
 112             </filename>
 113           </para>
 114         </listitem>
 115       </varlistentry>
 116
 117       <varlistentry>
 118         <term>
 119           <emphasis>make pdf</emphasis>
 120         </term>
 121         <term>
 122           <emphasis>make install-pdf</emphasis>
 123         </term>
 124         <listitem>
 125           <para>
 126             Generates indexed PDF documentation, and installs it as
 127             the following files:
 128           </para>
 129           <para>
 130             <filename>doc/libstdc++/libstdc++-api.pdf</filename>
 131           </para>
 132           <para>
 133             <filename>doc/libstdc++/libstdc++-manual.pdf</filename>
 134           </para>
 135         </listitem>
 136       </varlistentry>
 137
 138       <varlistentry>
 139         <term>
 140           <emphasis>make man</emphasis>
 141         </term>
 142         <term>
 143           <emphasis>make install-man</emphasis>
 144         </term>
 145         <listitem>
 146           <para>
 147             Generates man pages, and installs it in the following directory:
 148           </para>
 149           <para>
 150             <filename class="directory">man/man3/</filename>
 151           </para>
 152           <para>
 153             The generated man pages are namespace-qualified, so to look at
 154             the man page for <classname>vector</classname>, one would use
 155             <command>man std::vector</command>.
 156           </para>
 157         </listitem>
 158       </varlistentry>
 159
 160       <varlistentry>
 161         <term>
 162           <emphasis>make epub</emphasis>
 163         </term>
 164         <term>
 165           <emphasis>make install-epub</emphasis>
 166         </term>
 167         <listitem>
 168           <para>
 169             Generates documentation in the ebook/portable electronic
 170             reader format called Epub, and installs it as the
 171             following file.
 172           </para>
 173           <para>
 174             <filename>doc/libstdc++/libstdc++-manual.epub</filename>
 175           </para>
 176         </listitem>
 177       </varlistentry>
 178
 179       <varlistentry>
 180         <term>
 181           <emphasis>make xml</emphasis>
 182         </term>
 183         <term>
 184           <emphasis>make install-xml</emphasis>
 185         </term>
 186         <listitem>
 187           <para>
 188             Generates single-file XML documentation, and installs it
 189             as the following files:
 190           </para>
 191           <para>
 192             <filename>doc/libstdc++/libstdc++-api-single.xml</filename>
 193           </para>
 194           <para>
 195             <filename>doc/libstdc++/libstdc++-manual-single.xml</filename>
 196           </para>
 197         </listitem>
 198       </varlistentry>
 199     </variablelist>
 200
 201     <para>
 202       Makefile rules for several other formats are explicitly not
 203       supported, and are always aliased to dummy rules. These
 204       unsupported formats are: <emphasis>info</emphasis>,
 205       <emphasis>ps</emphasis>, and <emphasis>dvi</emphasis>.
 206     </para>
 207   </section>
 208
 209   <section xml:id="doc.doxygen"><info><title>Doxygen</title></info>
 210
 211     <section xml:id="doxygen.prereq"><info><title>Prerequisites</title></info>
 212
 213  <table frame="all">
 214 <title>Doxygen Prerequisites</title>
 215
 216 <tgroup cols="3" align="center" colsep="1" rowsep="1">
 217 <colspec colname="c1"/>
 218 <colspec colname="c2"/>
 219 <colspec colname="c3"/>
 220
 221   <thead>
 222     <row>
 223       <entry>Tool</entry>
 224       <entry>Version</entry>
 225       <entry>Required By</entry>
 226     </row>
 227   </thead>
 228
 229   <tbody>
 230
 231     <row>
 232       <entry>coreutils</entry>
 233       <entry>8.5</entry>
 234       <entry>all</entry>
 235     </row>
 236
 237     <row>
 238       <entry>bash</entry>
 239       <entry>4.1</entry>
 240       <entry>all</entry>
 241     </row>
 242
 243     <row>
 244       <entry>doxygen</entry>
 245       <entry>1.7.0</entry>
 246       <entry>all</entry>
 247     </row>
 248
 249     <row>
 250       <entry>graphviz</entry>
 251       <entry>2.26</entry>
 252       <entry>graphical hierarchies</entry>
 253     </row>
 254
 255     <row>
 256       <entry>pdflatex</entry>
 257       <entry>2007-59</entry>
 258       <entry>pdf output</entry>
 259     </row>
 260
 261   </tbody>
 262 </tgroup>
 263 </table>
 264
 265
 266       <para>
 267         Prerequisite tools are Bash 2.0 or later,
 268         <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.doxygen.org/">Doxygen</link>, and
 269         the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.gnu.org/software/coreutils/">GNU
 270         coreutils</link>. (GNU versions of find, xargs, and possibly
 271         sed and grep are used, just because the GNU versions make
 272         things very easy.)
 273       </para>
 274
 275       <para>
 276         To generate the pretty pictures and hierarchy
 277         graphs, the
 278         <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.graphviz.org">Graphviz</link> package
 279         will need to be installed. For PDF
 280         output, <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.tug.org/applications/pdftex/">
 281         pdflatex</link> is required.
 282       </para>
 283     </section>
 284
 285     <section xml:id="doxygen.rules"><info><title>Generating the Doxygen Files</title></info>
 286
 287       <para>
 288         The following Makefile rules run Doxygen to generate HTML
 289         docs, XML docs, XML docs as a single file, PDF docs, and the
 290         man pages. These rules are not conditional! If the required
 291         tools are not found, or are the wrong versions, the rule may
 292         end in an error.
 293       </para>
 294
 295       <para>
 296       <screen><userinput>make doc-html-doxygen</userinput></screen>
 297       </para>
 298
 299       <para>
 300       <screen><userinput>make doc-xml-doxygen</userinput></screen>
 301       </para>
 302
 303       <para>
 304       <screen><userinput>make doc-xml-single-doxygen</userinput></screen>
 305       </para>
 306
 307       <para>
 308       <screen><userinput>make doc-pdf-doxygen</userinput></screen>
 309       </para>
 310
 311       <para>
 312       <screen><userinput>make doc-man-doxygen</userinput></screen>
 313       </para>
 314
 315       <para>
 316         Generated files are output into separate sub directories of
 317         <filename class="directory">doc/doxygen/</filename> in the
 318         build directory, based on the output format. For instance, the
 319         HTML docs will be in <filename class="directory">doc/doxygen/html</filename>.
 320       </para>
 321
 322       <para>
 323         Careful observers will see that the Makefile rules simply call
 324         a script from the source tree, <filename>run_doxygen</filename>, which
 325         does the actual work of running Doxygen and then (most
 326         importantly) massaging the output files. If for some reason
 327         you prefer to not go through the Makefile, you can call this
 328         script directly. (Start by passing <literal>--help</literal>.)
 329       </para>
 330
 331       <para>
 332         If you wish to tweak the Doxygen settings, do so by editing
 333         <filename>doc/doxygen/user.cfg.in</filename>. Notes to fellow
 334         library hackers are written in triple-# comments.
 335       </para>
 336
 337     </section>
 338
 339     <section xml:id="doxygen.markup"><info><title>Markup</title></info>
 340
 341
 342       <para>
 343         In general, libstdc++ files should be formatted according to
 344         the rules found in the
 345         <link linkend="contrib.coding_style">Coding Standard</link>. Before
 346         any doxygen-specific formatting tweaks are made, please try to
 347         make sure that the initial formatting is sound.
 348       </para>
 349
 350       <para>
 351         Adding Doxygen markup to a file (informally called
 352         <quote>doxygenating</quote>) is very simple. The Doxygen manual can be
 353         found
 354         <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.stack.nl/~dimitri/doxygen/download.html#latestman">here</link>.
 355         We try to use a very-recent version of Doxygen.
 356       </para>
 357
 358       <para>
 359         For classes, use
 360         <classname>deque</classname>/<classname>vector</classname>/<classname>list</classname>
 361         and <classname>std::pair</classname> as examples.  For
 362         functions, see their member functions, and the free functions
 363         in <filename>stl_algobase.h</filename>. Member functions of
 364         other container-like types should read similarly to these
 365         member functions.
 366       </para>
 367
 368       <para>
 369         Some commentary to accompany
 370         the first list in the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.stack.nl/~dimitri/doxygen/docblocks.html">Special
 371         Documentation Blocks</link> section of
 372         the Doxygen manual:
 373       </para>
 374
 375       <orderedlist inheritnum="ignore" continuation="restarts">
 376         <listitem>
 377           <para>For longer comments, use the Javadoc style...</para>
 378         </listitem>
 379
 380         <listitem>
 381           <para>
 382             ...not the Qt style. The intermediate *'s are preferred.
 383           </para>
 384         </listitem>
 385
 386         <listitem>
 387           <para>
 388             Use the triple-slash style only for one-line comments (the
 389             <quote>brief</quote> mode).
 390           </para>
 391         </listitem>
 392
 393         <listitem>
 394           <para>
 395             This is disgusting. Don't do this.
 396           </para>
 397         </listitem>
 398       </orderedlist>
 399
 400       <para>
 401         Some specific guidelines:
 402       </para>
 403
 404       <para>
 405         Use the @-style of commands, not the !-style. Please be
 406         careful about whitespace in your markup comments. Most of the
 407         time it doesn't matter; doxygen absorbs most whitespace, and
 408         both HTML and *roff are agnostic about whitespace. However,
 409         in &lt;pre&gt; blocks and @code/@endcode sections, spacing can
 410         have <quote>interesting</quote> effects.
 411       </para>
 412
 413       <para>
 414         Use either kind of grouping, as
 415         appropriate. <filename>doxygroups.cc</filename> exists for this
 416         purpose. See <filename>stl_iterator.h</filename> for a good example
 417         of the <quote>other</quote> kind of grouping.
 418       </para>
 419
 420       <para>
 421         Please use markup tags like @p and @a when referring to things
 422         such as the names of function parameters. Use @e for emphasis
 423         when necessary. Use @c to refer to other standard names.
 424         (Examples of all these abound in the present code.)
 425       </para>
 426
 427       <para>
 428         Complicated math functions should use the multi-line
 429         format. An example from <filename>random.h</filename>:
 430       </para>
 431
 432       <para>
 433 <literallayout class="normal">
 434 /**
 435  * @brief A model of a linear congruential random number generator.
 436  *
 437  * @f[
 438  *     x_{i+1}\leftarrow(ax_{i} + c) \bmod m
 439  * @f]
 440  */
 441 </literallayout>
 442       </para>
 443
 444       <para>
 445         One area of note is the markup required for
 446         <literal>@file</literal> markup in header files. Two details
 447         are important: for filenames that have the same name in
 448         multiple directories, include part of the installed path to
 449         disambiguate. For example:
 450       </para>
 451
 452       <para>
 453 <literallayout class="normal">
 454 /** @file debug/vector
 455  *  This file is a GNU debug extension to the Standard C++ Library.
 456  */
 457 </literallayout>
 458       </para>
 459
 460       <para>
 461         The other relevant detail for header files is the use of a
 462         libstdc++-specific doxygen alias that helps distinguish
 463         between public header files (like <filename>random</filename>)
 464         from implementation or private header files (like
 465         <filename>bits/c++config.h</filename>.) This alias is spelled
 466         <literal>@headername</literal> and can take one or two
 467         arguments that detail the public header file or files that
 468         should be included to use the contents of the file. All header
 469         files that are not intended for direct inclusion must use
 470         <literal>headername</literal> in the <literal>file</literal>
 471         block. An example:
 472       </para>
 473
 474       <para>
 475 <literallayout class="normal">
 476 /** @file bits/basic_string.h
 477  *  This is an internal header file, included by other library headers.
 478  *  Do not attempt to use it directly. @headername{string}
 479  */
 480 </literallayout>
 481       </para>
 482
 483       <para>
 484         Be careful about using certain, special characters when
 485         writing Doxygen comments. Single and double quotes, and
 486         separators in filenames are two common trouble spots. When in
 487         doubt, consult the following table.
 488       </para>
 489
 490 <table frame="all">
 491 <title>HTML to Doxygen Markup Comparison</title>
 492
 493 <tgroup cols="2" align="left" colsep="1" rowsep="1">
 494 <colspec colname="c1"/>
 495 <colspec colname="c2"/>
 496
 497   <thead>
 498     <row>
 499       <entry>HTML</entry>
 500       <entry>Doxygen</entry>
 501     </row>
 502   </thead>
 503
 504   <tbody>
 505     <row>
 506       <entry>\</entry>
 507       <entry>\\</entry>
 508     </row>
 509
 510     <row>
 511       <entry>"</entry>
 512       <entry>\"</entry>
 513     </row>
 514
 515     <row>
 516       <entry>'</entry>
 517       <entry>\'</entry>
 518     </row>
 519
 520     <row>
 521       <entry>&lt;i&gt;</entry>
 522       <entry>@a word</entry>
 523     </row>
 524
 525     <row>
 526       <entry>&lt;b&gt;</entry>
 527       <entry>@b word</entry>
 528     </row>
 529
 530     <row>
 531       <entry>&lt;code&gt;</entry>
 532       <entry>@c word</entry>
 533     </row>
 534
 535     <row>
 536       <entry>&lt;em&gt;</entry>
 537       <entry>@a word</entry>
 538     </row>
 539
 540     <row>
 541       <entry>&lt;em&gt;</entry>
 542       <entry>&lt;em&gt;two words or more&lt;/em&gt;</entry>
 543     </row>
 544   </tbody>
 545
 546 </tgroup>
 547 </table>
 548
 549
 550     </section>
 551
 552   </section>
 553
 554   <section xml:id="doc.docbook"><info><title>Docbook</title></info>
 555
 556
 557     <section xml:id="docbook.prereq"><info><title>Prerequisites</title></info>
 558
 559
 560  <table frame="all">
 561 <title>Docbook Prerequisites</title>
 562
 563 <tgroup cols="3" align="center" colsep="1" rowsep="1">
 564 <colspec colname="c1"/>
 565 <colspec colname="c2"/>
 566 <colspec colname="c3"/>
 567
 568   <thead>
 569     <row>
 570       <entry>Tool</entry>
 571       <entry>Version</entry>
 572       <entry>Required By</entry>
 573     </row>
 574   </thead>
 575
 576   <tbody>
 577
 578     <row>
 579       <entry>docbook5-style-xsl</entry>
 580       <entry>1.76.1</entry>
 581       <entry>all</entry>
 582     </row>
 583
 584     <row>
 585       <entry>xsltproc</entry>
 586       <entry>1.1.26</entry>
 587       <entry>all</entry>
 588     </row>
 589
 590     <row>
 591       <entry>xmllint</entry>
 592       <entry>2.7.7</entry>
 593       <entry>validation</entry>
 594     </row>
 595
 596     <row>
 597       <entry>dblatex</entry>
 598       <entry>0.3</entry>
 599       <entry>pdf output</entry>
 600     </row>
 601
 602     <row>
 603       <entry>pdflatex</entry>
 604       <entry>2007-59</entry>
 605       <entry>pdf output</entry>
 606     </row>
 607
 608     <row>
 609       <entry>docbook2X</entry>
 610       <entry>0.8.8</entry>
 611       <entry>info output</entry>
 612     </row>
 613
 614   </tbody>
 615 </tgroup>
 616 </table>
 617
 618       <para>
 619         Editing the DocBook sources requires an XML editor. Many
 620         exist: some notable options
 621         include <command>emacs</command>, <application>Kate</application>,
 622         or <application>Conglomerate</application>.
 623       </para>
 624
 625       <para>
 626         Some editors support special <quote>XML Validation</quote>
 627         modes that can validate the file as it is
 628         produced. Recommended is the <command>nXML Mode</command>
 629         for <command>emacs</command>.
 630       </para>
 631
 632       <para>
 633         Besides an editor, additional DocBook files and XML tools are
 634         also required.
 635       </para>
 636
 637       <para>
 638         Access to the DocBook 5.0 stylesheets and schema is required. The
 639         stylesheets are usually packaged by vendor, in something
 640         like <filename>docbook5-style-xsl</filename>. To exactly match
 641         generated output, please use a version of the stylesheets
 642         equivalent
 643         to <filename>docbook5-style-xsl-1.75.2-3</filename>. The
 644         installation directory for this package corresponds to
 645         the <literal>XSL_STYLE_DIR</literal>
 646         in <filename>doc/Makefile.am</filename> and defaults
 647         to <filename class="directory">/usr/share/sgml/docbook/xsl-ns-stylesheets</filename>.
 648       </para>
 649
 650       <para>
 651         For processing XML, an XML processor and some style
 652         sheets are necessary. Defaults are <command>xsltproc</command>
 653         provided by <filename>libxslt</filename>.
 654       </para>
 655
 656       <para>
 657         For validating the XML document, you'll need
 658         something like <command>xmllint</command> and access to the
 659         relevant DocBook schema. These are provided
 660         by a vendor package like <filename>libxml2</filename> and <filename>docbook5-schemas-5.0-4</filename>
 661       </para>
 662
 663       <para>
 664         For PDF output, something that transforms valid Docbook XML to PDF is
 665         required. Possible solutions include <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://dblatex.sourceforge.net">dblatex</link>,
 666         <command>xmlto</command>, or <command>prince</command>. Of
 667         these, <command>dblatex</command> is the default. Other
 668         options are listed on the DocBook web <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://wiki.docbook.org/topic/DocBookPublishingTools">pages</link>. Please
 669         consult the <email>libstdc++@gcc.gnu.org</email> list when
 670         preparing printed manuals for current best practice and
 671         suggestions.
 672       </para>
 673
 674       <para>
 675         For Texinfo output, something that transforms valid Docbook
 676         XML to Texinfo is required. The default choice is <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://docbook2x.sourceforge.net/">docbook2X</link>.
 677       </para>
 678     </section>
 679
 680     <section xml:id="docbook.rules"><info><title>Generating the DocBook Files</title></info>
 681
 682
 683       <para>
 684         The following Makefile rules generate (in order): an HTML
 685         version of all the DocBook documentation, a PDF version of the
 686         same, and a single XML document.  These rules are not
 687         conditional! If the required tools are not found, or are the
 688         wrong versions, the rule may end in an error.
 689       </para>
 690
 691       <para>
 692       <screen><userinput>make doc-html-docbook</userinput></screen>
 693       </para>
 694
 695       <para>
 696       <screen><userinput>make doc-pdf-docbook</userinput></screen>
 697       </para>
 698
 699       <para>
 700       <screen><userinput>make doc-xml-single-docbook</userinput></screen>
 701       </para>
 702
 703       <para>
 704         Generated files are output into separate sub directores of
 705         <filename class="directory">doc/docbook/</filename> in the
 706         build directory, based on the output format. For instance, the
 707         HTML docs will be in <filename
 708         class="directory">doc/docbook/html</filename>.
 709       </para>
 710
 711       <para>
 712         If the Docbook stylesheets are installed in a custom location,
 713         one can use the variable <literal>XSL_STYLE_DIR</literal> to
 714         over-ride the Makefile defaults. As so:
 715       </para>
 716
 717       <screen>
 718         <userinput>
 719 make <literal>XSL_STYLE_DIR="/usr/share/xml/docbook/stylesheet/nwalsh"</literal> doc-html-docbook
 720         </userinput>
 721       </screen>
 722
 723       </section>
 724
 725     <section xml:id="docbook.validation"><info><title>Editing and Validation</title></info>
 726
 727       <para>
 728         After editing the xml sources, please make sure that the XML
 729         documentation and markup is still valid. This can be
 730         done easily, with the following validation rule:
 731       </para>
 732
 733       <screen>
 734         <userinput>make doc-xml-validate-docbook</userinput>
 735       </screen>
 736
 737       <para>
 738         This is equivalent to doing:
 739       </para>
 740
 741       <screen>
 742         <userinput>
 743           xmllint --noout --valid <filename>xml/index.xml</filename>
 744         </userinput>
 745       </screen>
 746
 747       <para>
 748         Please note that individual sections and chapters of the
 749         manual can be validated by substituting the file desired for
 750         <filename>xml/index.xml</filename> in the command
 751         above. Reducing scope in this manner can be helpful when
 752         validation on the entire manual fails.
 753       </para>
 754
 755       <para>
 756         All Docbook xml sources should always validate. No excuses!
 757       </para>
 758
 759     </section>
 760
 761     <section xml:id="docbook.examples"><info><title>File Organization and Basics</title></info>
 762
 763
 764     <literallayout class="normal">
 765       <emphasis>Which files are important</emphasis>
 766
 767       All Docbook files are in the directory
 768       libstdc++-v3/doc/xml
 769
 770       Inside this directory, the files of importance:
 771       spine.xml         - index to documentation set
 772       manual/spine.xml  - index to manual
 773       manual/*.xml      - individual chapters and sections of the manual
 774       faq.xml           - index to FAQ
 775       api.xml           - index to source level / API
 776
 777       All *.txml files are template xml files, i.e., otherwise empty files with
 778       the correct structure, suitable for filling in with new information.
 779
 780       <emphasis>Canonical Writing Style</emphasis>
 781
 782       class template
 783       function template
 784       member function template
 785       (via C++ Templates, Vandevoorde)
 786
 787       class in namespace std: allocator, not std::allocator
 788
 789       header file: iostream, not &lt;iostream&gt;
 790
 791
 792       <emphasis>General structure</emphasis>
 793
 794       &lt;set&gt;
 795       &lt;book&gt;
 796       &lt;/book&gt;
 797
 798       &lt;book&gt;
 799       &lt;chapter&gt;
 800       &lt;/chapter&gt;
 801       &lt;/book&gt;
 802
 803       &lt;book&gt;
 804       &lt;part&gt;
 805       &lt;chapter&gt;
 806       &lt;section&gt;
 807       &lt;/section&gt;
 808
 809       &lt;sect1&gt;
 810       &lt;/sect1&gt;
 811
 812       &lt;sect1&gt;
 813       &lt;sect2&gt;
 814       &lt;/sect2&gt;
 815       &lt;/sect1&gt;
 816       &lt;/chapter&gt;
 817
 818       &lt;chapter&gt;
 819       &lt;/chapter&gt;
 820       &lt;/part&gt;
 821       &lt;/book&gt;
 822
 823       &lt;/set&gt;
 824     </literallayout>
 825     </section>
 826
 827     <section xml:id="docbook.markup"><info><title>Markup By Example</title></info>
 828
 829
 830       <para>
 831         Complete details on Docbook markup can be found in the DocBook
 832         Element Reference,
 833         <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.docbook.org/tdg/en/html/part2.html">online</link>.
 834         An incomplete reference for HTML to Docbook conversion is
 835         detailed in the table below.
 836       </para>
 837
 838 <table frame="all">
 839 <title>HTML to Docbook XML Markup Comparison</title>
 840
 841 <tgroup cols="2" align="left" colsep="1" rowsep="1">
 842 <colspec colname="c1"/>
 843 <colspec colname="c2"/>
 844
 845   <thead>
 846     <row>
 847       <entry>HTML</entry>
 848       <entry>Docbook</entry>
 849     </row>
 850   </thead>
 851
 852   <tbody>
 853     <row>
 854       <entry>&lt;p&gt;</entry>
 855       <entry>&lt;para&gt;</entry>
 856     </row>
 857     <row>
 858       <entry>&lt;pre&gt;</entry>
 859       <entry>&lt;computeroutput&gt;, &lt;programlisting&gt;,
 860         &lt;literallayout&gt;</entry>
 861     </row>
 862     <row>
 863       <entry>&lt;ul&gt;</entry>
 864       <entry>&lt;itemizedlist&gt;</entry>
 865     </row>
 866     <row>
 867       <entry>&lt;ol&gt;</entry>
 868       <entry>&lt;orderedlist&gt;</entry>
 869     </row>
 870     <row>
 871       <entry>&lt;il&gt;</entry>
 872       <entry>&lt;listitem&gt;</entry>
 873     </row>
 874     <row>
 875       <entry>&lt;dl&gt;</entry>
 876       <entry>&lt;variablelist&gt;</entry>
 877     </row>
 878     <row>
 879       <entry>&lt;dt&gt;</entry>
 880       <entry>&lt;term&gt;</entry>
 881     </row>
 882     <row>
 883       <entry>&lt;dd&gt;</entry>
 884       <entry>&lt;listitem&gt;</entry>
 885     </row>
 886
 887     <row>
 888       <entry>&lt;a href=""&gt;</entry>
 889       <entry>&lt;ulink url=""&gt;</entry>
 890     </row>
 891     <row>
 892       <entry>&lt;code&gt;</entry>
 893       <entry>&lt;literal&gt;, &lt;programlisting&gt;</entry>
 894     </row>
 895     <row>
 896       <entry>&lt;strong&gt;</entry>
 897       <entry>&lt;emphasis&gt;</entry>
 898     </row>
 899     <row>
 900       <entry>&lt;em&gt;</entry>
 901       <entry>&lt;emphasis&gt;</entry>
 902     </row>
 903     <row>
 904       <entry>"</entry>
 905       <entry>&lt;quote&gt;</entry>
 906     </row>
 907    </tbody>
 908 </tgroup>
 909 </table>
 910
 911 <para>
 912   And examples of detailed markup for which there are no real HTML
 913   equivalents are listed in the table below.
 914 </para>
 915
 916 <table frame="all">
 917 <title>Docbook XML Element Use</title>
 918
 919 <tgroup cols="2" align="left" colsep="1" rowsep="1">
 920 <colspec colname="c1"/>
 921 <colspec colname="c2"/>
 922
 923   <thead>
 924     <row>
 925       <entry>Element</entry>
 926       <entry>Use</entry>
 927     </row>
 928   </thead>
 929
 930   <tbody>
 931     <row>
 932       <entry>&lt;structname&gt;</entry>
 933       <entry>&lt;structname&gt;char_traits&lt;/structname&gt;</entry>
 934     </row>
 935     <row>
 936       <entry>&lt;classname&gt;</entry>
 937       <entry>&lt;classname&gt;string&lt;/classname&gt;</entry>
 938     </row>
 939     <row>
 940       <entry>&lt;function&gt;</entry>
 941       <entry>
 942         <para>&lt;function&gt;clear()&lt;/function&gt;</para>
 943         <para>&lt;function&gt;fs.clear()&lt;/function&gt;</para>
 944       </entry>
 945     </row>
 946     <row>
 947       <entry>&lt;type&gt;</entry>
 948       <entry>&lt;type&gt;long long&lt;/type&gt;</entry>
 949     </row>
 950     <row>
 951       <entry>&lt;varname&gt;</entry>
 952       <entry>&lt;varname&gt;fs&lt;/varname&gt;</entry>
 953     </row>
 954     <row>
 955       <entry>&lt;literal&gt;</entry>
 956       <entry>
 957         <para>&lt;literal&gt;-Weffc++&lt;/literal&gt;</para>
 958         <para>&lt;literal&gt;rel_ops&lt;/literal&gt;</para>
 959       </entry>
 960     </row>
 961     <row>
 962       <entry>&lt;constant&gt;</entry>
 963       <entry>
 964         <para>&lt;constant&gt;_GNU_SOURCE&lt;/constant&gt;</para>
 965         <para>&lt;constant&gt;3.0&lt;/constant&gt;</para>
 966       </entry>
 967     </row>
 968     <row>
 969       <entry>&lt;command&gt;</entry>
 970       <entry>&lt;command&gt;g++&lt;/command&gt;</entry>
 971     </row>
 972     <row>
 973       <entry>&lt;errortext&gt;</entry>
 974       <entry>&lt;errortext&gt;In instantiation of&lt;/errortext&gt;</entry>
 975     </row>
 976     <row>
 977       <entry>&lt;filename&gt;</entry>
 978       <entry>
 979         <para>&lt;filename class="headerfile"&gt;ctype.h&lt;/filename&gt;</para>
 980         <para>&lt;filename class="directory"&gt;/home/gcc/build&lt;/filename&gt;</para>
 981         <para>&lt;filename class="libraryfile"&gt;libstdc++.so&lt;/filename&gt;</para>
 982       </entry>
 983     </row>
 984    </tbody>
 985 </tgroup>
 986 </table>
 987
 988 </section>
 989 </section>
 990 </section>