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