Writing and Generating Documentation

+ Prerequisite tools are Bash 2.0 or later, + Doxygen, and + the GNU + coreutils. (GNU versions of find, xargs, and possibly + sed and grep are used, just because the GNU versions make + things very easy.) +

+ To generate the pretty pictures and hierarchy + graphs, the + Graphviz package + will need to be installed. For PDF + output, + pdflatex is required. +

Generating the Doxygen Files

+ 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. +

make doc-html-doxygen

make doc-xml-doxygen

make doc-xml-single-doxygen

make doc-pdf-doxygen

make doc-man-doxygen

+ Generated files are output into separate sub directories of + doc/doxygen/ in the + build directory, based on the output format. For instance, the + HTML docs will be in doc/doxygen/html. +

+ Careful observers will see that the Makefile rules simply call + a script from the source tree, run_doxygen, 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 --help.) +

+ If you wish to tweak the Doxygen settings, do so by editing + doc/doxygen/user.cfg.in. Notes to fellow + library hackers are written in triple-# comments. +

Markup

+ In general, libstdc++ files should be formatted according to + the rules found in the + Coding Standard. Before + any doxygen-specific formatting tweaks are made, please try to + make sure that the initial formatting is sound. +

+ Adding Doxygen markup to a file (informally called + “doxygenating”) is very simple. The Doxygen manual can be + found + here. + We try to use a very-recent version of Doxygen. +

+ For classes, use + deque/vector/list + and std::pair as examples. For + functions, see their member functions, and the free functions + in stl_algobase.h. Member functions of + other container-like types should read similarly to these + member functions. +

+ Some commentary to accompany + the first list in the Special + Documentation Blocks section of + the Doxygen manual: +

For longer comments, use the Javadoc style...
+ ...not the Qt style. The intermediate *'s are preferred. +
+ Use the triple-slash style only for one-line comments (the + “brief” mode). +
+ This is disgusting. Don't do this. +

+ Some specific guidelines: +

+ 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 “interesting” effects. +

+ Use either kind of grouping, as + appropriate. doxygroups.cc exists for this + purpose. See stl_iterator.h for a good example + of the “other” kind of grouping. +

+ Please use markup tags like @p and @a when referring to things + such as the names of function parameters. Use @e for emphasis + when necessary. Use @c to refer to other standard names. + (Examples of all these abound in the present code.) +

+ Complicated math functions should use the multi-line + format. An example from random.h: +

+/**
+ * @brief A model of a linear congruential random number generator.
+ *
+ * @f[
+ * x_{i+1}\leftarrow(ax_{i} + c) \bmod m
+ * @f]
+ */
+

+ One area of note is the markup required for + @file 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: +

+/** @file debug/vector
+ * This file is a GNU debug extension to the Standard C++ Library.
+ */
+

+ The other relevant detail for header files is the use of a + libstdc++-specific doxygen alias that helps distinguish + between public header files (like random) + from implementation or private header files (like + bits/c++config.h.) This alias is spelled + @headername 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 + headername in the file + block. An example: +

+/** @file bits/basic_string.h
+ * This is an internal header file, included by other library headers.
+ * Do not attempt to use it directly. @headername{string}
+ */
+

+ 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. +

Table B.2. HTML to Doxygen Markup Comparison

HTML	Doxygen
\	\\
"	\"
'	\'
<i>	@a word
<b>	@b word
<code>	@c word
<em>	@a word
<em>	<em>two words or more</em>

Docbook

Prerequisites

Table B.3. Docbook Prerequisites

Tool	Version	Required By
docbook5-style-xsl	1.76.1	all
xsltproc	1.1.26	all
xmllint	2.7.7	validation
dblatex	0.3	pdf output
pdflatex	2007-59	pdf output
docbook2X	0.8.8	info output

+ Editing the DocBook sources requires an XML editor. Many + exist: some notable options + include emacs, Kate, + or Conglomerate. +

+ Some editors support special “XML Validation” + modes that can validate the file as it is + produced. Recommended is the nXML Mode + for emacs. +

+ Besides an editor, additional DocBook files and XML tools are + also required. +

+ Access to the DocBook 5.0 stylesheets and schema is required. The + stylesheets are usually packaged by vendor, in something + like docbook5-style-xsl. To exactly match + generated output, please use a version of the stylesheets + equivalent + to docbook5-style-xsl-1.75.2-3. The + installation directory for this package corresponds to + the XSL_STYLE_DIR + in doc/Makefile.am and defaults + to /usr/share/sgml/docbook/xsl-ns-stylesheets. +

