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" title="Documentation Style"><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" title="Doxygen"><div class="titlepage"><div><div><h3 class="title"><a id="doc_style.doxygen"></a>Doxygen</h3></div></div></div><div class="sect3" title="Prerequisites"><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,
+ Prerequisite tools are Bash 2.x or higher,
<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.)
+ things very easy.)
</p><p>
To generate the pretty pictures and hierarchy
graphs, the
- <a class="ulink" href="http://www.graphviz.org" target="_top">Graphviz</a>
- package will need to be installed.
+ <a class="ulink" href="http://www.graphviz.org" target="_top">Graphviz</a> package
+ will need to be installed. For PDF
+ output, <a class="ulink" href="http://www.tug.org/applications/pdftex/" target="_top">
+ pdflatex</a> is required.
</p></div><div class="sect3" title="Generating the Doxygen Files"><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.
+ docs, XML docs, PDF 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-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>
Careful observers will see that the Makefile rules simply call
...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).
+ <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>
* @brief A model of a linear congruential random number generator.<br />
*<br />
* @f[<br />
- * x_{i+1}\leftarrow(ax_{i} + c) \bmod m <br />
+ * x_{i+1}\leftarrow(ax_{i} + c) \bmod m<br />
* @f]<br />
*/<br />
</p></div><p>
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="id
645775"></a><p class="title"><b>Table A.1. HTML to Doxygen markup comparison</b></p><div class="table-contents"><table summary="HTML to Doxygen markup comparison" border="1"><colgroup><col align="left" /><col align="left" /></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="sect2" title="Docbook"><div class="titlepage"><div><div><h3 class="title"><a id="doc_style.docbook"></a>Docbook</h3></div></div></div><div class="sect3" title="Prerequisites"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.prereq"></a>Prerequisites</h4></div></div></div><p>
+ </p><div class="table"><a id="id
389869"></a><p class="title"><b>Table A.1. HTML to Doxygen Markup Comparison</b></p><div class="table-contents"><table summary="HTML to Doxygen Markup Comparison" border="1"><colgroup><col align="left" /><col align="left" /></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="sect2" title="Docbook"><div class="titlepage"><div><div><h3 class="title"><a id="doc_style.docbook"></a>Docbook</h3></div></div></div><div class="sect3" title="Prerequisites"><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>,
by a vendor package like <code class="filename">libxml2</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
+ required. Possible solutions include
+ <a class="ulink" href="http://dblatex.sourceforge.net" target="_top">dblatex</a>,
+ <span class="command"><strong>xmlto</strong></span>, 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.
+ 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:
+ 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" title="Generating the DocBook Files"><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
+ version of all the DocBook 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><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</code></strong></pre><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</code></strong></pre><p>
+ </p><pre class="screen"><strong class="userinput"><code>make doc-xml-single
-docbook</code></strong></pre><p>
</p><p>
- </p><pre class="screen"><strong class="userinput"><code>make doc-xml-validate</code></strong></pre><p>
+ </p><pre class="screen"><strong class="userinput"><code>make doc-xml-validate
-docbook</code></strong></pre><p>
</p></div><div class="sect3" title="File Organization and Basics"><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 />
libstdc++-v3/doc/xml<br />
<br />
Inside this directory, the files of importance:<br />
- spine.xml - index to documentation set<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 />
+ 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 />
</chapter><br />
</book><br />
<br />
- <book> <br />
+ <book><br />
<part><br />
<chapter><br />
<section><br />
<br />
<chapter><br />
</chapter><br />
- </part> <br />
+ </part><br />
</book><br />
<br />
</set><br />
</p></div></div><div class="sect3" title="Markup By Example"><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="id724766"></a><p class="title"><b>Table A.2. 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">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>,
+ 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="id501323"></a><p class="title"><b>Table A.2. 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">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="id
631420"></a><p class="title"><b>Table A.3. 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><div class="table"><a id="id
377073"></a><p class="title"><b>Table A.3. 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><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="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>
+ </td></tr></tbody></table></div></div><br class="table-break" /></div></div><div class="sect2" title="Combines"><div class="titlepage"><div><div><h3 class="title"><a id="doc_style.combines"></a>Combines</h3></div></div></div><div class="sect3" title="Generating Combines and Assemblages"><div class="titlepage"><div><div><h4 class="title"><a id="combines.rules"></a>Generating Combines and Assemblages</h4></div></div></div><p>
+ The following Makefile rules are defaults, and are usually
+ aliased to variable rules.
+ </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-man</code></strong></pre><p>
+ </p><p>
+ </p><pre class="screen"><strong class="userinput"><code>make doc-pdf</code></strong></pre><p>
+ </p></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>
OSDN Git Service
