diff options
| author | bkoz <bkoz@138bc75d-0d04-0410-961f-82ee72b054a4> | 2011-02-08 18:33:31 +0000 |
|---|---|---|
| committer | bkoz <bkoz@138bc75d-0d04-0410-961f-82ee72b054a4> | 2011-02-08 18:33:31 +0000 |
| commit | 8ada162555e5336d630d927b1b37275e3fc9d92b (patch) | |
| tree | 996623394fa1c65bcb0eb5b38106e733bfbd2253 /libstdc++-v3 | |
| parent | 11a9e74f6a391868da08900024e48143df615232 (diff) | |
| download | gcc-8ada162555e5336d630d927b1b37275e3fc9d92b.tar.gz | |
2011-02-08 Benjamin Kosnik <bkoz@redhat.com>
* doc/xml/manual/appendix_porting.xml: Add doc section.
* doc/xml/manual/appendix_contributing.xml: Split out doc bits to...
* doc/xml/manual/documentation_hacking.xml: ...here.
* doc/xml/manual/debug_mode.xml: Adjust.
* doc/xml/manual/prerequisites.xml: Adjust.
* doc/Makefile.am (xml_sources): Add dot files,
documentation_hacking.xml.
* doc/Makefile.in: Regenerate.
* doc/xml/manual/build_hacking.xml: Use absolute paths for images.
* doc/xml/images/confdeps.pdf: Add.
git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@169932 138bc75d-0d04-0410-961f-82ee72b054a4
Diffstat (limited to 'libstdc++-v3')
| -rw-r--r-- | libstdc++-v3/ChangeLog | 15 | ||||
| -rw-r--r-- | libstdc++-v3/doc/Makefile.am | 8 | ||||
| -rw-r--r-- | libstdc++-v3/doc/Makefile.in | 6 | ||||
| -rw-r--r-- | libstdc++-v3/doc/xml/images/confdeps.pdf | bin | 0 -> 50629 bytes | |||
| -rw-r--r-- | libstdc++-v3/doc/xml/manual/appendix_contributing.xml | 692 | ||||
| -rw-r--r-- | libstdc++-v3/doc/xml/manual/appendix_porting.xml | 6 | ||||
| -rw-r--r-- | libstdc++-v3/doc/xml/manual/build_hacking.xml | 32 | ||||
| -rw-r--r-- | libstdc++-v3/doc/xml/manual/debug_mode.xml | 8 | ||||
| -rw-r--r-- | libstdc++-v3/doc/xml/manual/documentation_hacking.xml | 990 | ||||
| -rw-r--r-- | libstdc++-v3/doc/xml/manual/prerequisites.xml | 4 |
10 files changed, 1043 insertions, 718 deletions
diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index 7127f26ae0d..f796047dc08 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,18 @@ +2011-02-08 Benjamin Kosnik <bkoz@redhat.com> + + * doc/xml/manual/appendix_porting.xml: Add doc section. + * doc/xml/manual/appendix_contributing.xml: Split out doc bits to... + * doc/xml/manual/documentation_hacking.xml: ...here. + + * doc/xml/manual/debug_mode.xml: Adjust. + * doc/xml/manual/prerequisites.xml: Adjust. + * doc/Makefile.am (xml_sources): Add dot files, + documentation_hacking.xml. + * doc/Makefile.in: Regenerate. + + * doc/xml/manual/build_hacking.xml: Use absolute paths for images. + * doc/xml/images/confdeps.pdf: Add. + 2011-02-08 Jonathan Wakely <jwakely.gcc@gmail.com> * doc/xml/gnu/fdl-1.2.xml: Remove. diff --git a/libstdc++-v3/doc/Makefile.am b/libstdc++-v3/doc/Makefile.am index f8e939fb38e..3cdb1fd8bc6 100644 --- a/libstdc++-v3/doc/Makefile.am +++ b/libstdc++-v3/doc/Makefile.am @@ -1,6 +1,6 @@ ## Makefile for the doc subdirectory of the GNU C++ Standard library. ## -## Copyright (C) 2008, 2009, 2010 Free Software Foundation, Inc. +## Copyright (C) 2008, 2009, 2010, 2011 Free Software Foundation, Inc. ## ## This file is part of the libstdc++ version 3 distribution. ## Process this file with automake to produce Makefile.in. @@ -318,6 +318,7 @@ xml_sources_manual = \ ${xml_dir}/manual/debug_mode.xml \ ${xml_dir}/manual/debug.xml \ ${xml_dir}/manual/diagnostics.xml \ + ${xml_dir}/manual/documentation_hacking.xml \ ${xml_dir}/manual/evolution.xml \ ${xml_dir}/manual/extensions.xml \ ${xml_dir}/manual/internals.xml \ @@ -360,7 +361,10 @@ xml_sources = \ xml_noinst = \ ${xml_dir}/book.txml \ ${xml_dir}/chapter.txml \ - ${xml_dir}/class.txml + ${xml_dir}/class.txml \ + ${xml_dir}/images/confdeps.dot \ + ${xml_dir}/images/confdeps.png \ + ${xml_dir}/images/confdeps.pdf XSLTPROC = xsltproc XSLTPROC_FLAGS = --nonet --xinclude diff --git a/libstdc++-v3/doc/Makefile.in b/libstdc++-v3/doc/Makefile.in index e6e19203ebd..60b1eb06d3f 100644 --- a/libstdc++-v3/doc/Makefile.in +++ b/libstdc++-v3/doc/Makefile.in @@ -369,6 +369,7 @@ xml_sources_manual = \ ${xml_dir}/manual/debug_mode.xml \ ${xml_dir}/manual/debug.xml \ ${xml_dir}/manual/diagnostics.xml \ + ${xml_dir}/manual/documentation_hacking.xml \ ${xml_dir}/manual/evolution.xml \ ${xml_dir}/manual/extensions.xml \ ${xml_dir}/manual/internals.xml \ @@ -411,7 +412,10 @@ xml_sources = \ xml_noinst = \ ${xml_dir}/book.txml \ ${xml_dir}/chapter.txml \ - ${xml_dir}/class.txml + ${xml_dir}/class.txml \ + ${xml_dir}/images/confdeps.dot \ + ${xml_dir}/images/confdeps.png \ + ${xml_dir}/images/confdeps.pdf XSLTPROC_FLAGS = --nonet --xinclude #XSL_STYLE_DIR = /usr/share/sgml/docbook/xsl-stylesheets diff --git a/libstdc++-v3/doc/xml/images/confdeps.pdf b/libstdc++-v3/doc/xml/images/confdeps.pdf Binary files differnew file mode 100644 index 00000000000..dab5ef341eb --- /dev/null +++ b/libstdc++-v3/doc/xml/images/confdeps.pdf diff --git a/libstdc++-v3/doc/xml/manual/appendix_contributing.xml b/libstdc++-v3/doc/xml/manual/appendix_contributing.xml index 7dfe8e0ddf4..49cbcab9ba3 100644 --- a/libstdc++-v3/doc/xml/manual/appendix_contributing.xml +++ b/libstdc++-v3/doc/xml/manual/appendix_contributing.xml @@ -940,698 +940,6 @@ indicate a place that may require attention for multi-thread safety. </section> </section> -<section xml:id="contrib.doc_style" xreflabel="Documentation Style"><info><title>Documentation Style</title></info> - <?dbhtml filename="documentation_style.html"?> - - <section xml:id="doc_style.doxygen"><info><title>Doxygen</title></info> - - <section xml:id="doxygen.prereq"><info><title>Prerequisites</title></info> - - <para> - Prerequisite tools are Bash 2.0 or later, - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.doxygen.org/">Doxygen</link>, and - the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.gnu.org/software/coreutils/">GNU - coreutils</link>. (GNU versions of find, xargs, and possibly - sed and grep are used, just because the GNU versions make - things very easy.) - </para> - - <para> - To generate the pretty pictures and hierarchy - graphs, the - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.graphviz.org">Graphviz</link> package - will need to be installed. For PDF - output, <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.tug.org/applications/pdftex/"> - pdflatex</link> is required. - </para> - </section> - - <section xml:id="doxygen.rules"><info><title>Generating the Doxygen Files</title></info> - - <para> - The following Makefile rules run Doxygen to generate HTML - docs, XML docs, XML docs as a single file, PDF docs, and the man pages. - </para> - - <para> - <screen><userinput>make doc-html-doxygen</userinput></screen> - </para> - - <para> - <screen><userinput>make doc-xml-doxygen</userinput></screen> - </para> - - <para> - <screen><userinput>make doc-xml-single-doxygen</userinput></screen> - </para> - - <para> - <screen><userinput>make doc-pdf-doxygen</userinput></screen> - </para> - - <para> - <screen><userinput>make doc-man-doxygen</userinput></screen> - </para> - - <para> - Generated files are output into separate sub directores of - <filename class="directory">doc/doxygen/</filename> in the - build directory, based on the output format. For instance, the - HTML docs will be in <filename class="directory">doc/doxygen/html</filename>. - </para> - - <para> - Careful observers will see that the Makefile rules simply call - a script from the source tree, <filename>run_doxygen</filename>, 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 <literal>--help</literal>.) - </para> - - <para> - If you wish to tweak the Doxygen settings, do so by editing - <filename>doc/doxygen/user.cfg.in</filename>. Notes to fellow - library hackers are written in triple-# comments. - </para> - - </section> - - <section xml:id="doxygen.markup"><info><title>Markup</title></info> - - - <para> - In general, libstdc++ files should be formatted according to - the rules found in the - <link linkend="contrib.coding_style">Coding Standard</link>. Before - any doxygen-specific formatting tweaks are made, please try to - make sure that the initial formatting is sound. - </para> - - <para> - Adding Doxygen markup to a file (informally called - <quote>doxygenating</quote>) is very simple. The Doxygen manual can be - found - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.stack.nl/~dimitri/doxygen/download.html#latestman">here</link>. - We try to use a very-recent version of Doxygen. - </para> - - <para> - For classes, use - <classname>deque</classname>/<classname>vector</classname>/<classname>list</classname> - and <classname>std::pair</classname> as examples. For - functions, see their member functions, and the free functions - in <filename>stl_algobase.h</filename>. Member functions of - other container-like types should read similarly to these - member functions. - </para> - - <para> - Some commentary to accompany - the first list in the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.stack.nl/~dimitri/doxygen/docblocks.html">Special - Documentation Blocks</link> section of - the Doxygen manual: - </para> - - <orderedlist inheritnum="ignore" continuation="restarts"> - <listitem> - <para>For longer comments, use the Javadoc style...</para> - </listitem> - - <listitem> - <para> - ...not the Qt style. The intermediate *'s are preferred. - </para> - </listitem> - - <listitem> - <para> - Use the triple-slash style only for one-line comments (the - <quote>brief</quote> mode). - </para> - </listitem> - - <listitem> - <para> - This is disgusting. Don't do this. - </para> - </listitem> - </orderedlist> - - <para> - Some specific guidelines: - </para> - - <para> - 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 <quote>interesting</quote> effects. - </para> - - <para> - Use either kind of grouping, as - appropriate. <filename>doxygroups.cc</filename> exists for this - purpose. See <filename>stl_iterator.h</filename> for a good example - of the <quote>other</quote> kind of grouping. - </para> - - <para> - 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.) - </para> - - <para> - Complicated math functions should use the multi-line - format. An example from <filename>random.h</filename>: - </para> - - <para> -<literallayout class="normal"> - /** - * @brief A model of a linear congruential random number generator. - * - * @f[ - * x_{i+1}\leftarrow(ax_{i} + c) \bmod m - * @f] - */ -</literallayout> - </para> - - <para> - Be careful about using certain, special characters when - writing Doxygen comments. Single and double quotes, and - separators in filenames are two common trouble spots. When in - doubt, consult the following table. - </para> - -<table frame="all"> -<title>HTML to Doxygen Markup Comparison</title> - -<tgroup cols="2" align="left" colsep="1" rowsep="1"> -<colspec colname="c1"/> -<colspec colname="c2"/> - - <thead> - <row> - <entry>HTML</entry> - <entry>Doxygen</entry> - </row> - </thead> - - <tbody> - <row> - <entry>\</entry> - <entry>\\</entry> - </row> - - <row> - <entry>"</entry> - <entry>\"</entry> - </row> - - <row> - <entry>'</entry> - <entry>\'</entry> - </row> - - <row> - <entry><i></entry> - <entry>@a word</entry> - </row> - - <row> - <entry><b></entry> - <entry>@b word</entry> - </row> - - <row> - <entry><code></entry> - <entry>@c word</entry> - </row> - - <row> - <entry><em></entry> - <entry>@a word</entry> - </row> - - <row> - <entry><em></entry> - <entry><em>two words or more</em></entry> - </row> - </tbody> - -</tgroup> -</table> - - - </section> - - </section> - - <section xml:id="doc_style.docbook"><info><title>Docbook</title></info> - - - <section xml:id="docbook.prereq"><info><title>Prerequisites</title></info> - - <para> - Editing the DocBook sources requires an XML editor. Many - exist: some notable options - include <command>emacs</command>, <application>Kate</application>, - or <application>Conglomerate</application>. - </para> - - <para> - Some editors support special <quote>XML Validation</quote> - modes that can validate the file as it is - produced. Recommended is the <command>nXML Mode</command> - for <command>emacs</command>. - </para> - - <para> - Besides an editor, additional DocBook files and XML tools are - also required. - </para> - - <para> - Access to the DocBook 5.0 stylesheets and schema is required. The - stylesheets are usually packaged by vendor, in something - like <filename>docbook5-style-xsl</filename>. To exactly match - generated output, please use a version of the stylesheets - equivalent - to <filename>docbook5-style-xsl-1.75.2-3</filename>. The - installation directory for this package corresponds to - the <literal>XSL_STYLE_DIR</literal> - in <filename>doc/Makefile.am</filename> and defaults - to <filename class="directory">/usr/share/sgml/docbook/xsl-ns-stylesheets</filename>. - </para> - - <para> - For processing XML, an XML processor and some style - sheets are necessary. Defaults are <command>xsltproc</command> - provided by <filename>libxslt</filename>. - </para> - - <para> - For validating the XML document, you'll need - something like <command>xmllint</command> and access to the - relevant DocBook schema. These are provided - by a vendor package like <filename>libxml2</filename> and <filename>docbook5-schemas-5.0-4</filename> - </para> - - <para> - For PDF output, something that transforms valid Docbook XML to PDF is - required. Possible solutions include <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://dblatex.sourceforge.net">dblatex</link>, - <command>xmlto</command>, or <command>prince</command>. Of - these, <command>dblatex</command> is the default. Other - options are listed on the DocBook web <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://wiki.docbook.org/topic/DocBookPublishingTools">pages</link>. Please - consult the <email>libstdc++@gcc.gnu.org</email> list when - preparing printed manuals for current best practice and - suggestions. - </para> - - <para> - For Texinfo output, something that transforms valid Docbook - XML to Texinfo is required. The default choice is <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://docbook2x.sourceforge.net/">docbook2X</link>. - </para> - - <para> - Please make sure that the XML documentation and markup is valid for - any change. This can be done easily, with the validation rule - detailed below, which is equivalent to doing: - </para> - - <screen> - <userinput> -xmllint --noout --valid <filename>xml/index.xml</filename> - </userinput> - </screen> - </section> - - <section xml:id="docbook.rules"><info><title>Generating the DocBook Files</title></info> - - - <para> - The following Makefile rules generate (in order): an HTML - 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. - </para> - - <para> - <screen><userinput>make doc-html-docbook</userinput></screen> - </para> - - <para> - <screen><userinput>make doc-pdf-docbook</userinput></screen> - </para> - - <para> - <screen><userinput>make doc-xml-single-docbook</userinput></screen> - </para> - - <para> - <screen><userinput>make doc-xml-validate-docbook</userinput></screen> - </para> - - <para> - Generated files are output into separate sub directores of - <filename class="directory">doc/docbook/</filename> in the - build directory, based on the output format. For instance, the - HTML docs will be in <filename class="directory">doc/docbook/html</filename>. - </para> - </section> - - <section xml:id="docbook.examples"><info><title>File Organization and Basics</title></info> - - - <literallayout class="normal"> - <emphasis>Which files are important</emphasis> - - All Docbook files are in the directory - libstdc++-v3/doc/xml - - Inside this directory, the files of importance: - spine.xml - index to documentation set - manual/spine.xml - index to manual - manual/*.xml - individual chapters and sections of the manual - faq.xml - index to FAQ - api.xml - index to source level / API - - All *.txml files are template xml files, i.e., otherwise empty files with - the correct structure, suitable for filling in with new information. - - <emphasis>Canonical Writing Style</emphasis> - - class template - function template - member function template - (via C++ Templates, Vandevoorde) - - class in namespace std: allocator, not std::allocator - - header file: iostream, not <iostream> - - - <emphasis>General structure</emphasis> - - <set> - <book> - </book> - - <book> - <chapter> - </chapter> - </book> - - <book> - <part> - <chapter> - <section> - </section> - - <sect1> - </sect1> - - <sect1> - <sect2> - </sect2> - </sect1> - </chapter> - - <chapter> - </chapter> - </part> - </book> - - </set> - </literallayout> - </section> - - <section xml:id="docbook.markup"><info><title>Markup By Example</title></info> - - - <para> - Complete details on Docbook markup can be found in the DocBook - Element Reference, - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.docbook.org/tdg/en/html/part2.html">online</link>. - An incomplete reference for HTML to Docbook conversion is - detailed in the table below. - </para> - -<table frame="all"> -<title>HTML to Docbook XML Markup Comparison</title> - -<tgroup cols="2" align="left" colsep="1" rowsep="1"> -<colspec colname="c1"/> -<colspec colname="c2"/> - - <thead> - <row> - <entry>HTML</entry> - <entry>Docbook</entry> - </row> - </thead> - - <tbody> - <row> - <entry><p></entry> - <entry><para></entry> - </row> - <row> - <entry><pre></entry> - <entry><computeroutput>, <programlisting>, - <literallayout></entry> - </row> - <row> - <entry><ul></entry> - <entry><itemizedlist></entry> - </row> - <row> - <entry><ol></entry> - <entry><orderedlist></entry> - </row> - <row> - <entry><il></entry> - <entry><listitem></entry> - </row> - <row> - <entry><dl></entry> - <entry><variablelist></entry> - </row> - <row> - <entry><dt></entry> - <entry><term></entry> - </row> - <row> - <entry><dd></entry> - <entry><listitem></entry> - </row> - - <row> - <entry><a href=""></entry> - <entry><ulink url=""></entry> - </row> - <row> - <entry><code></entry> - <entry><literal>, <programlisting></entry> - </row> - <row> - <entry><strong></entry> - <entry><emphasis></entry> - </row> - <row> - <entry><em></entry> - <entry><emphasis></entry> - </row> - <row> - <entry>"</entry> - <entry><quote></entry> - </row> - </tbody> -</tgroup> -</table> - -<para> - And examples of detailed markup for which there are no real HTML - equivalents are listed in the table below. -</para> - -<table frame="all"> -<title>Docbook XML Element Use</title> - -<tgroup cols="2" align="left" colsep="1" rowsep="1"> -<colspec colname="c1"/> -<colspec colname="c2"/> - - <thead> - <row> - <entry>Element</entry> - <entry>Use</entry> - </row> - </thead> - - <tbody> - <row> - <entry><structname></entry> - <entry><structname>char_traits</structname></entry> - </row> - <row> - <entry><classname></entry> - <entry><classname>string</classname></entry> - </row> - <row> - <entry><function></entry> - <entry> - <para><function>clear()</function></para> - <para><function>fs.clear()</function></para> - </entry> - </row> - <row> - <entry><type></entry> - <entry><type>long long</type></entry> - </row> - <row> - <entry><varname></entry> - <entry><varname>fs</varname></entry> - </row> - <row> - <entry><literal></entry> - <entry> - <para><literal>-Weffc++</literal></para> - <para><literal>rel_ops</literal></para> - </entry> - </row> - <row> - <entry><constant></entry> - <entry> - <para><constant>_GNU_SOURCE</constant></para> - <para><constant>3.0</constant></para> - </entry> - </row> - <row> - <entry><command></entry> - <entry><command>g++</command></entry> - </row> - <row> - <entry><errortext></entry> - <entry><errortext>In instantiation of</errortext></entry> - </row> - <row> - <entry><filename></entry> - <entry> - <para><filename class="headerfile">ctype.h</filename></para> - <para><filename class="directory">/home/gcc/build</filename></para> - <para><filename class="libraryfile">libstdc++.so</filename></para> - </entry> - </row> - </tbody> -</tgroup> -</table> - - </section> - </section> - - <section xml:id="doc_style.combines"><info><title>Combines</title></info> - - - <section xml:id="combines.rules"><info><title>Generating Combines and Assemblages</title></info> - - - <para> - The following Makefile rules are defaults, and are usually - aliased to more detailed rules. They are shortcuts for - generating HTML, PDF, Texinfo, XML, or man files and then collecting - the generated files into the build directory's doc directory. - </para> - -<variablelist> - -<varlistentry><term> - <emphasis>make doc-html</emphasis> - </term> -<listitem> - <para> - Generates multi-page HTML documentation in the following directories: - </para> - <para> - <filename class="directory">doc/libstdc++-api.html</filename> - </para> - <para> - <filename class="directory">doc/libstdc++-manual.html</filename> - </para> -</listitem> -</varlistentry> - -<varlistentry><term> - <emphasis>make doc-man</emphasis> - </term> -<listitem> - <para> - Generates man pages in the following directory: - </para> - <para> - <filename class="directory">doc/libstdc++-api.man</filename> - </para> -</listitem> -</varlistentry> - -<varlistentry><term> - <emphasis>make doc-pdf</emphasis> - </term> -<listitem> - <para> - Generates indexed PDF documentation in the following files: - </para> - <para> - <filename>doc/libstdc++-api.pdf</filename> - </para> - <para> - <filename>doc/libstdc++-manual.pdf</filename> - </para> -</listitem> -</varlistentry> - -<varlistentry><term> - <emphasis>make doc-texinfo</emphasis> - </term> -<listitem> - <para> - Generates Texinfo documentation in the following files: - </para> - <para> - <filename>doc/libstdc++-manual.texinfo</filename> - </para> -</listitem> -</varlistentry> - -<varlistentry><term> - <emphasis>make doc-xml</emphasis> - </term> -<listitem> - <para> - Generates single-file XML documentation in the following files: - </para> - <para> - <filename>doc/libstdc++-api.xml</filename> - </para> - <para> - <filename>doc/libstdc++-manual.xml</filename> - </para> -</listitem> -</varlistentry> - -</variablelist> - - - </section> - </section> -</section> - <section xml:id="contrib.design_notes" xreflabel="Design Notes"><info><title>Design Notes</title></info> <?dbhtml filename="source_design_notes.html"?> diff --git a/libstdc++-v3/doc/xml/manual/appendix_porting.xml b/libstdc++-v3/doc/xml/manual/appendix_porting.xml index dc29a35353f..68f3f435d99 100644 --- a/libstdc++-v3/doc/xml/manual/appendix_porting.xml +++ b/libstdc++-v3/doc/xml/manual/appendix_porting.xml @@ -19,12 +19,14 @@ </keywordset> </info> - - <!-- Hacking the Build System --> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="build_hacking.xml"> </xi:include> + <!-- Hacking the Documentation Systems --> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="documentation_hacking.xml"> + </xi:include> + <!-- Internals: Porting to New Hardware or Operating Systems --> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="internals.xml"> </xi:include> diff --git a/libstdc++-v3/doc/xml/manual/build_hacking.xml b/libstdc++-v3/doc/xml/manual/build_hacking.xml index 686ff31fc90..945ef499681 100644 --- a/libstdc++-v3/doc/xml/manual/build_hacking.xml +++ b/libstdc++-v3/doc/xml/manual/build_hacking.xml @@ -1,4 +1,4 @@ -<section xmlns="http://docbook.org/ns/docbook" version="5.0" +<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="appendix.porting.build_hacking" xreflabel="Build Hacking"> <?dbhtml filename="build_hacking.html"?> @@ -22,10 +22,8 @@ </keywordset> </info> - - <section xml:id="build_hacking.prereq"><info><title>Prerequisites</title></info> - + <para> As noted <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/install/prerequisites.html">previously</link>, certain other tools are necessary for hacking on files that @@ -41,18 +39,22 @@ </section> <section xml:id="build_hacking.map"><info><title>Overview: What Comes from Where</title></info> - - <screen> - <inlinemediaobject> + + <figure> + <title>Configure and Build File Dependencies</title> + <mediaobject> + <imageobject> + <imagedata align="center" format="PDF" fileref="/mnt/share/src/gcc.svn-trunk/libstdc++-v3/doc/xml/images/confdeps.pdf"/> + </imageobject> <imageobject> - <imagedata fileref="images/confdeps.png"/> + <imagedata align="center" format="PNG" fileref="/mnt/share/src/gcc.svn-trunk/libstdc++-v3/doc/xml/images/confdeps.png"/> </imageobject> <textobject> - <phrase>Dependency Graph Configure to Build Files</phrase> + <phrase>Dependency Graph for Configure and Build Files</phrase> </textobject> - </inlinemediaobject> - </screen> + </mediaobject> + </figure> <para> Regenerate all generated files by using the command sequence @@ -68,7 +70,7 @@ </section> <section xml:id="build_hacking.scripts"><info><title>Storing Information in non-AC files (like configure.host)</title></info> - + <para> Until that glorious day when we can use AC_TRY_LINK with a @@ -100,7 +102,7 @@ </section> <section xml:id="build_hacking.conventions"><info><title>Coding and Commenting Conventions</title></info> - + <para> Most comments should use {octothorpes, shibboleths, hash marks, @@ -125,7 +127,7 @@ </section> <section xml:id="build_hacking.acinclude"><info><title>The acinclude.m4 layout</title></info> - + <para> The nice thing about acinclude.m4/aclocal.m4 is that macros aren't actually performed/called/expanded/whatever here, just loaded. So @@ -216,7 +218,7 @@ </section> <section xml:id="build_hacking.enable"><info><title><constant>GLIBCXX_ENABLE</constant>, the <literal>--enable</literal> maker</title></info> - + <para> All the GLIBCXX_ENABLE_FOO macros use a common helper, diff --git a/libstdc++-v3/doc/xml/manual/debug_mode.xml b/libstdc++-v3/doc/xml/manual/debug_mode.xml index f0ab4992846..c58bde34065 100644 --- a/libstdc++-v3/doc/xml/manual/debug_mode.xml +++ b/libstdc++-v3/doc/xml/manual/debug_mode.xml @@ -627,7 +627,7 @@ namespace std </programlisting> <para>In debug mode we include the release-mode container (which is now -defined in the namespace <code>__norm</code>) and also the +defined in the namespace <code>__cxx1998</code>) and also the debug-mode container. The debug-mode container is defined within the namespace <code>__debug</code>, which is associated with namespace <code>std</code> via the C++0x namespace association language feature. This @@ -639,7 +639,7 @@ to C++ code as follows:</para> <programlisting> namespace std { - namespace __norm + namespace __cxx1998 { template<typename _Tp, typename _Alloc = allocator<_Tp> > class list @@ -652,12 +652,12 @@ namespace std { template<typename _Tp, typename _Alloc = allocator<_Tp> > class list - : public __norm::list<_Tp, _Alloc>, + : public __cxx1998::list<_Tp, _Alloc>, public __gnu_debug::_Safe_sequence<list<_Tp, _Alloc> > { // ... }; - } // namespace __norm + } // namespace __cxx1998 // namespace __debug __attribute__ ((strong)); inline namespace __debug { } diff --git a/libstdc++-v3/doc/xml/manual/documentation_hacking.xml b/libstdc++-v3/doc/xml/manual/documentation_hacking.xml new file mode 100644 index 00000000000..a2d1cddd814 --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/documentation_hacking.xml @@ -0,0 +1,990 @@ +<section xmlns="http://docbook.org/ns/docbook" version="5.0" + xml:id="appendix.porting.doc" xreflabel="Documentation Hacking"> +<?dbhtml filename="documentation_hacking.html"?> + +<info><title>Writing and Generating Documentation</title> + <keywordset> + <keyword>ISO C++</keyword> + <keyword>documentation</keyword> + <keyword>style</keyword> + <keyword>docbook</keyword> + <keyword>doxygen</keyword> + </keywordset> +</info> + + <section xml:id="doc.intro"> + <info> + <title>Introduction</title> + </info> + <para> + Documentation for the GNU C++ Library is created from three + independent sources: a manual, a FAQ, and an API reference. + </para> + <para> + The sub-directory <filename class="directory">doc</filename> + within the main source directory contains + <filename>Makefile.am</filename> and + <filename>Makefile.in</filename>, which provide rules for + generating documentation, described in excruciating detail + below. The <filename class="directory">doc</filename> + sub-directory also contains three directories: <filename + class="directory">doxygen</filename>, which contains scripts and + fragments for <command>doxygen</command>, <filename + class="directory">html</filename>, which contains an html + version of the manual, and <filename + class="directory">xml</filename>, which contains an xml version + of the manual. + </para> + <para> + Diverging from established documentation conventions in the rest + of the GCC project, libstdc++ does not use Texinfo as a markup + language. Instead, Docbook is used to create the manual and the + FAQ, and Doxygen is used to construct the API + reference. Although divergent, this conforms to the GNU Project + recommendations as long as the output is of sufficient quality, + as per + <link xmlns:xlink="http://www.w3.org/1999/xlink" + xlink:href="http://www.gnu.org/prep/standards/standards.html#Documentation"> + GNU Manuals</link>. + </para> + </section> + + <section xml:id="doc.generation"> + <info> + <title>Generating Documentation</title> + </info> + + <para> + Certain Makefile rules are required by the GNU Coding + Standards. These standard rules generate HTML, PDF, XML, or man + files. For each of the generative rules, there is an additional + install rule that is used to install any generated documentation + files into the prescribed installation directory. Files are + installed into <filename class="directory">share/doc</filename> + or <filename class="directory">share/man</filename> directories. + </para> + + <para> + The standard Makefile rules are conditionally supported, based + on the results of examining the host environment for + prerequisites at configuration time. If requirements are not + found, the rule is aliased to a dummy rule that does nothing, + and produces no documentation. If the requirements are found, + the rule forwards to a private rule that produces the requested + documentation. + </para> + + <para> + For more details on what prerequisites were found and where, + please consult the file <filename>config.log</filename> in the + libstdc++ build directory. Compare this log to what is expected + for the relevant Makefile conditionals: + <literal>BUILD_INFO</literal>, <literal>BUILD_XML</literal>, + <literal>BUILD_HTML</literal>, <literal>BUILD_MAN</literal>, + <literal>BUILD_PDF</literal>, and <literal>BUILD_EPUB</literal>. + </para> + + <para> + Supported Makefile rules: + </para> + + <variablelist> + <varlistentry> + <term> + <emphasis>make html</emphasis> + </term> + <term> + <emphasis>make install-html</emphasis> + </term> + <listitem> + <para> + Generates multi-page HTML documentation, and installs it + in the following directories: + </para> + <para> + <filename class="directory"> + doc/libstdc++/libstdc++-api.html + </filename> + </para> + <para> + <filename class="directory"> + doc/libstdc++/libstdc++-manual.html + </filename> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <emphasis>make pdf</emphasis> + </term> + <term> + <emphasis>make install-pdf</emphasis> + </term> + <listitem> + <para> + Generates indexed PDF documentation, and installs it as + the following files: + </para> + <para> + <filename>doc/libstdc++/libstdc++-api.pdf</filename> + </para> + <para> + <filename>doc/libstdc++/libstdc++-manual.pdf</filename> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <emphasis>make man</emphasis> + </term> + <term> + <emphasis>make install-man</emphasis> + </term> + <listitem> + <para> + Generates man pages, and installs it in the following directory: + </para> + <para> + <filename class="directory">man/man3/</filename> + </para> + <para> + The generated man pages are namespace-qualified, so to look at + the man page for <classname>vector</classname>, one would use + <command>man std::vector</command>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <emphasis>make epub</emphasis> + </term> + <term> + <emphasis>make install-epub</emphasis> + </term> + <listitem> + <para> + Generates documentation in the ebook/portable electronic + reader format called Epub, and installs it as the + following file. + </para> + <para> + <filename>doc/libstdc++/libstdc++-manual.epub</filename> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <emphasis>make xml</emphasis> + </term> + <term> + <emphasis>make install-xml</emphasis> + </term> + <listitem> + <para> + Generates single-file XML documentation, and installs it + as the following files: + </para> + <para> + <filename>doc/libstdc++/libstdc++-api-single.xml</filename> + </para> + <para> + <filename>doc/libstdc++/libstdc++-manual-single.xml</filename> + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + Makefile rules for several other formats are explicitly not + supported, and are always aliased to dummy rules. These + unsupported formats are: <emphasis>info</emphasis>, + <emphasis>ps</emphasis>, and <emphasis>dvi</emphasis>. + </para> + </section> + + <section xml:id="doc.doxygen"><info><title>Doxygen</title></info> + + <section xml:id="doxygen.prereq"><info><title>Prerequisites</title></info> + + <table frame="all"> +<title>Doxygen Prerequisites</title> + +<tgroup cols="3" align="center" colsep="1" rowsep="1"> +<colspec colname="c1"/> +<colspec colname="c2"/> +<colspec colname="c3"/> + + <thead> + <row> + <entry>Tool</entry> + <entry>Version</entry> + <entry>Required By</entry> + </row> + </thead> + + <tbody> + + <row> + <entry>coreutils</entry> + <entry>8.5</entry> + <entry>all</entry> + </row> + + <row> + <entry>bash</entry> + <entry>4.1</entry> + <entry>all</entry> + </row> + + <row> + <entry>doxygen</entry> + <entry>1.7.0</entry> + <entry>all</entry> + </row> + + <row> + <entry>graphviz</entry> + <entry>2.26</entry> + <entry>graphical hierarchies</entry> + </row> + + <row> + <entry>pdflatex</entry> + <entry>2007-59</entry> + <entry>pdf output</entry> + </row> + + </tbody> +</tgroup> +</table> + + + <para> + Prerequisite tools are Bash 2.0 or later, + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.doxygen.org/">Doxygen</link>, and + the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.gnu.org/software/coreutils/">GNU + coreutils</link>. (GNU versions of find, xargs, and possibly + sed and grep are used, just because the GNU versions make + things very easy.) + </para> + + <para> + To generate the pretty pictures and hierarchy + graphs, the + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.graphviz.org">Graphviz</link> package + will need to be installed. For PDF + output, <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.tug.org/applications/pdftex/"> + pdflatex</link> is required. + </para> + </section> + + <section xml:id="doxygen.rules"><info><title>Generating the Doxygen Files</title></info> + + <para> + The following Makefile rules run Doxygen to generate HTML + docs, XML docs, XML docs as a single file, PDF docs, and the + man pages. These rules are not conditional! If the required + tools are not found, or are the wrong versions, the rule may + end in an error. + </para> + + <para> + <screen><userinput>make doc-html-doxygen</userinput></screen> + </para> + + <para> + <screen><userinput>make doc-xml-doxygen</userinput></screen> + </para> + + <para> + <screen><userinput>make doc-xml-single-doxygen</userinput></screen> + </para> + + <para> + <screen><userinput>make doc-pdf-doxygen</userinput></screen> + </para> + + <para> + <screen><userinput>make doc-man-doxygen</userinput></screen> + </para> + + <para> + Generated files are output into separate sub directories of + <filename class="directory">doc/doxygen/</filename> in the + build directory, based on the output format. For instance, the + HTML docs will be in <filename class="directory">doc/doxygen/html</filename>. + </para> + + <para> + Careful observers will see that the Makefile rules simply call + a script from the source tree, <filename>run_doxygen</filename>, 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 <literal>--help</literal>.) + </para> + + <para> + If you wish to tweak the Doxygen settings, do so by editing + <filename>doc/doxygen/user.cfg.in</filename>. Notes to fellow + library hackers are written in triple-# comments. + </para> + + </section> + + <section xml:id="doxygen.markup"><info><title>Markup</title></info> + + + <para> + In general, libstdc++ files should be formatted according to + the rules found in the + <link linkend="contrib.coding_style">Coding Standard</link>. Before + any doxygen-specific formatting tweaks are made, please try to + make sure that the initial formatting is sound. + </para> + + <para> + Adding Doxygen markup to a file (informally called + <quote>doxygenating</quote>) is very simple. The Doxygen manual can be + found + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.stack.nl/~dimitri/doxygen/download.html#latestman">here</link>. + We try to use a very-recent version of Doxygen. + </para> + + <para> + For classes, use + <classname>deque</classname>/<classname>vector</classname>/<classname>list</classname> + and <classname>std::pair</classname> as examples. For + functions, see their member functions, and the free functions + in <filename>stl_algobase.h</filename>. Member functions of + other container-like types should read similarly to these + member functions. + </para> + + <para> + Some commentary to accompany + the first list in the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.stack.nl/~dimitri/doxygen/docblocks.html">Special + Documentation Blocks</link> section of + the Doxygen manual: + </para> + + <orderedlist inheritnum="ignore" continuation="restarts"> + <listitem> + <para>For longer comments, use the Javadoc style...</para> + </listitem> + + <listitem> + <para> + ...not the Qt style. The intermediate *'s are preferred. + </para> + </listitem> + + <listitem> + <para> + Use the triple-slash style only for one-line comments (the + <quote>brief</quote> mode). + </para> + </listitem> + + <listitem> + <para> + This is disgusting. Don't do this. + </para> + </listitem> + </orderedlist> + + <para> + Some specific guidelines: + </para> + + <para> + 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 <quote>interesting</quote> effects. + </para> + + <para> + Use either kind of grouping, as + appropriate. <filename>doxygroups.cc</filename> exists for this + purpose. See <filename>stl_iterator.h</filename> for a good example + of the <quote>other</quote> kind of grouping. + </para> + + <para> + 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.) + </para> + + <para> + Complicated math functions should use the multi-line + format. An example from <filename>random.h</filename>: + </para> + + <para> +<literallayout class="normal"> +/** + * @brief A model of a linear congruential random number generator. + * + * @f[ + * x_{i+1}\leftarrow(ax_{i} + c) \bmod m + * @f] + */ +</literallayout> + </para> + + <para> + One area of note is the markup required for + <literal>@file</literal> markup in header files. Two details + are important: for filenames that have the same name in + multiple directories, include part of the installed path to + disambiguate. For example: + </para> + + <para> +<literallayout class="normal"> +/** @file debug/vector + * This file is a GNU debug extension to the Standard C++ Library. + */ +</literallayout> + </para> + + <para> + The other relevant detail for header files is the use of a + libstdc++-specific doxygen alias that helps distinguish + between public header files (like <filename>random</filename>) + from implementation or private header files (like + <filename>bits/c++config.h</filename>.) This alias is spelled + <literal>@headername</literal> and can take one or two + arguments that detail the public header file or files that + should be included to use the contents of the file. All header + files that are not intended for direct inclusion must use + <literal>headername</literal> in the <literal>file</literal> + block. An example: + </para> + + <para> +<literallayout class="normal"> +/** @file bits/basic_string.h + * This is an internal header file, included by other library headers. + * Do not attempt to use it directly. @headername{string} + */ +</literallayout> + </para> + + <para> + Be careful about using certain, special characters when + writing Doxygen comments. Single and double quotes, and + separators in filenames are two common trouble spots. When in + doubt, consult the following table. + </para> + +<table frame="all"> +<title>HTML to Doxygen Markup Comparison</title> + +<tgroup cols="2" align="left" colsep="1" rowsep="1"> +<colspec colname="c1"/> +<colspec colname="c2"/> + + <thead> + <row> + <entry>HTML</entry> + <entry>Doxygen</entry> + </row> + </thead> + + <tbody> + <row> + <entry>\</entry> + <entry>\\</entry> + </row> + + <row> + <entry>"</entry> + <entry>\"</entry> + </row> + + <row> + <entry>'</entry> + <entry>\'</entry> + </row> + + <row> + <entry><i></entry> + <entry>@a word</entry> + </row> + + <row> + <entry><b></entry> + <entry>@b word</entry> + </row> + + <row> + <entry><code></entry> + <entry>@c word</entry> + </row> + + <row> + <entry><em></entry> + <entry>@a word</entry> + </row> + + <row> + <entry><em></entry> + <entry><em>two words or more</em></entry> + </row> + </tbody> + +</tgroup> +</table> + + + </section> + + </section> + + <section xml:id="doc.docbook"><info><title>Docbook</title></info> + + + <section xml:id="docbook.prereq"><info><title>Prerequisites</title></info> + + + <table frame="all"> +<title>Docbook Prerequisites</title> + +<tgroup cols="3" align="center" colsep="1" rowsep="1"> +<colspec colname="c1"/> +<colspec colname="c2"/> +<colspec colname="c3"/> + + <thead> + <row> + <entry>Tool</entry> + <entry>Version</entry> + <entry>Required By</entry> + </row> + </thead> + + <tbody> + + <row> + <entry>docbook5-style-xsl</entry> + <entry>1.76.1</entry> + <entry>all</entry> + </row> + + <row> + <entry>xsltproc</entry> + <entry>1.1.26</entry> + <entry>all</entry> + </row> + + <row> + <entry>xmllint</entry> + <entry>2.7.7</entry> + <entry>validation</entry> + </row> + + <row> + <entry>dblatex</entry> + <entry>0.3</entry> + <entry>pdf output</entry> + </row> + + <row> + <entry>pdflatex</entry> + <entry>2007-59</entry> + <entry>pdf output</entry> + </row> + + <row> + <entry>docbook2X</entry> + <entry>0.8.8</entry> + <entry>info output</entry> + </row> + + </tbody> +</tgroup> +</table> + + <para> + Editing the DocBook sources requires an XML editor. Many + exist: some notable options + include <command>emacs</command>, <application>Kate</application>, + or <application>Conglomerate</application>. + </para> + + <para> + Some editors support special <quote>XML Validation</quote> + modes that can validate the file as it is + produced. Recommended is the <command>nXML Mode</command> + for <command>emacs</command>. + </para> + + <para> + Besides an editor, additional DocBook files and XML tools are + also required. + </para> + + <para> + Access to the DocBook 5.0 stylesheets and schema is required. The + stylesheets are usually packaged by vendor, in something + like <filename>docbook5-style-xsl</filename>. To exactly match + generated output, please use a version of the stylesheets + equivalent + to <filename>docbook5-style-xsl-1.75.2-3</filename>. The + installation directory for this package corresponds to + the <literal>XSL_STYLE_DIR</literal> + in <filename>doc/Makefile.am</filename> and defaults + to <filename class="directory">/usr/share/sgml/docbook/xsl-ns-stylesheets</filename>. + </para> + + <para> + For processing XML, an XML processor and some style + sheets are necessary. Defaults are <command>xsltproc</command> + provided by <filename>libxslt</filename>. + </para> + + <para> + For validating the XML document, you'll need + something like <command>xmllint</command> and access to the + relevant DocBook schema. These are provided + by a vendor package like <filename>libxml2</filename> and <filename>docbook5-schemas-5.0-4</filename> + </para> + + <para> + For PDF output, something that transforms valid Docbook XML to PDF is + required. Possible solutions include <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://dblatex.sourceforge.net">dblatex</link>, + <command>xmlto</command>, or <command>prince</command>. Of + these, <command>dblatex</command> is the default. Other + options are listed on the DocBook web <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://wiki.docbook.org/topic/DocBookPublishingTools">pages</link>. Please + consult the <email>libstdc++@gcc.gnu.org</email> list when + preparing printed manuals for current best practice and + suggestions. + </para> + + <para> + For Texinfo output, something that transforms valid Docbook + XML to Texinfo is required. The default choice is <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://docbook2x.sourceforge.net/">docbook2X</link>. + </para> + </section> + + <section xml:id="docbook.rules"><info><title>Generating the DocBook Files</title></info> + + + <para> + The following Makefile rules generate (in order): an HTML + version of all the DocBook documentation, a PDF version of the + same, and a single XML document. These rules are not + conditional! If the required tools are not found, or are the + wrong versions, the rule may end in an error. + </para> + + <para> + <screen><userinput>make doc-html-docbook</userinput></screen> + </para> + + <para> + <screen><userinput>make doc-pdf-docbook</userinput></screen> + </para> + + <para> + <screen><userinput>make doc-xml-single-docbook</userinput></screen> + </para> + + <para> + Generated files are output into separate sub directores of + <filename class="directory">doc/docbook/</filename> in the + build directory, based on the output format. For instance, the + HTML docs will be in <filename + class="directory">doc/docbook/html</filename>. + </para> + + <para> + If the Docbook stylesheets are installed in a custom location, + one can use the variable <literal>XSL_STYLE_DIR</literal> to + over-ride the Makefile defaults. As so: + </para> + + <screen> + <userinput> +make <literal>XSL_STYLE_DIR="/usr/share/xml/docbook/stylesheet/nwalsh"</literal> doc-html-docbook + </userinput> + </screen> + + </section> + + <section xml:id="docbook.validation"><info><title>Editing and Validation</title></info> + + <para> + 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: + </para> + + <screen> + <userinput>make doc-xml-validate-docbook</userinput> + </screen> + + <para> + This is equivalent to doing: + </para> + + <screen> + <userinput> + xmllint --noout --valid <filename>xml/index.xml</filename> + </userinput> + </screen> + + <para> + Please note that individual sections and chapters of the + manual can be validated by substiuting the file desired for + <filename>xml/index.xml</filename> in the command + above. Reducing scope in this manner can be helpful when + validation on the entire manual fails. + </para> + + <para> + All Docbook xml sources should always validate. No excuses! + </para> + + </section> + + <section xml:id="docbook.examples"><info><title>File Organization and Basics</title></info> + + + <literallayout class="normal"> + <emphasis>Which files are important</emphasis> + + All Docbook files are in the directory + libstdc++-v3/doc/xml + + Inside this directory, the files of importance: + spine.xml - index to documentation set + manual/spine.xml - index to manual + manual/*.xml - individual chapters and sections of the manual + faq.xml - index to FAQ + api.xml - index to source level / API + + All *.txml files are template xml files, i.e., otherwise empty files with + the correct structure, suitable for filling in with new information. + + <emphasis>Canonical Writing Style</emphasis> + + class template + function template + member function template + (via C++ Templates, Vandevoorde) + + class in namespace std: allocator, not std::allocator + + header file: iostream, not <iostream> + + + <emphasis>General structure</emphasis> + + <set> + <book> + </book> + + <book> + <chapter> + </chapter> + </book> + + <book> + <part> + <chapter> + <section> + </section> + + <sect1> + </sect1> + + <sect1> + <sect2> + </sect2> + </sect1> + </chapter> + + <chapter> + </chapter> + </part> + </book> + + </set> + </literallayout> + </section> + + <section xml:id="docbook.markup"><info><title>Markup By Example</title></info> + + + <para> + Complete details on Docbook markup can be found in the DocBook + Element Reference, + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.docbook.org/tdg/en/html/part2.html">online</link>. + An incomplete reference for HTML to Docbook conversion is + detailed in the table below. + </para> + +<table frame="all"> +<title>HTML to Docbook XML Markup Comparison</title> + +<tgroup cols="2" align="left" colsep="1" rowsep="1"> +<colspec colname="c1"/> +<colspec colname="c2"/> + + <thead> + <row> + <entry>HTML</entry> + <entry>Docbook</entry> + </row> + </thead> + + <tbody> + <row> + <entry><p></entry> + <entry><para></entry> + </row> + <row> + <entry><pre></entry> + <entry><computeroutput>, <programlisting>, + <literallayout></entry> + </row> + <row> + <entry><ul></entry> + <entry><itemizedlist></entry> + </row> + <row> + <entry><ol></entry> + <entry><orderedlist></entry> + </row> + <row> + <entry><il></entry> + <entry><listitem></entry> + </row> + <row> + <entry><dl></entry> + <entry><variablelist></entry> + </row> + <row> + <entry><dt></entry> + <entry><term></entry> + </row> + <row> + <entry><dd></entry> + <entry><listitem></entry> + </row> + + <row> + <entry><a href=""></entry> + <entry><ulink url=""></entry> + </row> + <row> + <entry><code></entry> + <entry><literal>, <programlisting></entry> + </row> + <row> + <entry><strong></entry> + <entry><emphasis></entry> + </row> + <row> + <entry><em></entry> + <entry><emphasis></entry> + </row> + <row> + <entry>"</entry> + <entry><quote></entry> + </row> + </tbody> +</tgroup> +</table> + +<para> + And examples of detailed markup for which there are no real HTML + equivalents are listed in the table below. +</para> + +<table frame="all"> +<title>Docbook XML Element Use</title> + +<tgroup cols="2" align="left" colsep="1" rowsep="1"> +<colspec colname="c1"/> +<colspec colname="c2"/> + + <thead> + <row> + <entry>Element</entry> + <entry>Use</entry> + </row> + </thead> + + <tbody> + <row> + <entry><structname></entry> + <entry><structname>char_traits</structname></entry> + </row> + <row> + <entry><classname></entry> + <entry><classname>string</classname></entry> + </row> + <row> + <entry><function></entry> + <entry> + <para><function>clear()</function></para> + <para><function>fs.clear()</function></para> + </entry> + </row> + <row> + <entry><type></entry> + <entry><type>long long</type></entry> + </row> + <row> + <entry><varname></entry> + <entry><varname>fs</varname></entry> + </row> + <row> + <entry><literal></entry> + <entry> + <para><literal>-Weffc++</literal></para> + <para><literal>rel_ops</literal></para> + </entry> + </row> + <row> + <entry><constant></entry> + <entry> + <para><constant>_GNU_SOURCE</constant></para> + <para><constant>3.0</constant></para> + </entry> + </row> + <row> + <entry><command></entry> + <entry><command>g++</command></entry> + </row> + <row> + <entry><errortext></entry> + <entry><errortext>In instantiation of</errortext></entry> + </row> + <row> + <entry><filename></entry> + <entry> + <para><filename class="headerfile">ctype.h</filename></para> + <para><filename class="directory">/home/gcc/build</filename></para> + <para><filename class="libraryfile">libstdc++.so</filename></para> + </entry> + </row> + </tbody> +</tgroup> +</table> + +</section> +</section> +</section>
\ No newline at end of file diff --git a/libstdc++-v3/doc/xml/manual/prerequisites.xml b/libstdc++-v3/doc/xml/manual/prerequisites.xml index 6fd813548f1..0a41c44ea75 100644 --- a/libstdc++-v3/doc/xml/manual/prerequisites.xml +++ b/libstdc++-v3/doc/xml/manual/prerequisites.xml @@ -43,8 +43,8 @@ <para> To generate the API documentation from the sources you will need - Doxygen, see <link linkend="contrib.doc_style">Documentation - Style</link> in the appendix for full details. + Doxygen, see <link linkend="appendix.porting.doc">Documentation + Hacking</link> in the appendix for full details. </para> <para> |