| <?xml version="1.0" encoding="UTF-8" standalone="no"?> | |
| <!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. | |
| Porting and Maintenance | |
| </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> | |
| Documentation for the GNU C++ Library is created from three | |
| independent sources: a manual, a FAQ, and an API reference. | |
| </p><p> | |
| The sub-directory <code class="filename">doc</code> | |
| within the main source directory contains | |
| <code class="filename">Makefile.am</code> and | |
| <code class="filename">Makefile.in</code>, which provide rules for | |
| generating documentation, described in excruciating detail | |
| below. The <code class="filename">doc</code> | |
| sub-directory also contains three directories: <code class="filename">doxygen</code>, which contains scripts and | |
| fragments for <span class="command"><strong>doxygen</strong></span>, <code class="filename">html</code>, which contains an html | |
| version of the manual, and <code class="filename">xml</code>, which contains an xml version | |
| of the manual. | |
| </p><p> | |
| Diverging from established documentation conventions in the rest | |
| of the GCC project, libstdc++ does not use Texinfo as a markup | |
| language. Instead, Docbook is used to create the manual and the | |
| FAQ, and Doxygen is used to construct the API | |
| reference. Although divergent, this conforms to the GNU Project | |
| recommendations as long as the output is of sufficient quality, | |
| as per | |
| <a class="link" href="http://www.gnu.org/prep/standards/standards.html#Documentation" target="_top"> | |
| GNU Manuals</a>. | |
| </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> | |
| Certain Makefile rules are required by the GNU Coding | |
| Standards. These standard rules generate HTML, PDF, XML, or man | |
| files. For each of the generative rules, there is an additional | |
| install rule that is used to install any generated documentation | |
| files into the prescribed installation directory. Files are | |
| installed into <code class="filename">share/doc</code> | |
| or <code class="filename">share/man</code> directories. | |
| </p><p> | |
| The standard Makefile rules are conditionally supported, based | |
| on the results of examining the host environment for | |
| prerequisites at configuration time. If requirements are not | |
| found, the rule is aliased to a dummy rule that does nothing, | |
| and produces no documentation. If the requirements are found, | |
| the rule forwards to a private rule that produces the requested | |
| documentation. | |
| </p><p> | |
| For more details on what prerequisites were found and where, | |
| please consult the file <code class="filename">config.log</code> in the | |
| libstdc++ build directory. Compare this log to what is expected | |
| for the relevant Makefile conditionals: | |
| <code class="literal">BUILD_INFO</code>, <code class="literal">BUILD_XML</code>, | |
| <code class="literal">BUILD_HTML</code>, <code class="literal">BUILD_MAN</code>, | |
| <code class="literal">BUILD_PDF</code>, and <code class="literal">BUILD_EPUB</code>. | |
| </p><p> | |
| Supported Makefile rules: | |
| </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"> | |
| <span class="emphasis"><em>make html</em></span> | |
| , </span><span class="term"> | |
| <span class="emphasis"><em>make install-html</em></span> | |
| </span></dt><dd><p> | |
| Generates multi-page HTML documentation, and installs it | |
| in the following directories: | |
| </p><p> | |
| <code class="filename">doc/libstdc++/libstdc++-api.html</code> | |
| </p><p> | |
| <code class="filename">doc/libstdc++/libstdc++-manual.html</code> | |
| </p></dd><dt><span class="term"> | |
| <span class="emphasis"><em>make pdf</em></span> | |
| , </span><span class="term"> | |
| <span class="emphasis"><em>make install-pdf</em></span> | |
| </span></dt><dd><p> | |
| Generates indexed PDF documentation, and installs it as | |
| the following files: | |
| </p><p> | |
| <code class="filename">doc/libstdc++/libstdc++-api.pdf</code> | |
| </p><p> | |
| <code class="filename">doc/libstdc++/libstdc++-manual.pdf</code> | |
| </p></dd><dt><span class="term"> | |
| <span class="emphasis"><em>make man</em></span> | |
| , </span><span class="term"> | |
| <span class="emphasis"><em>make install-man</em></span> | |
| </span></dt><dd><p> | |
| Generates man pages, and installs it in the following directory: | |
| </p><p> | |
| <code class="filename">man/man3/</code> | |
| </p><p> | |
| The generated man pages are namespace-qualified, so to look at | |
| the man page for <code class="classname">vector</code>, one would use | |
| <span class="command"><strong>man std::vector</strong></span>. | |
| </p></dd><dt><span class="term"> | |
| <span class="emphasis"><em>make epub</em></span> | |
| , </span><span class="term"> | |
| <span class="emphasis"><em>make install-epub</em></span> | |
| </span></dt><dd><p> | |
| Generates documentation in the ebook/portable electronic | |
| reader format called Epub, and installs it as the | |
| following file. | |
| </p><p> | |
| <code class="filename">doc/libstdc++/libstdc++-manual.epub</code> | |
| </p></dd><dt><span class="term"> | |
| <span class="emphasis"><em>make xml</em></span> | |
| , </span><span class="term"> | |
| <span class="emphasis"><em>make install-xml</em></span> | |
| </span></dt><dd><p> | |
| Generates single-file XML documentation, and installs it | |
| as the following files: | |
| </p><p> | |
| <code class="filename">doc/libstdc++/libstdc++-api-single.xml</code> | |
| </p><p> | |
| <code class="filename">doc/libstdc++/libstdc++-manual-single.xml</code> | |
| </p></dd></dl></div><p> | |
| Makefile rules for several other formats are explicitly not | |
| supported, and are always aliased to dummy rules. These | |
| unsupported formats are: <span class="emphasis"><em>info</em></span>, | |
| <span class="emphasis"><em>ps</em></span>, and <span class="emphasis"><em>dvi</em></span>. | |
| </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.9.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> | |
| Prerequisite tools are Bash 2.0 or later, | |
| <a class="link" href="https://www.doxygen.nl" target="_top">Doxygen</a> | |
| 1.9.1 or later (for best results use at least 1.9.6), and | |
| the <a class="link" href="http://www.gnu.org/software/coreutils/" target="_top">GNU | |
| coreutils</a>. (GNU versions of find, xargs, and possibly | |
| sed and grep are used, just because the GNU versions make | |
| things very easy.) | |
| </p><p> | |
| To generate the pretty pictures and hierarchy | |
| graphs, the | |
| <a class="link" href="https://www.graphviz.org" target="_top">Graphviz</a> package | |
| will need to be installed. For PDF | |
| output, <a class="link" href="https://tug.org/applications/pdftex/" target="_top"> | |
| pdflatex</a> is required as well as a number of TeX packages | |
| such as <span class="package">texlive-xtab</span> and | |
| <span class="package">texlive-tocloft</span>. | |
| </p><p> | |
| Be warned the PDF file generated via doxygen is extremely | |
| large. At last count, the PDF file is over three thousand | |
| pages. Generating this document taxes the underlying TeX | |
| formatting system, and will require the expansion of TeX's memory | |
| capacity. Specifically, the <code class="literal">pool_size</code> | |
| variable in the configuration file <code class="filename">texmf.cnf</code> may | |
| need to be increased by a minimum factor of two. Alternatively, using | |
| <strong class="userinput"><code>LATEX_CMD=lualatex</code></strong> might allow the docs to be | |
| built without running out of memory. | |
| </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> | |
| The following Makefile rules run Doxygen to generate HTML | |
| docs, XML docs, XML docs as a single file, PDF docs, and the | |
| man pages. These rules are not conditional! If the required | |
| tools are not found, or are the wrong versions, the rule may | |
| end in an error. | |
| </p><p> | |
| </p><pre class="screen"><strong class="userinput"><code>make doc-html-doxygen</code></strong></pre><p> | |
| </p><p> | |
| </p><pre class="screen"><strong class="userinput"><code>make doc-xml-doxygen</code></strong></pre><p> | |
| </p><p> | |
| </p><pre class="screen"><strong class="userinput"><code>make doc-xml-single-doxygen</code></strong></pre><p> | |
| </p><p> | |
| </p><pre class="screen"><strong class="userinput"><code>make doc-pdf-doxygen</code></strong></pre><p> | |
| </p><p> | |
| </p><pre class="screen"><strong class="userinput"><code>make doc-man-doxygen</code></strong></pre><p> | |
| </p><p> | |
| Generated files are output into separate sub directories of | |
| <code class="filename">doc/doxygen/</code> in the | |
| build directory, based on the output format. For instance, the | |
| HTML docs will be in <code class="filename">doc/doxygen/html</code>. | |
| </p><p> | |
| Careful observers will see that the Makefile rules simply call | |
| a script from the source tree, <code class="filename">run_doxygen</code>, which | |
| does the actual work of running Doxygen and then (most | |
| importantly) massaging the output files. If for some reason | |
| you prefer to not go through the Makefile, you can call this | |
| script directly. (Start by passing <code class="literal">--help</code>.) | |
| </p><p> | |
| If you wish to tweak the Doxygen settings, do so by editing | |
| <code class="filename">doc/doxygen/user.cfg.in</code>. Notes to fellow | |
| library hackers are written in triple-# comments. | |
| </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> | |
| Sometimes, mis-configuration of the pre-requisite tools can | |
| lead to errors when attempting to build the | |
| documentation. Here are some of the obvious errors, and ways | |
| to fix some common issues that may appear quite cryptic. | |
| </p><p> | |
| First, if using a rule like <code class="code">make pdf</code>, try to | |
| narrow down the scope of the error to either docbook | |
| (<code class="code">make doc-pdf-docbook</code>) or doxygen (<code class="code">make | |
| doc-pdf-doxygen</code>). | |
| </p><p> | |
| Working on the doxygen path only, closely examine the | |
| contents of the following build directory: <code class="filename">build/target/libstdc++-v3/doc/doxygen/latex</code>. | |
| Pay attention to three files enclosed within, annotated as follows. | |
| </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> | |
| <span class="emphasis"><em>refman.tex</em></span> | |
| </p><p> | |
| The actual latex file, or partial latex file. This is generated | |
| via <span class="command"><strong>doxygen</strong></span>, and is the LaTeX version of the | |
| Doxygen XML file <code class="filename">libstdc++-api.xml</code>. Go to a specific | |
| line, and look at the generated LaTeX, and try to deduce what | |
| markup in <code class="filename">libstdc++-api.xml</code> is causing it. | |
| </p></li><li class="listitem"><p> | |
| <span class="emphasis"><em>refman.log</em></span> | |
| </p><p> | |
| A log created by <span class="command"><strong>latex</strong></span> as it processes the | |
| <code class="filename">refman.tex</code> file. If generating the PDF fails | |
| look at the end of this file for errors such as: | |
| </p><pre class="screen"> | |
| ! LaTeX Error: File `xtab.sty' not found. | |
| </pre><p> | |
| This indicates a required TeX package is missing. For the example | |
| above the <span class="package">texlive-xtab</span> package needs to be | |
| installed. | |
| </p></li><li class="listitem"><p> | |
| <span class="emphasis"><em>refman.out</em></span> | |
| </p><p> | |
| A log of the compilation of the converted LaTeX form to PDF. This | |
| is a linear list, from the beginning of the | |
| <code class="filename">refman.tex</code> file: the last entry of this file | |
| should be the end of the LaTeX file. If it is truncated, then you | |
| know that the last entry is the last part of the generated LaTeX | |
| source file that is valid. Often this file contains an error with | |
| a specific line number of <code class="filename">refman.tex</code> that is | |
| incorrect, or will have clues at the end of the file with the dump | |
| of the memory usage of LaTeX. | |
| </p></li></ul></div><p> | |
| If the error at hand is not obvious after examination, a | |
| fall-back strategy is to start commenting out the doxygen | |
| input sources, which can be found in | |
| <code class="filename">doc/doxygen/user.cfg.in</code>, look for the | |
| <code class="literal">INPUT</code> tag. Start by commenting out whole | |
| directories of header files, until the offending header is | |
| identified. Then, read the latex log files to try and find | |
| surround text, and look for that in the offending header. | |
| </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="doxygen.markup"></a>Markup</h4></div></div></div><p> | |
| In general, libstdc++ files should be formatted according to | |
| the rules found in the | |
| <a class="link" href="source_code_style.html" title="Coding Style">Coding Standard</a>. Before | |
| any doxygen-specific formatting tweaks are made, please try to | |
| make sure that the initial formatting is sound. | |
| </p><p> | |
| Adding Doxygen markup to a file (informally called | |
| <span class="quote">“<span class="quote">doxygenating</span>”</span>) is very simple. See the | |
| <a class="link" href="https://www.doxygen.nl/download.html#latestman" target="_top">Doxygen | |
| manual</a> for details. | |
| We try to use a very-recent version of Doxygen. | |
| </p><p> | |
| For classes, use | |
| <code class="classname">deque</code>/<code class="classname">vector</code>/<code class="classname">list</code> | |
| and <code class="classname">std::pair</code> as examples. For | |
| functions, see their member functions, and the free functions | |
| in <code class="filename">stl_algobase.h</code>. Member | |
| functions of other container-like types should read similarly to | |
| these member functions. | |
| </p><p> | |
| Some commentary to accompany | |
| the first list in the <a class="link" href="https://www.doxygen.nl/manual/docblocks.html" target="_top">Special | |
| Documentation Blocks</a> section of the Doxygen manual: | |
| </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> | |
| ...not the Qt style. The intermediate *'s are preferred. | |
| </p></li><li class="listitem"><p> | |
| Use the triple-slash style only for one-line comments (the | |
| <span class="quote">“<span class="quote">brief</span>”</span> mode). | |
| </p></li><li class="listitem"><p> | |
| This is disgusting. Don't do this. | |
| </p></li></ol></div><p> | |
| Some specific guidelines: | |
| </p><p> | |
| Use the @-style of commands, not the !-style. Please be | |
| careful about whitespace in your markup comments. Most of the | |
| time it doesn't matter; doxygen absorbs most whitespace, and | |
| both HTML and *roff are agnostic about whitespace. However, | |
| in <pre> blocks and @code/@endcode sections, spacing can | |
| have <span class="quote">“<span class="quote">interesting</span>”</span> effects. | |
| </p><p> | |
| Use either kind of grouping, as | |
| appropriate. <code class="filename">doxygroups.cc</code> exists for this | |
| purpose. See <code class="filename">stl_iterator.h</code> | |
| for a good example of the <span class="quote">“<span class="quote">other</span>”</span> kind of grouping. | |
| </p><p> | |
| Markdown can be used for formatting text. Doxygen is configured to | |
| support this, and it is a good compromise between readable comments | |
| in the C++ source and nice formatting in the generated HTML. | |
| Please format the names of function parameters in either code font | |
| or italics. Use underscores or @e for emphasis when necessary. | |
| Use backticks or @c to refer to other standard names. | |
| (Examples of all these abound in the present code.) | |
| </p><p> | |
| Complicated math functions should use the multi-line format. | |
| An example from <code class="filename">random.h</code>: | |
| </p><p> | |
| </p><div class="literallayout"><p><br /> | |
| /**<br /> | |
| * @brief A model of a linear congruential random number generator.<br /> | |
| *<br /> | |
| * @f[<br /> | |
| * x_{i+1}\leftarrow(ax_{i} + c) \bmod m<br /> | |
| * @f]<br /> | |
| */<br /> | |
| </p></div><p> | |
| </p><p> | |
| One area of note is the markup required for | |
| <code class="literal">@file</code> markup in header files. Two details | |
| are important: for filenames that have the same name in | |
| multiple directories, include part of the installed path to | |
| disambiguate. For example: | |
| </p><p> | |
| </p><div class="literallayout"><p><br /> | |
| /** @file debug/vector<br /> | |
| * This file is a GNU debug extension to the Standard C++ Library.<br /> | |
| */<br /> | |
| </p></div><p> | |
| </p><p> | |
| The other relevant detail for header files is the use of a | |
| libstdc++-specific doxygen alias that helps distinguish | |
| between public header files (like <code class="filename">random</code>) | |
| from implementation or private header files (like | |
| <code class="filename">bits/c++config.h</code>.) This alias is spelled | |
| <code class="literal">@headername</code> and can take one or two | |
| arguments that detail the public header file or files that | |
| should be included to use the contents of the file. All header | |
| files that are not intended for direct inclusion must use | |
| <code class="literal">headername</code> in the <code class="literal">file</code> | |
| block. An example: | |
| </p><p> | |
| </p><div class="literallayout"><p><br /> | |
| /** @file bits/basic_string.h<br /> | |
| * This is an internal header file, included by other library headers.<br /> | |
| * Do not attempt to use it directly. @headername{string}<br /> | |
| */<br /> | |
| </p></div><p> | |
| </p><p> | |
| Be careful about using certain, special characters when | |
| writing Doxygen comments. Single and double quotes, and | |
| separators in filenames are two common trouble spots. When in | |
| doubt, consult the following table. | |
| </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><th align="left">Markdown</th></tr></thead><tbody><tr><td align="left">\</td><td align="left">\\</td><td align="left">\\</td></tr><tr><td align="left">"</td><td align="left">\"</td><td align="left">\"</td></tr><tr><td align="left">'</td><td align="left">\'</td><td align="left">\'</td></tr><tr><td align="left"><i></td><td align="left">@a word</td><td align="left">_word_ or *word*</td></tr><tr><td align="left"><b></td><td align="left">@b word</td><td align="left">**word** or __word__</td></tr><tr><td align="left"><code></td><td align="left">@c word</td><td align="left">`word`</td></tr><tr><td align="left"><em></td><td align="left">@a word</td><td align="left">_word_ or *word*</td></tr><tr><td align="left"><em></td><td align="left"><em>two words or more</em></td><td align="left">_two words or more_</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> | |
| An XML editor is recommended for editing the DocBook sources. Many | |
| exist: some notable options | |
| include <span class="command"><strong>emacs</strong></span>, <span class="application">Kate</span>, | |
| or <span class="application">Conglomerate</span>. | |
| </p><p> | |
| Some editors support special <span class="quote">“<span class="quote">XML Validation</span>”</span> | |
| modes that can validate the file as it is | |
| produced. Recommended is the <span class="command"><strong>nXML Mode</strong></span> | |
| for <span class="command"><strong>emacs</strong></span>. | |
| </p><p> | |
| Besides an editor, additional DocBook files and XML tools are | |
| also required. | |
| </p><p> | |
| Access to the DocBook 5.0 stylesheets and schema is required. The | |
| stylesheets are usually packaged by vendor, in something | |
| like <code class="filename">docbook5-style-xsl</code>. To exactly match | |
| generated output, please use a version of the stylesheets | |
| equivalent | |
| to <code class="filename">docbook5-style-xsl-1.75.2-3</code>. The | |
| installation directory for this package corresponds to | |
| the <code class="literal">XSL_STYLE_DIR</code> | |
| in <code class="filename">doc/Makefile.am</code> and defaults | |
| to <code class="filename">/usr/share/sgml/docbook/xsl-ns-stylesheets</code>. | |
| </p><p> | |
| For processing XML, an XSLT processor and some style | |
| sheets are necessary. Defaults are <span class="command"><strong>xsltproc</strong></span> | |
| provided by <code class="filename">libxslt</code>. | |
| </p><p> | |
| For validating the XML document, you'll need | |
| something like <span class="command"><strong>xmllint</strong></span> and access to the | |
| relevant DocBook schema. These are provided | |
| by a vendor package like <code class="filename">libxml2</code> and <code class="filename">docbook5-schemas-5.0-4</code> | |
| </p><p> | |
| For PDF output, something that transforms valid Docbook XML to PDF is | |
| required. Possible solutions include <a class="link" href="https://dblatex.sourceforge.net" target="_top">dblatex</a>, | |
| <span class="command"><strong>xmlto</strong></span>, or <span class="command"><strong>prince</strong></span>. Of | |
| these, <span class="command"><strong>dblatex</strong></span> is the default. | |
| Please consult the <code class="email"><<a class="email" href="mailto:libstdc++@gcc.gnu.org">libstdc++@gcc.gnu.org</a>></code> list when | |
| preparing printed manuals for current best practice and | |
| suggestions. | |
| </p><p> | |
| For Texinfo output, something that transforms valid Docbook | |
| XML to Texinfo is required. The default choice is <a class="link" href="https://docbook2x.sourceforge.net/" target="_top">docbook2X</a>. | |
| </p><p> | |
| 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. | |
| </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> | |
| The following Makefile rules generate (in order): an HTML | |
| version of all the DocBook documentation, a PDF version of the | |
| same, and a single XML document. These rules are not | |
| conditional! If the required tools are not found, or are the | |
| wrong versions, the rule may end in an error. | |
| </p><p> | |
| </p><pre class="screen"><strong class="userinput"><code>make doc-html-docbook</code></strong></pre><p> | |
| </p><p> | |
| </p><pre class="screen"><strong class="userinput"><code>make doc-pdf-docbook</code></strong></pre><p> | |
| </p><p> | |
| </p><pre class="screen"><strong class="userinput"><code>make doc-xml-single-docbook</code></strong></pre><p> | |
| </p><p> | |
| Generated files are output into separate sub-directories of | |
| <code class="filename">doc/docbook/</code> in the | |
| build directory, based on the output format. For instance, the | |
| HTML docs will be in <code class="filename">doc/docbook/html</code>. | |
| </p><p> | |
| The <strong class="userinput"><code>doc-html-docbook-regenerate</code></strong> target will | |
| generate the HTML files and copy them back to the libstdc++ source tree. | |
| This can be used to update the HTML files that are checked in to | |
| version control. | |
| </p><p> | |
| If the Docbook stylesheets are installed in a custom location, | |
| one can use the variable <code class="literal">XSL_STYLE_DIR</code> to | |
| override the Makefile defaults. For example: | |
| </p><pre class="screen"> | |
| <strong class="userinput"><code> | |
| make <code class="literal">XSL_STYLE_DIR="/usr/share/xml/docbook/stylesheet/nwalsh"</code> doc-html-docbook | |
| </code></strong> | |
| </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> | |
| Sometimes, mis-configuration of the pre-requisite tools can | |
| lead to errors when attempting to build the | |
| documentation. Here are some of the obvious errors, and ways | |
| to fix some common issues that may appear quite cryptic. | |
| </p><p> | |
| First, if using a rule like <code class="code">make pdf</code>, try to | |
| narrow down the scope of the error to either docbook | |
| (<code class="code">make doc-pdf-docbook</code>) or doxygen (<code class="code">make | |
| doc-pdf-doxygen</code>). | |
| </p><p> | |
| Working on the docbook path only, closely examine the | |
| contents of the following build directory: | |
| <code class="filename">build/target/libstdc++-v3/doc/docbook/latex</code>. | |
| Pay attention to three files enclosed within, annotated as follows. | |
| </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> | |
| <span class="emphasis"><em>spine.tex</em></span> | |
| </p><p> | |
| The actual latex file, or partial latex file. This is generated | |
| via <span class="command"><strong>dblatex</strong></span>, and is the LaTeX version of the | |
| DocBook XML file <code class="filename">spine.xml</code>. Go to a specific | |
| line, and look at the generated LaTeX, and try to deduce what | |
| markup in <code class="filename">spine.xml</code> is causing it. | |
| </p></li><li class="listitem"><p> | |
| <span class="emphasis"><em>spine.out</em></span> | |
| </p><p> | |
| A log of the conversion from the XML form to the LaTeX form. This | |
| is a linear list, from the beginning of the | |
| <code class="filename">spine.xml</code> file: the last entry of this file | |
| should be the end of the DocBook file. If it is truncated, then | |
| you know that the last entry is the last part of the XML source | |
| file that is valid. The error is after this point. | |
| </p></li><li class="listitem"><p> | |
| <span class="emphasis"><em>spine.log</em></span> | |
| </p><p> | |
| A log of the compilation of the converted LaTeX form to pdf. This | |
| is a linear list, from the beginning of the | |
| <code class="filename">spine.tex</code> file: the last entry of this file | |
| should be the end of the LaTeX file. If it is truncated, then you | |
| know that the last entry is the last part of the generated LaTeX | |
| source file that is valid. Often this file contains an error with | |
| a specific line number of <code class="filename">spine.tex</code> that is | |
| incorrect. | |
| </p></li></ul></div><p> | |
| If the error at hand is not obvious after examination, or if one | |
| encounters the inscrutable <span class="quote">“<span class="quote">Incomplete | |
| \ifmmode</span>”</span> error, a fall-back strategy is to start | |
| commenting out parts of the XML document (regardless of what | |
| this does to over-all document validity). Start by | |
| commenting out each of the largest parts of the | |
| <code class="filename">spine.xml</code> file, section by section, | |
| until the offending section is identified. | |
| </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> | |
| After editing the xml sources, please make sure that the XML | |
| documentation and markup is still valid. This can be | |
| done easily, with the following validation rule: | |
| </p><pre class="screen"> | |
| <strong class="userinput"><code>make doc-xml-validate-docbook</code></strong> | |
| </pre><p> | |
| This is equivalent to doing: | |
| </p><pre class="screen"> | |
| <strong class="userinput"><code> | |
| xmllint --noout --valid <code class="filename">xml/index.xml</code> | |
| </code></strong> | |
| </pre><p> | |
| Please note that individual sections and chapters of the | |
| manual can be validated by substituting the file desired for | |
| <code class="filename">xml/index.xml</code> in the command | |
| above. Reducing scope in this manner can be helpful when | |
| validation on the entire manual fails. | |
| </p><p> | |
| All Docbook xml sources should always validate. No excuses! | |
| </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 /> | |
| <span class="emphasis"><em>Which files are important</em></span><br /> | |
| <br /> | |
| All Docbook files are in the directory<br /> | |
| libstdc++-v3/doc/xml<br /> | |
| <br /> | |
| Inside this directory, the files of importance:<br /> | |
| spine.xml - index to documentation set<br /> | |
| manual/spine.xml - index to manual<br /> | |
| manual/*.xml - individual chapters and sections of the manual<br /> | |
| faq.xml - index to FAQ<br /> | |
| api.xml - index to source level / API<br /> | |
| <br /> | |
| All *.txml files are template xml files, i.e., otherwise empty files with<br /> | |
| the correct structure, suitable for filling in with new information.<br /> | |
| <br /> | |
| <span class="emphasis"><em>Canonical Writing Style</em></span><br /> | |
| <br /> | |
| class template<br /> | |
| function template<br /> | |
| member function template<br /> | |
| (via C++ Templates, Vandevoorde)<br /> | |
| <br /> | |
| class in namespace std: allocator, not std::allocator<br /> | |
| <br /> | |
| header file: iostream, not <iostream><br /> | |
| <br /> | |
| <br /> | |
| <span class="emphasis"><em>General structure</em></span><br /> | |
| <br /> | |
| <set><br /> | |
| <book><br /> | |
| </book><br /> | |
| <br /> | |
| <book><br /> | |
| <chapter><br /> | |
| </chapter><br /> | |
| </book><br /> | |
| <br /> | |
| <book><br /> | |
| <part><br /> | |
| <chapter><br /> | |
| <section><br /> | |
| </section><br /> | |
| <br /> | |
| <sect1><br /> | |
| </sect1><br /> | |
| <br /> | |
| <sect1><br /> | |
| <sect2><br /> | |
| </sect2><br /> | |
| </sect1><br /> | |
| </chapter><br /> | |
| <br /> | |
| <chapter><br /> | |
| </chapter><br /> | |
| </part><br /> | |
| </book><br /> | |
| <br /> | |
| </set><br /> | |
| </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> | |
| Complete details on Docbook markup can be found in the | |
| <a class="link" href="https://tdg.docbook.org/tdg/5.0/ref-elements.html" target="_top">DocBook Element Reference</a>. | |
| An incomplete reference for HTML to Docbook conversion is | |
| detailed in the table below. | |
| </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>, | |
| <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> | |
| And examples of detailed markup for which there are no real HTML | |
| equivalents are listed in the table below. | |
| </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"> | |
| <p><function>clear()</function></p> | |
| <p><function>fs.clear()</function></p> | |
| </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"> | |
| <p><literal>-Weffc++</literal></p> | |
| <p><literal>rel_ops</literal></p> | |
| </td></tr><tr><td align="left"><constant></td><td align="left"> | |
| <p><constant>_GNU_SOURCE</constant></p> | |
| <p><constant>3.0</constant></p> | |
| </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"> | |
| <p><filename class="headerfile">ctype.h</filename></p> | |
| <p><filename class="directory">/home/gcc/build</filename></p> | |
| <p><filename class="libraryfile">libstdc++.so</filename></p> | |
| </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. | |
| Porting and Maintenance | |
| </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> |