From 554fd8c5195424bdbcabf5de30fdc183aba391bd Mon Sep 17 00:00:00 2001 From: upstream source tree Date: Sun, 15 Mar 2015 20:14:05 -0400 Subject: obtained gcc-4.6.4.tar.bz2 from upstream website; verified gcc-4.6.4.tar.bz2.sig; imported gcc-4.6.4 source tree from verified upstream tarball. downloading a git-generated archive based on the 'upstream' tag should provide you with a source tree that is binary identical to the one extracted from the above tarball. if you have obtained the source via the command 'git clone', however, do note that line-endings of files in your working directory might differ from line-endings of the respective files in the upstream repository. --- .../doc/xml/manual/documentation_hacking.xml | 990 +++++++++++++++++++++ 1 file changed, 990 insertions(+) create mode 100644 libstdc++-v3/doc/xml/manual/documentation_hacking.xml (limited to 'libstdc++-v3/doc/xml/manual/documentation_hacking.xml') 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 000000000..7b2ed7c09 --- /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 substituting 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> + + + + +
+ +
+
+
-- cgit v1.2.3