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