46abada07f
2008-02-11 Benjamin Kosnik <bkoz@redhat.com> * doc/html/*: Populate with regenerated files. From-SVN: r132251
264 lines
15 KiB
HTML
264 lines
15 KiB
HTML
<?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>Documentation Style</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content=" ISO C++ , library " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="appendix_contributing.html" title="Appendix A. Contributing" /><link rel="prev" href="bk01apas03.html" title="Coding Style" /><link rel="next" href="bk01apas05.html" title="Design Notes" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Documentation Style</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01apas03.html">Prev</a> </td><th width="60%" align="center">Appendix A. Contributing</th><td width="20%" align="right"> <a accesskey="n" href="bk01apas05.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="contrib.doc_style"></a>Documentation Style</h2></div></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="doc_style.doxygen"></a>Doxygen</h3></div></div></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="doxygen.prereq"></a>Prerequisites</h4></div></div></div><p>
|
||
Prerequisite tools are Bash 2.x,
|
||
<a class="ulink" href="http://www.doxygen.org/" target="_top">Doxygen</a>, and
|
||
the <a class="ulink" 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="ulink" href="http://www.research.att.com/sw/tools/graphviz/download.html" target="_top">Graphviz</a>
|
||
package will need to be installed.
|
||
</p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="doxygen.rules"></a>Generating the Doxygen Files</h4></div></div></div><p>
|
||
The Makefile rules
|
||
</p><pre class="screen"><strong class="userinput"><code>make doc-html-doxygen</code></strong></pre><p>
|
||
and
|
||
</p><pre class="screen"><strong class="userinput"><code>make doc-xml-doxygen</code></strong></pre><p>
|
||
and
|
||
</p><pre class="screen"><strong class="userinput"><code>make doc-man-doxygen</code></strong></pre><p>
|
||
in the libstdc++ build directory generate the HTML docs, the
|
||
XML docs, and the man pages.
|
||
</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="sect3" lang="en" xml:lang="en"><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="bk01apas03.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">doxygenating</span>”) is very simple. The Doxygen manual can be
|
||
found
|
||
<a class="ulink" 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
|
||
<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>
|
||
These points accompany the first list in section 3.1 of the
|
||
Doxygen manual:
|
||
</p><div class="orderedlist"><ol type="1"><li><p>Use the Javadoc style...</p></li><li><p>
|
||
...not the Qt style. The intermediate *'s are preferred.
|
||
</p></li><li><p>
|
||
Use the triple-slash style only for one-line comments (the
|
||
“<span class="quote">brief</span>” mode). Very recent versions of Doxygen permit
|
||
full-mode comments in triple-slash blocks, but the
|
||
formatting still comes out wonky.
|
||
</p></li><li><p>
|
||
This is disgusting. Don't do this.
|
||
</p></li></ol></div><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">interesting</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">other</span>” kind of grouping.
|
||
</p><p>
|
||
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.)
|
||
</p></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="doc_style.docbook"></a>Docbook</h3></div></div></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.prereq"></a>Prerequisites</h4></div></div></div><p>
|
||
Editing the DocBook sources requires an XML editor. Many
|
||
exist: some noteable 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">XML Validation</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 stylesheets and DTD is required. The
|
||
stylesheets are usually packaged by vendor, in something
|
||
like <code class="filename">docbook-style-xsl</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-stylesheets</code>.
|
||
</p><p>
|
||
For procesessing XML, an XML 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
|
||
DocBook DTD. These are provided
|
||
by a vendor package like <code class="filename">lixml2</code>.
|
||
</p><p>
|
||
For PDF output, something that transforms valid XML to PDF is
|
||
required. Possible solutions include <span class="command"><strong>xmlto</strong></span>,
|
||
<a class="ulink" href="http://xmlgraphics.apache.org/fop/" target="_top">Apache
|
||
FOP</a>, or <span class="command"><strong>prince</strong></span>. Other options are
|
||
listed on the DocBook web <a class="ulink" 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>
|
||
Make sure that the XML documentation and markup is valid for
|
||
any change. This can be done easily, with the validation rules
|
||
in the <code class="filename">Makefile</code>, which 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></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.rules"></a>Generating the DocBook Files</h4></div></div></div><p>
|
||
The Makefile rules
|
||
</p><pre class="screen"><strong class="userinput"><code>make doc-html</code></strong></pre><p>
|
||
and
|
||
</p><pre class="screen"><strong class="userinput"><code>make doc-pdf</code></strong></pre><p>
|
||
and
|
||
</p><pre class="screen"><strong class="userinput"><code>make doc-xml-single</code></strong></pre><p>
|
||
and
|
||
</p><pre class="screen"><strong class="userinput"><code>make doc-xml-validate</code></strong></pre><p>
|
||
in the libstdc++ build directory result respectively in the
|
||
following: the generation of an HTML version of all the
|
||
documentation, a PDF version of the same, a single XML
|
||
document, and the results of validating the XML document.
|
||
</p></div><div class="sect3" lang="en" xml:lang="en"><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, ie otherwise empty files with<br />
|
||
the correct structure, suitable for filling in with new information.<br />
|
||
<br />
|
||
<span class="emphasis"><em>Cannonical 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="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.markup"></a>Markup By Example</h4></div></div></div><div class="literallayout"><p><br />
|
||
HTML to XML rough equivalents<br />
|
||
<br />
|
||
<p> <para><br />
|
||
<br />
|
||
<pre> <computeroutput><br />
|
||
<pre> <programlisting><br />
|
||
<pre> <literallayout><br />
|
||
<br />
|
||
<ul> <itemizedlist><br />
|
||
<ol> <orderedlist><br />
|
||
<il> <listitem><br />
|
||
<br />
|
||
<dl> <variablelist><br />
|
||
<br />
|
||
<varlistentry><br />
|
||
<dt> <term><br />
|
||
</dt> </term><br />
|
||
<dd> <listitem><br />
|
||
</dt> </listitem><br />
|
||
</varlistentry><br />
|
||
<br />
|
||
<a href <ulink url<br />
|
||
<code> <literal><br />
|
||
<code> <programlisting><br />
|
||
<br />
|
||
<strong> <emphasis><br />
|
||
<em> <emphasis><br />
|
||
" <quote><br />
|
||
<br />
|
||
ctype.h <filename class="headerfile"></filename><br />
|
||
<br />
|
||
<br />
|
||
build_dir <filename class="directory">path_to_build_dir</filename><br />
|
||
<br />
|
||
Finer gradations of <code><br />
|
||
<br />
|
||
<classname> <classname>string</classname><br />
|
||
<classname>vector<></classname> <br />
|
||
<function>fs.clear()</function><br />
|
||
<br />
|
||
<structname><br />
|
||
<br />
|
||
<function> <function>clear()</function><br />
|
||
<br />
|
||
<type> <type>long long</type><br />
|
||
<br />
|
||
<varname> <varname>fs</varname><br />
|
||
<br />
|
||
<literal> <literal>-Weffc++</literal> <br />
|
||
<literal>rel_ops</literal><br />
|
||
<br />
|
||
<constant> <constant>_GNU_SOURCE</constant><br />
|
||
<constant>3.0</constant><br />
|
||
<br />
|
||
<filename><br />
|
||
<br />
|
||
<command> <command>g++</command><br />
|
||
<br />
|
||
<errortext> <errortext>foo Concept </errortext><br />
|
||
</p></div></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01apas03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendix_contributing.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01apas05.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Coding Style </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Design Notes</td></tr></table></div></body></html>
|