main/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/manual/docblocks.html">Special
 447         Documentation Blocks</link> section of the Doxygen manual:
 448       </para>
 449
 450       <orderedlist inheritnum="ignore" continuation="restarts">
 451         <listitem>
 452           <para>For longer comments, use the Javadoc style...</para>
 453         </listitem>
 454
 455         <listitem>
 456           <para>
 457             ...not the Qt style. The intermediate *'s are preferred.
 458           </para>
 459         </listitem>
 460
 461         <listitem>
 462           <para>
 463             Use the triple-slash style only for one-line comments (the
 464             <quote>brief</quote> mode).
 465           </para>
 466         </listitem>
 467
 468         <listitem>
 469           <para>
 470             This is disgusting. Don't do this.
 471           </para>
 472         </listitem>
 473       </orderedlist>
 474
 475       <para>
 476         Some specific guidelines:
 477       </para>
 478
 479       <para>
 480         Use the @-style of commands, not the !-style. Please be
 481         careful about whitespace in your markup comments. Most of the
 482         time it doesn't matter; doxygen absorbs most whitespace, and
 483         both HTML and *roff are agnostic about whitespace. However,
 484         in &lt;pre&gt; blocks and @code/@endcode sections, spacing can
 485         have <quote>interesting</quote> effects.
 486       </para>
 487
 488       <para>
 489         Use either kind of grouping, as
 490         appropriate. <filename>doxygroups.cc</filename> exists for this
 491         purpose. See <filename>stl_iterator.h</filename> for a good example
 492         of the <quote>other</quote> kind of grouping.
 493       </para>
 494
 495       <para>
 496         Please use markup tags like @p and @a when referring to things
 497         such as the names of function parameters. Use @e for emphasis
 498         when necessary. Use @c to refer to other standard names.
 499         (Examples of all these abound in the present code.)
 500       </para>
 501
 502       <para>
 503         Complicated math functions should use the multi-line
 504         format. An example from <filename>random.h</filename>:
 505       </para>
 506
 507       <para>
 508 <literallayout class="normal">
 509 /**
 510  * @brief A model of a linear congruential random number generator.
 511  *
 512  * @f[
 513  *     x_{i+1}\leftarrow(ax_{i} + c) \bmod m
 514  * @f]
 515  */
 516 </literallayout>
 517       </para>
 518
 519       <para>
 520         One area of note is the markup required for
 521         <literal>@file</literal> markup in header files. Two details
 522         are important: for filenames that have the same name in
 523         multiple directories, include part of the installed path to
 524         disambiguate. For example:
 525       </para>
 526
 527       <para>
 528 <literallayout class="normal">
 529 /** @file debug/vector
 530  *  This file is a GNU debug extension to the Standard C++ Library.
 531  */
 532 </literallayout>
 533       </para>
 534
 535       <para>
 536         The other relevant detail for header files is the use of a
 537         libstdc++-specific doxygen alias that helps distinguish
 538         between public header files (like <filename>random</filename>)
 539         from implementation or private header files (like
 540         <filename>bits/c++config.h</filename>.) This alias is spelled
 541         <literal>@headername</literal> and can take one or two
 542         arguments that detail the public header file or files that
 543         should be included to use the contents of the file. All header
 544         files that are not intended for direct inclusion must use
 545         <literal>headername</literal> in the <literal>file</literal>
 546         block. An example:
 547       </para>
 548
 549       <para>
 550 <literallayout class="normal">
 551 /** @file bits/basic_string.h
 552  *  This is an internal header file, included by other library headers.
 553  *  Do not attempt to use it directly. @headername{string}
 554  */
 555 </literallayout>
 556       </para>
 557
 558       <para>
 559         Be careful about using certain, special characters when
 560         writing Doxygen comments. Single and double quotes, and
 561         separators in filenames are two common trouble spots. When in
 562         doubt, consult the following table.
 563       </para>
 564
 565 <table frame="all">
 566 <title>HTML to Doxygen Markup Comparison</title>
 567
 568 <tgroup cols="2" align="left" colsep="1" rowsep="1">
 569 <colspec colname="c1"/>
 570 <colspec colname="c2"/>
 571
 572   <thead>
 573     <row>
 574       <entry>HTML</entry>
 575       <entry>Doxygen</entry>
 576     </row>
 577   </thead>
 578
 579   <tbody>
 580     <row>
 581       <entry>\</entry>
 582       <entry>\\</entry>
 583     </row>
 584
 585     <row>
 586       <entry>"</entry>
 587       <entry>\"</entry>
 588     </row>
 589
 590     <row>
 591       <entry>'</entry>
 592       <entry>\'</entry>
 593     </row>
 594
 595     <row>
 596       <entry>&lt;i&gt;</entry>
 597       <entry>@a word</entry>
 598     </row>
 599
 600     <row>
 601       <entry>&lt;b&gt;</entry>
 602       <entry>@b word</entry>
 603     </row>
 604
 605     <row>
 606       <entry>&lt;code&gt;</entry>
 607       <entry>@c word</entry>
 608     </row>
 609
 610     <row>
 611       <entry>&lt;em&gt;</entry>
 612       <entry>@a word</entry>
 613     </row>
 614
 615     <row>
 616       <entry>&lt;em&gt;</entry>
 617       <entry>&lt;em&gt;two words or more&lt;/em&gt;</entry>
 618     </row>
 619   </tbody>
 620
 621 </tgroup>
 622 </table>
 623
 624
 625     </section>
 626
 627   </section>
 628
 629   <section xml:id="doc.docbook"><info><title>Docbook</title></info>
 630
 631
 632     <section xml:id="docbook.prereq"><info><title>Prerequisites</title></info>
 633
 634
 635  <table frame="all">
 636 <title>Docbook Prerequisites</title>
 637
 638 <tgroup cols="3" align="center" colsep="1" rowsep="1">
 639 <colspec colname="c1"/>
 640 <colspec colname="c2"/>
 641 <colspec colname="c3"/>
 642
 643   <thead>
 644     <row>
 645       <entry>Tool</entry>
 646       <entry>Version</entry>
 647       <entry>Required By</entry>
 648     </row>
 649   </thead>
 650
 651   <tbody>
 652
 653     <row>
 654       <entry>docbook5-style-xsl</entry>
 655       <entry>1.76.1</entry>
 656       <entry>all</entry>
 657     </row>
 658
 659     <row>
 660       <entry>xsltproc</entry>
 661       <entry>1.1.26</entry>
 662       <entry>all</entry>
 663     </row>
 664
 665     <row>
 666       <entry>xmllint</entry>
 667       <entry>2.7.7</entry>
 668       <entry>validation</entry>
 669     </row>
 670
 671     <row>
 672       <entry>dblatex</entry>
 673       <entry>0.3</entry>
 674       <entry>pdf output</entry>
 675     </row>
 676
 677     <row>
 678       <entry>pdflatex</entry>
 679       <entry>2007-59</entry>
 680       <entry>pdf output</entry>
 681     </row>
 682
 683     <row>
 684       <entry>docbook2X</entry>
 685       <entry>0.8.8</entry>
 686       <entry>info output</entry>
 687     </row>
 688
 689     <row>
 690       <entry>epub3 stylesheets</entry>
 691       <entry>b3</entry>
 692       <entry>epub output</entry>
 693     </row>
 694
 695   </tbody>
 696 </tgroup>
 697 </table>
 698
 699       <para>
 700         Editing the DocBook sources requires an XML editor. Many
 701         exist: some notable options
 702         include <command>emacs</command>, <application>Kate</application>,
 703         or <application>Conglomerate</application>.
 704       </para>
 705
 706       <para>
 707         Some editors support special <quote>XML Validation</quote>
 708         modes that can validate the file as it is
 709         produced. Recommended is the <command>nXML Mode</command>
 710         for <command>emacs</command>.
 711       </para>
 712
 713       <para>
 714         Besides an editor, additional DocBook files and XML tools are
 715         also required.
 716       </para>
 717
 718       <para>
 719         Access to the DocBook 5.0 stylesheets and schema is required. The
 720         stylesheets are usually packaged by vendor, in something
 721         like <filename>docbook5-style-xsl</filename>. To exactly match
 722         generated output, please use a version of the stylesheets
 723         equivalent
 724         to <filename>docbook5-style-xsl-1.75.2-3</filename>. The
 725         installation directory for this package corresponds to
 726         the <literal>XSL_STYLE_DIR</literal>
 727         in <filename>doc/Makefile.am</filename> and defaults
 728         to <filename class="directory">/usr/share/sgml/docbook/xsl-ns-stylesheets</filename>.
 729       </para>
 730
 731       <para>
 732         For processing XML, an XSLT processor and some style
 733         sheets are necessary. Defaults are <command>xsltproc</command>
 734         provided by <filename>libxslt</filename>.
 735       </para>
 736
 737       <para>
 738         For validating the XML document, you'll need
 739         something like <command>xmllint</command> and access to the
 740         relevant DocBook schema. These are provided
 741         by a vendor package like <filename>libxml2</filename> and <filename>docbook5-schemas-5.0-4</filename>
 742       </para>
 743
 744       <para>
 745         For PDF output, something that transforms valid Docbook XML to PDF is
 746         required. Possible solutions include <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://dblatex.sourceforge.net">dblatex</link>,
 747         <command>xmlto</command>, or <command>prince</command>. Of
 748         these, <command>dblatex</command> is the default. Other
 749         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
 750         consult the <email>libstdc++@gcc.gnu.org</email> list when
 751         preparing printed manuals for current best practice and
 752         suggestions.
 753       </para>
 754
 755       <para>
 756         For Texinfo output, something that transforms valid Docbook
 757         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>.
 758       </para>
 759
 760       <para>
 761         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.
 762       </para>
 763     </section>
 764
 765     <section xml:id="docbook.rules"><info><title>Generating the DocBook Files</title></info>
 766
 767
 768       <para>
 769         The following Makefile rules generate (in order): an HTML
 770         version of all the DocBook documentation, a PDF version of the
 771         same, and a single XML document.  These rules are not
 772         conditional! If the required tools are not found, or are the
 773         wrong versions, the rule may end in an error.
 774       </para>
 775
 776       <para>
 777       <screen><userinput>make doc-html-docbook</userinput></screen>
 778       </para>
 779
 780       <para>
 781       <screen><userinput>make doc-pdf-docbook</userinput></screen>
 782       </para>
 783
 784       <para>
 785       <screen><userinput>make doc-xml-single-docbook</userinput></screen>
 786       </para>
 787
 788       <para>
 789         Generated files are output into separate sub directores of
 790         <filename class="directory">doc/docbook/</filename> in the
 791         build directory, based on the output format. For instance, the
 792         HTML docs will be in <filename
 793         class="directory">doc/docbook/html</filename>.
 794       </para>
 795
 796       <para>
 797         If the Docbook stylesheets are installed in a custom location,
 798         one can use the variable <literal>XSL_STYLE_DIR</literal> to
 799         override the Makefile defaults. For example:
 800       </para>
 801
 802       <screen>
 803         <userinput>
 804 make <literal>XSL_STYLE_DIR="/usr/share/xml/docbook/stylesheet/nwalsh"</literal> doc-html-docbook
 805         </userinput>
 806       </screen>
 807
 808       </section>
 809
 810     <section xml:id="docbook.debug">
 811         <info><title>Debugging Generation</title></info>
 812
 813         <para>
 814           Sometimes, mis-configuration of the pre-requisite tools can
 815           lead to errors when attempting to build the
 816           documentation. Here are some of the obvious errors, and ways
 817           to fix some common issues that may appear quite cryptic.
 818         </para>
 819
 820         <para>
 821           First, if using a rule like <code>make pdf</code>, try to
 822           narrow down the scope of the error to either docbook
 823           (<code>make doc-pdf-docbook</code>) or doxygen (<code>make
 824           doc-pdf-doxygen</code>).
 825         </para>
 826
 827         <para>
 828           Working on the docbook path only, closely examine the
 829           contents of the following build directory:
 830           <filename>build/target/libstdc++-v3/doc/docbook/latex</filename>.
 831           Pay attention to three files enclosed within, annotated as follows.
 832         </para>
 833
 834 <itemizedlist>
 835
 836 <listitem>
 837   <para>
 838    <emphasis>spine.tex</emphasis>
 839   </para>
 840
 841   <para>
 842     The actual latex file, or partial latex file. This is generated
 843     via <command>dblatex</command>, and is the LaTeX version of the
 844     DocBook XML file <filename>spine.xml</filename>. Go to a specific
 845     line, and look at the genrated LaTeX, and try to deduce what
 846     markup in <filename>spine.xml</filename> is causing it.
 847   </para>
 848 </listitem>
 849
 850 <listitem>
 851   <para>
 852    <emphasis>spine.out</emphasis>
 853   </para>
 854
 855   <para>
 856     A log of the conversion from the XML form to the LaTeX form. This
 857     is a linear list, from the beginning of the
 858     <filename>spine.xml</filename> file: the last entry of this file
 859     should be the end of the DocBook file. If it is truncated, then
 860     you know that the last entry is the last part of the XML source
 861     file that is valid. The error is after this point.
 862   </para>
 863 </listitem>
 864
 865
 866 <listitem>
 867   <para>
 868    <emphasis>spine.log</emphasis>
 869   </para>
 870
 871   <para>
 872     A log of the compilation of the converted LaTeX form to pdf. This
 873     is a linear list, from the beginning of the
 874     <filename>spine.tex</filename> file: the last entry of this file
 875     should be the end of the LaTeX file. If it is truncated, then you
 876     know that the last entry is the last part of the generated LaTeX
 877     source file that is valid. Often this file contains an error with
 878     a specific line number of <filename>spine.tex</filename> that is
 879     incorrect.
 880   </para>
 881 </listitem>
 882
 883 </itemizedlist>
 884
 885         <para>
 886           If the error at hand is not obvious after examination, or if one
 887           encounters the inscruitable <quote>Incomplete
 888           \ifmmode</quote> error, a fall-back strategy is to start
 889           commenting out parts of the XML document (regardless of what
 890           this does to over-all document validity). Start by
 891           commenting out each of the largest parts of the
 892           <filename>spine.xml</filename> file, section by section,
 893           until the offending section is identified.
 894         </para>
 895
 896
 897     </section>
 898
 899     <section xml:id="docbook.validation"><info><title>Editing and Validation</title></info>
 900
 901       <para>
 902         After editing the xml sources, please make sure that the XML
 903         documentation and markup is still valid. This can be
 904         done easily, with the following validation rule:
 905       </para>
 906
 907       <screen>
 908         <userinput>make doc-xml-validate-docbook</userinput>
 909       </screen>
 910
 911       <para>
 912         This is equivalent to doing:
 913       </para>
 914
 915       <screen>
 916         <userinput>
 917           xmllint --noout --valid <filename>xml/index.xml</filename>
 918         </userinput>
 919       </screen>
 920
 921       <para>
 922         Please note that individual sections and chapters of the
 923         manual can be validated by substituting the file desired for
 924         <filename>xml/index.xml</filename> in the command
 925         above. Reducing scope in this manner can be helpful when
 926         validation on the entire manual fails.
 927       </para>
 928
 929       <para>
 930         All Docbook xml sources should always validate. No excuses!
 931       </para>
 932
 933     </section>
 934
 935     <section xml:id="docbook.examples"><info><title>File Organization and Basics</title></info>
 936
 937
 938     <literallayout class="normal">
 939       <emphasis>Which files are important</emphasis>
 940
 941       All Docbook files are in the directory
 942       libstdc++-v3/doc/xml
 943
 944       Inside this directory, the files of importance:
 945       spine.xml         - index to documentation set
 946       manual/spine.xml  - index to manual
 947       manual/*.xml      - individual chapters and sections of the manual
 948       faq.xml           - index to FAQ
 949       api.xml           - index to source level / API
 950
 951       All *.txml files are template xml files, i.e., otherwise empty files with
 952       the correct structure, suitable for filling in with new information.
 953
 954       <emphasis>Canonical Writing Style</emphasis>
 955
 956       class template
 957       function template
 958       member function template
 959       (via C++ Templates, Vandevoorde)
 960
 961       class in namespace std: allocator, not std::allocator
 962
 963       header file: iostream, not &lt;iostream&gt;
 964
 965
 966       <emphasis>General structure</emphasis>
 967
 968       &lt;set&gt;
 969       &lt;book&gt;
 970       &lt;/book&gt;
 971
 972       &lt;book&gt;
 973       &lt;chapter&gt;
 974       &lt;/chapter&gt;
 975       &lt;/book&gt;
 976
 977       &lt;book&gt;
 978       &lt;part&gt;
 979       &lt;chapter&gt;
 980       &lt;section&gt;
 981       &lt;/section&gt;
 982
 983       &lt;sect1&gt;
 984       &lt;/sect1&gt;
 985
 986       &lt;sect1&gt;
 987       &lt;sect2&gt;
 988       &lt;/sect2&gt;
 989       &lt;/sect1&gt;
 990       &lt;/chapter&gt;
 991
 992       &lt;chapter&gt;
 993       &lt;/chapter&gt;
 994       &lt;/part&gt;
 995       &lt;/book&gt;
 996
 997       &lt;/set&gt;
 998     </literallayout>
 999     </section>
1000
1001     <section xml:id="docbook.markup"><info><title>Markup By Example</title></info>
1002
1003
1004       <para>
1005         Complete details on Docbook markup can be found in the DocBook
1006         Element Reference,
1007         <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.docbook.org/tdg/en/html/part2.html">online</link>.
1008         An incomplete reference for HTML to Docbook conversion is
1009         detailed in the table below.
1010       </para>
1011
1012 <table frame="all">
1013 <title>HTML to Docbook XML Markup Comparison</title>
1014
1015 <tgroup cols="2" align="left" colsep="1" rowsep="1">
1016 <colspec colname="c1"/>
1017 <colspec colname="c2"/>
1018
1019   <thead>
1020     <row>
1021       <entry>HTML</entry>
1022       <entry>Docbook</entry>
1023     </row>
1024   </thead>
1025
1026   <tbody>
1027     <row>
1028       <entry>&lt;p&gt;</entry>
1029       <entry>&lt;para&gt;</entry>
1030     </row>
1031     <row>
1032       <entry>&lt;pre&gt;</entry>
1033       <entry>&lt;computeroutput&gt;, &lt;programlisting&gt;,
1034         &lt;literallayout&gt;</entry>
1035     </row>
1036     <row>
1037       <entry>&lt;ul&gt;</entry>
1038       <entry>&lt;itemizedlist&gt;</entry>
1039     </row>
1040     <row>
1041       <entry>&lt;ol&gt;</entry>
1042       <entry>&lt;orderedlist&gt;</entry>
1043     </row>
1044     <row>
1045       <entry>&lt;il&gt;</entry>
1046       <entry>&lt;listitem&gt;</entry>
1047     </row>
1048     <row>
1049       <entry>&lt;dl&gt;</entry>
1050       <entry>&lt;variablelist&gt;</entry>
1051     </row>
1052     <row>
1053       <entry>&lt;dt&gt;</entry>
1054       <entry>&lt;term&gt;</entry>
1055     </row>
1056     <row>
1057       <entry>&lt;dd&gt;</entry>
1058       <entry>&lt;listitem&gt;</entry>
1059     </row>
1060
1061     <row>
1062       <entry>&lt;a href=""&gt;</entry>
1063       <entry>&lt;ulink url=""&gt;</entry>
1064     </row>
1065     <row>
1066       <entry>&lt;code&gt;</entry>
1067       <entry>&lt;literal&gt;, &lt;programlisting&gt;</entry>
1068     </row>
1069     <row>
1070       <entry>&lt;strong&gt;</entry>
1071       <entry>&lt;emphasis&gt;</entry>
1072     </row>
1073     <row>
1074       <entry>&lt;em&gt;</entry>
1075       <entry>&lt;emphasis&gt;</entry>
1076     </row>
1077     <row>
1078       <entry>"</entry>
1079       <entry>&lt;quote&gt;</entry>
1080     </row>
1081    </tbody>
1082 </tgroup>
1083 </table>
1084
1085 <para>
1086   And examples of detailed markup for which there are no real HTML
1087   equivalents are listed in the table below.
1088 </para>
1089
1090 <table frame="all">
1091 <title>Docbook XML Element Use</title>
1092
1093 <tgroup cols="2" align="left" colsep="1" rowsep="1">
1094 <colspec colname="c1"/>
1095 <colspec colname="c2"/>
1096
1097   <thead>
1098     <row>
1099       <entry>Element</entry>
1100       <entry>Use</entry>
1101     </row>
1102   </thead>
1103
1104   <tbody>
1105     <row>
1106       <entry>&lt;structname&gt;</entry>
1107       <entry>&lt;structname&gt;char_traits&lt;/structname&gt;</entry>
1108     </row>
1109     <row>
1110       <entry>&lt;classname&gt;</entry>
1111       <entry>&lt;classname&gt;string&lt;/classname&gt;</entry>
1112     </row>
1113     <row>
1114       <entry>&lt;function&gt;</entry>
1115       <entry>
1116         <para>&lt;function&gt;clear()&lt;/function&gt;</para>
1117         <para>&lt;function&gt;fs.clear()&lt;/function&gt;</para>
1118       </entry>
1119     </row>
1120     <row>
1121       <entry>&lt;type&gt;</entry>
1122       <entry>&lt;type&gt;long long&lt;/type&gt;</entry>
1123     </row>
1124     <row>
1125       <entry>&lt;varname&gt;</entry>
1126       <entry>&lt;varname&gt;fs&lt;/varname&gt;</entry>
1127     </row>
1128     <row>
1129       <entry>&lt;literal&gt;</entry>
1130       <entry>
1131         <para>&lt;literal&gt;-Weffc++&lt;/literal&gt;</para>
1132         <para>&lt;literal&gt;rel_ops&lt;/literal&gt;</para>
1133       </entry>
1134     </row>
1135     <row>
1136       <entry>&lt;constant&gt;</entry>
1137       <entry>
1138         <para>&lt;constant&gt;_GNU_SOURCE&lt;/constant&gt;</para>
1139         <para>&lt;constant&gt;3.0&lt;/constant&gt;</para>
1140       </entry>
1141     </row>
1142     <row>
1143       <entry>&lt;command&gt;</entry>
1144       <entry>&lt;command&gt;g++&lt;/command&gt;</entry>
1145     </row>
1146     <row>
1147       <entry>&lt;errortext&gt;</entry>
1148       <entry>&lt;errortext&gt;In instantiation of&lt;/errortext&gt;</entry>
1149     </row>
1150     <row>
1151       <entry>&lt;filename&gt;</entry>
1152       <entry>
1153         <para>&lt;filename class="headerfile"&gt;ctype.h&lt;/filename&gt;</para>
1154         <para>&lt;filename class="directory"&gt;/home/gcc/build&lt;/filename&gt;</para>
1155         <para>&lt;filename class="libraryfile"&gt;libstdc++.so&lt;/filename&gt;</para>
1156       </entry>
1157     </row>
1158    </tbody>
1159 </tgroup>
1160 </table>
1161
1162 </section>
1163 </section>
1164 </section>