136ac495dSmrg<?xml version="1.0" encoding="UTF-8" standalone="no"?> 236ac495dSmrg<!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. 336ac495dSmrg Porting and Maintenance 436ac495dSmrg 536ac495dSmrg</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> 636ac495dSmrg Documentation for the GNU C++ Library is created from three 736ac495dSmrg independent sources: a manual, a FAQ, and an API reference. 836ac495dSmrg </p><p> 936ac495dSmrg The sub-directory <code class="filename">doc</code> 1036ac495dSmrg within the main source directory contains 1136ac495dSmrg <code class="filename">Makefile.am</code> and 1236ac495dSmrg <code class="filename">Makefile.in</code>, which provide rules for 1336ac495dSmrg generating documentation, described in excruciating detail 1436ac495dSmrg below. The <code class="filename">doc</code> 1536ac495dSmrg sub-directory also contains three directories: <code class="filename">doxygen</code>, which contains scripts and 1636ac495dSmrg fragments for <span class="command"><strong>doxygen</strong></span>, <code class="filename">html</code>, which contains an html 1736ac495dSmrg version of the manual, and <code class="filename">xml</code>, which contains an xml version 1836ac495dSmrg of the manual. 1936ac495dSmrg </p><p> 2036ac495dSmrg Diverging from established documentation conventions in the rest 2136ac495dSmrg of the GCC project, libstdc++ does not use Texinfo as a markup 2236ac495dSmrg language. Instead, Docbook is used to create the manual and the 2336ac495dSmrg FAQ, and Doxygen is used to construct the API 2436ac495dSmrg reference. Although divergent, this conforms to the GNU Project 2536ac495dSmrg recommendations as long as the output is of sufficient quality, 2636ac495dSmrg as per 2736ac495dSmrg <a class="link" href="http://www.gnu.org/prep/standards/standards.html#Documentation" target="_top"> 2836ac495dSmrg GNU Manuals</a>. 2936ac495dSmrg </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> 3036ac495dSmrg Certain Makefile rules are required by the GNU Coding 3136ac495dSmrg Standards. These standard rules generate HTML, PDF, XML, or man 3236ac495dSmrg files. For each of the generative rules, there is an additional 3336ac495dSmrg install rule that is used to install any generated documentation 3436ac495dSmrg files into the prescribed installation directory. Files are 3536ac495dSmrg installed into <code class="filename">share/doc</code> 3636ac495dSmrg or <code class="filename">share/man</code> directories. 3736ac495dSmrg </p><p> 3836ac495dSmrg The standard Makefile rules are conditionally supported, based 3936ac495dSmrg on the results of examining the host environment for 4036ac495dSmrg prerequisites at configuration time. If requirements are not 4136ac495dSmrg found, the rule is aliased to a dummy rule that does nothing, 4236ac495dSmrg and produces no documentation. If the requirements are found, 4336ac495dSmrg the rule forwards to a private rule that produces the requested 4436ac495dSmrg documentation. 4536ac495dSmrg </p><p> 4636ac495dSmrg For more details on what prerequisites were found and where, 4736ac495dSmrg please consult the file <code class="filename">config.log</code> in the 4836ac495dSmrg libstdc++ build directory. Compare this log to what is expected 4936ac495dSmrg for the relevant Makefile conditionals: 5036ac495dSmrg <code class="literal">BUILD_INFO</code>, <code class="literal">BUILD_XML</code>, 5136ac495dSmrg <code class="literal">BUILD_HTML</code>, <code class="literal">BUILD_MAN</code>, 5236ac495dSmrg <code class="literal">BUILD_PDF</code>, and <code class="literal">BUILD_EPUB</code>. 5336ac495dSmrg </p><p> 5436ac495dSmrg Supported Makefile rules: 5536ac495dSmrg </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"> 5636ac495dSmrg <span class="emphasis"><em>make html</em></span> 5736ac495dSmrg , </span><span class="term"> 5836ac495dSmrg <span class="emphasis"><em>make install-html</em></span> 5936ac495dSmrg </span></dt><dd><p> 6036ac495dSmrg Generates multi-page HTML documentation, and installs it 6136ac495dSmrg in the following directories: 6236ac495dSmrg </p><p> 6336ac495dSmrg <code class="filename">doc/libstdc++/libstdc++-api.html</code> 6436ac495dSmrg </p><p> 6536ac495dSmrg <code class="filename">doc/libstdc++/libstdc++-manual.html</code> 6636ac495dSmrg </p></dd><dt><span class="term"> 6736ac495dSmrg <span class="emphasis"><em>make pdf</em></span> 6836ac495dSmrg , </span><span class="term"> 6936ac495dSmrg <span class="emphasis"><em>make install-pdf</em></span> 7036ac495dSmrg </span></dt><dd><p> 7136ac495dSmrg Generates indexed PDF documentation, and installs it as 7236ac495dSmrg the following files: 7336ac495dSmrg </p><p> 7436ac495dSmrg <code class="filename">doc/libstdc++/libstdc++-api.pdf</code> 7536ac495dSmrg </p><p> 7636ac495dSmrg <code class="filename">doc/libstdc++/libstdc++-manual.pdf</code> 7736ac495dSmrg </p></dd><dt><span class="term"> 7836ac495dSmrg <span class="emphasis"><em>make man</em></span> 7936ac495dSmrg , </span><span class="term"> 8036ac495dSmrg <span class="emphasis"><em>make install-man</em></span> 8136ac495dSmrg </span></dt><dd><p> 8236ac495dSmrg Generates man pages, and installs it in the following directory: 8336ac495dSmrg </p><p> 8436ac495dSmrg <code class="filename">man/man3/</code> 8536ac495dSmrg </p><p> 8636ac495dSmrg The generated man pages are namespace-qualified, so to look at 8736ac495dSmrg the man page for <code class="classname">vector</code>, one would use 8836ac495dSmrg <span class="command"><strong>man std::vector</strong></span>. 8936ac495dSmrg </p></dd><dt><span class="term"> 9036ac495dSmrg <span class="emphasis"><em>make epub</em></span> 9136ac495dSmrg , </span><span class="term"> 9236ac495dSmrg <span class="emphasis"><em>make install-epub</em></span> 9336ac495dSmrg </span></dt><dd><p> 9436ac495dSmrg Generates documentation in the ebook/portable electronic 9536ac495dSmrg reader format called Epub, and installs it as the 9636ac495dSmrg following file. 9736ac495dSmrg </p><p> 9836ac495dSmrg <code class="filename">doc/libstdc++/libstdc++-manual.epub</code> 9936ac495dSmrg </p></dd><dt><span class="term"> 10036ac495dSmrg <span class="emphasis"><em>make xml</em></span> 10136ac495dSmrg , </span><span class="term"> 10236ac495dSmrg <span class="emphasis"><em>make install-xml</em></span> 10336ac495dSmrg </span></dt><dd><p> 10436ac495dSmrg Generates single-file XML documentation, and installs it 10536ac495dSmrg as the following files: 10636ac495dSmrg </p><p> 10736ac495dSmrg <code class="filename">doc/libstdc++/libstdc++-api-single.xml</code> 10836ac495dSmrg </p><p> 10936ac495dSmrg <code class="filename">doc/libstdc++/libstdc++-manual-single.xml</code> 11036ac495dSmrg </p></dd></dl></div><p> 11136ac495dSmrg Makefile rules for several other formats are explicitly not 11236ac495dSmrg supported, and are always aliased to dummy rules. These 11336ac495dSmrg unsupported formats are: <span class="emphasis"><em>info</em></span>, 11436ac495dSmrg <span class="emphasis"><em>ps</em></span>, and <span class="emphasis"><em>dvi</em></span>. 11536ac495dSmrg </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> 11636ac495dSmrg Prerequisite tools are Bash 2.0 or later, 117*8feb0f0bSmrg <a class="link" href="http://www.doxygen.nl" target="_top">Doxygen</a>, and 11836ac495dSmrg the <a class="link" href="http://www.gnu.org/software/coreutils/" target="_top">GNU 11936ac495dSmrg coreutils</a>. (GNU versions of find, xargs, and possibly 12036ac495dSmrg sed and grep are used, just because the GNU versions make 12136ac495dSmrg things very easy.) 12236ac495dSmrg </p><p> 12336ac495dSmrg To generate the pretty pictures and hierarchy 12436ac495dSmrg graphs, the 12536ac495dSmrg <a class="link" href="http://www.graphviz.org" target="_top">Graphviz</a> package 12636ac495dSmrg will need to be installed. For PDF 12736ac495dSmrg output, <a class="link" href="http://www.tug.org/applications/pdftex/" target="_top"> 12836ac495dSmrg pdflatex</a> is required as well as a number of TeX packages 12936ac495dSmrg such as <span class="package">texlive-xtab</span> and 13036ac495dSmrg <span class="package">texlive-tocloft</span>. 13136ac495dSmrg </p><p> 13236ac495dSmrg Be warned the PDF file generated via doxygen is extremely 13336ac495dSmrg large. At last count, the PDF file is over three thousand 13436ac495dSmrg pages. Generating this document taxes the underlying TeX 13536ac495dSmrg formatting system, and will require the expansion of TeX's memory 13636ac495dSmrg capacity. Specifically, the <code class="literal">pool_size</code> 13736ac495dSmrg variable in the configuration file <code class="filename">texmf.cnf</code> may 13836ac495dSmrg need to be increased by a minimum factor of two. 13936ac495dSmrg </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> 14036ac495dSmrg The following Makefile rules run Doxygen to generate HTML 14136ac495dSmrg docs, XML docs, XML docs as a single file, PDF docs, and the 14236ac495dSmrg man pages. These rules are not conditional! If the required 14336ac495dSmrg tools are not found, or are the wrong versions, the rule may 14436ac495dSmrg end in an error. 14536ac495dSmrg </p><p> 14636ac495dSmrg </p><pre class="screen"><strong class="userinput"><code>make doc-html-doxygen</code></strong></pre><p> 14736ac495dSmrg </p><p> 14836ac495dSmrg </p><pre class="screen"><strong class="userinput"><code>make doc-xml-doxygen</code></strong></pre><p> 14936ac495dSmrg </p><p> 15036ac495dSmrg </p><pre class="screen"><strong class="userinput"><code>make doc-xml-single-doxygen</code></strong></pre><p> 15136ac495dSmrg </p><p> 15236ac495dSmrg </p><pre class="screen"><strong class="userinput"><code>make doc-pdf-doxygen</code></strong></pre><p> 15336ac495dSmrg </p><p> 15436ac495dSmrg </p><pre class="screen"><strong class="userinput"><code>make doc-man-doxygen</code></strong></pre><p> 15536ac495dSmrg </p><p> 15636ac495dSmrg Generated files are output into separate sub directories of 15736ac495dSmrg <code class="filename">doc/doxygen/</code> in the 15836ac495dSmrg build directory, based on the output format. For instance, the 15936ac495dSmrg HTML docs will be in <code class="filename">doc/doxygen/html</code>. 16036ac495dSmrg </p><p> 16136ac495dSmrg Careful observers will see that the Makefile rules simply call 16236ac495dSmrg a script from the source tree, <code class="filename">run_doxygen</code>, which 16336ac495dSmrg does the actual work of running Doxygen and then (most 16436ac495dSmrg importantly) massaging the output files. If for some reason 16536ac495dSmrg you prefer to not go through the Makefile, you can call this 16636ac495dSmrg script directly. (Start by passing <code class="literal">--help</code>.) 16736ac495dSmrg </p><p> 16836ac495dSmrg If you wish to tweak the Doxygen settings, do so by editing 16936ac495dSmrg <code class="filename">doc/doxygen/user.cfg.in</code>. Notes to fellow 17036ac495dSmrg library hackers are written in triple-# comments. 17136ac495dSmrg </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> 17236ac495dSmrg Sometimes, mis-configuration of the pre-requisite tools can 17336ac495dSmrg lead to errors when attempting to build the 17436ac495dSmrg documentation. Here are some of the obvious errors, and ways 17536ac495dSmrg to fix some common issues that may appear quite cryptic. 17636ac495dSmrg </p><p> 17736ac495dSmrg First, if using a rule like <code class="code">make pdf</code>, try to 17836ac495dSmrg narrow down the scope of the error to either docbook 17936ac495dSmrg (<code class="code">make doc-pdf-docbook</code>) or doxygen (<code class="code">make 18036ac495dSmrg doc-pdf-doxygen</code>). 18136ac495dSmrg </p><p> 18236ac495dSmrg Working on the doxygen path only, closely examine the 18336ac495dSmrg contents of the following build directory: <code class="filename">build/target/libstdc++-v3/doc/doxygen/latex</code>. 18436ac495dSmrg Pay attention to three files enclosed within, annotated as follows. 18536ac495dSmrg </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> 18636ac495dSmrg <span class="emphasis"><em>refman.tex</em></span> 18736ac495dSmrg </p><p> 18836ac495dSmrg The actual latex file, or partial latex file. This is generated 18936ac495dSmrg via <span class="command"><strong>doxygen</strong></span>, and is the LaTeX version of the 19036ac495dSmrg Doxygen XML file <code class="filename">libstdc++-api.xml</code>. Go to a specific 19136ac495dSmrg line, and look at the generated LaTeX, and try to deduce what 19236ac495dSmrg markup in <code class="filename">libstdc++-api.xml</code> is causing it. 19336ac495dSmrg </p></li><li class="listitem"><p> 19436ac495dSmrg <span class="emphasis"><em>refman.log</em></span> 19536ac495dSmrg </p><p> 19636ac495dSmrg A log created by <span class="command"><strong>latex</strong></span> as it processes the 19736ac495dSmrg <code class="filename">refman.tex</code> file. If generating the PDF fails 19836ac495dSmrg look at the end of this file for errors such as: 19936ac495dSmrg </p><pre class="screen"> 20036ac495dSmrg ! LaTeX Error: File `xtab.sty' not found. 20136ac495dSmrg </pre><p> 20236ac495dSmrg This indicates a required TeX package is missing. For the example 20336ac495dSmrg above the <span class="package">texlive-xtab</span> package needs to be 20436ac495dSmrg installed. 20536ac495dSmrg </p></li><li class="listitem"><p> 20636ac495dSmrg <span class="emphasis"><em>refman.out</em></span> 20736ac495dSmrg </p><p> 20836ac495dSmrg A log of the compilation of the converted LaTeX form to PDF. This 20936ac495dSmrg is a linear list, from the beginning of the 21036ac495dSmrg <code class="filename">refman.tex</code> file: the last entry of this file 21136ac495dSmrg should be the end of the LaTeX file. If it is truncated, then you 21236ac495dSmrg know that the last entry is the last part of the generated LaTeX 21336ac495dSmrg source file that is valid. Often this file contains an error with 21436ac495dSmrg a specific line number of <code class="filename">refman.tex</code> that is 21536ac495dSmrg incorrect, or will have clues at the end of the file with the dump 21636ac495dSmrg of the memory usage of LaTeX. 21736ac495dSmrg </p></li></ul></div><p> 21836ac495dSmrg If the error at hand is not obvious after examination, a 21936ac495dSmrg fall-back strategy is to start commenting out the doxygen 22036ac495dSmrg input sources, which can be found in 22136ac495dSmrg <code class="filename">doc/doxygen/user.cfg.in</code>, look for the 22236ac495dSmrg <code class="literal">INPUT</code> tag. Start by commenting out whole 22336ac495dSmrg directories of header files, until the offending header is 22436ac495dSmrg identified. Then, read the latex log files to try and find 22536ac495dSmrg surround text, and look for that in the offending header. 22636ac495dSmrg </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="doxygen.markup"></a>Markup</h4></div></div></div><p> 22736ac495dSmrg In general, libstdc++ files should be formatted according to 22836ac495dSmrg the rules found in the 22936ac495dSmrg <a class="link" href="source_code_style.html" title="Coding Style">Coding Standard</a>. Before 23036ac495dSmrg any doxygen-specific formatting tweaks are made, please try to 23136ac495dSmrg make sure that the initial formatting is sound. 23236ac495dSmrg </p><p> 23336ac495dSmrg Adding Doxygen markup to a file (informally called 234*8feb0f0bSmrg <span class="quote">“<span class="quote">doxygenating</span>”</span>) is very simple. See the 235*8feb0f0bSmrg <a class="link" href="http://www.doxygen.nl/download.html#latestman" target="_top">Doxygen 236*8feb0f0bSmrg manual</a> for details. 23736ac495dSmrg We try to use a very-recent version of Doxygen. 23836ac495dSmrg </p><p> 23936ac495dSmrg For classes, use 24036ac495dSmrg <code class="classname">deque</code>/<code class="classname">vector</code>/<code class="classname">list</code> 24136ac495dSmrg and <code class="classname">std::pair</code> as examples. For 24236ac495dSmrg functions, see their member functions, and the free functions 24336ac495dSmrg in <code class="filename">stl_algobase.h</code>. Member 24436ac495dSmrg functions of other container-like types should read similarly to 24536ac495dSmrg these member functions. 24636ac495dSmrg </p><p> 24736ac495dSmrg Some commentary to accompany 248*8feb0f0bSmrg the first list in the <a class="link" href="http://www.doxygen.nl/manual/docblocks.html" target="_top">Special 24936ac495dSmrg Documentation Blocks</a> section of the Doxygen manual: 25036ac495dSmrg </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> 25136ac495dSmrg ...not the Qt style. The intermediate *'s are preferred. 25236ac495dSmrg </p></li><li class="listitem"><p> 25336ac495dSmrg Use the triple-slash style only for one-line comments (the 25436ac495dSmrg <span class="quote">“<span class="quote">brief</span>”</span> mode). 25536ac495dSmrg </p></li><li class="listitem"><p> 25636ac495dSmrg This is disgusting. Don't do this. 25736ac495dSmrg </p></li></ol></div><p> 25836ac495dSmrg Some specific guidelines: 25936ac495dSmrg </p><p> 26036ac495dSmrg Use the @-style of commands, not the !-style. Please be 26136ac495dSmrg careful about whitespace in your markup comments. Most of the 26236ac495dSmrg time it doesn't matter; doxygen absorbs most whitespace, and 26336ac495dSmrg both HTML and *roff are agnostic about whitespace. However, 26436ac495dSmrg in <pre> blocks and @code/@endcode sections, spacing can 26536ac495dSmrg have <span class="quote">“<span class="quote">interesting</span>”</span> effects. 26636ac495dSmrg </p><p> 26736ac495dSmrg Use either kind of grouping, as 26836ac495dSmrg appropriate. <code class="filename">doxygroups.cc</code> exists for this 26936ac495dSmrg purpose. See <code class="filename">stl_iterator.h</code> 27036ac495dSmrg for a good example of the <span class="quote">“<span class="quote">other</span>”</span> kind of grouping. 27136ac495dSmrg </p><p> 27236ac495dSmrg Please use markup tags like @p and @a when referring to things 27336ac495dSmrg such as the names of function parameters. Use @e for emphasis 27436ac495dSmrg when necessary. Use @c to refer to other standard names. 27536ac495dSmrg (Examples of all these abound in the present code.) 27636ac495dSmrg </p><p> 27736ac495dSmrg Complicated math functions should use the multi-line format. 27836ac495dSmrg An example from <code class="filename">random.h</code>: 27936ac495dSmrg </p><p> 28036ac495dSmrg</p><div class="literallayout"><p><br /> 28136ac495dSmrg/**<br /> 28236ac495dSmrg * @brief A model of a linear congruential random number generator.<br /> 28336ac495dSmrg *<br /> 28436ac495dSmrg * @f[<br /> 28536ac495dSmrg * x_{i+1}\leftarrow(ax_{i} + c) \bmod m<br /> 28636ac495dSmrg * @f]<br /> 28736ac495dSmrg */<br /> 28836ac495dSmrg</p></div><p> 28936ac495dSmrg </p><p> 29036ac495dSmrg One area of note is the markup required for 29136ac495dSmrg <code class="literal">@file</code> markup in header files. Two details 29236ac495dSmrg are important: for filenames that have the same name in 29336ac495dSmrg multiple directories, include part of the installed path to 29436ac495dSmrg disambiguate. For example: 29536ac495dSmrg </p><p> 29636ac495dSmrg</p><div class="literallayout"><p><br /> 29736ac495dSmrg/** @file debug/vector<br /> 29836ac495dSmrg * This file is a GNU debug extension to the Standard C++ Library.<br /> 29936ac495dSmrg */<br /> 30036ac495dSmrg</p></div><p> 30136ac495dSmrg </p><p> 30236ac495dSmrg The other relevant detail for header files is the use of a 30336ac495dSmrg libstdc++-specific doxygen alias that helps distinguish 30436ac495dSmrg between public header files (like <code class="filename">random</code>) 30536ac495dSmrg from implementation or private header files (like 30636ac495dSmrg <code class="filename">bits/c++config.h</code>.) This alias is spelled 30736ac495dSmrg <code class="literal">@headername</code> and can take one or two 30836ac495dSmrg arguments that detail the public header file or files that 30936ac495dSmrg should be included to use the contents of the file. All header 31036ac495dSmrg files that are not intended for direct inclusion must use 31136ac495dSmrg <code class="literal">headername</code> in the <code class="literal">file</code> 31236ac495dSmrg block. An example: 31336ac495dSmrg </p><p> 31436ac495dSmrg</p><div class="literallayout"><p><br /> 31536ac495dSmrg/** @file bits/basic_string.h<br /> 31636ac495dSmrg * This is an internal header file, included by other library headers.<br /> 31736ac495dSmrg * Do not attempt to use it directly. @headername{string}<br /> 31836ac495dSmrg */<br /> 31936ac495dSmrg</p></div><p> 32036ac495dSmrg </p><p> 32136ac495dSmrg Be careful about using certain, special characters when 32236ac495dSmrg writing Doxygen comments. Single and double quotes, and 32336ac495dSmrg separators in filenames are two common trouble spots. When in 32436ac495dSmrg doubt, consult the following table. 32536ac495dSmrg </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"><i></td><td align="left">@a word</td></tr><tr><td align="left"><b></td><td align="left">@b word</td></tr><tr><td align="left"><code></td><td align="left">@c word</td></tr><tr><td align="left"><em></td><td align="left">@a word</td></tr><tr><td align="left"><em></td><td align="left"><em>two words or more</em></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> 32636ac495dSmrg Editing the DocBook sources requires an XML editor. Many 32736ac495dSmrg exist: some notable options 32836ac495dSmrg include <span class="command"><strong>emacs</strong></span>, <span class="application">Kate</span>, 32936ac495dSmrg or <span class="application">Conglomerate</span>. 33036ac495dSmrg </p><p> 33136ac495dSmrg Some editors support special <span class="quote">“<span class="quote">XML Validation</span>”</span> 33236ac495dSmrg modes that can validate the file as it is 33336ac495dSmrg produced. Recommended is the <span class="command"><strong>nXML Mode</strong></span> 33436ac495dSmrg for <span class="command"><strong>emacs</strong></span>. 33536ac495dSmrg </p><p> 33636ac495dSmrg Besides an editor, additional DocBook files and XML tools are 33736ac495dSmrg also required. 33836ac495dSmrg </p><p> 33936ac495dSmrg Access to the DocBook 5.0 stylesheets and schema is required. The 34036ac495dSmrg stylesheets are usually packaged by vendor, in something 34136ac495dSmrg like <code class="filename">docbook5-style-xsl</code>. To exactly match 34236ac495dSmrg generated output, please use a version of the stylesheets 34336ac495dSmrg equivalent 34436ac495dSmrg to <code class="filename">docbook5-style-xsl-1.75.2-3</code>. The 34536ac495dSmrg installation directory for this package corresponds to 34636ac495dSmrg the <code class="literal">XSL_STYLE_DIR</code> 34736ac495dSmrg in <code class="filename">doc/Makefile.am</code> and defaults 34836ac495dSmrg to <code class="filename">/usr/share/sgml/docbook/xsl-ns-stylesheets</code>. 34936ac495dSmrg </p><p> 35036ac495dSmrg For processing XML, an XSLT processor and some style 35136ac495dSmrg sheets are necessary. Defaults are <span class="command"><strong>xsltproc</strong></span> 35236ac495dSmrg provided by <code class="filename">libxslt</code>. 35336ac495dSmrg </p><p> 35436ac495dSmrg For validating the XML document, you'll need 35536ac495dSmrg something like <span class="command"><strong>xmllint</strong></span> and access to the 35636ac495dSmrg relevant DocBook schema. These are provided 35736ac495dSmrg by a vendor package like <code class="filename">libxml2</code> and <code class="filename">docbook5-schemas-5.0-4</code> 35836ac495dSmrg </p><p> 35936ac495dSmrg For PDF output, something that transforms valid Docbook XML to PDF is 36036ac495dSmrg required. Possible solutions include <a class="link" href="http://dblatex.sourceforge.net" target="_top">dblatex</a>, 36136ac495dSmrg <span class="command"><strong>xmlto</strong></span>, or <span class="command"><strong>prince</strong></span>. Of 36236ac495dSmrg these, <span class="command"><strong>dblatex</strong></span> is the default. 36336ac495dSmrg Please consult the <code class="email"><<a class="email" href="mailto:libstdc++@gcc.gnu.org">libstdc++@gcc.gnu.org</a>></code> list when 36436ac495dSmrg preparing printed manuals for current best practice and 36536ac495dSmrg suggestions. 36636ac495dSmrg </p><p> 36736ac495dSmrg For Texinfo output, something that transforms valid Docbook 36836ac495dSmrg XML to Texinfo is required. The default choice is <a class="link" href="http://docbook2x.sourceforge.net/" target="_top">docbook2X</a>. 36936ac495dSmrg </p><p> 370c0a68be4Smrg 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. 37136ac495dSmrg </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> 37236ac495dSmrg The following Makefile rules generate (in order): an HTML 37336ac495dSmrg version of all the DocBook documentation, a PDF version of the 37436ac495dSmrg same, and a single XML document. These rules are not 37536ac495dSmrg conditional! If the required tools are not found, or are the 37636ac495dSmrg wrong versions, the rule may end in an error. 37736ac495dSmrg </p><p> 37836ac495dSmrg </p><pre class="screen"><strong class="userinput"><code>make doc-html-docbook</code></strong></pre><p> 37936ac495dSmrg </p><p> 38036ac495dSmrg </p><pre class="screen"><strong class="userinput"><code>make doc-pdf-docbook</code></strong></pre><p> 38136ac495dSmrg </p><p> 38236ac495dSmrg </p><pre class="screen"><strong class="userinput"><code>make doc-xml-single-docbook</code></strong></pre><p> 38336ac495dSmrg </p><p> 384a2dc1f3fSmrg Generated files are output into separate sub-directores of 38536ac495dSmrg <code class="filename">doc/docbook/</code> in the 38636ac495dSmrg build directory, based on the output format. For instance, the 38736ac495dSmrg HTML docs will be in <code class="filename">doc/docbook/html</code>. 38836ac495dSmrg </p><p> 389a2dc1f3fSmrg The </p><pre class="screen">doc-html-docbook-regenerate</pre><p> target will generate 390a2dc1f3fSmrg the HTML files and copy them back to the libstdc++ source tree. 391a2dc1f3fSmrg This can be used to update the HTML files that are checked in to 392a2dc1f3fSmrg version control. 393a2dc1f3fSmrg </p><p> 39436ac495dSmrg If the Docbook stylesheets are installed in a custom location, 39536ac495dSmrg one can use the variable <code class="literal">XSL_STYLE_DIR</code> to 39636ac495dSmrg override the Makefile defaults. For example: 39736ac495dSmrg </p><pre class="screen"> 39836ac495dSmrg <strong class="userinput"><code> 39936ac495dSmrgmake <code class="literal">XSL_STYLE_DIR="/usr/share/xml/docbook/stylesheet/nwalsh"</code> doc-html-docbook 40036ac495dSmrg </code></strong> 40136ac495dSmrg </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> 40236ac495dSmrg Sometimes, mis-configuration of the pre-requisite tools can 40336ac495dSmrg lead to errors when attempting to build the 40436ac495dSmrg documentation. Here are some of the obvious errors, and ways 40536ac495dSmrg to fix some common issues that may appear quite cryptic. 40636ac495dSmrg </p><p> 40736ac495dSmrg First, if using a rule like <code class="code">make pdf</code>, try to 40836ac495dSmrg narrow down the scope of the error to either docbook 40936ac495dSmrg (<code class="code">make doc-pdf-docbook</code>) or doxygen (<code class="code">make 41036ac495dSmrg doc-pdf-doxygen</code>). 41136ac495dSmrg </p><p> 41236ac495dSmrg Working on the docbook path only, closely examine the 41336ac495dSmrg contents of the following build directory: 41436ac495dSmrg <code class="filename">build/target/libstdc++-v3/doc/docbook/latex</code>. 41536ac495dSmrg Pay attention to three files enclosed within, annotated as follows. 41636ac495dSmrg </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> 41736ac495dSmrg <span class="emphasis"><em>spine.tex</em></span> 41836ac495dSmrg </p><p> 41936ac495dSmrg The actual latex file, or partial latex file. This is generated 42036ac495dSmrg via <span class="command"><strong>dblatex</strong></span>, and is the LaTeX version of the 42136ac495dSmrg DocBook XML file <code class="filename">spine.xml</code>. Go to a specific 42236ac495dSmrg line, and look at the generated LaTeX, and try to deduce what 42336ac495dSmrg markup in <code class="filename">spine.xml</code> is causing it. 42436ac495dSmrg </p></li><li class="listitem"><p> 42536ac495dSmrg <span class="emphasis"><em>spine.out</em></span> 42636ac495dSmrg </p><p> 42736ac495dSmrg A log of the conversion from the XML form to the LaTeX form. This 42836ac495dSmrg is a linear list, from the beginning of the 42936ac495dSmrg <code class="filename">spine.xml</code> file: the last entry of this file 43036ac495dSmrg should be the end of the DocBook file. If it is truncated, then 43136ac495dSmrg you know that the last entry is the last part of the XML source 43236ac495dSmrg file that is valid. The error is after this point. 43336ac495dSmrg </p></li><li class="listitem"><p> 43436ac495dSmrg <span class="emphasis"><em>spine.log</em></span> 43536ac495dSmrg </p><p> 43636ac495dSmrg A log of the compilation of the converted LaTeX form to pdf. This 43736ac495dSmrg is a linear list, from the beginning of the 43836ac495dSmrg <code class="filename">spine.tex</code> file: the last entry of this file 43936ac495dSmrg should be the end of the LaTeX file. If it is truncated, then you 44036ac495dSmrg know that the last entry is the last part of the generated LaTeX 44136ac495dSmrg source file that is valid. Often this file contains an error with 44236ac495dSmrg a specific line number of <code class="filename">spine.tex</code> that is 44336ac495dSmrg incorrect. 44436ac495dSmrg </p></li></ul></div><p> 44536ac495dSmrg If the error at hand is not obvious after examination, or if one 44636ac495dSmrg encounters the inscruitable <span class="quote">“<span class="quote">Incomplete 44736ac495dSmrg \ifmmode</span>”</span> error, a fall-back strategy is to start 44836ac495dSmrg commenting out parts of the XML document (regardless of what 44936ac495dSmrg this does to over-all document validity). Start by 45036ac495dSmrg commenting out each of the largest parts of the 45136ac495dSmrg <code class="filename">spine.xml</code> file, section by section, 45236ac495dSmrg until the offending section is identified. 45336ac495dSmrg </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> 45436ac495dSmrg After editing the xml sources, please make sure that the XML 45536ac495dSmrg documentation and markup is still valid. This can be 45636ac495dSmrg done easily, with the following validation rule: 45736ac495dSmrg </p><pre class="screen"> 45836ac495dSmrg <strong class="userinput"><code>make doc-xml-validate-docbook</code></strong> 45936ac495dSmrg </pre><p> 46036ac495dSmrg This is equivalent to doing: 46136ac495dSmrg </p><pre class="screen"> 46236ac495dSmrg <strong class="userinput"><code> 46336ac495dSmrg xmllint --noout --valid <code class="filename">xml/index.xml</code> 46436ac495dSmrg </code></strong> 46536ac495dSmrg </pre><p> 46636ac495dSmrg Please note that individual sections and chapters of the 46736ac495dSmrg manual can be validated by substituting the file desired for 46836ac495dSmrg <code class="filename">xml/index.xml</code> in the command 46936ac495dSmrg above. Reducing scope in this manner can be helpful when 47036ac495dSmrg validation on the entire manual fails. 47136ac495dSmrg </p><p> 47236ac495dSmrg All Docbook xml sources should always validate. No excuses! 47336ac495dSmrg </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 /> 47436ac495dSmrg <span class="emphasis"><em>Which files are important</em></span><br /> 47536ac495dSmrg<br /> 47636ac495dSmrg All Docbook files are in the directory<br /> 47736ac495dSmrg libstdc++-v3/doc/xml<br /> 47836ac495dSmrg<br /> 47936ac495dSmrg Inside this directory, the files of importance:<br /> 48036ac495dSmrg spine.xml - index to documentation set<br /> 48136ac495dSmrg manual/spine.xml - index to manual<br /> 48236ac495dSmrg manual/*.xml - individual chapters and sections of the manual<br /> 48336ac495dSmrg faq.xml - index to FAQ<br /> 48436ac495dSmrg api.xml - index to source level / API<br /> 48536ac495dSmrg<br /> 48636ac495dSmrg All *.txml files are template xml files, i.e., otherwise empty files with<br /> 48736ac495dSmrg the correct structure, suitable for filling in with new information.<br /> 48836ac495dSmrg<br /> 48936ac495dSmrg <span class="emphasis"><em>Canonical Writing Style</em></span><br /> 49036ac495dSmrg<br /> 49136ac495dSmrg class template<br /> 49236ac495dSmrg function template<br /> 49336ac495dSmrg member function template<br /> 49436ac495dSmrg (via C++ Templates, Vandevoorde)<br /> 49536ac495dSmrg<br /> 49636ac495dSmrg class in namespace std: allocator, not std::allocator<br /> 49736ac495dSmrg<br /> 49836ac495dSmrg header file: iostream, not <iostream><br /> 49936ac495dSmrg<br /> 50036ac495dSmrg<br /> 50136ac495dSmrg <span class="emphasis"><em>General structure</em></span><br /> 50236ac495dSmrg<br /> 50336ac495dSmrg <set><br /> 50436ac495dSmrg <book><br /> 50536ac495dSmrg </book><br /> 50636ac495dSmrg<br /> 50736ac495dSmrg <book><br /> 50836ac495dSmrg <chapter><br /> 50936ac495dSmrg </chapter><br /> 51036ac495dSmrg </book><br /> 51136ac495dSmrg<br /> 51236ac495dSmrg <book><br /> 51336ac495dSmrg <part><br /> 51436ac495dSmrg <chapter><br /> 51536ac495dSmrg <section><br /> 51636ac495dSmrg </section><br /> 51736ac495dSmrg<br /> 51836ac495dSmrg <sect1><br /> 51936ac495dSmrg </sect1><br /> 52036ac495dSmrg<br /> 52136ac495dSmrg <sect1><br /> 52236ac495dSmrg <sect2><br /> 52336ac495dSmrg </sect2><br /> 52436ac495dSmrg </sect1><br /> 52536ac495dSmrg </chapter><br /> 52636ac495dSmrg<br /> 52736ac495dSmrg <chapter><br /> 52836ac495dSmrg </chapter><br /> 52936ac495dSmrg </part><br /> 53036ac495dSmrg </book><br /> 53136ac495dSmrg<br /> 53236ac495dSmrg </set><br /> 53336ac495dSmrg </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> 53436ac495dSmrg Complete details on Docbook markup can be found in the 535a2dc1f3fSmrg <a class="link" href="https://tdg.docbook.org/tdg/5.0/ref-elements.html" target="_top">DocBook Element Reference</a>. 53636ac495dSmrg An incomplete reference for HTML to Docbook conversion is 53736ac495dSmrg detailed in the table below. 53836ac495dSmrg </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"><p></td><td align="left"><para></td></tr><tr><td align="left"><pre></td><td align="left"><computeroutput>, <programlisting>, 53936ac495dSmrg <literallayout></td></tr><tr><td align="left"><ul></td><td align="left"><itemizedlist></td></tr><tr><td align="left"><ol></td><td align="left"><orderedlist></td></tr><tr><td align="left"><il></td><td align="left"><listitem></td></tr><tr><td align="left"><dl></td><td align="left"><variablelist></td></tr><tr><td align="left"><dt></td><td align="left"><term></td></tr><tr><td align="left"><dd></td><td align="left"><listitem></td></tr><tr><td align="left"><a href=""></td><td align="left"><ulink url=""></td></tr><tr><td align="left"><code></td><td align="left"><literal>, <programlisting></td></tr><tr><td align="left"><strong></td><td align="left"><emphasis></td></tr><tr><td align="left"><em></td><td align="left"><emphasis></td></tr><tr><td align="left">"</td><td align="left"><quote></td></tr></tbody></table></div></div><br class="table-break" /><p> 54036ac495dSmrg And examples of detailed markup for which there are no real HTML 54136ac495dSmrg equivalents are listed in the table below. 54236ac495dSmrg</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"><structname></td><td align="left"><structname>char_traits</structname></td></tr><tr><td align="left"><classname></td><td align="left"><classname>string</classname></td></tr><tr><td align="left"><function></td><td align="left"> 54336ac495dSmrg <p><function>clear()</function></p> 54436ac495dSmrg <p><function>fs.clear()</function></p> 54536ac495dSmrg </td></tr><tr><td align="left"><type></td><td align="left"><type>long long</type></td></tr><tr><td align="left"><varname></td><td align="left"><varname>fs</varname></td></tr><tr><td align="left"><literal></td><td align="left"> 54636ac495dSmrg <p><literal>-Weffc++</literal></p> 54736ac495dSmrg <p><literal>rel_ops</literal></p> 54836ac495dSmrg </td></tr><tr><td align="left"><constant></td><td align="left"> 54936ac495dSmrg <p><constant>_GNU_SOURCE</constant></p> 55036ac495dSmrg <p><constant>3.0</constant></p> 55136ac495dSmrg </td></tr><tr><td align="left"><command></td><td align="left"><command>g++</command></td></tr><tr><td align="left"><errortext></td><td align="left"><errortext>In instantiation of</errortext></td></tr><tr><td align="left"><filename></td><td align="left"> 55236ac495dSmrg <p><filename class="headerfile">ctype.h</filename></p> 55336ac495dSmrg <p><filename class="directory">/home/gcc/build</filename></p> 55436ac495dSmrg <p><filename class="libraryfile">libstdc++.so</filename></p> 55536ac495dSmrg </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. 55636ac495dSmrg Porting and Maintenance 55736ac495dSmrg 55836ac495dSmrg </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>