| <?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.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="appendix_contributing.html" title="Appendix A. Contributing" /><link rel="prev" href="source_code_style.html" title="Coding Style" /><link rel="next" href="source_design_notes.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="source_code_style.html">Prev</a> </td><th width="60%" align="center">Appendix A. |
| Contributing |
| |
| </th><td width="20%" align="right"> <a accesskey="n" href="source_design_notes.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 following Makefile rules run Doxygen to generate HTML |
| docs, XML docs, and the man pages. |
| </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-man-doxygen</code></strong></pre><p> |
| </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="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">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 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">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>. To exactly match |
| generated output, please use a version of the stylesheets |
| equivalent |
| to <code class="filename">docbook-style-xsl-1.74.0-5</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 processing 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 following Makefile rules generate (in order): an HTML |
| version of all the documentation, a PDF version of the same, a |
| single XML document, and the result of validating the entire XML |
| document. |
| </p><p> |
| </p><pre class="screen"><strong class="userinput"><code>make doc-html</code></strong></pre><p> |
| </p><p> |
| </p><pre class="screen"><strong class="userinput"><code>make doc-pdf</code></strong></pre><p> |
| </p><p> |
| </p><pre class="screen"><strong class="userinput"><code>make doc-xml-single</code></strong></pre><p> |
| </p><p> |
| </p><pre class="screen"><strong class="userinput"><code>make doc-xml-validate</code></strong></pre><p> |
| </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, 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="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><p> |
| Complete details on Docbook markup can be found in the DocBook Element |
| Reference, <a class="ulink" 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="id435551"></a><p class="title"><b>Table A.1. 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" /><col align="left" /></colgroup><thead><tr><th align="left">HTML</th><th align="left">XML</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="id500888"></a><p class="title"><b>Table A.2. Docbook XML Element Use</b></p><div class="table-contents"><table summary="Docbook XML Element Use" border="1"><colgroup><col align="left" /><col align="left" /></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> |
| </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="source_code_style.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="source_design_notes.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> |