-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Writing and Generating Documentation</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><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 align="left"><a accesskey="p" href="appendix_porting.html">Prev</a> </td><th width="60%" align="center">Appendix B.
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Writing and Generating Documentation</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><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 bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><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
align="right"> <a accesskey="n" href="internals.html">Next</a></td></tr></table><hr/></div><div class="section" title="Writing and Generating Documentation"><div class="titlepage"><div><div><h2 class="title"><a id="appendix.porting.doc"/>Writing and Generating Documentation</h2></div></div></div><div class="section" title="Introduction"><div class="titlepage"><div><div><h3 class="title"><a id="doc.intro"/>Introduction</h3></div></div></div><p>
+</th><td
width="20%" align="right"> <a accesskey="n" href="internals.html">Next</a></td></tr></table><hr></div><div class="section" title="Writing and Generating Documentation"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="appendix.porting.doc"></a>Writing and Generating Documentation</h2></div></div></div><div class="section" title="Introduction"><div class="titlepage"><div><div><h3 class="title"><a name="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>
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">
+ <a class="link" href="http://www.gnu.org/prep/standards/standards.html#Documentation" target="_top">
GNU Manuals</a>.
- </p></div><div class="section" title="Generating Documentation"><div class="titlepage"><div><div><h3 class="title"><a
id="doc.generation"/>Generating Documentation</h3></div></div></div><p>
+ </p></div><div class="section" title="Generating Documentation"><div class="titlepage"><div><div><h3 class="title"><a
name="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
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" title="Doxygen"><div class="titlepage"><div><div><h3 class="title"><a
id="doc.doxygen"/>Doxygen</h3></div></div></div><div class="section" title="Prerequisites"><div class="titlepage"><div><div><h4 class="title"><a id="doxygen.prereq"/>Prerequisites</h4></div></div></div><div class="table"><a id="id564711"/><p class="title"><strong>Table B.1. Doxygen Prerequisites</strong></p><div class="table-contents"><table summary="Doxygen Prerequisites" border="1"><colgroup><col style="text-align: center" class="c1"/><col style="text-align: center" class="c2"/><col style="text-align: center" class="c3"/></colgroup><thead><tr><th style="text-align: center">Tool</th><th style="text-align: center">Version</th><th style="text-align: center">Required By</th></tr></thead><tbody><tr><td style="text-align: center">coreutils</td><td style="text-align: center">8.5</td><td style="text-align: center">all</td></tr><tr><td style="text-align: center">bash</td><td style="text-align: center">4.1</td><td style="text-align: center">all</td></tr><tr><td style="text-align: center">doxygen</td><td style="text-align: center">1.7.6.1</td><td style="text-align: center">all</td></tr><tr><td style="text-align: center">graphviz</td><td style="text-align: center">2.26</td><td style="text-align: center">graphical hierarchies</td></tr><tr><td style="text-align: center">pdflatex</td><td style="text-align: center">2007-59</td><td style="text-align: center">pdf output</td></tr></tbody></table></div></div><br class="table-break"/><p>
+ </p></div><div class="section" title="Doxygen"><div class="titlepage"><div><div><h3 class="title"><a
name="doc.doxygen"></a>Doxygen</h3></div></div></div><div class="section" title="Prerequisites"><div class="titlepage"><div><div><h4 class="title"><a name="doxygen.prereq"></a>Prerequisites</h4></div></div></div><div class="table"><a name="id678029"></a><p class="title"><b>Table B.1. Doxygen Prerequisites</b></p><div class="table-contents"><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>
Prerequisite tools are Bash 2.0 or later,
- <a class="link" href="http://www.doxygen.org/">Doxygen</a>, and
- the <a class="link" href="http://www.gnu.org/software/coreutils/">GNU
+ <a class="link" href="http://www.doxygen.org/" target="_top">Doxygen</a>, 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="http://www.graphviz.org">Graphviz</a> package
+ <a class="link" href="http://www.graphviz.org" target="_top">Graphviz</a> package
will need to be installed. For PDF
- output, <a class="link" href="http://www.tug.org/applications/pdftex/">
+ output, <a class="link" href="http://www.tug.org/applications/pdftex/" target="_top">
pdflatex</a> is required.
</p><p>
Be warned the PDF file generated via doxygen is extremely
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.
- </p></div><div class="section" title="Generating the Doxygen Files"><div class="titlepage"><div><div><h4 class="title"><a
id="doxygen.rules"/>Generating the Doxygen Files</h4></div></div></div><p>
+ </p></div><div class="section" title="Generating the Doxygen Files"><div class="titlepage"><div><div><h4 class="title"><a
name="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
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" title="Markup"><div class="titlepage"><div><div><h4 class="title"><a
id="doxygen.markup"/>Markup</h4></div></div></div><p>
+ </p></div><div class="section" title="Markup"><div class="titlepage"><div><div><h4 class="title"><a
name="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
Adding Doxygen markup to a file (informally called
<span class="quote">“<span class="quote">doxygenating</span>”</span>) is very simple. The Doxygen manual can be
found
- <a class="link" href="http://www.stack.nl/~dimitri/doxygen/download.html#latestman">here</a>.
+ <a class="link" href="http://www.stack.nl/~dimitri/doxygen/download.html#latestman" target="_top">here</a>.
We try to use a very-recent version of Doxygen.
</p><p>
For classes, use
member functions.
</p><p>
Some commentary to accompany
- the first list in the <a class="link" href="http://www.stack.nl/~dimitri/doxygen/docblocks.html">Special
+ the first list in the <a class="link" href="http://www.stack.nl/~dimitri/doxygen/docblocks.html" target="_top">Special
Documentation Blocks</a> section of
the Doxygen manual:
- </p><div class="orderedlist"><ol class="orderedlist"><li class="listitem"><p>For longer comments, use the Javadoc style...</p></li><li class="listitem"><p>
+ </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
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 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
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 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
<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 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="id565227"/><p class="title"><strong>Table B.2. HTML to Doxygen Markup Comparison</strong></p><div class="table-contents"><table summary="HTML to Doxygen Markup Comparison" border="1"><colgroup><col style="text-align: left" class="c1"/><col style="text-align: left" class="c2"/></colgroup><thead><tr><th style="text-align: left">HTML</th><th style="text-align: left">Doxygen</th></tr></thead><tbody><tr><td style="text-align: left">\</td><td style="text-align: left">\\</td></tr><tr><td style="text-align: left">"</td><td style="text-align: left">\"</td></tr><tr><td style="text-align: left">'</td><td style="text-align: left">\'</td></tr><tr><td style="text-align: left"><i></td><td style="text-align: left">@a word</td></tr><tr><td style="text-align: left"><b></td><td style="text-align: left">@b word</td></tr><tr><td style="text-align: left"><code></td><td style="text-align: left">@c word</td></tr><tr><td style="text-align: left"><em></td><td style="text-align: left">@a word</td></tr><tr><td style="text-align: left"><em></td><td style="text-align: left"><em>two words or more</em></td></tr></tbody></table></div></div><br class="table-break"/></div></div><div class="section" title="Docbook"><div class="titlepage"><div><div><h3 class="title"><a id="doc.docbook"/>Docbook</h3></div></div></div><div class="section" title="Prerequisites"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.prereq"/>Prerequisites</h4></div></div></div><div class="table"><a id="id565389"/><p class="title"><strong>Table B.3. Docbook Prerequisites</strong></p><div class="table-contents"><table summary="Docbook Prerequisites" border="1"><colgroup><col style="text-align: center" class="c1"/><col style="text-align: center" class="c2"/><col style="text-align: center" class="c3"/></colgroup><thead><tr><th style="text-align: center">Tool</th><th style="text-align: center">Version</th><th style="text-align: center">Required By</th></tr></thead><tbody><tr><td style="text-align: center">docbook5-style-xsl</td><td style="text-align: center">1.76.1</td><td style="text-align: center">all</td></tr><tr><td style="text-align: center">xsltproc</td><td style="text-align: center">1.1.26</td><td style="text-align: center">all</td></tr><tr><td style="text-align: center">xmllint</td><td style="text-align: center">2.7.7</td><td style="text-align: center">validation</td></tr><tr><td style="text-align: center">dblatex</td><td style="text-align: center">0.3</td><td style="text-align: center">pdf output</td></tr><tr><td style="text-align: center">pdflatex</td><td style="text-align: center">2007-59</td><td style="text-align: center">pdf output</td></tr><tr><td style="text-align: center">docbook2X</td><td style="text-align: center">0.8.8</td><td style="text-align: center">info output</td></tr><tr><td style="text-align: center">epub3 stylesheets</td><td style="text-align: center">b3</td><td style="text-align: center">epub output</td></tr></tbody></table></div></div><br class="table-break"/><p>
+ </p><div class="table"><a
name="id678546"></a><p class="title"><b>Table B.2. HTML to Doxygen Markup Comparison</b></p><div class="table-contents"><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" title="Docbook"><div class="titlepage"><div><div><h3 class="title"><a name="doc.docbook"></a>Docbook</h3></div></div></div><div class="section" title="Prerequisites"><div class="titlepage"><div><div><h4 class="title"><a name="docbook.prereq"></a>Prerequisites</h4></div></div></div><div class="table"><a name="id678708"></a><p class="title"><b>Table B.3. Docbook Prerequisites</b></p><div class="table-contents"><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>
Editing the DocBook sources requires an XML editor. Many
exist: some notable options
include <span class="command"><strong>emacs</strong></span>, <span class="application">Kate</span>,
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="http://dblatex.sourceforge.net">dblatex</a>,
+ required. Possible solutions include <a class="link" href="http://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. Other
- options are listed on the DocBook web <a class="link" href="http://wiki.docbook.org/topic/DocBookPublishingTools">pages</a>. Please
+ options are listed on the DocBook web <a class="link" href="http://wiki.docbook.org/topic/DocBookPublishingTools" target="_top">pages</a>. 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="http://docbook2x.sourceforge.net/">docbook2X</a>.
+ XML to Texinfo is required. The default choice is <a class="link" href="http://docbook2x.sourceforge.net/" target="_top">docbook2X</a>.
</p><p>
- For epub output, the <a class="link" href="http://sourceforge.net/projects/docbook/files/epub3/">stylesheets</a> for EPUB3 are required. These stylesheets are still in development. To validate the created file, <a class="link" href="https://code.google.com/p/epubcheck/">epubcheck</a> is necessary.
- </p></div><div class="section" title="Generating the DocBook Files"><div class="titlepage"><div><div><h4 class="title"><a
id="docbook.rules"/>Generating the DocBook Files</h4></div></div></div><p>
+ For epub output, the <a class="link" href="http://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://code.google.com/p/epubcheck/" target="_top">epubcheck</a> is necessary.
+ </p></div><div class="section" title="Generating the DocBook Files"><div class="titlepage"><div><div><h4 class="title"><a
name="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
<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" title="Editing and Validation"><div class="titlepage"><div><div><h4 class="title"><a
id="docbook.validation"/>Editing and Validation</h4></div></div></div><p>
+ </pre></div><div class="section" title="Editing and Validation"><div class="titlepage"><div><div><h4 class="title"><a
name="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:
validation on the entire manual fails.
</p><p>
All Docbook xml sources should always validate. No excuses!
- </p></div><div class="section" title="File Organization and Basics"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.examples"/>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" title="Markup By Example"><div class="titlepage"><div><div><h4 class="title"><a
id="docbook.markup"/>Markup By Example</h4></div></div></div><p>
+ </p></div><div class="section" title="File Organization and Basics"><div class="titlepage"><div><div><h4 class="title"><a name="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" title="Markup By Example"><div class="titlepage"><div><div><h4 class="title"><a
name="docbook.markup"></a>Markup By Example</h4></div></div></div><p>
Complete details on Docbook markup can be found in the DocBook
Element Reference,
- <a class="link" href="http://www.docbook.org/tdg/en/html/part2.html">online</a>.
+ <a class="link" href="http://www.docbook.org/tdg/en/html/part2.html" target="_top">online</a>.
An incomplete reference for HTML to Docbook conversion is
detailed in the table below.
- </p><div class="table"><a id="id565901"/><p class="title"><strong>Table B.4. HTML to Docbook XML Markup Comparison</strong></p><div class="table-contents"><table summary="HTML to Docbook XML Markup Comparison" border="1"><colgroup><col style="text-align: left" class="c1"/><col style="text-align: left" class="c2"/></colgroup><thead><tr><th style="text-align: left">HTML</th><th style="text-align: left">Docbook</th></tr></thead><tbody><tr><td style="text-align: left"><p></td><td style="text-align: left"><para></td></tr><tr><td style="text-align: left"><pre></td><td style="text-align: left"><computeroutput>, <programlisting>,
- <literallayout></td></tr><tr><td
style="text-align: left"><ul></td><td style="text-align: left"><itemizedlist></td></tr><tr><td style="text-align: left"><ol></td><td style="text-align: left"><orderedlist></td></tr><tr><td style="text-align: left"><il></td><td style="text-align: left"><listitem></td></tr><tr><td style="text-align: left"><dl></td><td style="text-align: left"><variablelist></td></tr><tr><td style="text-align: left"><dt></td><td style="text-align: left"><term></td></tr><tr><td style="text-align: left"><dd></td><td style="text-align: left"><listitem></td></tr><tr><td style="text-align: left"><a href=""></td><td style="text-align: left"><ulink url=""></td></tr><tr><td style="text-align: left"><code></td><td style="text-align: left"><literal>, <programlisting></td></tr><tr><td style="text-align: left"><strong></td><td style="text-align: left"><emphasis></td></tr><tr><td style="text-align: left"><em></td><td style="text-align: left"><emphasis></td></tr><tr><td style="text-align: left">"</td><td style="text-align: left"><quote></td></tr></tbody></table></div></div><br class="table-break"/><p>
+ </p><div class="table"><a name="id679219"></a><p class="title"><b>Table B.4. HTML to Docbook XML Markup Comparison</b></p><div class="table-contents"><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="id566102"/><p class="title"><strong>Table B.5. Docbook XML Element Use</strong></p><div class="table-contents"><table summary="Docbook XML Element Use" border="1"><colgroup><col style="text-align: left" class="c1"/><col style="text-align: left" class="c2"/></colgroup><thead><tr><th style="text-align: left">Element</th><th style="text-align: left">Use</th></tr></thead><tbody><tr><td style="text-align: left"><structname></td><td style="text-align: left"><structname>char_traits</structname></td></tr><tr><td style="text-align: left"><classname></td><td style="text-align: left"><classname>string</classname></td></tr><tr><td style="text-align: left"><function></td><td style="text-align: left">
+</p><div class="table"><a name="id679421"></a><p class="title"><b>Table B.5. Docbook XML Element Use</b></p><div class="table-contents"><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 style="text-align: left"><type></td><td style="text-align: left"><type>long long</type></td></tr><tr><td style="text-align: left"><varname></td><td style="text-align: left"><varname>fs</varname></td></tr><tr><td style="text-align: left"><literal></td><td style="text-align: left">
+ </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 style="text-align: left"><constant></td><td style="text-align: left">
+ </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 style="text-align: left"><command></td><td style="text-align: left"><command>g++</command></td></tr><tr><td style="text-align: left"><errortext></td><td style="text-align: left"><errortext>In instantiation of</errortext></td></tr><tr><td style="text-align: left"><filename></td><td style="text-align: left">
+ </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 align="left"><a accesskey="p" href="appendix_porting.html">Prev</a> </td><td align="center"><a accesskey="u" href="appendix_porting.html">Up</a></td><td align="right"> <a accesskey="n" href="internals.html">Next</a></td></tr><tr><td align="left" valign="top">Appendix B.
+ </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 align="center"><a accesskey="h" href="../index.html">Home</a></td><td align="right" valign="top"> Porting to New Hardware or Operating Systems</td></tr></table></div></body></html>
+ </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>
projects / gcc.git / blobdiff