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>doc/libstdc++/libstdc++-api.html</filename>
 106           </para>
 107           <para>
 108             <filename>doc/libstdc++/libstdc++-manual.html</filename>
 109           </para>
 110         </listitem>
 111       </varlistentry>
 112
 113       <varlistentry>
 114         <term>
 115           <emphasis>make pdf</emphasis>
 116         </term>
 117         <term>
 118           <emphasis>make install-pdf</emphasis>
 119         </term>
 120         <listitem>
 121           <para>
 122             Generates indexed PDF documentation, and installs it as
 123             the following files:
 124           </para>
 125           <para>
 126             <filename>doc/libstdc++/libstdc++-api.pdf</filename>
 127           </para>
 128           <para>
 129             <filename>doc/libstdc++/libstdc++-manual.pdf</filename>
 130           </para>
 131         </listitem>
 132       </varlistentry>
 133
 134       <varlistentry>
 135         <term>
 136           <emphasis>make man</emphasis>
 137         </term>
 138         <term>
 139           <emphasis>make install-man</emphasis>
 140         </term>
 141         <listitem>
 142           <para>
 143             Generates man pages, and installs it in the following directory:
 144           </para>
 145           <para>
 146             <filename class="directory">man/man3/</filename>
 147           </para>
 148           <para>
 149             The generated man pages are namespace-qualified, so to look at
 150             the man page for <classname>vector</classname>, one would use
 151             <command>man std::vector</command>.
 152           </para>
 153         </listitem>
 154       </varlistentry>
 155
 156       <varlistentry>
 157         <term>
 158           <emphasis>make epub</emphasis>
 159         </term>
 160         <term>
 161           <emphasis>make install-epub</emphasis>
 162         </term>
 163         <listitem>
 164           <para>
 165             Generates documentation in the ebook/portable electronic
 166             reader format called Epub, and installs it as the
 167             following file.
 168           </para>
 169           <para>
 170             <filename>doc/libstdc++/libstdc++-manual.epub</filename>
 171           </para>
 172         </listitem>
 173       </varlistentry>
 174
 175       <varlistentry>
 176         <term>
 177           <emphasis>make xml</emphasis>
 178         </term>
 179         <term>
 180           <emphasis>make install-xml</emphasis>
 181         </term>
 182         <listitem>
 183           <para>
 184             Generates single-file XML documentation, and installs it
 185             as the following files:
 186           </para>
 187           <para>
 188             <filename>doc/libstdc++/libstdc++-api-single.xml</filename>
 189           </para>
 190           <para>
 191             <filename>doc/libstdc++/libstdc++-manual-single.xml</filename>
 192           </para>
 193         </listitem>
 194       </varlistentry>
 195     </variablelist>
 196
 197     <para>
 198       Makefile rules for several other formats are explicitly not
 199       supported, and are always aliased to dummy rules. These
 200       unsupported formats are: <emphasis>info</emphasis>,
 201       <emphasis>ps</emphasis>, and <emphasis>dvi</emphasis>.
 202     </para>
 203   </section>
 204
 205   <section xml:id="doc.doxygen"><info><title>Doxygen</title></info>
 206
 207     <section xml:id="doxygen.prereq"><info><title>Prerequisites</title></info>
 208
 209  <table frame="all">
 210 <title>Doxygen Prerequisites</title>
 211
 212 <tgroup cols="3" align="center" colsep="1" rowsep="1">
 213 <colspec colname="c1"/>
 214 <colspec colname="c2"/>
 215 <colspec colname="c3"/>
 216
 217   <thead>
 218     <row>
 219       <entry>Tool</entry>
 220       <entry>Version</entry>
 221       <entry>Required By</entry>
 222     </row>
 223   </thead>
 224
 225   <tbody>
 226
 227     <row>
 228       <entry>coreutils</entry>
 229       <entry>8.5</entry>
 230       <entry>all</entry>
 231     </row>
 232
 233     <row>
 234       <entry>bash</entry>
 235       <entry>4.1</entry>
 236       <entry>all</entry>
 237     </row>
 238
 239     <row>
 240       <entry>doxygen</entry>
 241       <entry>1.7.6.1</entry>
 242       <entry>all</entry>
 243     </row>
 244
 245     <row>
 246       <entry>graphviz</entry>
 247       <entry>2.26</entry>
 248       <entry>graphical hierarchies</entry>
 249     </row>
 250
 251     <row>
 252       <entry>pdflatex</entry>
 253       <entry>2007-59</entry>
 254       <entry>pdf output</entry>
 255     </row>
 256
 257   </tbody>
 258 </tgroup>
 259 </table>
 260
 261
 262       <para>
 263         Prerequisite tools are Bash 2.0 or later,
 264         <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.doxygen.org/">Doxygen</link>, and
 265         the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.gnu.org/software/coreutils/">GNU
 266         coreutils</link>. (GNU versions of find, xargs, and possibly
 267         sed and grep are used, just because the GNU versions make
 268         things very easy.)
 269       </para>
 270
 271       <para>
 272         To generate the pretty pictures and hierarchy
 273         graphs, the
 274         <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.graphviz.org">Graphviz</link> package
 275         will need to be installed. For PDF
 276         output, <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.tug.org/applications/pdftex/">
 277         pdflatex</link> is required.
 278       </para>
 279
 280       <para>
 281         Be warned the PDF file generated via doxygen is extremely
 282         large. At last count, the PDF file is over three thousand
 283         pages. Generating this document taxes the underlying TeX
 284         formatting system, and will require the expansion of TeX's memory
 285         capacity. Specifically, the <literal>pool_size</literal>
 286         variable in the configuration file <filename>texmf.cnf</filename> may
 287         need to be increased by a minimum factor of two.
 288       </para>
 289     </section>
 290
 291     <section xml:id="doxygen.rules"><info><title>Generating the Doxygen Files</title></info>
 292
 293       <para>
 294         The following Makefile rules run Doxygen to generate HTML
 295         docs, XML docs, XML docs as a single file, PDF docs, and the
 296         man pages. These rules are not conditional! If the required
 297         tools are not found, or are the wrong versions, the rule may
 298         end in an error.
 299       </para>
 300
 301       <para>
 302       <screen><userinput>make doc-html-doxygen</userinput></screen>
 303       </para>
 304
 305       <para>
 306       <screen><userinput>make doc-xml-doxygen</userinput></screen>
 307       </para>
 308
 309       <para>
 310       <screen><userinput>make doc-xml-single-doxygen</userinput></screen>
 311       </para>
 312
 313       <para>
 314       <screen><userinput>make doc-pdf-doxygen</userinput></screen>
 315       </para>
 316
 317       <para>
 318       <screen><userinput>make doc-man-doxygen</userinput></screen>
 319       </para>
 320
 321       <para>
 322         Generated files are output into separate sub directories of
 323         <filename class="directory">doc/doxygen/</filename> in the
 324         build directory, based on the output format. For instance, the
 325         HTML docs will be in <filename class="directory">doc/doxygen/html</filename>.
 326       </para>
 327
 328       <para>
 329         Careful observers will see that the Makefile rules simply call
 330         a script from the source tree, <filename>run_doxygen</filename>, which
 331         does the actual work of running Doxygen and then (most
 332         importantly) massaging the output files. If for some reason
 333         you prefer to not go through the Makefile, you can call this
 334         script directly. (Start by passing <literal>--help</literal>.)
 335       </para>
 336
 337       <para>
 338         If you wish to tweak the Doxygen settings, do so by editing
 339         <filename>doc/doxygen/user.cfg.in</filename>. Notes to fellow
 340         library hackers are written in triple-# comments.
 341       </para>
 342
 343     </section>
 344
 345  <section xml:id="doxygen.debug">
 346    <info><title>Debugging Generation</title></info>
 347
 348         <para>
 349           Sometimes, mis-configuration of the pre-requisite tools can
 350           lead to errors when attempting to build the
 351           documentation. Here are some of the obvious errors, and ways
 352           to fix some common issues that may appear quite cryptic.
 353         </para>
 354
 355         <para>
 356           First, if using a rule like <code>make pdf</code>, try to
 357           narrow down the scope of the error to either docbook
 358           (<code>make doc-pdf-docbook</code>) or doxygen (<code>make
 359           doc-pdf-doxygen</code>).
 360         </para>
 361         <para>
 362           Working on the doxygen path only, closely examine the
 363           contents of the following build directory:
 364           <filename>build/target/libstdc++-v3/doc/doxygen/latex</filename>.
 365           Pay attention to three files enclosed within, annotated as follows.
 366         </para>
 367 <itemizedlist>
 368
 369 <listitem>
 370   <para>
 371    <emphasis>refman.tex</emphasis>
 372   </para>
 373
 374   <para>
 375     The actual latex file, or partial latex file. This is generated
 376     via <command>doxygen</command>, and is the LaTeX version of the
 377     Doxygen XML file <filename>libstdc++-api.xml</filename>. Go to a specific
 378     line, and look at the genrated LaTeX, and try to deduce what
 379     markup in <filename>libstdc++-api.xml</filename> is causing it.
 380   </para>
 381 </listitem>
 382
 383 <listitem>
 384   <para>
 385    <emphasis>refman.out</emphasis>
 386   </para>
 387
 388   <para>
 389     A log of the compilation of the converted LaTeX form to pdf. This
 390     is a linear list, from the beginning of the
 391     <filename>refman.tex</filename> file: the last entry of this file
 392     should be the end of the LaTeX file. If it is truncated, then you
 393     know that the last entry is the last part of the generated LaTeX
 394     source file that is valid. Often this file contains an error with
 395     a specific line number of <filename>refman.tex</filename> that is
 396     incorrect, or will have clues at the end of the file with the dump
 397     of the memory usage of LaTeX.
 398   </para>
 399 </listitem>
 400 </itemizedlist>
 401
 402         <para>
 403           If the error at hand is not obvious after examination, a
 404           fall-back strategy is to start commenting out the doxygen
 405           input sources, which can be found in
 406           <filename>doc/doxygen/user.cfg.in</filename>, look for the
 407           <literal>INPUT</literal> tag. Start by commenting out whole
 408           directories of header files, until the offending header is
 409           identified. Then, read the latex log files to try and find
 410           surround text, and look for that in the offending header.
 411         </para>
 412
 413  </section>
 414
 415     <section xml:id="doxygen.markup"><info><title>Markup</title></info>
 416
 417
 418       <para>
 419         In general, libstdc++ files should be formatted according to
 420         the rules found in the
 421         <link linkend="contrib.coding_style">Coding Standard</link>. Before
 422         any doxygen-specific formatting tweaks are made, please try to
 423         make sure that the initial formatting is sound.
 424       </para>
 425
 426       <para>
 427         Adding Doxygen markup to a file (informally called
 428         <quote>doxygenating</quote>) is very simple. The Doxygen manual can be
 429         found
 430         <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.stack.nl/~dimitri/doxygen/download.html#latestman">here</link>.
 431         We try to use a very-recent version of Doxygen.
 432       </para>
 433
 434       <para>
 435         For classes, use
 436         <classname>deque</classname>/<classname>vector</classname>/<classname>list</classname>
 437         and <classname>std::pair</classname> as examples.  For
 438         functions, see their member functions, and the free functions
 439         in <filename>stl_algobase.h</filename>. Member functions of
 440         other container-like types should read similarly to these
 441         member functions.
 442       </para>
 443
 444       <para>
 445         Some commentary to accompany
 446         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
 447         Documentation Blocks</link> section of
 448         the Doxygen manual:
 449       </para>
 450
 451       <orderedlist inheritnum="ignore" continuation="restarts">
 452         <listitem>
 453           <para>For longer comments, use the Javadoc style...</para>
 454         </listitem>
 455
 456         <listitem>
 457           <para>
 458             ...not the Qt style. The intermediate *'s are preferred.
 459           </para>
 460         </listitem>
 461
 462         <listitem>
 463           <para>
 464             Use the triple-slash style only for one-line comments (the
 465             <quote>brief</quote> mode).
 466           </para>
 467         </listitem>
 468
 469         <listitem>
 470           <para>
 471             This is disgusting. Don't do this.
 472           </para>
 473         </listitem>
 474       </orderedlist>
 475
 476       <para>
 477         Some specific guidelines:
 478       </para>
 479
 480       <para>
 481         Use the @-style of commands, not the !-style. Please be
 482         careful about whitespace in your markup comments. Most of the
 483         time it doesn't matter; doxygen absorbs most whitespace, and
 484         both HTML and *roff are agnostic about whitespace. However,
 485         in &lt;pre&gt; blocks and @code/@endcode sections, spacing can
 486         have <quote>interesting</quote> effects.
 487       </para>
 488
 489       <para>
 490         Use either kind of grouping, as
 491         appropriate. <filename>doxygroups.cc</filename> exists for this
 492         purpose. See <filename>stl_iterator.h</filename> for a good example
 493         of the <quote>other</quote> kind of grouping.
 494       </para>
 495
 496       <para>
 497         Please use markup tags like @p and @a when referring to things
 498         such as the names of function parameters. Use @e for emphasis
 499         when necessary. Use @c to refer to other standard names.
 500         (Examples of all these abound in the present code.)
 501       </para>
 502
 503       <para>
 504         Complicated math functions should use the multi-line
 505         format. An example from <filename>random.h</filename>:
 506       </para>
 507
 508       <para>
 509 <literallayout class="normal">
 510 /**
 511  * @brief A model of a linear congruential random number generator.
 512  *
 513  * @f[
 514  *     x_{i+1}\leftarrow(ax_{i} + c) \bmod m
 515  * @f]
 516  */
 517 </literallayout>
 518       </para>
 519
 520       <para>
 521         One area of note is the markup required for
 522         <literal>@file</literal> markup in header files. Two details
 523         are important: for filenames that have the same name in
 524         multiple directories, include part of the installed path to
 525         disambiguate. For example:
 526       </para>
 527
 528       <para>
 529 <literallayout class="normal">
 530 /** @file debug/vector
 531  *  This file is a GNU debug extension to the Standard C++ Library.
 532  */
 533 </literallayout>
 534       </para>
 535
 536       <para>
 537         The other relevant detail for header files is the use of a
 538         libstdc++-specific doxygen alias that helps distinguish
 539         between public header files (like <filename>random</filename>)
 540         from implementation or private header files (like
 541         <filename>bits/c++config.h</filename>.) This alias is spelled
 542         <literal>@headername</literal> and can take one or two
 543         arguments that detail the public header file or files that
 544         should be included to use the contents of the file. All header
 545         files that are not intended for direct inclusion must use
 546         <literal>headername</literal> in the <literal>file</literal>
 547         block. An example:
 548       </para>
 549
 550       <para>
 551 <literallayout class="normal">
 552 /** @file bits/basic_string.h
 553  *  This is an internal header file, included by other library headers.
 554  *  Do not attempt to use it directly. @headername{string}
 555  */
 556 </literallayout>
 557       </para>
 558
 559       <para>
 560         Be careful about using certain, special characters when
 561         writing Doxygen comments. Single and double quotes, and
 562         separators in filenames are two common trouble spots. When in
 563         doubt, consult the following table.
 564       </para>
 565
 566 <table frame="all">
 567 <title>HTML to Doxygen Markup Comparison</title>
 568
 569 <tgroup cols="2" align="left" colsep="1" rowsep="1">
 570 <colspec colname="c1"/>
 571 <colspec colname="c2"/>
 572
 573   <thead>
 574     <row>
 575       <entry>HTML</entry>
 576       <entry>Doxygen</entry>
 577     </row>
 578   </thead>
 579
 580   <tbody>
 581     <row>
 582       <entry>\</entry>
 583       <entry>\\</entry>
 584     </row>
 585
 586     <row>
 587       <entry>"</entry>
 588       <entry>\"</entry>
 589     </row>
 590
 591     <row>
 592       <entry>'</entry>
 593       <entry>\'</entry>
 594     </row>
 595
 596     <row>
 597       <entry>&lt;i&gt;</entry>
 598       <entry>@a word</entry>
 599     </row>
 600
 601     <row>
 602       <entry>&lt;b&gt;</entry>
 603       <entry>@b word</entry>
 604     </row>
 605
 606     <row>
 607       <entry>&lt;code&gt;</entry>
 608       <entry>@c word</entry>
 609     </row>
 610
 611     <row>
 612       <entry>&lt;em&gt;</entry>
 613       <entry>@a word</entry>
 614     </row>
 615
 616     <row>
 617       <entry>&lt;em&gt;</entry>
 618       <entry>&lt;em&gt;two words or more&lt;/em&gt;</entry>
 619     </row>
 620   </tbody>
 621
 622 </tgroup>
 623 </table>
 624
 625
 626     </section>
 627
 628   </section>
 629
 630   <section xml:id="doc.docbook"><info><title>Docbook</title></info>
 631
 632
 633     <section xml:id="docbook.prereq"><info><title>Prerequisites</title></info>
 634
 635
 636  <table frame="all">
 637 <title>Docbook Prerequisites</title>
 638
 639 <tgroup cols="3" align="center" colsep="1" rowsep="1">
 640 <colspec colname="c1"/>
 641 <colspec colname="c2"/>
 642 <colspec colname="c3"/>
 643
 644   <thead>
 645     <row>
 646       <entry>Tool</entry>
 647       <entry>Version</entry>
 648       <entry>Required By</entry>
 649     </row>
 650   </thead>
 651
 652   <tbody>
 653
 654     <row>
 655       <entry>docbook5-style-xsl</entry>
 656       <entry>1.76.1</entry>
 657       <entry>all</entry>
 658     </row>
 659
 660     <row>
 661       <entry>xsltproc</entry>
 662       <entry>1.1.26</entry>
 663       <entry>all</entry>
 664     </row>
 665
 666     <row>
 667       <entry>xmllint</entry>
 668       <entry>2.7.7</entry>
 669       <entry>validation</entry>
 670     </row>
 671
 672     <row>
 673       <entry>dblatex</entry>
 674       <entry>0.3</entry>
 675       <entry>pdf output</entry>
 676     </row>
 677
 678     <row>
 679       <entry>pdflatex</entry>
 680       <entry>2007-59</entry>
 681       <entry>pdf output</entry>
 682     </row>
 683
 684     <row>
 685       <entry>docbook2X</entry>
 686       <entry>0.8.8</entry>
 687       <entry>info output</entry>
 688     </row>
 689
 690     <row>
 691       <entry>epub3 stylesheets</entry>
 692       <entry>b3</entry>
 693       <entry>epub output</entry>
 694     </row>
 695
 696   </tbody>
 697 </tgroup>
 698 </table>
 699
 700       <para>
 701         Editing the DocBook sources requires an XML editor. Many
 702         exist: some notable options
 703         include <command>emacs</command>, <application>Kate</application>,
 704         or <application>Conglomerate</application>.
 705       </para>
 706
 707       <para>
 708         Some editors support special <quote>XML Validation</quote>
 709         modes that can validate the file as it is
 710         produced. Recommended is the <command>nXML Mode</command>
 711         for <command>emacs</command>.
 712       </para>
 713
 714       <para>
 715         Besides an editor, additional DocBook files and XML tools are
 716         also required.
 717       </para>
 718
 719       <para>
 720         Access to the DocBook 5.0 stylesheets and schema is required. The
 721         stylesheets are usually packaged by vendor, in something
 722         like <filename>docbook5-style-xsl</filename>. To exactly match
 723         generated output, please use a version of the stylesheets
 724         equivalent
 725         to <filename>docbook5-style-xsl-1.75.2-3</filename>. The
 726         installation directory for this package corresponds to
 727         the <literal>XSL_STYLE_DIR</literal>
 728         in <filename>doc/Makefile.am</filename> and defaults
 729         to <filename class="directory">/usr/share/sgml/docbook/xsl-ns-stylesheets</filename>.
 730       </para>
 731
 732       <para>
 733         For processing XML, an XSLT processor and some style
 734         sheets are necessary. Defaults are <command>xsltproc</command>
 735         provided by <filename>libxslt</filename>.
 736       </para>
 737
 738       <para>
 739         For validating the XML document, you'll need
 740         something like <command>xmllint</command> and access to the
 741         relevant DocBook schema. These are provided
 742         by a vendor package like <filename>libxml2</filename> and <filename>docbook5-schemas-5.0-4</filename>
 743       </para>
 744
 745       <para>
 746         For PDF output, something that transforms valid Docbook XML to PDF is
 747         required. Possible solutions include <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://dblatex.sourceforge.net">dblatex</link>,
 748         <command>xmlto</command>, or <command>prince</command>. Of
 749         these, <command>dblatex</command> is the default. Other
 750         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
 751         consult the <email>libstdc++@gcc.gnu.org</email> list when
 752         preparing printed manuals for current best practice and
 753         suggestions.
 754       </para>
 755
 756       <para>
 757         For Texinfo output, something that transforms valid Docbook
 758         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>.
 759       </para>
 760
 761       <para>
 762         For epub output, the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink: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" xlink:href="https://code.google.com/p/epubcheck/">epubcheck</link> is necessary.
 763       </para>
 764     </section>
 765
 766     <section xml:id="docbook.rules"><info><title>Generating the DocBook Files</title></info>
 767
 768
 769       <para>
 770         The following Makefile rules generate (in order): an HTML
 771         version of all the DocBook documentation, a PDF version of the
 772         same, and a single XML document.  These rules are not
 773         conditional! If the required tools are not found, or are the
 774         wrong versions, the rule may end in an error.
 775       </para>
 776
 777       <para>
 778       <screen><userinput>make doc-html-docbook</userinput></screen>
 779       </para>
 780
 781       <para>
 782       <screen><userinput>make doc-pdf-docbook</userinput></screen>
 783       </para>
 784
 785       <para>
 786       <screen><userinput>make doc-xml-single-docbook</userinput></screen>
 787       </para>
 788
 789       <para>
 790         Generated files are output into separate sub directores of
 791         <filename class="directory">doc/docbook/</filename> in the
 792         build directory, based on the output format. For instance, the
 793         HTML docs will be in <filename
 794         class="directory">doc/docbook/html</filename>.
 795       </para>
 796
 797       <para>
 798         If the Docbook stylesheets are installed in a custom location,
 799         one can use the variable <literal>XSL_STYLE_DIR</literal> to
 800         override the Makefile defaults. For example:
 801       </para>
 802
 803       <screen>
 804         <userinput>
 805 make <literal>XSL_STYLE_DIR="/usr/share/xml/docbook/stylesheet/nwalsh"</literal> doc-html-docbook
 806         </userinput>
 807       </screen>
 808
 809       </section>
 810
 811     <section xml:id="docbook.debug">
 812         <info><title>Debugging Generation</title></info>
 813
 814         <para>
 815           Sometimes, mis-configuration of the pre-requisite tools can
 816           lead to errors when attempting to build the
 817           documentation. Here are some of the obvious errors, and ways
 818           to fix some common issues that may appear quite cryptic.
 819         </para>
 820
 821         <para>
 822           First, if using a rule like <code>make pdf</code>, try to
 823           narrow down the scope of the error to either docbook
 824           (<code>make doc-pdf-docbook</code>) or doxygen (<code>make
 825           doc-pdf-doxygen</code>).
 826         </para>
 827
 828         <para>
 829           Working on the docbook path only, closely examine the
 830           contents of the following build directory:
 831           <filename>build/target/libstdc++-v3/doc/docbook/latex</filename>.
 832           Pay attention to three files enclosed within, annotated as follows.
 833         </para>
 834
 835 <itemizedlist>
 836
 837 <listitem>
 838   <para>
 839    <emphasis>spine.tex</emphasis>
 840   </para>
 841
 842   <para>
 843     The actual latex file, or partial latex file. This is generated
 844     via <command>dblatex</command>, and is the LaTeX version of the
 845     DocBook XML file <filename>spine.xml</filename>. Go to a specific
 846     line, and look at the genrated LaTeX, and try to deduce what
 847     markup in <filename>spine.xml</filename> is causing it.
 848   </para>
 849 </listitem>
 850
 851 <listitem>
 852   <para>
 853    <emphasis>spine.out</emphasis>
 854   </para>
 855
 856   <para>
 857     A log of the conversion from the XML form to the LaTeX form. This
 858     is a linear list, from the beginning of the
 859     <filename>spine.xml</filename> file: the last entry of this file
 860     should be the end of the DocBook file. If it is truncated, then
 861     you know that the last entry is the last part of the XML source
 862     file that is valid. The error is after this point.
 863   </para>
 864 </listitem>
 865
 866
 867 <listitem>
 868   <para>
 869    <emphasis>spine.log</emphasis>
 870   </para>
 871
 872   <para>
 873     A log of the compilation of the converted LaTeX form to pdf. This
 874     is a linear list, from the beginning of the
 875     <filename>spine.tex</filename> file: the last entry of this file
 876     should be the end of the LaTeX file. If it is truncated, then you
 877     know that the last entry is the last part of the generated LaTeX
 878     source file that is valid. Often this file contains an error with
 879     a specific line number of <filename>spine.tex</filename> that is
 880     incorrect.
 881   </para>
 882 </listitem>
 883
 884 </itemizedlist>
 885
 886         <para>
 887           If the error at hand is not obvious after examination, or if one
 888           encounters the inscruitable <quote>Incomplete
 889           \ifmmode</quote> error, a fall-back strategy is to start
 890           commenting out parts of the XML document (regardless of what
 891           this does to over-all document validity). Start by
 892           commenting out each of the largest parts of the
 893           <filename>spine.xml</filename> file, section by section,
 894           until the offending section is identified.
 895         </para>
 896
 897
 898     </section>
 899
 900     <section xml:id="docbook.validation"><info><title>Editing and Validation</title></info>
 901
 902       <para>
 903         After editing the xml sources, please make sure that the XML
 904         documentation and markup is still valid. This can be
 905         done easily, with the following validation rule:
 906       </para>
 907
 908       <screen>
 909         <userinput>make doc-xml-validate-docbook</userinput>
 910       </screen>
 911
 912       <para>
 913         This is equivalent to doing:
 914       </para>
 915
 916       <screen>
 917         <userinput>
 918           xmllint --noout --valid <filename>xml/index.xml</filename>
 919         </userinput>
 920       </screen>
 921
 922       <para>
 923         Please note that individual sections and chapters of the
 924         manual can be validated by substituting the file desired for
 925         <filename>xml/index.xml</filename> in the command
 926         above. Reducing scope in this manner can be helpful when
 927         validation on the entire manual fails.
 928       </para>
 929
 930       <para>
 931         All Docbook xml sources should always validate. No excuses!
 932       </para>
 933
 934     </section>
 935
 936     <section xml:id="docbook.examples"><info><title>File Organization and Basics</title></info>
 937
 938
 939     <literallayout class="normal">
 940       <emphasis>Which files are important</emphasis>
 941
 942       All Docbook files are in the directory
 943       libstdc++-v3/doc/xml
 944
 945       Inside this directory, the files of importance:
 946       spine.xml         - index to documentation set
 947       manual/spine.xml  - index to manual
 948       manual/*.xml      - individual chapters and sections of the manual
 949       faq.xml           - index to FAQ
 950       api.xml           - index to source level / API
 951
 952       All *.txml files are template xml files, i.e., otherwise empty files with
 953       the correct structure, suitable for filling in with new information.
 954
 955       <emphasis>Canonical Writing Style</emphasis>
 956
 957       class template
 958       function template
 959       member function template
 960       (via C++ Templates, Vandevoorde)
 961
 962       class in namespace std: allocator, not std::allocator
 963
 964       header file: iostream, not &lt;iostream&gt;
 965
 966
 967       <emphasis>General structure</emphasis>
 968
 969       &lt;set&gt;
 970       &lt;book&gt;
 971       &lt;/book&gt;
 972
 973       &lt;book&gt;
 974       &lt;chapter&gt;
 975       &lt;/chapter&gt;
 976       &lt;/book&gt;
 977
 978       &lt;book&gt;
 979       &lt;part&gt;
 980       &lt;chapter&gt;
 981       &lt;section&gt;
 982       &lt;/section&gt;
 983
 984       &lt;sect1&gt;
 985       &lt;/sect1&gt;
 986
 987       &lt;sect1&gt;
 988       &lt;sect2&gt;
 989       &lt;/sect2&gt;
 990       &lt;/sect1&gt;
 991       &lt;/chapter&gt;
 992
 993       &lt;chapter&gt;
 994       &lt;/chapter&gt;
 995       &lt;/part&gt;
 996       &lt;/book&gt;
 997
 998       &lt;/set&gt;
 999     </literallayout>
1000     </section>
1001
1002     <section xml:id="docbook.markup"><info><title>Markup By Example</title></info>
1003
1004
1005       <para>
1006         Complete details on Docbook markup can be found in the DocBook
1007         Element Reference,
1008         <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.docbook.org/tdg/en/html/part2.html">online</link>.
1009         An incomplete reference for HTML to Docbook conversion is
1010         detailed in the table below.
1011       </para>
1012
1013 <table frame="all">
1014 <title>HTML to Docbook XML Markup Comparison</title>
1015
1016 <tgroup cols="2" align="left" colsep="1" rowsep="1">
1017 <colspec colname="c1"/>
1018 <colspec colname="c2"/>
1019
1020   <thead>
1021     <row>
1022       <entry>HTML</entry>
1023       <entry>Docbook</entry>
1024     </row>
1025   </thead>
1026
1027   <tbody>
1028     <row>
1029       <entry>&lt;p&gt;</entry>
1030       <entry>&lt;para&gt;</entry>
1031     </row>
1032     <row>
1033       <entry>&lt;pre&gt;</entry>
1034       <entry>&lt;computeroutput&gt;, &lt;programlisting&gt;,
1035         &lt;literallayout&gt;</entry>
1036     </row>
1037     <row>
1038       <entry>&lt;ul&gt;</entry>
1039       <entry>&lt;itemizedlist&gt;</entry>
1040     </row>
1041     <row>
1042       <entry>&lt;ol&gt;</entry>
1043       <entry>&lt;orderedlist&gt;</entry>
1044     </row>
1045     <row>
1046       <entry>&lt;il&gt;</entry>
1047       <entry>&lt;listitem&gt;</entry>
1048     </row>
1049     <row>
1050       <entry>&lt;dl&gt;</entry>
1051       <entry>&lt;variablelist&gt;</entry>
1052     </row>
1053     <row>
1054       <entry>&lt;dt&gt;</entry>
1055       <entry>&lt;term&gt;</entry>
1056     </row>
1057     <row>
1058       <entry>&lt;dd&gt;</entry>
1059       <entry>&lt;listitem&gt;</entry>
1060     </row>
1061
1062     <row>
1063       <entry>&lt;a href=""&gt;</entry>
1064       <entry>&lt;ulink url=""&gt;</entry>
1065     </row>
1066     <row>
1067       <entry>&lt;code&gt;</entry>
1068       <entry>&lt;literal&gt;, &lt;programlisting&gt;</entry>
1069     </row>
1070     <row>
1071       <entry>&lt;strong&gt;</entry>
1072       <entry>&lt;emphasis&gt;</entry>
1073     </row>
1074     <row>
1075       <entry>&lt;em&gt;</entry>
1076       <entry>&lt;emphasis&gt;</entry>
1077     </row>
1078     <row>
1079       <entry>"</entry>
1080       <entry>&lt;quote&gt;</entry>
1081     </row>
1082    </tbody>
1083 </tgroup>
1084 </table>
1085
1086 <para>
1087   And examples of detailed markup for which there are no real HTML
1088   equivalents are listed in the table below.
1089 </para>
1090
1091 <table frame="all">
1092 <title>Docbook XML Element Use</title>
1093
1094 <tgroup cols="2" align="left" colsep="1" rowsep="1">
1095 <colspec colname="c1"/>
1096 <colspec colname="c2"/>
1097
1098   <thead>
1099     <row>
1100       <entry>Element</entry>
1101       <entry>Use</entry>
1102     </row>
1103   </thead>
1104
1105   <tbody>
1106     <row>
1107       <entry>&lt;structname&gt;</entry>
1108       <entry>&lt;structname&gt;char_traits&lt;/structname&gt;</entry>
1109     </row>
1110     <row>
1111       <entry>&lt;classname&gt;</entry>
1112       <entry>&lt;classname&gt;string&lt;/classname&gt;</entry>
1113     </row>
1114     <row>
1115       <entry>&lt;function&gt;</entry>
1116       <entry>
1117         <para>&lt;function&gt;clear()&lt;/function&gt;</para>
1118         <para>&lt;function&gt;fs.clear()&lt;/function&gt;</para>
1119       </entry>
1120     </row>
1121     <row>
1122       <entry>&lt;type&gt;</entry>
1123       <entry>&lt;type&gt;long long&lt;/type&gt;</entry>
1124     </row>
1125     <row>
1126       <entry>&lt;varname&gt;</entry>
1127       <entry>&lt;varname&gt;fs&lt;/varname&gt;</entry>
1128     </row>
1129     <row>
1130       <entry>&lt;literal&gt;</entry>
1131       <entry>
1132         <para>&lt;literal&gt;-Weffc++&lt;/literal&gt;</para>
1133         <para>&lt;literal&gt;rel_ops&lt;/literal&gt;</para>
1134       </entry>
1135     </row>
1136     <row>
1137       <entry>&lt;constant&gt;</entry>
1138       <entry>
1139         <para>&lt;constant&gt;_GNU_SOURCE&lt;/constant&gt;</para>
1140         <para>&lt;constant&gt;3.0&lt;/constant&gt;</para>
1141       </entry>
1142     </row>
1143     <row>
1144       <entry>&lt;command&gt;</entry>
1145       <entry>&lt;command&gt;g++&lt;/command&gt;</entry>
1146     </row>
1147     <row>
1148       <entry>&lt;errortext&gt;</entry>
1149       <entry>&lt;errortext&gt;In instantiation of&lt;/errortext&gt;</entry>
1150     </row>
1151     <row>
1152       <entry>&lt;filename&gt;</entry>
1153       <entry>
1154         <para>&lt;filename class="headerfile"&gt;ctype.h&lt;/filename&gt;</para>
1155         <para>&lt;filename class="directory"&gt;/home/gcc/build&lt;/filename&gt;</para>
1156         <para>&lt;filename class="libraryfile"&gt;libstdc++.so&lt;/filename&gt;</para>
1157       </entry>
1158     </row>
1159    </tbody>
1160 </tgroup>
1161 </table>
1162
1163 </section>
1164 </section>
1165 </section>