diff options
Diffstat (limited to 'libstdc++-v3/doc/html/manual/documentation_style.html')
| -rw-r--r-- | libstdc++-v3/doc/html/manual/documentation_style.html | 36 |
1 files changed, 18 insertions, 18 deletions
diff --git a/libstdc++-v3/doc/html/manual/documentation_style.html b/libstdc++-v3/doc/html/manual/documentation_style.html index e8d7831cb5c..6cb74dce14c 100644 --- a/libstdc++-v3/doc/html/manual/documentation_style.html +++ b/libstdc++-v3/doc/html/manual/documentation_style.html @@ -1,9 +1,9 @@ <?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.3" /><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. +<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.75.2" /><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> +</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, <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 @@ -15,7 +15,7 @@ graphs, the <a class="ulink" href="http://www.graphviz.org" 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> + </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. </p><p> @@ -35,7 +35,7 @@ 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> + </p></div><div class="sect3" title="Markup"><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 @@ -43,7 +43,7 @@ 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 + <span class="quote">“<span class="quote">doxygenating</span>”</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. @@ -58,14 +58,14 @@ </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> + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Use the Javadoc style...</p></li><li class="listitem"><p> ...not the Qt style. The intermediate *'s are preferred. - </p></li><li><p> + </p></li><li class="listitem"><p> Use the triple-slash style only for one-line comments (the - “<span class="quote">brief</span>” mode). Very recent versions of Doxygen permit + <span class="quote">“<span class="quote">brief</span>”</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> + </p></li><li class="listitem"><p> This is disgusting. Don't do this. </p></li></ol></div><p> Use the @-style of commands, not the !-style. Please be @@ -73,24 +73,24 @@ 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. + have <span class="quote">“<span class="quote">interesting</span>”</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. + of the <span class="quote">“<span class="quote">other</span>”</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> + </p></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>, or <span class="application">Conglomerate</span>. </p><p> - Some editors support special “<span class="quote">XML Validation</span>” + Some editors support special <span class="quote">“<span class="quote">XML Validation</span>”</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>. @@ -133,7 +133,7 @@ <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> + </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 single XML document, and the result of validating the entire XML @@ -146,7 +146,7 @@ xmllint --noout --valid <code class="filename">xml/index.xml</code> </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 /> + </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 /> All Docbook files are in the directory<br /> @@ -206,16 +206,16 @@ xmllint --noout --valid <code class="filename">xml/index.xml</code> </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> + </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="id740402"></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>, +</p><div class="table"><a id="id414841"></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="id613462"></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><div class="table"><a id="id516730"></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"> |