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.6.1</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
 284       <para>
 285         Be warned the PDF file generated via doxygen is extremely
 286         large. At last count, the PDF file is over three thousand
 287         pages. Generating this document taxes the underlying TeX
 288         formatting system, and will require the expansion of TeX's memory
 289         capacity. Specifically, the <literal>pool_size</literal>
 290         variable in the configuration file <filename>texmf.cnf</filename> may
 291         need to be increased by a minimum factor of two.
 292       </para>
 293     </section>
 294
 295     <section xml:id="doxygen.rules"><info><title>Generating the Doxygen Files</title></info>
 296
 297       <para>
 298         The following Makefile rules run Doxygen to generate HTML
 299         docs, XML docs, XML docs as a single file, PDF docs, and the
 300         man pages. These rules are not conditional! If the required
 301         tools are not found, or are the wrong versions, the rule may
 302         end in an error.
 303       </para>
 304
 305       <para>
 306       <screen><userinput>make doc-html-doxygen</userinput></screen>
 307       </para>
 308
 309       <para>
 310       <screen><userinput>make doc-xml-doxygen</userinput></screen>
 311       </para>
 312
 313       <para>
 314       <screen><userinput>make doc-xml-single-doxygen</userinput></screen>
 315       </para>
 316
 317       <para>
 318       <screen><userinput>make doc-pdf-doxygen</userinput></screen>
 319       </para>
 320
 321       <para>
 322       <screen><userinput>make doc-man-doxygen</userinput></screen>
 323       </para>
 324
 325       <para>
 326         Generated files are output into separate sub directories of
 327         <filename class="directory">doc/doxygen/</filename> in the
 328         build directory, based on the output format. For instance, the
 329         HTML docs will be in <filename class="directory">doc/doxygen/html</filename>.
 330       </para>
 331
 332       <para>
 333         Careful observers will see that the Makefile rules simply call
 334         a script from the source tree, <filename>run_doxygen</filename>, which
 335         does the actual work of running Doxygen and then (most
 336         importantly) massaging the output files. If for some reason
 337         you prefer to not go through the Makefile, you can call this
 338         script directly. (Start by passing <literal>--help</literal>.)
 339       </para>
 340
 341       <para>
 342         If you wish to tweak the Doxygen settings, do so by editing
 343         <filename>doc/doxygen/user.cfg.in</filename>. Notes to fellow
 344         library hackers are written in triple-# comments.
 345       </para>
 346
 347     </section>
 348
 349     <section xml:id="doxygen.markup"><info><title>Markup</title></info>
 350
 351
 352       <para>
 353         In general, libstdc++ files should be formatted according to
 354         the rules found in the
 355         <link linkend="contrib.coding_style">Coding Standard</link>. Before
 356         any doxygen-specific formatting tweaks are made, please try to
 357         make sure that the initial formatting is sound.
 358       </para>
 359
 360       <para>
 361         Adding Doxygen markup to a file (informally called
 362         <quote>doxygenating</quote>) is very simple. The Doxygen manual can be
 363         found
 364         <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.stack.nl/~dimitri/doxygen/download.html#latestman">here</link>.
 365         We try to use a very-recent version of Doxygen.
 366       </para>
 367
 368       <para>
 369         For classes, use
 370         <classname>deque</classname>/<classname>vector</classname>/<classname>list</classname>
 371         and <classname>std::pair</classname> as examples.  For
 372         functions, see their member functions, and the free functions
 373         in <filename>stl_algobase.h</filename>. Member functions of
 374         other container-like types should read similarly to these
 375         member functions.
 376       </para>
 377
 378       <para>
 379         Some commentary to accompany
 380         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
 381         Documentation Blocks</link> section of
 382         the Doxygen manual:
 383       </para>
 384
 385       <orderedlist inheritnum="ignore" continuation="restarts">
 386         <listitem>
 387           <para>For longer comments, use the Javadoc style...</para>
 388         </listitem>
 389
 390         <listitem>
 391           <para>
 392             ...not the Qt style. The intermediate *'s are preferred.
 393           </para>
 394         </listitem>
 395
 396         <listitem>
 397           <para>
 398             Use the triple-slash style only for one-line comments (the
 399             <quote>brief</quote> mode).
 400           </para>
 401         </listitem>
 402
 403         <listitem>
 404           <para>
 405             This is disgusting. Don't do this.
 406           </para>
 407         </listitem>
 408       </orderedlist>
 409
 410       <para>
 411         Some specific guidelines:
 412       </para>
 413
 414       <para>
 415         Use the @-style of commands, not the !-style. Please be
 416         careful about whitespace in your markup comments. Most of the
 417         time it doesn't matter; doxygen absorbs most whitespace, and
 418         both HTML and *roff are agnostic about whitespace. However,
 419         in &lt;pre&gt; blocks and @code/@endcode sections, spacing can
 420         have <quote>interesting</quote> effects.
 421       </para>
 422
 423       <para>
 424         Use either kind of grouping, as
 425         appropriate. <filename>doxygroups.cc</filename> exists for this
 426         purpose. See <filename>stl_iterator.h</filename> for a good example
 427         of the <quote>other</quote> kind of grouping.
 428       </para>
 429
 430       <para>
 431         Please use markup tags like @p and @a when referring to things
 432         such as the names of function parameters. Use @e for emphasis
 433         when necessary. Use @c to refer to other standard names.
 434         (Examples of all these abound in the present code.)
 435       </para>
 436
 437       <para>
 438         Complicated math functions should use the multi-line
 439         format. An example from <filename>random.h</filename>:
 440       </para>
 441
 442       <para>
 443 <literallayout class="normal">
 444 /**
 445  * @brief A model of a linear congruential random number generator.
 446  *
 447  * @f[
 448  *     x_{i+1}\leftarrow(ax_{i} + c) \bmod m
 449  * @f]
 450  */
 451 </literallayout>
 452       </para>
 453
 454       <para>
 455         One area of note is the markup required for
 456         <literal>@file</literal> markup in header files. Two details
 457         are important: for filenames that have the same name in
 458         multiple directories, include part of the installed path to
 459         disambiguate. For example:
 460       </para>
 461
 462       <para>
 463 <literallayout class="normal">
 464 /** @file debug/vector
 465  *  This file is a GNU debug extension to the Standard C++ Library.
 466  */
 467 </literallayout>
 468       </para>
 469
 470       <para>
 471         The other relevant detail for header files is the use of a
 472         libstdc++-specific doxygen alias that helps distinguish
 473         between public header files (like <filename>random</filename>)
 474         from implementation or private header files (like
 475         <filename>bits/c++config.h</filename>.) This alias is spelled
 476         <literal>@headername</literal> and can take one or two
 477         arguments that detail the public header file or files that
 478         should be included to use the contents of the file. All header
 479         files that are not intended for direct inclusion must use
 480         <literal>headername</literal> in the <literal>file</literal>
 481         block. An example:
 482       </para>
 483
 484       <para>
 485 <literallayout class="normal">
 486 /** @file bits/basic_string.h
 487  *  This is an internal header file, included by other library headers.
 488  *  Do not attempt to use it directly. @headername{string}
 489  */
 490 </literallayout>
 491       </para>
 492
 493       <para>
 494         Be careful about using certain, special characters when
 495         writing Doxygen comments. Single and double quotes, and
 496         separators in filenames are two common trouble spots. When in
 497         doubt, consult the following table.
 498       </para>
 499
 500 <table frame="all">
 501 <title>HTML to Doxygen Markup Comparison</title>
 502
 503 <tgroup cols="2" align="left" colsep="1" rowsep="1">
 504 <colspec colname="c1"/>
 505 <colspec colname="c2"/>
 506
 507   <thead>
 508     <row>
 509       <entry>HTML</entry>
 510       <entry>Doxygen</entry>
 511     </row>
 512   </thead>
 513
 514   <tbody>
 515     <row>
 516       <entry>\</entry>
 517       <entry>\\</entry>
 518     </row>
 519
 520     <row>
 521       <entry>"</entry>
 522       <entry>\"</entry>
 523     </row>
 524
 525     <row>
 526       <entry>'</entry>
 527       <entry>\'</entry>
 528     </row>
 529
 530     <row>
 531       <entry>&lt;i&gt;</entry>
 532       <entry>@a word</entry>
 533     </row>
 534
 535     <row>
 536       <entry>&lt;b&gt;</entry>
 537       <entry>@b word</entry>
 538     </row>
 539
 540     <row>
 541       <entry>&lt;code&gt;</entry>
 542       <entry>@c word</entry>
 543     </row>
 544
 545     <row>
 546       <entry>&lt;em&gt;</entry>
 547       <entry>@a word</entry>
 548     </row>
 549
 550     <row>
 551       <entry>&lt;em&gt;</entry>
 552       <entry>&lt;em&gt;two words or more&lt;/em&gt;</entry>
 553     </row>
 554   </tbody>
 555
 556 </tgroup>
 557 </table>
 558
 559
 560     </section>
 561
 562   </section>
 563
 564   <section xml:id="doc.docbook"><info><title>Docbook</title></info>
 565
 566
 567     <section xml:id="docbook.prereq"><info><title>Prerequisites</title></info>
 568
 569
 570  <table frame="all">
 571 <title>Docbook Prerequisites</title>
 572
 573 <tgroup cols="3" align="center" colsep="1" rowsep="1">
 574 <colspec colname="c1"/>
 575 <colspec colname="c2"/>
 576 <colspec colname="c3"/>
 577
 578   <thead>
 579     <row>
 580       <entry>Tool</entry>
 581       <entry>Version</entry>
 582       <entry>Required By</entry>
 583     </row>
 584   </thead>
 585
 586   <tbody>
 587
 588     <row>
 589       <entry>docbook5-style-xsl</entry>
 590       <entry>1.76.1</entry>
 591       <entry>all</entry>
 592     </row>
 593
 594     <row>
 595       <entry>xsltproc</entry>
 596       <entry>1.1.26</entry>
 597       <entry>all</entry>
 598     </row>
 599
 600     <row>
 601       <entry>xmllint</entry>
 602       <entry>2.7.7</entry>
 603       <entry>validation</entry>
 604     </row>
 605
 606     <row>
 607       <entry>dblatex</entry>
 608       <entry>0.3</entry>
 609       <entry>pdf output</entry>
 610     </row>
 611
 612     <row>
 613       <entry>pdflatex</entry>
 614       <entry>2007-59</entry>
 615       <entry>pdf output</entry>
 616     </row>
 617
 618     <row>
 619       <entry>docbook2X</entry>
 620       <entry>0.8.8</entry>
 621       <entry>info output</entry>
 622     </row>
 623
 624     <row>
 625       <entry>epub3 stylesheets</entry>
 626       <entry>b3</entry>
 627       <entry>epub output</entry>
 628     </row>
 629
 630   </tbody>
 631 </tgroup>
 632 </table>
 633
 634       <para>
 635         Editing the DocBook sources requires an XML editor. Many
 636         exist: some notable options
 637         include <command>emacs</command>, <application>Kate</application>,
 638         or <application>Conglomerate</application>.
 639       </para>
 640
 641       <para>
 642         Some editors support special <quote>XML Validation</quote>
 643         modes that can validate the file as it is
 644         produced. Recommended is the <command>nXML Mode</command>
 645         for <command>emacs</command>.
 646       </para>
 647
 648       <para>
 649         Besides an editor, additional DocBook files and XML tools are
 650         also required.
 651       </para>
 652
 653       <para>
 654         Access to the DocBook 5.0 stylesheets and schema is required. The
 655         stylesheets are usually packaged by vendor, in something
 656         like <filename>docbook5-style-xsl</filename>. To exactly match
 657         generated output, please use a version of the stylesheets
 658         equivalent
 659         to <filename>docbook5-style-xsl-1.75.2-3</filename>. The
 660         installation directory for this package corresponds to
 661         the <literal>XSL_STYLE_DIR</literal>
 662         in <filename>doc/Makefile.am</filename> and defaults
 663         to <filename class="directory">/usr/share/sgml/docbook/xsl-ns-stylesheets</filename>.
 664       </para>
 665
 666       <para>
 667         For processing XML, an XSLT processor and some style
 668         sheets are necessary. Defaults are <command>xsltproc</command>
 669         provided by <filename>libxslt</filename>.
 670       </para>
 671
 672       <para>
 673         For validating the XML document, you'll need
 674         something like <command>xmllint</command> and access to the
 675         relevant DocBook schema. These are provided
 676         by a vendor package like <filename>libxml2</filename> and <filename>docbook5-schemas-5.0-4</filename>
 677       </para>
 678
 679       <para>
 680         For PDF output, something that transforms valid Docbook XML to PDF is
 681         required. Possible solutions include <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://dblatex.sourceforge.net">dblatex</link>,
 682         <command>xmlto</command>, or <command>prince</command>. Of
 683         these, <command>dblatex</command> is the default. Other
 684         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
 685         consult the <email>libstdc++@gcc.gnu.org</email> list when
 686         preparing printed manuals for current best practice and
 687         suggestions.
 688       </para>
 689
 690       <para>
 691         For Texinfo output, something that transforms valid Docbook
 692         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>.
 693       </para>
 694
 695       <para>
 696         For epub output, the <link xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:href="http://sourceforge.net/projects/docbook/files/epub3/">stylesheets</link> for EPUB3 are required. These stylesheets are still in development. To validate the created file, <link xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:href="https://code.google.com/p/epubcheck/">epubcheck</link> is necessary.
 697       </para>
 698     </section>
 699
 700     <section xml:id="docbook.rules"><info><title>Generating the DocBook Files</title></info>
 701
 702
 703       <para>
 704         The following Makefile rules generate (in order): an HTML
 705         version of all the DocBook documentation, a PDF version of the
 706         same, and a single XML document.  These rules are not
 707         conditional! If the required tools are not found, or are the
 708         wrong versions, the rule may end in an error.
 709       </para>
 710
 711       <para>
 712       <screen><userinput>make doc-html-docbook</userinput></screen>
 713       </para>
 714
 715       <para>
 716       <screen><userinput>make doc-pdf-docbook</userinput></screen>
 717       </para>
 718
 719       <para>
 720       <screen><userinput>make doc-xml-single-docbook</userinput></screen>
 721       </para>
 722
 723       <para>
 724         Generated files are output into separate sub directores of
 725         <filename class="directory">doc/docbook/</filename> in the
 726         build directory, based on the output format. For instance, the
 727         HTML docs will be in <filename
 728         class="directory">doc/docbook/html</filename>.
 729       </para>
 730
 731       <para>
 732         If the Docbook stylesheets are installed in a custom location,
 733         one can use the variable <literal>XSL_STYLE_DIR</literal> to
 734         override the Makefile defaults. For example:
 735       </para>
 736
 737       <screen>
 738         <userinput>
 739 make <literal>XSL_STYLE_DIR="/usr/share/xml/docbook/stylesheet/nwalsh"</literal> doc-html-docbook
 740         </userinput>
 741       </screen>
 742
 743       </section>
 744
 745     <section xml:id="docbook.validation"><info><title>Editing and Validation</title></info>
 746
 747       <para>
 748         After editing the xml sources, please make sure that the XML
 749         documentation and markup is still valid. This can be
 750         done easily, with the following validation rule:
 751       </para>
 752
 753       <screen>
 754         <userinput>make doc-xml-validate-docbook</userinput>
 755       </screen>
 756
 757       <para>
 758         This is equivalent to doing:
 759       </para>
 760
 761       <screen>
 762         <userinput>
 763           xmllint --noout --valid <filename>xml/index.xml</filename>
 764         </userinput>
 765       </screen>
 766
 767       <para>
 768         Please note that individual sections and chapters of the
 769         manual can be validated by substituting the file desired for
 770         <filename>xml/index.xml</filename> in the command
 771         above. Reducing scope in this manner can be helpful when
 772         validation on the entire manual fails.
 773       </para>
 774
 775       <para>
 776         All Docbook xml sources should always validate. No excuses!
 777       </para>
 778
 779     </section>
 780
 781     <section xml:id="docbook.examples"><info><title>File Organization and Basics</title></info>
 782
 783
 784     <literallayout class="normal">
 785       <emphasis>Which files are important</emphasis>
 786
 787       All Docbook files are in the directory
 788       libstdc++-v3/doc/xml
 789
 790       Inside this directory, the files of importance:
 791       spine.xml         - index to documentation set
 792       manual/spine.xml  - index to manual
 793       manual/*.xml      - individual chapters and sections of the manual
 794       faq.xml           - index to FAQ
 795       api.xml           - index to source level / API
 796
 797       All *.txml files are template xml files, i.e., otherwise empty files with
 798       the correct structure, suitable for filling in with new information.
 799
 800       <emphasis>Canonical Writing Style</emphasis>
 801
 802       class template
 803       function template
 804       member function template
 805       (via C++ Templates, Vandevoorde)
 806
 807       class in namespace std: allocator, not std::allocator
 808
 809       header file: iostream, not &lt;iostream&gt;
 810
 811
 812       <emphasis>General structure</emphasis>
 813
 814       &lt;set&gt;
 815       &lt;book&gt;
 816       &lt;/book&gt;
 817
 818       &lt;book&gt;
 819       &lt;chapter&gt;
 820       &lt;/chapter&gt;
 821       &lt;/book&gt;
 822
 823       &lt;book&gt;
 824       &lt;part&gt;
 825       &lt;chapter&gt;
 826       &lt;section&gt;
 827       &lt;/section&gt;
 828
 829       &lt;sect1&gt;
 830       &lt;/sect1&gt;
 831
 832       &lt;sect1&gt;
 833       &lt;sect2&gt;
 834       &lt;/sect2&gt;
 835       &lt;/sect1&gt;
 836       &lt;/chapter&gt;
 837
 838       &lt;chapter&gt;
 839       &lt;/chapter&gt;
 840       &lt;/part&gt;
 841       &lt;/book&gt;
 842
 843       &lt;/set&gt;
 844     </literallayout>
 845     </section>
 846
 847     <section xml:id="docbook.markup"><info><title>Markup By Example</title></info>
 848
 849
 850       <para>
 851         Complete details on Docbook markup can be found in the DocBook
 852         Element Reference,
 853         <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.docbook.org/tdg/en/html/part2.html">online</link>.
 854         An incomplete reference for HTML to Docbook conversion is
 855         detailed in the table below.
 856       </para>
 857
 858 <table frame="all">
 859 <title>HTML to Docbook XML Markup Comparison</title>
 860
 861 <tgroup cols="2" align="left" colsep="1" rowsep="1">
 862 <colspec colname="c1"/>
 863 <colspec colname="c2"/>
 864
 865   <thead>
 866     <row>
 867       <entry>HTML</entry>
 868       <entry>Docbook</entry>
 869     </row>
 870   </thead>
 871
 872   <tbody>
 873     <row>
 874       <entry>&lt;p&gt;</entry>
 875       <entry>&lt;para&gt;</entry>
 876     </row>
 877     <row>
 878       <entry>&lt;pre&gt;</entry>
 879       <entry>&lt;computeroutput&gt;, &lt;programlisting&gt;,
 880         &lt;literallayout&gt;</entry>
 881     </row>
 882     <row>
 883       <entry>&lt;ul&gt;</entry>
 884       <entry>&lt;itemizedlist&gt;</entry>
 885     </row>
 886     <row>
 887       <entry>&lt;ol&gt;</entry>
 888       <entry>&lt;orderedlist&gt;</entry>
 889     </row>
 890     <row>
 891       <entry>&lt;il&gt;</entry>
 892       <entry>&lt;listitem&gt;</entry>
 893     </row>
 894     <row>
 895       <entry>&lt;dl&gt;</entry>
 896       <entry>&lt;variablelist&gt;</entry>
 897     </row>
 898     <row>
 899       <entry>&lt;dt&gt;</entry>
 900       <entry>&lt;term&gt;</entry>
 901     </row>
 902     <row>
 903       <entry>&lt;dd&gt;</entry>
 904       <entry>&lt;listitem&gt;</entry>
 905     </row>
 906
 907     <row>
 908       <entry>&lt;a href=""&gt;</entry>
 909       <entry>&lt;ulink url=""&gt;</entry>
 910     </row>
 911     <row>
 912       <entry>&lt;code&gt;</entry>
 913       <entry>&lt;literal&gt;, &lt;programlisting&gt;</entry>
 914     </row>
 915     <row>
 916       <entry>&lt;strong&gt;</entry>
 917       <entry>&lt;emphasis&gt;</entry>
 918     </row>
 919     <row>
 920       <entry>&lt;em&gt;</entry>
 921       <entry>&lt;emphasis&gt;</entry>
 922     </row>
 923     <row>
 924       <entry>"</entry>
 925       <entry>&lt;quote&gt;</entry>
 926     </row>
 927    </tbody>
 928 </tgroup>
 929 </table>
 930
 931 <para>
 932   And examples of detailed markup for which there are no real HTML
 933   equivalents are listed in the table below.
 934 </para>
 935
 936 <table frame="all">
 937 <title>Docbook XML Element Use</title>
 938
 939 <tgroup cols="2" align="left" colsep="1" rowsep="1">
 940 <colspec colname="c1"/>
 941 <colspec colname="c2"/>
 942
 943   <thead>
 944     <row>
 945       <entry>Element</entry>
 946       <entry>Use</entry>
 947     </row>
 948   </thead>
 949
 950   <tbody>
 951     <row>
 952       <entry>&lt;structname&gt;</entry>
 953       <entry>&lt;structname&gt;char_traits&lt;/structname&gt;</entry>
 954     </row>
 955     <row>
 956       <entry>&lt;classname&gt;</entry>
 957       <entry>&lt;classname&gt;string&lt;/classname&gt;</entry>
 958     </row>
 959     <row>
 960       <entry>&lt;function&gt;</entry>
 961       <entry>
 962         <para>&lt;function&gt;clear()&lt;/function&gt;</para>
 963         <para>&lt;function&gt;fs.clear()&lt;/function&gt;</para>
 964       </entry>
 965     </row>
 966     <row>
 967       <entry>&lt;type&gt;</entry>
 968       <entry>&lt;type&gt;long long&lt;/type&gt;</entry>
 969     </row>
 970     <row>
 971       <entry>&lt;varname&gt;</entry>
 972       <entry>&lt;varname&gt;fs&lt;/varname&gt;</entry>
 973     </row>
 974     <row>
 975       <entry>&lt;literal&gt;</entry>
 976       <entry>
 977         <para>&lt;literal&gt;-Weffc++&lt;/literal&gt;</para>
 978         <para>&lt;literal&gt;rel_ops&lt;/literal&gt;</para>
 979       </entry>
 980     </row>
 981     <row>
 982       <entry>&lt;constant&gt;</entry>
 983       <entry>
 984         <para>&lt;constant&gt;_GNU_SOURCE&lt;/constant&gt;</para>
 985         <para>&lt;constant&gt;3.0&lt;/constant&gt;</para>
 986       </entry>
 987     </row>
 988     <row>
 989       <entry>&lt;command&gt;</entry>
 990       <entry>&lt;command&gt;g++&lt;/command&gt;</entry>
 991     </row>
 992     <row>
 993       <entry>&lt;errortext&gt;</entry>
 994       <entry>&lt;errortext&gt;In instantiation of&lt;/errortext&gt;</entry>
 995     </row>
 996     <row>
 997       <entry>&lt;filename&gt;</entry>
 998       <entry>
 999         <para>&lt;filename class="headerfile"&gt;ctype.h&lt;/filename&gt;</para>
1000         <para>&lt;filename class="directory"&gt;/home/gcc/build&lt;/filename&gt;</para>
1001         <para>&lt;filename class="libraryfile"&gt;libstdc++.so&lt;/filename&gt;</para>
1002       </entry>
1003     </row>
1004    </tbody>
1005 </tgroup>
1006 </table>
1007
1008 </section>
1009 </section>
1010 </section>