+ For processing XML, an XML processor and some style + sheets are necessary. Defaults are xsltproc + provided by libxslt. +

+ For validating the XML document, you'll need + something like xmllint and access to the + relevant DocBook schema. These are provided + by a vendor package like libxml2 and docbook5-schemas-5.0-4 +

+ For PDF output, something that transforms valid Docbook XML to PDF is + required. Possible solutions include dblatex, + xmlto, or prince. Of + these, dblatex is the default. Other + options are listed on the DocBook web pages. Please + consult the <libstdc++@gcc.gnu.org> list when + preparing printed manuals for current best practice and + suggestions. +

+ For Texinfo output, something that transforms valid Docbook + XML to Texinfo is required. The default choice is docbook2X. +

Generating the DocBook Files

+ 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. +

make doc-html-docbook

make doc-pdf-docbook

make doc-xml-single-docbook

+ Generated files are output into separate sub directores of + doc/docbook/ in the + build directory, based on the output format. For instance, the + HTML docs will be in doc/docbook/html. +

+ If the Docbook stylesheets are installed in a custom location, + one can use the variable XSL_STYLE_DIR to + over-ride the Makefile defaults. As so: +

+	
+make XSL_STYLE_DIR="/usr/share/xml/docbook/stylesheet/nwalsh" doc-html-docbook
+	
+

Editing and Validation

+ 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: +

+	make doc-xml-validate-docbook
+

+ This is equivalent to doing: +

+	
+	  xmllint --noout --valid xml/index.xml
+	
+

+ Please note that individual sections and chapters of the + manual can be validated by substituting the file desired for + xml/index.xml in the command + above. Reducing scope in this manner can be helpful when + validation on the entire manual fails. +

+ All Docbook xml sources should always validate. No excuses! +

File Organization and Basics

+      Which files are important
+
+      All Docbook files are in the directory
+      libstdc++-v3/doc/xml
+
+      Inside this directory, the files of importance:
+      spine.xml - index to documentation set
+      manual/spine.xml  - index to manual
+      manual/*.xml   - individual chapters and sections of the manual
+      faq.xml   - index to FAQ
+      api.xml   - index to source level / API
+
+      All *.txml files are template xml files, i.e., otherwise empty files with
+      the correct structure, suitable for filling in with new information.
+
+      Canonical Writing Style
+
+      class template
+      function template
+      member function template
+      (via C++ Templates, Vandevoorde)
+
+      class in namespace std: allocator, not std::allocator
+
+      header file: iostream, not <iostream>
+
+
+      General structure
+
+      <set>
+      <book>
+      </book>
+
+      <book>
+      <chapter>
+      </chapter>
+      </book>
+
+      <book>
+      <part>
+      <chapter>
+      <section>
+      </section>
+
+      <sect1>
+      </sect1>
+
+      <sect1>
+      <sect2>
+      </sect2>
+      </sect1>
+      </chapter>
+
+      <chapter>
+      </chapter>
+      </part>
+      </book>
+
+      </set>
+

Markup By Example

+ Complete details on Docbook markup can be found in the DocBook + Element Reference, + online. + An incomplete reference for HTML to Docbook conversion is + detailed in the table below. +

Table B.4. HTML to Docbook XML Markup Comparison

HTML	Docbook
<p>	<para>
<pre>	<computeroutput>, <programlisting>, + <literallayout>
<ul>	<itemizedlist>
<ol>	<orderedlist>
<il>	<listitem>
<dl>	<variablelist>
<dt>	<term>
<dd>	<listitem>
<a href="">	<ulink url="">
<code>	<literal>, <programlisting>
<strong>	<emphasis>
<em>	<emphasis>
"	<quote>

+ And examples of detailed markup for which there are no real HTML + equivalents are listed in the table below. +

Table B.5. Docbook XML Element Use

Element	Use
<structname>	<structname>char_traits</structname>
<classname>	<classname>string</classname>
<function>	+ <function>clear()</function> + <function>fs.clear()</function> +
<type>	<type>long long</type>
<varname>	<varname>fs</varname>
<literal>	+ <literal>-Weffc++</literal> + <literal>rel_ops</literal> +
<constant>	+ <constant>_GNU_SOURCE</constant> + <constant>3.0</constant> +
<command>	<command>g++</command>
<errortext>	<errortext>In instantiation of</errortext>
<filename>	+ <filename class="headerfile">ctype.h</filename> + <filename class="directory">/home/gcc/build</filename> + <filename class="libraryfile">libstdc++.so</filename> +