<?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.7
3.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>
+<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.7
4.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="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
<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
+ 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>
- and
+ </p><p>
</p><pre class="screen"><strong class="userinput"><code>make doc-xml-doxygen</code></strong></pre><p>
- and
+ </p><p>
</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
</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
+ 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>.
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
+ 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>
- and
+ </p><p>
</p><pre class="screen"><strong class="userinput"><code>make doc-pdf</code></strong></pre><p>
- and
+ </p><p>
</p><pre class="screen"><strong class="userinput"><code>make doc-xml-single</code></strong></pre><p>
- and
+ </p><p>
</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 />
</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>
+ </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="id552441"></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="id554436"></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="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>
OSDN Git Service
