libstdc++-v3/doc/html/manual/documentation_hacking.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Writing and Generating Documentation</title><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><meta name="keywords" content="ISO C++, documentation, style, docbook, doxygen" /><meta name="keywords" content="ISO C++, library" /><meta name="keywords" content="ISO C++, runtime, library" /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="appendix_porting.html" title="Appendix B.  Porting and Maintenance" /><link rel="prev" href="appendix_porting.html" title="Appendix B.  Porting and Maintenance" /><link rel="next" href="internals.html" title="Porting to New Hardware or Operating Systems" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Writing and Generating Documentation</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="appendix_porting.html">Prev</a> </td><th width="60%" align="center">Appendix B.
   3   Porting and Maintenance
   4
   5 </th><td width="20%" align="right"> <a accesskey="n" href="internals.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="appendix.porting.doc"></a>Writing and Generating Documentation</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="doc.intro"></a>Introduction</h3></div></div></div><p>
   6       Documentation for the GNU C++ Library is created from three
   7       independent sources: a manual, a FAQ, and an API reference.
   8     </p><p>
   9       The sub-directory <code class="filename">doc</code>
  10       within the main source directory contains
  11       <code class="filename">Makefile.am</code> and
  12       <code class="filename">Makefile.in</code>, which provide rules for
  13       generating documentation, described in excruciating detail
  14       below. The <code class="filename">doc</code>
  15       sub-directory also contains three directories: <code class="filename">doxygen</code>, which contains scripts and
  16       fragments for <span class="command"><strong>doxygen</strong></span>, <code class="filename">html</code>, which contains an html
  17       version of the manual, and <code class="filename">xml</code>, which contains an xml version
  18       of the manual.
  19     </p><p>
  20       Diverging from established documentation conventions in the rest
  21       of the GCC project, libstdc++ does not use Texinfo as a markup
  22       language. Instead, Docbook is used to create the manual and the
  23       FAQ, and Doxygen is used to construct the API
  24       reference. Although divergent, this conforms to the GNU Project
  25       recommendations as long as the output is of sufficient quality,
  26       as per
  27       <a class="link" href="http://www.gnu.org/prep/standards/standards.html#Documentation" target="_top">
  28       GNU Manuals</a>.
  29     </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="doc.generation"></a>Generating Documentation</h3></div></div></div><p>
  30       Certain Makefile rules are required by the GNU Coding
  31       Standards. These standard rules generate HTML, PDF, XML, or man
  32       files. For each of the generative rules, there is an additional
  33       install rule that is used to install any generated documentation
  34       files into the prescribed installation directory. Files are
  35       installed into <code class="filename">share/doc</code>
  36       or <code class="filename">share/man</code> directories.
  37     </p><p>
  38       The standard Makefile rules are conditionally supported, based
  39       on the results of examining the host environment for
  40       prerequisites at configuration time. If requirements are not
  41       found, the rule is aliased to a dummy rule that does nothing,
  42       and produces no documentation. If the requirements are found,
  43       the rule forwards to a private rule that produces the requested
  44       documentation.
  45     </p><p>
  46       For more details on what prerequisites were found and where,
  47       please consult the file <code class="filename">config.log</code> in the
  48       libstdc++ build directory. Compare this log to what is expected
  49       for the relevant Makefile conditionals:
  50       <code class="literal">BUILD_INFO</code>, <code class="literal">BUILD_XML</code>,
  51       <code class="literal">BUILD_HTML</code>, <code class="literal">BUILD_MAN</code>,
  52       <code class="literal">BUILD_PDF</code>, and <code class="literal">BUILD_EPUB</code>.
  53     </p><p>
  54       Supported Makefile rules:
  55     </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
  56           <span class="emphasis"><em>make html</em></span>
  57         , </span><span class="term">
  58           <span class="emphasis"><em>make install-html</em></span>
  59         </span></dt><dd><p>
  60             Generates multi-page HTML documentation, and installs it
  61             in the following directories:
  62           </p><p>
  63             <code class="filename">doc/libstdc++/libstdc++-api.html</code>
  64           </p><p>
  65             <code class="filename">doc/libstdc++/libstdc++-manual.html</code>
  66           </p></dd><dt><span class="term">
  67           <span class="emphasis"><em>make pdf</em></span>
  68         , </span><span class="term">
  69           <span class="emphasis"><em>make install-pdf</em></span>
  70         </span></dt><dd><p>
  71             Generates indexed PDF documentation, and installs it as
  72             the following files:
  73           </p><p>
  74             <code class="filename">doc/libstdc++/libstdc++-api.pdf</code>
  75           </p><p>
  76             <code class="filename">doc/libstdc++/libstdc++-manual.pdf</code>
  77           </p></dd><dt><span class="term">
  78           <span class="emphasis"><em>make man</em></span>
  79         , </span><span class="term">
  80           <span class="emphasis"><em>make install-man</em></span>
  81         </span></dt><dd><p>
  82             Generates man pages, and installs it in the following directory:
  83           </p><p>
  84             <code class="filename">man/man3/</code>
  85           </p><p>
  86             The generated man pages are namespace-qualified, so to look at
  87             the man page for <code class="classname">vector</code>, one would use
  88             <span class="command"><strong>man std::vector</strong></span>.
  89           </p></dd><dt><span class="term">
  90           <span class="emphasis"><em>make epub</em></span>
  91         , </span><span class="term">
  92           <span class="emphasis"><em>make install-epub</em></span>
  93         </span></dt><dd><p>
  94             Generates documentation in the ebook/portable electronic
  95             reader format called Epub, and installs it as the
  96             following file.
  97           </p><p>
  98             <code class="filename">doc/libstdc++/libstdc++-manual.epub</code>
  99           </p></dd><dt><span class="term">
 100           <span class="emphasis"><em>make xml</em></span>
 101         , </span><span class="term">
 102           <span class="emphasis"><em>make install-xml</em></span>
 103         </span></dt><dd><p>
 104             Generates single-file XML documentation, and installs it
 105             as the following files:
 106           </p><p>
 107             <code class="filename">doc/libstdc++/libstdc++-api-single.xml</code>
 108           </p><p>
 109             <code class="filename">doc/libstdc++/libstdc++-manual-single.xml</code>
 110           </p></dd></dl></div><p>
 111       Makefile rules for several other formats are explicitly not
 112       supported, and are always aliased to dummy rules. These
 113       unsupported formats are: <span class="emphasis"><em>info</em></span>,
 114       <span class="emphasis"><em>ps</em></span>, and <span class="emphasis"><em>dvi</em></span>.
 115     </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="doc.doxygen"></a>Doxygen</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="doxygen.prereq"></a>Prerequisites</h4></div></div></div><div class="table"><a id="table.doxygen_prereq"></a><p class="title"><strong>Table B.1. Doxygen Prerequisites</strong></p><div class="table-contents"><table class="table" summary="Doxygen Prerequisites" border="1"><colgroup><col align="center" class="c1" /><col align="center" class="c2" /><col align="center" class="c3" /></colgroup><thead><tr><th align="center">Tool</th><th align="center">Version</th><th align="center">Required By</th></tr></thead><tbody><tr><td align="center">coreutils</td><td align="center">8.5</td><td align="center">all</td></tr><tr><td align="center">bash</td><td align="center">4.1</td><td align="center">all</td></tr><tr><td align="center">doxygen</td><td align="center">1.7.6.1</td><td align="center">all</td></tr><tr><td align="center">graphviz</td><td align="center">2.26</td><td align="center">graphical hierarchies</td></tr><tr><td align="center">pdflatex</td><td align="center">2007-59</td><td align="center">pdf output</td></tr></tbody></table></div></div><br class="table-break" /><p>
 116         Prerequisite tools are Bash 2.0 or later,
 117         <a class="link" href="http://www.doxygen.org" target="_top">Doxygen</a>, and
 118         the <a class="link" href="http://www.gnu.org/software/coreutils/" target="_top">GNU
 119         coreutils</a>. (GNU versions of find, xargs, and possibly
 120         sed and grep are used, just because the GNU versions make
 121         things very easy.)
 122       </p><p>
 123         To generate the pretty pictures and hierarchy
 124         graphs, the
 125         <a class="link" href="http://www.graphviz.org" target="_top">Graphviz</a> package
 126         will need to be installed. For PDF
 127         output, <a class="link" href="http://www.tug.org/applications/pdftex/" target="_top">
 128         pdflatex</a> is required as well as a number of TeX packages
 129         such as <span class="package">texlive-xtab</span> and
 130         <span class="package">texlive-tocloft</span>.
 131       </p><p>
 132         Be warned the PDF file generated via doxygen is extremely
 133         large. At last count, the PDF file is over three thousand
 134         pages. Generating this document taxes the underlying TeX
 135         formatting system, and will require the expansion of TeX's memory
 136         capacity. Specifically, the <code class="literal">pool_size</code>
 137         variable in the configuration file <code class="filename">texmf.cnf</code> may
 138         need to be increased by a minimum factor of two.
 139       </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="doxygen.rules"></a>Generating the Doxygen Files</h4></div></div></div><p>
 140         The following Makefile rules run Doxygen to generate HTML
 141         docs, XML docs, XML docs as a single file, PDF docs, and the
 142         man pages. These rules are not conditional! If the required
 143         tools are not found, or are the wrong versions, the rule may
 144         end in an error.
 145       </p><p>
 146       </p><pre class="screen"><strong class="userinput"><code>make doc-html-doxygen</code></strong></pre><p>
 147       </p><p>
 148       </p><pre class="screen"><strong class="userinput"><code>make doc-xml-doxygen</code></strong></pre><p>
 149       </p><p>
 150       </p><pre class="screen"><strong class="userinput"><code>make doc-xml-single-doxygen</code></strong></pre><p>
 151       </p><p>
 152       </p><pre class="screen"><strong class="userinput"><code>make doc-pdf-doxygen</code></strong></pre><p>
 153       </p><p>
 154       </p><pre class="screen"><strong class="userinput"><code>make doc-man-doxygen</code></strong></pre><p>
 155       </p><p>
 156         Generated files are output into separate sub directories of
 157         <code class="filename">doc/doxygen/</code> in the
 158         build directory, based on the output format. For instance, the
 159         HTML docs will be in <code class="filename">doc/doxygen/html</code>.
 160       </p><p>
 161         Careful observers will see that the Makefile rules simply call
 162         a script from the source tree, <code class="filename">run_doxygen</code>, which
 163         does the actual work of running Doxygen and then (most
 164         importantly) massaging the output files. If for some reason
 165         you prefer to not go through the Makefile, you can call this
 166         script directly. (Start by passing <code class="literal">--help</code>.)
 167       </p><p>
 168         If you wish to tweak the Doxygen settings, do so by editing
 169         <code class="filename">doc/doxygen/user.cfg.in</code>. Notes to fellow
 170         library hackers are written in triple-# comments.
 171       </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="doxygen.debug"></a>Debugging Generation</h4></div></div></div><p>
 172           Sometimes, mis-configuration of the pre-requisite tools can
 173           lead to errors when attempting to build the
 174           documentation. Here are some of the obvious errors, and ways
 175           to fix some common issues that may appear quite cryptic.
 176         </p><p>
 177           First, if using a rule like <code class="code">make pdf</code>, try to
 178           narrow down the scope of the error to either docbook
 179           (<code class="code">make doc-pdf-docbook</code>) or doxygen (<code class="code">make
 180           doc-pdf-doxygen</code>).
 181         </p><p>
 182           Working on the doxygen path only, closely examine the
 183           contents of the following build directory: <code class="filename">build/target/libstdc++-v3/doc/doxygen/latex</code>.
 184           Pay attention to three files enclosed within, annotated as follows.
 185         </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
 186    <span class="emphasis"><em>refman.tex</em></span>
 187   </p><p>
 188     The actual latex file, or partial latex file. This is generated
 189     via <span class="command"><strong>doxygen</strong></span>, and is the LaTeX version of the
 190     Doxygen XML file <code class="filename">libstdc++-api.xml</code>. Go to a specific
 191     line, and look at the generated LaTeX, and try to deduce what
 192     markup in <code class="filename">libstdc++-api.xml</code> is causing it.
 193   </p></li><li class="listitem"><p>
 194    <span class="emphasis"><em>refman.log</em></span>
 195   </p><p>
 196     A log created by <span class="command"><strong>latex</strong></span> as it processes the
 197     <code class="filename">refman.tex</code> file. If generating the PDF fails
 198     look at the end of this file for errors such as:
 199     </p><pre class="screen">
 200     ! LaTeX Error: File `xtab.sty' not found.
 201     </pre><p>
 202     This indicates a required TeX package is missing. For the example
 203     above the <span class="package">texlive-xtab</span> package needs to be
 204     installed.
 205   </p></li><li class="listitem"><p>
 206    <span class="emphasis"><em>refman.out</em></span>
 207   </p><p>
 208     A log of the compilation of the converted LaTeX form to PDF. This
 209     is a linear list, from the beginning of the
 210     <code class="filename">refman.tex</code> file: the last entry of this file
 211     should be the end of the LaTeX file. If it is truncated, then you
 212     know that the last entry is the last part of the generated LaTeX
 213     source file that is valid. Often this file contains an error with
 214     a specific line number of <code class="filename">refman.tex</code> that is
 215     incorrect, or will have clues at the end of the file with the dump
 216     of the memory usage of LaTeX.
 217   </p></li></ul></div><p>
 218           If the error at hand is not obvious after examination, a
 219           fall-back strategy is to start commenting out the doxygen
 220           input sources, which can be found in
 221           <code class="filename">doc/doxygen/user.cfg.in</code>, look for the
 222           <code class="literal">INPUT</code> tag. Start by commenting out whole
 223           directories of header files, until the offending header is
 224           identified. Then, read the latex log files to try and find
 225           surround text, and look for that in the offending header.
 226         </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="doxygen.markup"></a>Markup</h4></div></div></div><p>
 227         In general, libstdc++ files should be formatted according to
 228         the rules found in the
 229         <a class="link" href="source_code_style.html" title="Coding Style">Coding Standard</a>. Before
 230         any doxygen-specific formatting tweaks are made, please try to
 231         make sure that the initial formatting is sound.
 232       </p><p>
 233         Adding Doxygen markup to a file (informally called
 234         <span class="quote">“<span class="quote">doxygenating</span>”</span>) is very simple. The Doxygen manual can be
 235         found
 236         <a class="link" href="http://www.stack.nl/~dimitri/doxygen/download.html#latestman" target="_top">here</a>.
 237         We try to use a very-recent version of Doxygen.
 238       </p><p>
 239         For classes, use
 240         <code class="classname">deque</code>/<code class="classname">vector</code>/<code class="classname">list</code>
 241         and <code class="classname">std::pair</code> as examples.  For
 242         functions, see their member functions, and the free functions
 243         in <code class="filename">stl_algobase.h</code>. Member
 244         functions of other container-like types should read similarly to
 245         these member functions.
 246       </p><p>
 247         Some commentary to accompany
 248         the first list in the <a class="link" href="http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html" target="_top">Special
 249         Documentation Blocks</a> section of the Doxygen manual:
 250       </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>For longer comments, use the Javadoc style...</p></li><li class="listitem"><p>
 251             ...not the Qt style. The intermediate *'s are preferred.
 252           </p></li><li class="listitem"><p>
 253             Use the triple-slash style only for one-line comments (the
 254             <span class="quote">“<span class="quote">brief</span>”</span> mode).
 255           </p></li><li class="listitem"><p>
 256             This is disgusting. Don't do this.
 257           </p></li></ol></div><p>
 258         Some specific guidelines:
 259       </p><p>
 260         Use the @-style of commands, not the !-style. Please be
 261         careful about whitespace in your markup comments. Most of the
 262         time it doesn't matter; doxygen absorbs most whitespace, and
 263         both HTML and *roff are agnostic about whitespace. However,
 264         in &lt;pre&gt; blocks and @code/@endcode sections, spacing can
 265         have <span class="quote">“<span class="quote">interesting</span>”</span> effects.
 266       </p><p>
 267         Use either kind of grouping, as
 268         appropriate. <code class="filename">doxygroups.cc</code> exists for this
 269         purpose. See <code class="filename">stl_iterator.h</code>
 270         for a good example of the <span class="quote">“<span class="quote">other</span>”</span> kind of grouping.
 271       </p><p>
 272         Please use markup tags like @p and @a when referring to things
 273         such as the names of function parameters. Use @e for emphasis
 274         when necessary. Use @c to refer to other standard names.
 275         (Examples of all these abound in the present code.)
 276       </p><p>
 277         Complicated math functions should use the multi-line format.
 278         An example from <code class="filename">random.h</code>:
 279       </p><p>
 280 </p><div class="literallayout"><p><br />
 281 /**<br />
 282  * @brief A model of a linear congruential random number generator.<br />
 283  *<br />
 284  * @f[<br />
 285  *     x_{i+1}\leftarrow(ax_{i} + c) \bmod m<br />
 286  * @f]<br />
 287  */<br />
 288 </p></div><p>
 289       </p><p>
 290         One area of note is the markup required for
 291         <code class="literal">@file</code> markup in header files. Two details
 292         are important: for filenames that have the same name in
 293         multiple directories, include part of the installed path to
 294         disambiguate. For example:
 295       </p><p>
 296 </p><div class="literallayout"><p><br />
 297 /** @file debug/vector<br />
 298  *  This file is a GNU debug extension to the Standard C++ Library.<br />
 299  */<br />
 300 </p></div><p>
 301       </p><p>
 302         The other relevant detail for header files is the use of a
 303         libstdc++-specific doxygen alias that helps distinguish
 304         between public header files (like <code class="filename">random</code>)
 305         from implementation or private header files (like
 306         <code class="filename">bits/c++config.h</code>.) This alias is spelled
 307         <code class="literal">@headername</code> and can take one or two
 308         arguments that detail the public header file or files that
 309         should be included to use the contents of the file. All header
 310         files that are not intended for direct inclusion must use
 311         <code class="literal">headername</code> in the <code class="literal">file</code>
 312         block. An example:
 313       </p><p>
 314 </p><div class="literallayout"><p><br />
 315 /** @file bits/basic_string.h<br />
 316  *  This is an internal header file, included by other library headers.<br />
 317  *  Do not attempt to use it directly. @headername{string}<br />
 318  */<br />
 319 </p></div><p>
 320       </p><p>
 321         Be careful about using certain, special characters when
 322         writing Doxygen comments. Single and double quotes, and
 323         separators in filenames are two common trouble spots. When in
 324         doubt, consult the following table.
 325       </p><div class="table"><a id="table.doxygen_cmp"></a><p class="title"><strong>Table B.2. HTML to Doxygen Markup Comparison</strong></p><div class="table-contents"><table class="table" summary="HTML to Doxygen Markup Comparison" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">HTML</th><th align="left">Doxygen</th></tr></thead><tbody><tr><td align="left">\</td><td align="left">\\</td></tr><tr><td align="left">"</td><td align="left">\"</td></tr><tr><td align="left">'</td><td align="left">\'</td></tr><tr><td align="left">&lt;i&gt;</td><td align="left">@a word</td></tr><tr><td align="left">&lt;b&gt;</td><td align="left">@b word</td></tr><tr><td align="left">&lt;code&gt;</td><td align="left">@c word</td></tr><tr><td align="left">&lt;em&gt;</td><td align="left">@a word</td></tr><tr><td align="left">&lt;em&gt;</td><td align="left">&lt;em&gt;two words or more&lt;/em&gt;</td></tr></tbody></table></div></div><br class="table-break" /></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="doc.docbook"></a>Docbook</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.prereq"></a>Prerequisites</h4></div></div></div><div class="table"><a id="table.docbook_prereq"></a><p class="title"><strong>Table B.3. Docbook Prerequisites</strong></p><div class="table-contents"><table class="table" summary="Docbook Prerequisites" border="1"><colgroup><col align="center" class="c1" /><col align="center" class="c2" /><col align="center" class="c3" /></colgroup><thead><tr><th align="center">Tool</th><th align="center">Version</th><th align="center">Required By</th></tr></thead><tbody><tr><td align="center">docbook5-style-xsl</td><td align="center">1.76.1</td><td align="center">all</td></tr><tr><td align="center">xsltproc</td><td align="center">1.1.26</td><td align="center">all</td></tr><tr><td align="center">xmllint</td><td align="center">2.7.7</td><td align="center">validation</td></tr><tr><td align="center">dblatex</td><td align="center">0.3</td><td align="center">pdf output</td></tr><tr><td align="center">pdflatex</td><td align="center">2007-59</td><td align="center">pdf output</td></tr><tr><td align="center">docbook2X</td><td align="center">0.8.8</td><td align="center">info output</td></tr><tr><td align="center">epub3 stylesheets</td><td align="center">b3</td><td align="center">epub output</td></tr></tbody></table></div></div><br class="table-break" /><p>
 326         Editing the DocBook sources requires an XML editor. Many
 327         exist: some notable options
 328         include <span class="command"><strong>emacs</strong></span>, <span class="application">Kate</span>,
 329         or <span class="application">Conglomerate</span>.
 330       </p><p>
 331         Some editors support special <span class="quote">“<span class="quote">XML Validation</span>”</span>
 332         modes that can validate the file as it is
 333         produced. Recommended is the <span class="command"><strong>nXML Mode</strong></span>
 334         for <span class="command"><strong>emacs</strong></span>.
 335       </p><p>
 336         Besides an editor, additional DocBook files and XML tools are
 337         also required.
 338       </p><p>
 339         Access to the DocBook 5.0 stylesheets and schema is required. The
 340         stylesheets are usually packaged by vendor, in something
 341         like <code class="filename">docbook5-style-xsl</code>. To exactly match
 342         generated output, please use a version of the stylesheets
 343         equivalent
 344         to <code class="filename">docbook5-style-xsl-1.75.2-3</code>. The
 345         installation directory for this package corresponds to
 346         the <code class="literal">XSL_STYLE_DIR</code>
 347         in <code class="filename">doc/Makefile.am</code> and defaults
 348         to <code class="filename">/usr/share/sgml/docbook/xsl-ns-stylesheets</code>.
 349       </p><p>
 350         For processing XML, an XSLT processor and some style
 351         sheets are necessary. Defaults are <span class="command"><strong>xsltproc</strong></span>
 352         provided by <code class="filename">libxslt</code>.
 353       </p><p>
 354         For validating the XML document, you'll need
 355         something like <span class="command"><strong>xmllint</strong></span> and access to the
 356         relevant DocBook schema. These are provided
 357         by a vendor package like <code class="filename">libxml2</code> and <code class="filename">docbook5-schemas-5.0-4</code>
 358       </p><p>
 359         For PDF output, something that transforms valid Docbook XML to PDF is
 360         required. Possible solutions include <a class="link" href="http://dblatex.sourceforge.net" target="_top">dblatex</a>,
 361         <span class="command"><strong>xmlto</strong></span>, or <span class="command"><strong>prince</strong></span>. Of
 362         these, <span class="command"><strong>dblatex</strong></span> is the default.
 363         Please consult the <code class="email">&lt;<a class="email" href="mailto:libstdc++@gcc.gnu.org">libstdc++@gcc.gnu.org</a>&gt;</code> list when
 364         preparing printed manuals for current best practice and
 365         suggestions.
 366       </p><p>
 367         For Texinfo output, something that transforms valid Docbook
 368         XML to Texinfo is required. The default choice is <a class="link" href="http://docbook2x.sourceforge.net/" target="_top">docbook2X</a>.
 369       </p><p>
 370         For epub output, the <a class="link" href="https://sourceforge.net/projects/docbook/files/epub3/" target="_top">stylesheets</a> for EPUB3 are required. These stylesheets are still in development. To validate the created file, <a class="link" href="https://github.com/w3c/epubcheck" target="_top">epubcheck</a> is necessary.
 371       </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.rules"></a>Generating the DocBook Files</h4></div></div></div><p>
 372         The following Makefile rules generate (in order): an HTML
 373         version of all the DocBook documentation, a PDF version of the
 374         same, and a single XML document.  These rules are not
 375         conditional! If the required tools are not found, or are the
 376         wrong versions, the rule may end in an error.
 377       </p><p>
 378       </p><pre class="screen"><strong class="userinput"><code>make doc-html-docbook</code></strong></pre><p>
 379       </p><p>
 380       </p><pre class="screen"><strong class="userinput"><code>make doc-pdf-docbook</code></strong></pre><p>
 381       </p><p>
 382       </p><pre class="screen"><strong class="userinput"><code>make doc-xml-single-docbook</code></strong></pre><p>
 383       </p><p>
 384         Generated files are output into separate sub directores of
 385         <code class="filename">doc/docbook/</code> in the
 386         build directory, based on the output format. For instance, the
 387         HTML docs will be in <code class="filename">doc/docbook/html</code>.
 388       </p><p>
 389         If the Docbook stylesheets are installed in a custom location,
 390         one can use the variable <code class="literal">XSL_STYLE_DIR</code> to
 391         override the Makefile defaults. For example:
 392       </p><pre class="screen">
 393         <strong class="userinput"><code>
 394 make <code class="literal">XSL_STYLE_DIR="/usr/share/xml/docbook/stylesheet/nwalsh"</code> doc-html-docbook
 395         </code></strong>
 396       </pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.debug"></a>Debugging Generation</h4></div></div></div><p>
 397           Sometimes, mis-configuration of the pre-requisite tools can
 398           lead to errors when attempting to build the
 399           documentation. Here are some of the obvious errors, and ways
 400           to fix some common issues that may appear quite cryptic.
 401         </p><p>
 402           First, if using a rule like <code class="code">make pdf</code>, try to
 403           narrow down the scope of the error to either docbook
 404           (<code class="code">make doc-pdf-docbook</code>) or doxygen (<code class="code">make
 405           doc-pdf-doxygen</code>).
 406         </p><p>
 407           Working on the docbook path only, closely examine the
 408           contents of the following build directory:
 409           <code class="filename">build/target/libstdc++-v3/doc/docbook/latex</code>.
 410           Pay attention to three files enclosed within, annotated as follows.
 411         </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
 412    <span class="emphasis"><em>spine.tex</em></span>
 413   </p><p>
 414     The actual latex file, or partial latex file. This is generated
 415     via <span class="command"><strong>dblatex</strong></span>, and is the LaTeX version of the
 416     DocBook XML file <code class="filename">spine.xml</code>. Go to a specific
 417     line, and look at the generated LaTeX, and try to deduce what
 418     markup in <code class="filename">spine.xml</code> is causing it.
 419   </p></li><li class="listitem"><p>
 420    <span class="emphasis"><em>spine.out</em></span>
 421   </p><p>
 422     A log of the conversion from the XML form to the LaTeX form. This
 423     is a linear list, from the beginning of the
 424     <code class="filename">spine.xml</code> file: the last entry of this file
 425     should be the end of the DocBook file. If it is truncated, then
 426     you know that the last entry is the last part of the XML source
 427     file that is valid. The error is after this point.
 428   </p></li><li class="listitem"><p>
 429    <span class="emphasis"><em>spine.log</em></span>
 430   </p><p>
 431     A log of the compilation of the converted LaTeX form to pdf. This
 432     is a linear list, from the beginning of the
 433     <code class="filename">spine.tex</code> file: the last entry of this file
 434     should be the end of the LaTeX file. If it is truncated, then you
 435     know that the last entry is the last part of the generated LaTeX
 436     source file that is valid. Often this file contains an error with
 437     a specific line number of <code class="filename">spine.tex</code> that is
 438     incorrect.
 439   </p></li></ul></div><p>
 440           If the error at hand is not obvious after examination, or if one
 441           encounters the inscruitable <span class="quote">“<span class="quote">Incomplete
 442           \ifmmode</span>”</span> error, a fall-back strategy is to start
 443           commenting out parts of the XML document (regardless of what
 444           this does to over-all document validity). Start by
 445           commenting out each of the largest parts of the
 446           <code class="filename">spine.xml</code> file, section by section,
 447           until the offending section is identified.
 448         </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.validation"></a>Editing and Validation</h4></div></div></div><p>
 449         After editing the xml sources, please make sure that the XML
 450         documentation and markup is still valid. This can be
 451         done easily, with the following validation rule:
 452       </p><pre class="screen">
 453         <strong class="userinput"><code>make doc-xml-validate-docbook</code></strong>
 454       </pre><p>
 455         This is equivalent to doing:
 456       </p><pre class="screen">
 457         <strong class="userinput"><code>
 458           xmllint --noout --valid <code class="filename">xml/index.xml</code>
 459         </code></strong>
 460       </pre><p>
 461         Please note that individual sections and chapters of the
 462         manual can be validated by substituting the file desired for
 463         <code class="filename">xml/index.xml</code> in the command
 464         above. Reducing scope in this manner can be helpful when
 465         validation on the entire manual fails.
 466       </p><p>
 467         All Docbook xml sources should always validate. No excuses!
 468       </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.examples"></a>File Organization and Basics</h4></div></div></div><div class="literallayout"><p><br />
 469       <span class="emphasis"><em>Which files are important</em></span><br />
 470 <br />
 471       All Docbook files are in the directory<br />
 472       libstdc++-v3/doc/xml<br />
 473 <br />
 474       Inside this directory, the files of importance:<br />
 475       spine.xml          - index to documentation set<br />
 476       manual/spine.xml  - index to manual<br />
 477       manual/*.xml      - individual chapters and sections of the manual<br />
 478       faq.xml           - index to FAQ<br />
 479       api.xml           - index to source level / API<br />
 480 <br />
 481       All *.txml files are template xml files, i.e., otherwise empty files with<br />
 482       the correct structure, suitable for filling in with new information.<br />
 483 <br />
 484       <span class="emphasis"><em>Canonical Writing Style</em></span><br />
 485 <br />
 486       class template<br />
 487       function template<br />
 488       member function template<br />
 489       (via C++ Templates, Vandevoorde)<br />
 490 <br />
 491       class in namespace std: allocator, not std::allocator<br />
 492 <br />
 493       header file: iostream, not &lt;iostream&gt;<br />
 494 <br />
 495 <br />
 496       <span class="emphasis"><em>General structure</em></span><br />
 497 <br />
 498       &lt;set&gt;<br />
 499       &lt;book&gt;<br />
 500       &lt;/book&gt;<br />
 501 <br />
 502       &lt;book&gt;<br />
 503       &lt;chapter&gt;<br />
 504       &lt;/chapter&gt;<br />
 505       &lt;/book&gt;<br />
 506 <br />
 507       &lt;book&gt;<br />
 508       &lt;part&gt;<br />
 509       &lt;chapter&gt;<br />
 510       &lt;section&gt;<br />
 511       &lt;/section&gt;<br />
 512 <br />
 513       &lt;sect1&gt;<br />
 514       &lt;/sect1&gt;<br />
 515 <br />
 516       &lt;sect1&gt;<br />
 517       &lt;sect2&gt;<br />
 518       &lt;/sect2&gt;<br />
 519       &lt;/sect1&gt;<br />
 520       &lt;/chapter&gt;<br />
 521 <br />
 522       &lt;chapter&gt;<br />
 523       &lt;/chapter&gt;<br />
 524       &lt;/part&gt;<br />
 525       &lt;/book&gt;<br />
 526 <br />
 527       &lt;/set&gt;<br />
 528     </p></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.markup"></a>Markup By Example</h4></div></div></div><p>
 529         Complete details on Docbook markup can be found in the
 530         <a class="link" href="https://tdg.docbook.org/tdg/5.0/ref-elements.html" target="_top">DocBook Element Reference</a>.
 531         An incomplete reference for HTML to Docbook conversion is
 532         detailed in the table below.
 533       </p><div class="table"><a id="table.docbook_cmp"></a><p class="title"><strong>Table B.4. HTML to Docbook XML Markup Comparison</strong></p><div class="table-contents"><table class="table" summary="HTML to Docbook XML Markup Comparison" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">HTML</th><th align="left">Docbook</th></tr></thead><tbody><tr><td align="left">&lt;p&gt;</td><td align="left">&lt;para&gt;</td></tr><tr><td align="left">&lt;pre&gt;</td><td align="left">&lt;computeroutput&gt;, &lt;programlisting&gt;,
 534         &lt;literallayout&gt;</td></tr><tr><td align="left">&lt;ul&gt;</td><td align="left">&lt;itemizedlist&gt;</td></tr><tr><td align="left">&lt;ol&gt;</td><td align="left">&lt;orderedlist&gt;</td></tr><tr><td align="left">&lt;il&gt;</td><td align="left">&lt;listitem&gt;</td></tr><tr><td align="left">&lt;dl&gt;</td><td align="left">&lt;variablelist&gt;</td></tr><tr><td align="left">&lt;dt&gt;</td><td align="left">&lt;term&gt;</td></tr><tr><td align="left">&lt;dd&gt;</td><td align="left">&lt;listitem&gt;</td></tr><tr><td align="left">&lt;a href=""&gt;</td><td align="left">&lt;ulink url=""&gt;</td></tr><tr><td align="left">&lt;code&gt;</td><td align="left">&lt;literal&gt;, &lt;programlisting&gt;</td></tr><tr><td align="left">&lt;strong&gt;</td><td align="left">&lt;emphasis&gt;</td></tr><tr><td align="left">&lt;em&gt;</td><td align="left">&lt;emphasis&gt;</td></tr><tr><td align="left">"</td><td align="left">&lt;quote&gt;</td></tr></tbody></table></div></div><br class="table-break" /><p>
 535   And examples of detailed markup for which there are no real HTML
 536   equivalents are listed in the table below.
 537 </p><div class="table"><a id="table.docbook_elem"></a><p class="title"><strong>Table B.5. Docbook XML Element Use</strong></p><div class="table-contents"><table class="table" summary="Docbook XML Element Use" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Element</th><th align="left">Use</th></tr></thead><tbody><tr><td align="left">&lt;structname&gt;</td><td align="left">&lt;structname&gt;char_traits&lt;/structname&gt;</td></tr><tr><td align="left">&lt;classname&gt;</td><td align="left">&lt;classname&gt;string&lt;/classname&gt;</td></tr><tr><td align="left">&lt;function&gt;</td><td align="left">
 538         <p>&lt;function&gt;clear()&lt;/function&gt;</p>
 539         <p>&lt;function&gt;fs.clear()&lt;/function&gt;</p>
 540       </td></tr><tr><td align="left">&lt;type&gt;</td><td align="left">&lt;type&gt;long long&lt;/type&gt;</td></tr><tr><td align="left">&lt;varname&gt;</td><td align="left">&lt;varname&gt;fs&lt;/varname&gt;</td></tr><tr><td align="left">&lt;literal&gt;</td><td align="left">
 541         <p>&lt;literal&gt;-Weffc++&lt;/literal&gt;</p>
 542         <p>&lt;literal&gt;rel_ops&lt;/literal&gt;</p>
 543       </td></tr><tr><td align="left">&lt;constant&gt;</td><td align="left">
 544         <p>&lt;constant&gt;_GNU_SOURCE&lt;/constant&gt;</p>
 545         <p>&lt;constant&gt;3.0&lt;/constant&gt;</p>
 546       </td></tr><tr><td align="left">&lt;command&gt;</td><td align="left">&lt;command&gt;g++&lt;/command&gt;</td></tr><tr><td align="left">&lt;errortext&gt;</td><td align="left">&lt;errortext&gt;In instantiation of&lt;/errortext&gt;</td></tr><tr><td align="left">&lt;filename&gt;</td><td align="left">
 547         <p>&lt;filename class="headerfile"&gt;ctype.h&lt;/filename&gt;</p>
 548         <p>&lt;filename class="directory"&gt;/home/gcc/build&lt;/filename&gt;</p>
 549         <p>&lt;filename class="libraryfile"&gt;libstdc++.so&lt;/filename&gt;</p>
 550       </td></tr></tbody></table></div></div><br class="table-break" /></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="appendix_porting.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendix_porting.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="internals.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Appendix B.
 551   Porting and Maintenance
 552
 553  </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Porting to New Hardware or Operating Systems</td></tr></table></div></body></html>