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