diff options
Diffstat (limited to 'libstdc++-v3/doc/html/manual/bk01apas04.html')
| -rw-r--r-- | libstdc++-v3/doc/html/manual/bk01apas04.html | 263 |
1 files changed, 263 insertions, 0 deletions
diff --git a/libstdc++-v3/doc/html/manual/bk01apas04.html b/libstdc++-v3/doc/html/manual/bk01apas04.html new file mode 100644 index 00000000000..ceb73d88346 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/bk01apas04.html @@ -0,0 +1,263 @@ +<?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> |