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 + + * 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 * 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 new file mode 100644 index 00000000000..dab5ef341eb Binary files /dev/null and b/libstdc++-v3/doc/xml/images/confdeps.pdf differ 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. -
Documentation Style - - -
Doxygen - -
Prerequisites - - - Prerequisite tools are Bash 2.0 or later, - Doxygen, and - the GNU - coreutils. (GNU versions of find, xargs, and possibly - sed and grep are used, just because the GNU versions make - things very easy.) - - - - To generate the pretty pictures and hierarchy - graphs, the - Graphviz package - will need to be installed. For PDF - output, - pdflatex is required. - -
- -
Generating the Doxygen Files - - - The following Makefile rules run Doxygen to generate HTML - docs, XML docs, XML docs as a single file, PDF docs, and the man pages. - - - - make doc-html-doxygen - - - - make doc-xml-doxygen - - - - make doc-xml-single-doxygen - - - - make doc-pdf-doxygen - - - - make doc-man-doxygen - - - - Generated files are output into separate sub directores of - doc/doxygen/ in the - build directory, based on the output format. For instance, the - HTML docs will be in doc/doxygen/html. - - - - Careful observers will see that the Makefile rules simply call - a script from the source tree, run_doxygen, 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 --help.) - - - - If you wish to tweak the Doxygen settings, do so by editing - doc/doxygen/user.cfg.in. Notes to fellow - library hackers are written in triple-# comments. - - -
- -
Markup - - - - In general, libstdc++ files should be formatted according to - the rules found in the - Coding Standard. Before - any doxygen-specific formatting tweaks are made, please try to - make sure that the initial formatting is sound. - - - - Adding Doxygen markup to a file (informally called - doxygenating) is very simple. The Doxygen manual can be - found - here. - We try to use a very-recent version of Doxygen. - - - - For classes, use - deque/vector/list - and std::pair as examples. For - functions, see their member functions, and the free functions - in stl_algobase.h. Member functions of - other container-like types should read similarly to these - member functions. - - - - Some commentary to accompany - the first list in the Special - Documentation Blocks section of - the Doxygen manual: - - - - - For longer comments, use the Javadoc style... - - - - - ...not the Qt style. The intermediate *'s are preferred. - - - - - - Use the triple-slash style only for one-line comments (the - brief mode). - - - - - - This is disgusting. Don't do this. - - - - - - Some specific guidelines: - - - - 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 interesting effects. - - - - Use either kind of grouping, as - appropriate. doxygroups.cc exists for this - purpose. See stl_iterator.h for a good example - of the other kind of grouping. - - - - 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.) - - - - Complicated math functions should use the multi-line - format. An example from random.h: - - - - - /** - * @brief A model of a linear congruential random number generator. - * - * @f[ - * x_{i+1}\leftarrow(ax_{i} + c) \bmod m - * @f] - */ - - - - - 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. - - - -HTML to Doxygen Markup Comparison - - - - - - - - HTML - Doxygen - - - - - - \ - \\ - - - - " - \" - - - - ' - \' - - - - <i> - @a word - - - - <b> - @b word - - - - <code> - @c word - - - - <em> - @a word - - - - <em> - <em>two words or more</em> - - - - -
- - -
- -
- -
Docbook - - -
Prerequisites - - - Editing the DocBook sources requires an XML editor. Many - exist: some notable options - include emacs, Kate, - or Conglomerate. - - - - Some editors support special XML Validation - modes that can validate the file as it is - produced. Recommended is the nXML Mode - for emacs. - - - - Besides an editor, additional DocBook files and XML tools are - also required. - - - - Access to the DocBook 5.0 stylesheets and schema is required. The - stylesheets are usually packaged by vendor, in something - like docbook5-style-xsl. To exactly match - generated output, please use a version of the stylesheets - equivalent - to docbook5-style-xsl-1.75.2-3. The - installation directory for this package corresponds to - the XSL_STYLE_DIR - in doc/Makefile.am and defaults - to /usr/share/sgml/docbook/xsl-ns-stylesheets. - - - - For processing XML, an XML processor and some style - sheets are necessary. Defaults are xsltproc - provided by libxslt. - - - - For validating the XML document, you'll need - something like xmllint and access to the - relevant DocBook schema. These are provided - by a vendor package like libxml2 and docbook5-schemas-5.0-4 - - - - For PDF output, something that transforms valid Docbook XML to PDF is - required. Possible solutions include dblatex, - xmlto, or prince. Of - these, dblatex is the default. Other - options are listed on the DocBook web pages. Please - consult the libstdc++@gcc.gnu.org list when - preparing printed manuals for current best practice and - suggestions. - - - - For Texinfo output, something that transforms valid Docbook - XML to Texinfo is required. The default choice is docbook2X. - - - - 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: - - - - -xmllint --noout --valid xml/index.xml - - -
- -
Generating the DocBook Files - - - - 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. - - - - make doc-html-docbook - - - - make doc-pdf-docbook - - - - make doc-xml-single-docbook - - - - make doc-xml-validate-docbook - - - - Generated files are output into separate sub directores of - doc/docbook/ in the - build directory, based on the output format. For instance, the - HTML docs will be in doc/docbook/html. - -
- -
File Organization and Basics - - - - Which files are important - - 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. - - Canonical Writing Style - - class template - function template - member function template - (via C++ Templates, Vandevoorde) - - class in namespace std: allocator, not std::allocator - - header file: iostream, not <iostream> - - - General structure - - <set> - <book> - </book> - - <book> - <chapter> - </chapter> - </book> - - <book> - <part> - <chapter> - <section> - </section> - - <sect1> - </sect1> - - <sect1> - <sect2> - </sect2> - </sect1> - </chapter> - - <chapter> - </chapter> - </part> - </book> - - </set> - -
- -
Markup By Example - - - - Complete details on Docbook markup can be found in the DocBook - Element Reference, - online. - An incomplete reference for HTML to Docbook conversion is - detailed in the table below. - - - -HTML to Docbook XML Markup Comparison - - - - - - - - HTML - Docbook - - - - - - <p> - <para> - - - <pre> - <computeroutput>, <programlisting>, - <literallayout> - - - <ul> - <itemizedlist> - - - <ol> - <orderedlist> - - - <il> - <listitem> - - - <dl> - <variablelist> - - - <dt> - <term> - - - <dd> - <listitem> - - - - <a href=""> - <ulink url=""> - - - <code> - <literal>, <programlisting> - - - <strong> - <emphasis> - - - <em> - <emphasis> - - - " - <quote> - - - -
- - - And examples of detailed markup for which there are no real HTML - equivalents are listed in the table below. - - - -Docbook XML Element Use - - - - - - - - Element - Use - - - - - - <structname> - <structname>char_traits</structname> - - - <classname> - <classname>string</classname> - - - <function> - - <function>clear()</function> - <function>fs.clear()</function> - - - - <type> - <type>long long</type> - - - <varname> - <varname>fs</varname> - - - <literal> - - <literal>-Weffc++</literal> - <literal>rel_ops</literal> - - - - <constant> - - <constant>_GNU_SOURCE</constant> - <constant>3.0</constant> - - - - <command> - <command>g++</command> - - - <errortext> - <errortext>In instantiation of</errortext> - - - <filename> - - <filename class="headerfile">ctype.h</filename> - <filename class="directory">/home/gcc/build</filename> - <filename class="libraryfile">libstdc++.so</filename> - - - - -
- -
-
- -
Combines - - -
Generating Combines and Assemblages - - - - 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. - - - - - - make doc-html - - - - Generates multi-page HTML documentation in the following directories: - - - doc/libstdc++-api.html - - - doc/libstdc++-manual.html - - - - - - make doc-man - - - - Generates man pages in the following directory: - - - doc/libstdc++-api.man - - - - - - make doc-pdf - - - - Generates indexed PDF documentation in the following files: - - - doc/libstdc++-api.pdf - - - doc/libstdc++-manual.pdf - - - - - - make doc-texinfo - - - - Generates Texinfo documentation in the following files: - - - doc/libstdc++-manual.texinfo - - - - - - make doc-xml - - - - Generates single-file XML documentation in the following files: - - - doc/libstdc++-api.xml - - - doc/libstdc++-manual.xml - - - - - - - -
-
-
-
Design Notes 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 @@ - - + + + + 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 @@ -
@@ -22,10 +22,8 @@ - -
Prerequisites - + As noted previously, certain other tools are necessary for hacking on files that @@ -41,18 +39,22 @@
Overview: What Comes from Where - - - + +
+ Configure and Build File Dependencies + - + + + + - Dependency Graph Configure to Build Files + Dependency Graph for Configure and Build Files - - + +
Regenerate all generated files by using the command sequence @@ -68,7 +70,7 @@
Storing Information in non-AC files (like configure.host) - + Until that glorious day when we can use AC_TRY_LINK with a @@ -100,7 +102,7 @@
Coding and Commenting Conventions - + Most comments should use {octothorpes, shibboleths, hash marks, @@ -125,7 +127,7 @@
The acinclude.m4 layout - + 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 @@
<constant>GLIBCXX_ENABLE</constant>, the <literal>--enable</literal> maker - + 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 In debug mode we include the release-mode container (which is now -defined in the namespace __norm) and also the +defined in the namespace __cxx1998) and also the debug-mode container. The debug-mode container is defined within the namespace __debug, which is associated with namespace std via the C++0x namespace association language feature. This @@ -639,7 +639,7 @@ to C++ code as follows: 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 @@ +
+ + +Writing and Generating Documentation + + ISO C++ + documentation + style + docbook + doxygen + + + +
+ + Introduction + + + Documentation for the GNU C++ Library is created from three + independent sources: a manual, a FAQ, and an API reference. + + + The sub-directory doc + within the main source directory contains + Makefile.am and + Makefile.in, which provide rules for + generating documentation, described in excruciating detail + below. The doc + sub-directory also contains three directories: doxygen, which contains scripts and + fragments for doxygen, html, which contains an html + version of the manual, and xml, which contains an xml version + of the manual. + + + 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 + + GNU Manuals. + +
+ +
+ + Generating Documentation + + + + 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 share/doc + or share/man directories. + + + + 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. + + + + For more details on what prerequisites were found and where, + please consult the file config.log in the + libstdc++ build directory. Compare this log to what is expected + for the relevant Makefile conditionals: + BUILD_INFO, BUILD_XML, + BUILD_HTML, BUILD_MAN, + BUILD_PDF, and BUILD_EPUB. + + + + Supported Makefile rules: + + + + + + make html + + + make install-html + + + + Generates multi-page HTML documentation, and installs it + in the following directories: + + + + doc/libstdc++/libstdc++-api.html + + + + + doc/libstdc++/libstdc++-manual.html + + + + + + + + make pdf + + + make install-pdf + + + + Generates indexed PDF documentation, and installs it as + the following files: + + + doc/libstdc++/libstdc++-api.pdf + + + doc/libstdc++/libstdc++-manual.pdf + + + + + + + make man + + + make install-man + + + + Generates man pages, and installs it in the following directory: + + + man/man3/ + + + The generated man pages are namespace-qualified, so to look at + the man page for vector, one would use + man std::vector. + + + + + + + make epub + + + make install-epub + + + + Generates documentation in the ebook/portable electronic + reader format called Epub, and installs it as the + following file. + + + doc/libstdc++/libstdc++-manual.epub + + + + + + + make xml + + + make install-xml + + + + Generates single-file XML documentation, and installs it + as the following files: + + + doc/libstdc++/libstdc++-api-single.xml + + + doc/libstdc++/libstdc++-manual-single.xml + + + + + + + Makefile rules for several other formats are explicitly not + supported, and are always aliased to dummy rules. These + unsupported formats are: info, + ps, and dvi. + +
+ +
Doxygen + +
Prerequisites + + +Doxygen Prerequisites + + + + + + + + + Tool + Version + Required By + + + + + + + coreutils + 8.5 + all + + + + bash + 4.1 + all + + + + doxygen + 1.7.0 + all + + + + graphviz + 2.26 + graphical hierarchies + + + + pdflatex + 2007-59 + pdf output + + + + +
+ + + + Prerequisite tools are Bash 2.0 or later, + Doxygen, and + the GNU + coreutils. (GNU versions of find, xargs, and possibly + sed and grep are used, just because the GNU versions make + things very easy.) + + + + To generate the pretty pictures and hierarchy + graphs, the + Graphviz package + will need to be installed. For PDF + output, + pdflatex is required. + +
+ +
Generating the Doxygen Files + + + 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. + + + + make doc-html-doxygen + + + + make doc-xml-doxygen + + + + make doc-xml-single-doxygen + + + + make doc-pdf-doxygen + + + + make doc-man-doxygen + + + + Generated files are output into separate sub directories of + doc/doxygen/ in the + build directory, based on the output format. For instance, the + HTML docs will be in doc/doxygen/html. + + + + Careful observers will see that the Makefile rules simply call + a script from the source tree, run_doxygen, 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 --help.) + + + + If you wish to tweak the Doxygen settings, do so by editing + doc/doxygen/user.cfg.in. Notes to fellow + library hackers are written in triple-# comments. + + +
+ +
Markup + + + + In general, libstdc++ files should be formatted according to + the rules found in the + Coding Standard. Before + any doxygen-specific formatting tweaks are made, please try to + make sure that the initial formatting is sound. + + + + Adding Doxygen markup to a file (informally called + doxygenating) is very simple. The Doxygen manual can be + found + here. + We try to use a very-recent version of Doxygen. + + + + For classes, use + deque/vector/list + and std::pair as examples. For + functions, see their member functions, and the free functions + in stl_algobase.h. Member functions of + other container-like types should read similarly to these + member functions. + + + + Some commentary to accompany + the first list in the Special + Documentation Blocks section of + the Doxygen manual: + + + + + For longer comments, use the Javadoc style... + + + + + ...not the Qt style. The intermediate *'s are preferred. + + + + + + Use the triple-slash style only for one-line comments (the + brief mode). + + + + + + This is disgusting. Don't do this. + + + + + + Some specific guidelines: + + + + 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 interesting effects. + + + + Use either kind of grouping, as + appropriate. doxygroups.cc exists for this + purpose. See stl_iterator.h for a good example + of the other kind of grouping. + + + + 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.) + + + + Complicated math functions should use the multi-line + format. An example from random.h: + + + + +/** + * @brief A model of a linear congruential random number generator. + * + * @f[ + * x_{i+1}\leftarrow(ax_{i} + c) \bmod m + * @f] + */ + + + + + One area of note is the markup required for + @file 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: + + + + +/** @file debug/vector + * This file is a GNU debug extension to the Standard C++ Library. + */ + + + + + The other relevant detail for header files is the use of a + libstdc++-specific doxygen alias that helps distinguish + between public header files (like random) + from implementation or private header files (like + bits/c++config.h.) This alias is spelled + @headername 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 + headername in the file + block. An example: + + + + +/** @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} + */ + + + + + 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. + + + +HTML to Doxygen Markup Comparison + + + + + + + + HTML + Doxygen + + + + + + \ + \\ + + + + " + \" + + + + ' + \' + + + + <i> + @a word + + + + <b> + @b word + + + + <code> + @c word + + + + <em> + @a word + + + + <em> + <em>two words or more</em> + + + + +
+ + +
+ +
+ +
Docbook + + +
Prerequisites + + + +Docbook Prerequisites + + + + + + + + + Tool + Version + Required By + + + + + + + docbook5-style-xsl + 1.76.1 + all + + + + xsltproc + 1.1.26 + all + + + + xmllint + 2.7.7 + validation + + + + dblatex + 0.3 + pdf output + + + + pdflatex + 2007-59 + pdf output + + + + docbook2X + 0.8.8 + info output + + + + +
+ + + Editing the DocBook sources requires an XML editor. Many + exist: some notable options + include emacs, Kate, + or Conglomerate. + + + + Some editors support special XML Validation + modes that can validate the file as it is + produced. Recommended is the nXML Mode + for emacs. + + + + Besides an editor, additional DocBook files and XML tools are + also required. + + + + Access to the DocBook 5.0 stylesheets and schema is required. The + stylesheets are usually packaged by vendor, in something + like docbook5-style-xsl. To exactly match + generated output, please use a version of the stylesheets + equivalent + to docbook5-style-xsl-1.75.2-3. The + installation directory for this package corresponds to + the XSL_STYLE_DIR + in doc/Makefile.am and defaults + to /usr/share/sgml/docbook/xsl-ns-stylesheets. + + + + For processing XML, an XML processor and some style + sheets are necessary. Defaults are xsltproc + provided by libxslt. + + + + For validating the XML document, you'll need + something like xmllint and access to the + relevant DocBook schema. These are provided + by a vendor package like libxml2 and docbook5-schemas-5.0-4 + + + + For PDF output, something that transforms valid Docbook XML to PDF is + required. Possible solutions include dblatex, + xmlto, or prince. Of + these, dblatex is the default. Other + options are listed on the DocBook web pages. Please + consult the libstdc++@gcc.gnu.org list when + preparing printed manuals for current best practice and + suggestions. + + + + For Texinfo output, something that transforms valid Docbook + XML to Texinfo is required. The default choice is docbook2X. + +
+ +
Generating the DocBook Files + + + + 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. + + + + make doc-html-docbook + + + + make doc-pdf-docbook + + + + make doc-xml-single-docbook + + + + Generated files are output into separate sub directores of + doc/docbook/ in the + build directory, based on the output format. For instance, the + HTML docs will be in doc/docbook/html. + + + + If the Docbook stylesheets are installed in a custom location, + one can use the variable XSL_STYLE_DIR to + over-ride the Makefile defaults. As so: + + + + +make XSL_STYLE_DIR="/usr/share/xml/docbook/stylesheet/nwalsh" doc-html-docbook + + + +
+ +
Editing and Validation + + + 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: + + + + make doc-xml-validate-docbook + + + + This is equivalent to doing: + + + + + xmllint --noout --valid xml/index.xml + + + + + Please note that individual sections and chapters of the + manual can be validated by substiuting the file desired for + xml/index.xml in the command + above. Reducing scope in this manner can be helpful when + validation on the entire manual fails. + + + + All Docbook xml sources should always validate. No excuses! + + +
+ +
File Organization and Basics + + + + Which files are important + + 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. + + Canonical Writing Style + + class template + function template + member function template + (via C++ Templates, Vandevoorde) + + class in namespace std: allocator, not std::allocator + + header file: iostream, not <iostream> + + + General structure + + <set> + <book> + </book> + + <book> + <chapter> + </chapter> + </book> + + <book> + <part> + <chapter> + <section> + </section> + + <sect1> + </sect1> + + <sect1> + <sect2> + </sect2> + </sect1> + </chapter> + + <chapter> + </chapter> + </part> + </book> + + </set> + +
+ +
Markup By Example + + + + Complete details on Docbook markup can be found in the DocBook + Element Reference, + online. + An incomplete reference for HTML to Docbook conversion is + detailed in the table below. + + + +HTML to Docbook XML Markup Comparison + + + + + + + + HTML + Docbook + + + + + + <p> + <para> + + + <pre> + <computeroutput>, <programlisting>, + <literallayout> + + + <ul> + <itemizedlist> + + + <ol> + <orderedlist> + + + <il> + <listitem> + + + <dl> + <variablelist> + + + <dt> + <term> + + + <dd> + <listitem> + + + + <a href=""> + <ulink url=""> + + + <code> + <literal>, <programlisting> + + + <strong> + <emphasis> + + + <em> + <emphasis> + + + " + <quote> + + + +
+ + + And examples of detailed markup for which there are no real HTML + equivalents are listed in the table below. + + + +Docbook XML Element Use + + + + + + + + Element + Use + + + + + + <structname> + <structname>char_traits</structname> + + + <classname> + <classname>string</classname> + + + <function> + + <function>clear()</function> + <function>fs.clear()</function> + + + + <type> + <type>long long</type> + + + <varname> + <varname>fs</varname> + + + <literal> + + <literal>-Weffc++</literal> + <literal>rel_ops</literal> + + + + <constant> + + <constant>_GNU_SOURCE</constant> + <constant>3.0</constant> + + + + <command> + <command>g++</command> + + + <errortext> + <errortext>In instantiation of</errortext> + + + <filename> + + <filename class="headerfile">ctype.h</filename> + <filename class="directory">/home/gcc/build</filename> + <filename class="libraryfile">libstdc++.so</filename> + + + + +
+ +
+
+
\ 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 @@ To generate the API documentation from the sources you will need - Doxygen, see Documentation - Style in the appendix for full details. + Doxygen, see Documentation + Hacking in the appendix for full details.