diff options
| author | redi <redi@138bc75d-0d04-0410-961f-82ee72b054a4> | 2012-12-18 11:08:33 +0000 |
|---|---|---|
| committer | redi <redi@138bc75d-0d04-0410-961f-82ee72b054a4> | 2012-12-18 11:08:33 +0000 |
| commit | 26331a7a2729ddd60edaa83a9db55f293d7b30ea (patch) | |
| tree | a512621844e4d61d6edf513b4b29f7b18d4917ca /libstdc++-v3/doc/html/manual/documentation_hacking.html | |
| parent | 11833cca5c63a5d9e65af0f84fc62bfdef20d610 (diff) | |
| download | ppe42-gcc-26331a7a2729ddd60edaa83a9db55f293d7b30ea.tar.gz ppe42-gcc-26331a7a2729ddd60edaa83a9db55f293d7b30ea.zip | |
* doc/xml/manual/abi.xml: Update URLs for C++ ABI.
* doc/xml/manual/policy_data_structures_biblio.xml: Add xmlns
attribute.
* doc/xml/manual/debug_mode.xml: Give filenames to chunks.
* doc/xml/manual/diagnostics.xml: Likewise.
* doc/xml/manual/extensions.xml: Likewise.
* doc/xml/manual/bitmap_allocator.xml: Likewise.
* doc/xml/manual/mt_allocator.xml: Likewise.
* doc/xml/manual/policy_data_structures.xml: Likewise.
* doc/xml/manual/parallel_mode.xml: Likewise.
* doc/xml/manual/profile_mode.xml: Likewise.
* doc/xml/manual/spine.xml: Likewise. Update copyright years.
* doc/html/*: Regenerate.
git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@194576 138bc75d-0d04-0410-961f-82ee72b054a4
Diffstat (limited to 'libstdc++-v3/doc/html/manual/documentation_hacking.html')
| -rw-r--r-- | libstdc++-v3/doc/html/manual/documentation_hacking.html | 118 |
1 files changed, 105 insertions, 13 deletions
diff --git a/libstdc++-v3/doc/html/manual/documentation_hacking.html b/libstdc++-v3/doc/html/manual/documentation_hacking.html index 95ae5255c18..51b77f796c0 100644 --- a/libstdc++-v3/doc/html/manual/documentation_hacking.html +++ b/libstdc++-v3/doc/html/manual/documentation_hacking.html @@ -1,6 +1,6 @@ <?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>Writing and Generating Documentation</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1" /><meta name="keywords" content="ISO C++, documentation, style, docbook, doxygen" /><meta name="keywords" content=" ISO C++ , library " /><meta name="keywords" content=" ISO C++ , runtime , library " /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="appendix_porting.html" title="Appendix B. Porting and Maintenance" /><link rel="prev" href="appendix_porting.html" title="Appendix B. Porting and Maintenance" /><link rel="next" href="internals.html" title="Porting to New Hardware or Operating Systems" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Writing and Generating Documentation</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="appendix_porting.html">Prev</a> </td><th width="60%" align="center">Appendix B. +<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Writing and Generating Documentation</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1" /><meta name="keywords" content="ISO C++, documentation, style, docbook, doxygen" /><meta name="keywords" content="ISO C++, library" /><meta name="keywords" content="ISO C++, runtime, library" /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="appendix_porting.html" title="Appendix B. Porting and Maintenance" /><link rel="prev" href="appendix_porting.html" title="Appendix B. Porting and Maintenance" /><link rel="next" href="internals.html" title="Porting to New Hardware or Operating Systems" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Writing and Generating Documentation</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="appendix_porting.html">Prev</a> </td><th width="60%" align="center">Appendix B. Porting and Maintenance </th><td width="20%" align="right"> <a accesskey="n" href="internals.html">Next</a></td></tr></table><hr /></div><div class="section" title="Writing and Generating Documentation"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="appendix.porting.doc"></a>Writing and Generating Documentation</h2></div></div></div><div class="section" title="Introduction"><div class="titlepage"><div><div><h3 class="title"><a id="doc.intro"></a>Introduction</h3></div></div></div><p> @@ -61,13 +61,9 @@ Generates multi-page HTML documentation, and installs it in the following directories: </p><p> - <code class="filename"> - doc/libstdc++/libstdc++-api.html - </code> + <code class="filename">doc/libstdc++/libstdc++-api.html</code> </p><p> - <code class="filename"> - doc/libstdc++/libstdc++-manual.html - </code> + <code class="filename">doc/libstdc++/libstdc++-manual.html</code> </p></dd><dt><span class="term"> <span class="emphasis"><em>make pdf</em></span> , </span><span class="term"> @@ -117,7 +113,7 @@ supported, and are always aliased to dummy rules. These unsupported formats are: <span class="emphasis"><em>info</em></span>, <span class="emphasis"><em>ps</em></span>, and <span class="emphasis"><em>dvi</em></span>. - </p></div><div class="section" title="Doxygen"><div class="titlepage"><div><div><h3 class="title"><a id="doc.doxygen"></a>Doxygen</h3></div></div></div><div class="section" title="Prerequisites"><div class="titlepage"><div><div><h4 class="title"><a id="doxygen.prereq"></a>Prerequisites</h4></div></div></div><div class="table"><a id="idp22114256"></a><p class="title"><strong>Table B.1. Doxygen Prerequisites</strong></p><div class="table-contents"><table summary="Doxygen Prerequisites" border="1"><colgroup><col align="center" class="c1" /><col align="center" class="c2" /><col align="center" class="c3" /></colgroup><thead><tr><th align="center">Tool</th><th align="center">Version</th><th align="center">Required By</th></tr></thead><tbody><tr><td align="center">coreutils</td><td align="center">8.5</td><td align="center">all</td></tr><tr><td align="center">bash</td><td align="center">4.1</td><td align="center">all</td></tr><tr><td align="center">doxygen</td><td align="center">1.7.6.1</td><td align="center">all</td></tr><tr><td align="center">graphviz</td><td align="center">2.26</td><td align="center">graphical hierarchies</td></tr><tr><td align="center">pdflatex</td><td align="center">2007-59</td><td align="center">pdf output</td></tr></tbody></table></div></div><br class="table-break" /><p> + </p></div><div class="section" title="Doxygen"><div class="titlepage"><div><div><h3 class="title"><a id="doc.doxygen"></a>Doxygen</h3></div></div></div><div class="section" title="Prerequisites"><div class="titlepage"><div><div><h4 class="title"><a id="doxygen.prereq"></a>Prerequisites</h4></div></div></div><div class="table"><a id="idp22321120"></a><p class="title"><strong>Table B.1. Doxygen Prerequisites</strong></p><div class="table-contents"><table summary="Doxygen Prerequisites" border="1"><colgroup><col align="center" class="c1" /><col align="center" class="c2" /><col align="center" class="c3" /></colgroup><thead><tr><th align="center">Tool</th><th align="center">Version</th><th align="center">Required By</th></tr></thead><tbody><tr><td align="center">coreutils</td><td align="center">8.5</td><td align="center">all</td></tr><tr><td align="center">bash</td><td align="center">4.1</td><td align="center">all</td></tr><tr><td align="center">doxygen</td><td align="center">1.7.6.1</td><td align="center">all</td></tr><tr><td align="center">graphviz</td><td align="center">2.26</td><td align="center">graphical hierarchies</td></tr><tr><td align="center">pdflatex</td><td align="center">2007-59</td><td align="center">pdf output</td></tr></tbody></table></div></div><br class="table-break" /><p> Prerequisite tools are Bash 2.0 or later, <a class="link" href="http://www.doxygen.org/" target="_top">Doxygen</a>, and the <a class="link" href="http://www.gnu.org/software/coreutils/" target="_top">GNU @@ -171,7 +167,51 @@ 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="section" title="Markup"><div class="titlepage"><div><div><h4 class="title"><a id="doxygen.markup"></a>Markup</h4></div></div></div><p> + </p></div><div class="section" title="Debugging Generation"><div class="titlepage"><div><div><h4 class="title"><a id="doxygen.debug"></a>Debugging Generation</h4></div></div></div><p> + Sometimes, mis-configuration of the pre-requisite tools can + lead to errors when attempting to build the + documentation. Here are some of the obvious errors, and ways + to fix some common issues that may appear quite cryptic. + </p><p> + First, if using a rule like <code class="code">make pdf</code>, try to + narrow down the scope of the error to either docbook + (<code class="code">make doc-pdf-docbook</code>) or doxygen (<code class="code">make + doc-pdf-doxygen</code>). + </p><p> + Working on the doxygen path only, closely examine the + contents of the following build directory: + <code class="filename">build/target/libstdc++-v3/doc/doxygen/latex</code>. + Pay attention to three files enclosed within, annotated as follows. + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> + <span class="emphasis"><em>refman.tex</em></span> + </p><p> + The actual latex file, or partial latex file. This is generated + via <span class="command"><strong>doxygen</strong></span>, and is the LaTeX version of the + Doxygen XML file <code class="filename">libstdc++-api.xml</code>. Go to a specific + line, and look at the genrated LaTeX, and try to deduce what + markup in <code class="filename">libstdc++-api.xml</code> is causing it. + </p></li><li class="listitem"><p> + <span class="emphasis"><em>refman.out</em></span> + </p><p> + A log of the compilation of the converted LaTeX form to pdf. This + is a linear list, from the beginning of the + <code class="filename">refman.tex</code> file: the last entry of this file + should be the end of the LaTeX file. If it is truncated, then you + know that the last entry is the last part of the generated LaTeX + source file that is valid. Often this file contains an error with + a specific line number of <code class="filename">refman.tex</code> that is + incorrect, or will have clues at the end of the file with the dump + of the memory usage of LaTeX. + </p></li></ul></div><p> + If the error at hand is not obvious after examination, a + fall-back strategy is to start commenting out the doxygen + input sources, which can be found in + <code class="filename">doc/doxygen/user.cfg.in</code>, look for the + <code class="literal">INPUT</code> tag. Start by commenting out whole + directories of header files, until the offending header is + identified. Then, read the latex log files to try and find + surround text, and look for that in the offending header. + </p></div><div class="section" 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 @@ -271,7 +311,7 @@ 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="idp22176240"></a><p class="title"><strong>Table B.2. HTML to Doxygen Markup Comparison</strong></p><div class="table-contents"><table summary="HTML to Doxygen Markup Comparison" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></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="section" title="Docbook"><div class="titlepage"><div><div><h3 class="title"><a id="doc.docbook"></a>Docbook</h3></div></div></div><div class="section" title="Prerequisites"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.prereq"></a>Prerequisites</h4></div></div></div><div class="table"><a id="idp22195616"></a><p class="title"><strong>Table B.3. Docbook Prerequisites</strong></p><div class="table-contents"><table summary="Docbook Prerequisites" border="1"><colgroup><col align="center" class="c1" /><col align="center" class="c2" /><col align="center" class="c3" /></colgroup><thead><tr><th align="center">Tool</th><th align="center">Version</th><th align="center">Required By</th></tr></thead><tbody><tr><td align="center">docbook5-style-xsl</td><td align="center">1.76.1</td><td align="center">all</td></tr><tr><td align="center">xsltproc</td><td align="center">1.1.26</td><td align="center">all</td></tr><tr><td align="center">xmllint</td><td align="center">2.7.7</td><td align="center">validation</td></tr><tr><td align="center">dblatex</td><td align="center">0.3</td><td align="center">pdf output</td></tr><tr><td align="center">pdflatex</td><td align="center">2007-59</td><td align="center">pdf output</td></tr><tr><td align="center">docbook2X</td><td align="center">0.8.8</td><td align="center">info output</td></tr><tr><td align="center">epub3 stylesheets</td><td align="center">b3</td><td align="center">epub output</td></tr></tbody></table></div></div><br class="table-break" /><p> + </p><div class="table"><a id="idp22396784"></a><p class="title"><strong>Table B.2. HTML to Doxygen Markup Comparison</strong></p><div class="table-contents"><table summary="HTML to Doxygen Markup Comparison" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></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="section" title="Docbook"><div class="titlepage"><div><div><h3 class="title"><a id="doc.docbook"></a>Docbook</h3></div></div></div><div class="section" title="Prerequisites"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.prereq"></a>Prerequisites</h4></div></div></div><div class="table"><a id="idp22416224"></a><p class="title"><strong>Table B.3. Docbook Prerequisites</strong></p><div class="table-contents"><table summary="Docbook Prerequisites" border="1"><colgroup><col align="center" class="c1" /><col align="center" class="c2" /><col align="center" class="c3" /></colgroup><thead><tr><th align="center">Tool</th><th align="center">Version</th><th align="center">Required By</th></tr></thead><tbody><tr><td align="center">docbook5-style-xsl</td><td align="center">1.76.1</td><td align="center">all</td></tr><tr><td align="center">xsltproc</td><td align="center">1.1.26</td><td align="center">all</td></tr><tr><td align="center">xmllint</td><td align="center">2.7.7</td><td align="center">validation</td></tr><tr><td align="center">dblatex</td><td align="center">0.3</td><td align="center">pdf output</td></tr><tr><td align="center">pdflatex</td><td align="center">2007-59</td><td align="center">pdf output</td></tr><tr><td align="center">docbook2X</td><td align="center">0.8.8</td><td align="center">info output</td></tr><tr><td align="center">epub3 stylesheets</td><td align="center">b3</td><td align="center">epub output</td></tr></tbody></table></div></div><br class="table-break" /><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>, @@ -343,7 +383,59 @@ <strong class="userinput"><code> make <code class="literal">XSL_STYLE_DIR="/usr/share/xml/docbook/stylesheet/nwalsh"</code> doc-html-docbook </code></strong> - </pre></div><div class="section" title="Editing and Validation"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.validation"></a>Editing and Validation</h4></div></div></div><p> + </pre></div><div class="section" title="Debugging Generation"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.debug"></a>Debugging Generation</h4></div></div></div><p> + Sometimes, mis-configuration of the pre-requisite tools can + lead to errors when attempting to build the + documentation. Here are some of the obvious errors, and ways + to fix some common issues that may appear quite cryptic. + </p><p> + First, if using a rule like <code class="code">make pdf</code>, try to + narrow down the scope of the error to either docbook + (<code class="code">make doc-pdf-docbook</code>) or doxygen (<code class="code">make + doc-pdf-doxygen</code>). + </p><p> + Working on the docbook path only, closely examine the + contents of the following build directory: + <code class="filename">build/target/libstdc++-v3/doc/docbook/latex</code>. + Pay attention to three files enclosed within, annotated as follows. + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> + <span class="emphasis"><em>spine.tex</em></span> + </p><p> + The actual latex file, or partial latex file. This is generated + via <span class="command"><strong>dblatex</strong></span>, and is the LaTeX version of the + DocBook XML file <code class="filename">spine.xml</code>. Go to a specific + line, and look at the genrated LaTeX, and try to deduce what + markup in <code class="filename">spine.xml</code> is causing it. + </p></li><li class="listitem"><p> + <span class="emphasis"><em>spine.out</em></span> + </p><p> + A log of the conversion from the XML form to the LaTeX form. This + is a linear list, from the beginning of the + <code class="filename">spine.xml</code> file: the last entry of this file + should be the end of the DocBook file. If it is truncated, then + you know that the last entry is the last part of the XML source + file that is valid. The error is after this point. + </p></li><li class="listitem"><p> + <span class="emphasis"><em>spine.log</em></span> + </p><p> + A log of the compilation of the converted LaTeX form to pdf. This + is a linear list, from the beginning of the + <code class="filename">spine.tex</code> file: the last entry of this file + should be the end of the LaTeX file. If it is truncated, then you + know that the last entry is the last part of the generated LaTeX + source file that is valid. Often this file contains an error with + a specific line number of <code class="filename">spine.tex</code> that is + incorrect. + </p></li></ul></div><p> + If the error at hand is not obvious after examination, or if one + encounters the inscruitable <span class="quote">“<span class="quote">Incomplete + \ifmmode</span>”</span> error, a fall-back strategy is to start + commenting out parts of the XML document (regardless of what + this does to over-all document validity). Start by + commenting out each of the largest parts of the + <code class="filename">spine.xml</code> file, section by section, + until the offending section is identified. + </p></div><div class="section" title="Editing and Validation"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.validation"></a>Editing and Validation</h4></div></div></div><p> After editing the xml sources, please make sure that the XML documentation and markup is still valid. This can be done easily, with the following validation rule: @@ -429,11 +521,11 @@ make <code class="literal">XSL_STYLE_DIR="/usr/share/xml/docbook/stylesheet/nwal <a class="link" 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="idp22257040"></a><p class="title"><strong>Table B.4. HTML to Docbook XML Markup Comparison</strong></p><div class="table-contents"><table summary="HTML to Docbook XML Markup Comparison" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></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>, + </p><div class="table"><a id="idp22493856"></a><p class="title"><strong>Table B.4. HTML to Docbook XML Markup Comparison</strong></p><div class="table-contents"><table summary="HTML to Docbook XML Markup Comparison" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></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="idp22281184"></a><p class="title"><strong>Table B.5. Docbook XML Element Use</strong></p><div class="table-contents"><table summary="Docbook XML Element Use" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></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="idp22518000"></a><p class="title"><strong>Table B.5. Docbook XML Element Use</strong></p><div class="table-contents"><table summary="Docbook XML Element Use" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></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"> |
