148fb7bfaSmrg<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2d79abf08Smrg<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Writing and Generating Documentation</title><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><meta name="keywords" content="ISO C++, documentation, style, docbook, doxygen" /><meta name="keywords" content="ISO C++, library" /><meta name="keywords" content="ISO C++, runtime, library" /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="appendix_porting.html" title="Appendix B. Porting and Maintenance" /><link rel="prev" href="appendix_porting.html" title="Appendix B. Porting and Maintenance" /><link rel="next" href="internals.html" title="Porting to New Hardware or Operating Systems" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Writing and Generating Documentation</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="appendix_porting.html">Prev</a> </td><th width="60%" align="center">Appendix B. 348fb7bfaSmrg Porting and Maintenance 448fb7bfaSmrg 548fb7bfaSmrg</th><td width="20%" align="right"> <a accesskey="n" href="internals.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="appendix.porting.doc"></a>Writing and Generating Documentation</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="doc.intro"></a>Introduction</h3></div></div></div><p> 648fb7bfaSmrg Documentation for the GNU C++ Library is created from three 748fb7bfaSmrg independent sources: a manual, a FAQ, and an API reference. 848fb7bfaSmrg </p><p> 948fb7bfaSmrg The sub-directory <code class="filename">doc</code> 1048fb7bfaSmrg within the main source directory contains 1148fb7bfaSmrg <code class="filename">Makefile.am</code> and 1248fb7bfaSmrg <code class="filename">Makefile.in</code>, which provide rules for 1348fb7bfaSmrg generating documentation, described in excruciating detail 1448fb7bfaSmrg below. The <code class="filename">doc</code> 1548fb7bfaSmrg sub-directory also contains three directories: <code class="filename">doxygen</code>, which contains scripts and 1648fb7bfaSmrg fragments for <span class="command"><strong>doxygen</strong></span>, <code class="filename">html</code>, which contains an html 1748fb7bfaSmrg version of the manual, and <code class="filename">xml</code>, which contains an xml version 1848fb7bfaSmrg of the manual. 1948fb7bfaSmrg </p><p> 2048fb7bfaSmrg Diverging from established documentation conventions in the rest 2148fb7bfaSmrg of the GCC project, libstdc++ does not use Texinfo as a markup 2248fb7bfaSmrg language. Instead, Docbook is used to create the manual and the 2348fb7bfaSmrg FAQ, and Doxygen is used to construct the API 2448fb7bfaSmrg reference. Although divergent, this conforms to the GNU Project 2548fb7bfaSmrg recommendations as long as the output is of sufficient quality, 2648fb7bfaSmrg as per 2748fb7bfaSmrg <a class="link" href="http://www.gnu.org/prep/standards/standards.html#Documentation" target="_top"> 2848fb7bfaSmrg GNU Manuals</a>. 2948fb7bfaSmrg </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="doc.generation"></a>Generating Documentation</h3></div></div></div><p> 3048fb7bfaSmrg Certain Makefile rules are required by the GNU Coding 3148fb7bfaSmrg Standards. These standard rules generate HTML, PDF, XML, or man 3248fb7bfaSmrg files. For each of the generative rules, there is an additional 3348fb7bfaSmrg install rule that is used to install any generated documentation 3448fb7bfaSmrg files into the prescribed installation directory. Files are 3548fb7bfaSmrg installed into <code class="filename">share/doc</code> 3648fb7bfaSmrg or <code class="filename">share/man</code> directories. 3748fb7bfaSmrg </p><p> 3848fb7bfaSmrg The standard Makefile rules are conditionally supported, based 3948fb7bfaSmrg on the results of examining the host environment for 4048fb7bfaSmrg prerequisites at configuration time. If requirements are not 4148fb7bfaSmrg found, the rule is aliased to a dummy rule that does nothing, 4248fb7bfaSmrg and produces no documentation. If the requirements are found, 4348fb7bfaSmrg the rule forwards to a private rule that produces the requested 4448fb7bfaSmrg documentation. 4548fb7bfaSmrg </p><p> 4648fb7bfaSmrg For more details on what prerequisites were found and where, 4748fb7bfaSmrg please consult the file <code class="filename">config.log</code> in the 4848fb7bfaSmrg libstdc++ build directory. Compare this log to what is expected 4948fb7bfaSmrg for the relevant Makefile conditionals: 5048fb7bfaSmrg <code class="literal">BUILD_INFO</code>, <code class="literal">BUILD_XML</code>, 5148fb7bfaSmrg <code class="literal">BUILD_HTML</code>, <code class="literal">BUILD_MAN</code>, 5248fb7bfaSmrg <code class="literal">BUILD_PDF</code>, and <code class="literal">BUILD_EPUB</code>. 5348fb7bfaSmrg </p><p> 5448fb7bfaSmrg Supported Makefile rules: 5548fb7bfaSmrg </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"> 5648fb7bfaSmrg <span class="emphasis"><em>make html</em></span> 5748fb7bfaSmrg , </span><span class="term"> 5848fb7bfaSmrg <span class="emphasis"><em>make install-html</em></span> 5948fb7bfaSmrg </span></dt><dd><p> 6048fb7bfaSmrg Generates multi-page HTML documentation, and installs it 6148fb7bfaSmrg in the following directories: 6248fb7bfaSmrg </p><p> 6348fb7bfaSmrg <code class="filename">doc/libstdc++/libstdc++-api.html</code> 6448fb7bfaSmrg </p><p> 6548fb7bfaSmrg <code class="filename">doc/libstdc++/libstdc++-manual.html</code> 6648fb7bfaSmrg </p></dd><dt><span class="term"> 6748fb7bfaSmrg <span class="emphasis"><em>make pdf</em></span> 6848fb7bfaSmrg , </span><span class="term"> 6948fb7bfaSmrg <span class="emphasis"><em>make install-pdf</em></span> 7048fb7bfaSmrg </span></dt><dd><p> 7148fb7bfaSmrg Generates indexed PDF documentation, and installs it as 7248fb7bfaSmrg the following files: 7348fb7bfaSmrg </p><p> 7448fb7bfaSmrg <code class="filename">doc/libstdc++/libstdc++-api.pdf</code> 7548fb7bfaSmrg </p><p> 7648fb7bfaSmrg <code class="filename">doc/libstdc++/libstdc++-manual.pdf</code> 7748fb7bfaSmrg </p></dd><dt><span class="term"> 7848fb7bfaSmrg <span class="emphasis"><em>make man</em></span> 7948fb7bfaSmrg , </span><span class="term"> 8048fb7bfaSmrg <span class="emphasis"><em>make install-man</em></span> 8148fb7bfaSmrg </span></dt><dd><p> 8248fb7bfaSmrg Generates man pages, and installs it in the following directory: 8348fb7bfaSmrg </p><p> 8448fb7bfaSmrg <code class="filename">man/man3/</code> 8548fb7bfaSmrg </p><p> 8648fb7bfaSmrg The generated man pages are namespace-qualified, so to look at 8748fb7bfaSmrg the man page for <code class="classname">vector</code>, one would use 8848fb7bfaSmrg <span class="command"><strong>man std::vector</strong></span>. 8948fb7bfaSmrg </p></dd><dt><span class="term"> 9048fb7bfaSmrg <span class="emphasis"><em>make epub</em></span> 9148fb7bfaSmrg , </span><span class="term"> 9248fb7bfaSmrg <span class="emphasis"><em>make install-epub</em></span> 9348fb7bfaSmrg </span></dt><dd><p> 9448fb7bfaSmrg Generates documentation in the ebook/portable electronic 9548fb7bfaSmrg reader format called Epub, and installs it as the 9648fb7bfaSmrg following file. 9748fb7bfaSmrg </p><p> 9848fb7bfaSmrg <code class="filename">doc/libstdc++/libstdc++-manual.epub</code> 9948fb7bfaSmrg </p></dd><dt><span class="term"> 10048fb7bfaSmrg <span class="emphasis"><em>make xml</em></span> 10148fb7bfaSmrg , </span><span class="term"> 10248fb7bfaSmrg <span class="emphasis"><em>make install-xml</em></span> 10348fb7bfaSmrg </span></dt><dd><p> 10448fb7bfaSmrg Generates single-file XML documentation, and installs it 10548fb7bfaSmrg as the following files: 10648fb7bfaSmrg </p><p> 10748fb7bfaSmrg <code class="filename">doc/libstdc++/libstdc++-api-single.xml</code> 10848fb7bfaSmrg </p><p> 10948fb7bfaSmrg <code class="filename">doc/libstdc++/libstdc++-manual-single.xml</code> 11048fb7bfaSmrg </p></dd></dl></div><p> 11148fb7bfaSmrg Makefile rules for several other formats are explicitly not 11248fb7bfaSmrg supported, and are always aliased to dummy rules. These 11348fb7bfaSmrg unsupported formats are: <span class="emphasis"><em>info</em></span>, 11448fb7bfaSmrg <span class="emphasis"><em>ps</em></span>, and <span class="emphasis"><em>dvi</em></span>. 115d79abf08Smrg </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="doc.doxygen"></a>Doxygen</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="doxygen.prereq"></a>Prerequisites</h4></div></div></div><div class="table"><a id="table.doxygen_prereq"></a><p class="title"><strong>Table B.1. Doxygen Prerequisites</strong></p><div class="table-contents"><table class="table" summary="Doxygen Prerequisites" border="1"><colgroup><col align="center" class="c1" /><col align="center" class="c2" /><col align="center" class="c3" /></colgroup><thead><tr><th align="center">Tool</th><th align="center">Version</th><th align="center">Required By</th></tr></thead><tbody><tr><td align="center">coreutils</td><td align="center">8.5</td><td align="center">all</td></tr><tr><td align="center">bash</td><td align="center">4.1</td><td align="center">all</td></tr><tr><td align="center">doxygen</td><td align="center">1.7.6.1</td><td align="center">all</td></tr><tr><td align="center">graphviz</td><td align="center">2.26</td><td align="center">graphical hierarchies</td></tr><tr><td align="center">pdflatex</td><td align="center">2007-59</td><td align="center">pdf output</td></tr></tbody></table></div></div><br class="table-break" /><p> 11648fb7bfaSmrg Prerequisite tools are Bash 2.0 or later, 117*b1e83836Smrg <a class="link" href="https://www.doxygen.nl" target="_top">Doxygen</a>, and 11848fb7bfaSmrg the <a class="link" href="http://www.gnu.org/software/coreutils/" target="_top">GNU 11948fb7bfaSmrg coreutils</a>. (GNU versions of find, xargs, and possibly 12048fb7bfaSmrg sed and grep are used, just because the GNU versions make 12148fb7bfaSmrg things very easy.) 12248fb7bfaSmrg </p><p> 12348fb7bfaSmrg To generate the pretty pictures and hierarchy 12448fb7bfaSmrg graphs, the 12548fb7bfaSmrg <a class="link" href="http://www.graphviz.org" target="_top">Graphviz</a> package 12648fb7bfaSmrg will need to be installed. For PDF 12748fb7bfaSmrg output, <a class="link" href="http://www.tug.org/applications/pdftex/" target="_top"> 1284d5abbe8Smrg pdflatex</a> is required as well as a number of TeX packages 1294d5abbe8Smrg such as <span class="package">texlive-xtab</span> and 1304d5abbe8Smrg <span class="package">texlive-tocloft</span>. 13148fb7bfaSmrg </p><p> 13248fb7bfaSmrg Be warned the PDF file generated via doxygen is extremely 13348fb7bfaSmrg large. At last count, the PDF file is over three thousand 13448fb7bfaSmrg pages. Generating this document taxes the underlying TeX 13548fb7bfaSmrg formatting system, and will require the expansion of TeX's memory 13648fb7bfaSmrg capacity. Specifically, the <code class="literal">pool_size</code> 13748fb7bfaSmrg variable in the configuration file <code class="filename">texmf.cnf</code> may 13848fb7bfaSmrg need to be increased by a minimum factor of two. 13948fb7bfaSmrg </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="doxygen.rules"></a>Generating the Doxygen Files</h4></div></div></div><p> 14048fb7bfaSmrg The following Makefile rules run Doxygen to generate HTML 14148fb7bfaSmrg docs, XML docs, XML docs as a single file, PDF docs, and the 14248fb7bfaSmrg man pages. These rules are not conditional! If the required 14348fb7bfaSmrg tools are not found, or are the wrong versions, the rule may 14448fb7bfaSmrg end in an error. 14548fb7bfaSmrg </p><p> 14648fb7bfaSmrg </p><pre class="screen"><strong class="userinput"><code>make doc-html-doxygen</code></strong></pre><p> 14748fb7bfaSmrg </p><p> 14848fb7bfaSmrg </p><pre class="screen"><strong class="userinput"><code>make doc-xml-doxygen</code></strong></pre><p> 14948fb7bfaSmrg </p><p> 15048fb7bfaSmrg </p><pre class="screen"><strong class="userinput"><code>make doc-xml-single-doxygen</code></strong></pre><p> 15148fb7bfaSmrg </p><p> 15248fb7bfaSmrg </p><pre class="screen"><strong class="userinput"><code>make doc-pdf-doxygen</code></strong></pre><p> 15348fb7bfaSmrg </p><p> 15448fb7bfaSmrg </p><pre class="screen"><strong class="userinput"><code>make doc-man-doxygen</code></strong></pre><p> 15548fb7bfaSmrg </p><p> 15648fb7bfaSmrg Generated files are output into separate sub directories of 15748fb7bfaSmrg <code class="filename">doc/doxygen/</code> in the 15848fb7bfaSmrg build directory, based on the output format. For instance, the 15948fb7bfaSmrg HTML docs will be in <code class="filename">doc/doxygen/html</code>. 16048fb7bfaSmrg </p><p> 16148fb7bfaSmrg Careful observers will see that the Makefile rules simply call 16248fb7bfaSmrg a script from the source tree, <code class="filename">run_doxygen</code>, which 16348fb7bfaSmrg does the actual work of running Doxygen and then (most 16448fb7bfaSmrg importantly) massaging the output files. If for some reason 16548fb7bfaSmrg you prefer to not go through the Makefile, you can call this 16648fb7bfaSmrg script directly. (Start by passing <code class="literal">--help</code>.) 16748fb7bfaSmrg </p><p> 16848fb7bfaSmrg If you wish to tweak the Doxygen settings, do so by editing 16948fb7bfaSmrg <code class="filename">doc/doxygen/user.cfg.in</code>. Notes to fellow 17048fb7bfaSmrg library hackers are written in triple-# comments. 17148fb7bfaSmrg </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="doxygen.debug"></a>Debugging Generation</h4></div></div></div><p> 17248fb7bfaSmrg Sometimes, mis-configuration of the pre-requisite tools can 17348fb7bfaSmrg lead to errors when attempting to build the 17448fb7bfaSmrg documentation. Here are some of the obvious errors, and ways 17548fb7bfaSmrg to fix some common issues that may appear quite cryptic. 17648fb7bfaSmrg </p><p> 17748fb7bfaSmrg First, if using a rule like <code class="code">make pdf</code>, try to 17848fb7bfaSmrg narrow down the scope of the error to either docbook 17948fb7bfaSmrg (<code class="code">make doc-pdf-docbook</code>) or doxygen (<code class="code">make 18048fb7bfaSmrg doc-pdf-doxygen</code>). 18148fb7bfaSmrg </p><p> 18248fb7bfaSmrg Working on the doxygen path only, closely examine the 1834d5abbe8Smrg contents of the following build directory: <code class="filename">build/target/libstdc++-v3/doc/doxygen/latex</code>. 18448fb7bfaSmrg Pay attention to three files enclosed within, annotated as follows. 18548fb7bfaSmrg </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> 18648fb7bfaSmrg <span class="emphasis"><em>refman.tex</em></span> 18748fb7bfaSmrg </p><p> 18848fb7bfaSmrg The actual latex file, or partial latex file. This is generated 18948fb7bfaSmrg via <span class="command"><strong>doxygen</strong></span>, and is the LaTeX version of the 19048fb7bfaSmrg Doxygen XML file <code class="filename">libstdc++-api.xml</code>. Go to a specific 1914d5abbe8Smrg line, and look at the generated LaTeX, and try to deduce what 19248fb7bfaSmrg markup in <code class="filename">libstdc++-api.xml</code> is causing it. 19348fb7bfaSmrg </p></li><li class="listitem"><p> 1944d5abbe8Smrg <span class="emphasis"><em>refman.log</em></span> 1954d5abbe8Smrg </p><p> 1964d5abbe8Smrg A log created by <span class="command"><strong>latex</strong></span> as it processes the 1974d5abbe8Smrg <code class="filename">refman.tex</code> file. If generating the PDF fails 1984d5abbe8Smrg look at the end of this file for errors such as: 1994d5abbe8Smrg </p><pre class="screen"> 2004d5abbe8Smrg ! LaTeX Error: File `xtab.sty' not found. 2014d5abbe8Smrg </pre><p> 2024d5abbe8Smrg This indicates a required TeX package is missing. For the example 2034d5abbe8Smrg above the <span class="package">texlive-xtab</span> package needs to be 2044d5abbe8Smrg installed. 2054d5abbe8Smrg </p></li><li class="listitem"><p> 20648fb7bfaSmrg <span class="emphasis"><em>refman.out</em></span> 20748fb7bfaSmrg </p><p> 2084d5abbe8Smrg A log of the compilation of the converted LaTeX form to PDF. This 20948fb7bfaSmrg is a linear list, from the beginning of the 21048fb7bfaSmrg <code class="filename">refman.tex</code> file: the last entry of this file 21148fb7bfaSmrg should be the end of the LaTeX file. If it is truncated, then you 21248fb7bfaSmrg know that the last entry is the last part of the generated LaTeX 21348fb7bfaSmrg source file that is valid. Often this file contains an error with 21448fb7bfaSmrg a specific line number of <code class="filename">refman.tex</code> that is 21548fb7bfaSmrg incorrect, or will have clues at the end of the file with the dump 21648fb7bfaSmrg of the memory usage of LaTeX. 21748fb7bfaSmrg </p></li></ul></div><p> 21848fb7bfaSmrg If the error at hand is not obvious after examination, a 21948fb7bfaSmrg fall-back strategy is to start commenting out the doxygen 22048fb7bfaSmrg input sources, which can be found in 22148fb7bfaSmrg <code class="filename">doc/doxygen/user.cfg.in</code>, look for the 22248fb7bfaSmrg <code class="literal">INPUT</code> tag. Start by commenting out whole 22348fb7bfaSmrg directories of header files, until the offending header is 22448fb7bfaSmrg identified. Then, read the latex log files to try and find 22548fb7bfaSmrg surround text, and look for that in the offending header. 22648fb7bfaSmrg </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="doxygen.markup"></a>Markup</h4></div></div></div><p> 22748fb7bfaSmrg In general, libstdc++ files should be formatted according to 22848fb7bfaSmrg the rules found in the 22948fb7bfaSmrg <a class="link" href="source_code_style.html" title="Coding Style">Coding Standard</a>. Before 23048fb7bfaSmrg any doxygen-specific formatting tweaks are made, please try to 23148fb7bfaSmrg make sure that the initial formatting is sound. 23248fb7bfaSmrg </p><p> 23348fb7bfaSmrg Adding Doxygen markup to a file (informally called 234fb8a8121Smrg <span class="quote">“<span class="quote">doxygenating</span>”</span>) is very simple. See the 235*b1e83836Smrg <a class="link" href="https://www.doxygen.nl/download.html#latestman" target="_top">Doxygen 236fb8a8121Smrg manual</a> for details. 23748fb7bfaSmrg We try to use a very-recent version of Doxygen. 23848fb7bfaSmrg </p><p> 23948fb7bfaSmrg For classes, use 24048fb7bfaSmrg <code class="classname">deque</code>/<code class="classname">vector</code>/<code class="classname">list</code> 24148fb7bfaSmrg and <code class="classname">std::pair</code> as examples. For 24248fb7bfaSmrg functions, see their member functions, and the free functions 2434d5abbe8Smrg in <code class="filename">stl_algobase.h</code>. Member 2444d5abbe8Smrg functions of other container-like types should read similarly to 2454d5abbe8Smrg these member functions. 24648fb7bfaSmrg </p><p> 24748fb7bfaSmrg Some commentary to accompany 248*b1e83836Smrg the first list in the <a class="link" href="https://www.doxygen.nl/manual/docblocks.html" target="_top">Special 24948fb7bfaSmrg Documentation Blocks</a> section of the Doxygen manual: 25048fb7bfaSmrg </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>For longer comments, use the Javadoc style...</p></li><li class="listitem"><p> 25148fb7bfaSmrg ...not the Qt style. The intermediate *'s are preferred. 25248fb7bfaSmrg </p></li><li class="listitem"><p> 25348fb7bfaSmrg Use the triple-slash style only for one-line comments (the 25448fb7bfaSmrg <span class="quote">“<span class="quote">brief</span>”</span> mode). 25548fb7bfaSmrg </p></li><li class="listitem"><p> 25648fb7bfaSmrg This is disgusting. Don't do this. 25748fb7bfaSmrg </p></li></ol></div><p> 25848fb7bfaSmrg Some specific guidelines: 25948fb7bfaSmrg </p><p> 26048fb7bfaSmrg Use the @-style of commands, not the !-style. Please be 26148fb7bfaSmrg careful about whitespace in your markup comments. Most of the 26248fb7bfaSmrg time it doesn't matter; doxygen absorbs most whitespace, and 26348fb7bfaSmrg both HTML and *roff are agnostic about whitespace. However, 26448fb7bfaSmrg in <pre> blocks and @code/@endcode sections, spacing can 26548fb7bfaSmrg have <span class="quote">“<span class="quote">interesting</span>”</span> effects. 26648fb7bfaSmrg </p><p> 26748fb7bfaSmrg Use either kind of grouping, as 26848fb7bfaSmrg appropriate. <code class="filename">doxygroups.cc</code> exists for this 2694d5abbe8Smrg purpose. See <code class="filename">stl_iterator.h</code> 2704d5abbe8Smrg for a good example of the <span class="quote">“<span class="quote">other</span>”</span> kind of grouping. 27148fb7bfaSmrg </p><p> 27248fb7bfaSmrg Please use markup tags like @p and @a when referring to things 27348fb7bfaSmrg such as the names of function parameters. Use @e for emphasis 27448fb7bfaSmrg when necessary. Use @c to refer to other standard names. 27548fb7bfaSmrg (Examples of all these abound in the present code.) 27648fb7bfaSmrg </p><p> 2774d5abbe8Smrg Complicated math functions should use the multi-line format. 2784d5abbe8Smrg An example from <code class="filename">random.h</code>: 27948fb7bfaSmrg </p><p> 28048fb7bfaSmrg</p><div class="literallayout"><p><br /> 28148fb7bfaSmrg/**<br /> 28248fb7bfaSmrg * @brief A model of a linear congruential random number generator.<br /> 28348fb7bfaSmrg *<br /> 28448fb7bfaSmrg * @f[<br /> 28548fb7bfaSmrg * x_{i+1}\leftarrow(ax_{i} + c) \bmod m<br /> 28648fb7bfaSmrg * @f]<br /> 28748fb7bfaSmrg */<br /> 28848fb7bfaSmrg</p></div><p> 28948fb7bfaSmrg </p><p> 29048fb7bfaSmrg One area of note is the markup required for 29148fb7bfaSmrg <code class="literal">@file</code> markup in header files. Two details 29248fb7bfaSmrg are important: for filenames that have the same name in 29348fb7bfaSmrg multiple directories, include part of the installed path to 29448fb7bfaSmrg disambiguate. For example: 29548fb7bfaSmrg </p><p> 29648fb7bfaSmrg</p><div class="literallayout"><p><br /> 29748fb7bfaSmrg/** @file debug/vector<br /> 29848fb7bfaSmrg * This file is a GNU debug extension to the Standard C++ Library.<br /> 29948fb7bfaSmrg */<br /> 30048fb7bfaSmrg</p></div><p> 30148fb7bfaSmrg </p><p> 30248fb7bfaSmrg The other relevant detail for header files is the use of a 30348fb7bfaSmrg libstdc++-specific doxygen alias that helps distinguish 30448fb7bfaSmrg between public header files (like <code class="filename">random</code>) 30548fb7bfaSmrg from implementation or private header files (like 30648fb7bfaSmrg <code class="filename">bits/c++config.h</code>.) This alias is spelled 30748fb7bfaSmrg <code class="literal">@headername</code> and can take one or two 30848fb7bfaSmrg arguments that detail the public header file or files that 30948fb7bfaSmrg should be included to use the contents of the file. All header 31048fb7bfaSmrg files that are not intended for direct inclusion must use 31148fb7bfaSmrg <code class="literal">headername</code> in the <code class="literal">file</code> 31248fb7bfaSmrg block. An example: 31348fb7bfaSmrg </p><p> 31448fb7bfaSmrg</p><div class="literallayout"><p><br /> 31548fb7bfaSmrg/** @file bits/basic_string.h<br /> 31648fb7bfaSmrg * This is an internal header file, included by other library headers.<br /> 31748fb7bfaSmrg * Do not attempt to use it directly. @headername{string}<br /> 31848fb7bfaSmrg */<br /> 31948fb7bfaSmrg</p></div><p> 32048fb7bfaSmrg </p><p> 32148fb7bfaSmrg Be careful about using certain, special characters when 32248fb7bfaSmrg writing Doxygen comments. Single and double quotes, and 32348fb7bfaSmrg separators in filenames are two common trouble spots. When in 32448fb7bfaSmrg doubt, consult the following table. 325d79abf08Smrg </p><div class="table"><a id="table.doxygen_cmp"></a><p class="title"><strong>Table B.2. HTML to Doxygen Markup Comparison</strong></p><div class="table-contents"><table class="table" summary="HTML to Doxygen Markup Comparison" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">HTML</th><th align="left">Doxygen</th></tr></thead><tbody><tr><td align="left">\</td><td align="left">\\</td></tr><tr><td align="left">"</td><td align="left">\"</td></tr><tr><td align="left">'</td><td align="left">\'</td></tr><tr><td align="left"><i></td><td align="left">@a word</td></tr><tr><td align="left"><b></td><td align="left">@b word</td></tr><tr><td align="left"><code></td><td align="left">@c word</td></tr><tr><td align="left"><em></td><td align="left">@a word</td></tr><tr><td align="left"><em></td><td align="left"><em>two words or more</em></td></tr></tbody></table></div></div><br class="table-break" /></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="doc.docbook"></a>Docbook</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.prereq"></a>Prerequisites</h4></div></div></div><div class="table"><a id="table.docbook_prereq"></a><p class="title"><strong>Table B.3. Docbook Prerequisites</strong></p><div class="table-contents"><table class="table" summary="Docbook Prerequisites" border="1"><colgroup><col align="center" class="c1" /><col align="center" class="c2" /><col align="center" class="c3" /></colgroup><thead><tr><th align="center">Tool</th><th align="center">Version</th><th align="center">Required By</th></tr></thead><tbody><tr><td align="center">docbook5-style-xsl</td><td align="center">1.76.1</td><td align="center">all</td></tr><tr><td align="center">xsltproc</td><td align="center">1.1.26</td><td align="center">all</td></tr><tr><td align="center">xmllint</td><td align="center">2.7.7</td><td align="center">validation</td></tr><tr><td align="center">dblatex</td><td align="center">0.3</td><td align="center">pdf output</td></tr><tr><td align="center">pdflatex</td><td align="center">2007-59</td><td align="center">pdf output</td></tr><tr><td align="center">docbook2X</td><td align="center">0.8.8</td><td align="center">info output</td></tr><tr><td align="center">epub3 stylesheets</td><td align="center">b3</td><td align="center">epub output</td></tr></tbody></table></div></div><br class="table-break" /><p> 32648fb7bfaSmrg Editing the DocBook sources requires an XML editor. Many 32748fb7bfaSmrg exist: some notable options 32848fb7bfaSmrg include <span class="command"><strong>emacs</strong></span>, <span class="application">Kate</span>, 32948fb7bfaSmrg or <span class="application">Conglomerate</span>. 33048fb7bfaSmrg </p><p> 33148fb7bfaSmrg Some editors support special <span class="quote">“<span class="quote">XML Validation</span>”</span> 33248fb7bfaSmrg modes that can validate the file as it is 33348fb7bfaSmrg produced. Recommended is the <span class="command"><strong>nXML Mode</strong></span> 33448fb7bfaSmrg for <span class="command"><strong>emacs</strong></span>. 33548fb7bfaSmrg </p><p> 33648fb7bfaSmrg Besides an editor, additional DocBook files and XML tools are 33748fb7bfaSmrg also required. 33848fb7bfaSmrg </p><p> 33948fb7bfaSmrg Access to the DocBook 5.0 stylesheets and schema is required. The 34048fb7bfaSmrg stylesheets are usually packaged by vendor, in something 34148fb7bfaSmrg like <code class="filename">docbook5-style-xsl</code>. To exactly match 34248fb7bfaSmrg generated output, please use a version of the stylesheets 34348fb7bfaSmrg equivalent 34448fb7bfaSmrg to <code class="filename">docbook5-style-xsl-1.75.2-3</code>. The 34548fb7bfaSmrg installation directory for this package corresponds to 34648fb7bfaSmrg the <code class="literal">XSL_STYLE_DIR</code> 34748fb7bfaSmrg in <code class="filename">doc/Makefile.am</code> and defaults 34848fb7bfaSmrg to <code class="filename">/usr/share/sgml/docbook/xsl-ns-stylesheets</code>. 34948fb7bfaSmrg </p><p> 35048fb7bfaSmrg For processing XML, an XSLT processor and some style 35148fb7bfaSmrg sheets are necessary. Defaults are <span class="command"><strong>xsltproc</strong></span> 35248fb7bfaSmrg provided by <code class="filename">libxslt</code>. 35348fb7bfaSmrg </p><p> 35448fb7bfaSmrg For validating the XML document, you'll need 35548fb7bfaSmrg something like <span class="command"><strong>xmllint</strong></span> and access to the 35648fb7bfaSmrg relevant DocBook schema. These are provided 35748fb7bfaSmrg by a vendor package like <code class="filename">libxml2</code> and <code class="filename">docbook5-schemas-5.0-4</code> 35848fb7bfaSmrg </p><p> 35948fb7bfaSmrg For PDF output, something that transforms valid Docbook XML to PDF is 36048fb7bfaSmrg required. Possible solutions include <a class="link" href="http://dblatex.sourceforge.net" target="_top">dblatex</a>, 36148fb7bfaSmrg <span class="command"><strong>xmlto</strong></span>, or <span class="command"><strong>prince</strong></span>. Of 362b17d1066Smrg these, <span class="command"><strong>dblatex</strong></span> is the default. 363b17d1066Smrg Please consult the <code class="email"><<a class="email" href="mailto:libstdc++@gcc.gnu.org">libstdc++@gcc.gnu.org</a>></code> list when 36448fb7bfaSmrg preparing printed manuals for current best practice and 36548fb7bfaSmrg suggestions. 36648fb7bfaSmrg </p><p> 36748fb7bfaSmrg For Texinfo output, something that transforms valid Docbook 36848fb7bfaSmrg XML to Texinfo is required. The default choice is <a class="link" href="http://docbook2x.sourceforge.net/" target="_top">docbook2X</a>. 36948fb7bfaSmrg </p><p> 370181254a7Smrg For epub output, the <a class="link" href="https://sourceforge.net/projects/docbook/files/epub3/" target="_top">stylesheets</a> for EPUB3 are required. These stylesheets are still in development. To validate the created file, <a class="link" href="https://github.com/w3c/epubcheck" target="_top">epubcheck</a> is necessary. 37148fb7bfaSmrg </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.rules"></a>Generating the DocBook Files</h4></div></div></div><p> 37248fb7bfaSmrg The following Makefile rules generate (in order): an HTML 37348fb7bfaSmrg version of all the DocBook documentation, a PDF version of the 37448fb7bfaSmrg same, and a single XML document. These rules are not 37548fb7bfaSmrg conditional! If the required tools are not found, or are the 37648fb7bfaSmrg wrong versions, the rule may end in an error. 37748fb7bfaSmrg </p><p> 37848fb7bfaSmrg </p><pre class="screen"><strong class="userinput"><code>make doc-html-docbook</code></strong></pre><p> 37948fb7bfaSmrg </p><p> 38048fb7bfaSmrg </p><pre class="screen"><strong class="userinput"><code>make doc-pdf-docbook</code></strong></pre><p> 38148fb7bfaSmrg </p><p> 38248fb7bfaSmrg </p><pre class="screen"><strong class="userinput"><code>make doc-xml-single-docbook</code></strong></pre><p> 38348fb7bfaSmrg </p><p> 384003ba354Smrg Generated files are output into separate sub-directores of 38548fb7bfaSmrg <code class="filename">doc/docbook/</code> in the 38648fb7bfaSmrg build directory, based on the output format. For instance, the 38748fb7bfaSmrg HTML docs will be in <code class="filename">doc/docbook/html</code>. 38848fb7bfaSmrg </p><p> 389003ba354Smrg The </p><pre class="screen">doc-html-docbook-regenerate</pre><p> target will generate 390003ba354Smrg the HTML files and copy them back to the libstdc++ source tree. 391003ba354Smrg This can be used to update the HTML files that are checked in to 392003ba354Smrg version control. 393003ba354Smrg </p><p> 39448fb7bfaSmrg If the Docbook stylesheets are installed in a custom location, 39548fb7bfaSmrg one can use the variable <code class="literal">XSL_STYLE_DIR</code> to 39648fb7bfaSmrg override the Makefile defaults. For example: 39748fb7bfaSmrg </p><pre class="screen"> 39848fb7bfaSmrg <strong class="userinput"><code> 39948fb7bfaSmrgmake <code class="literal">XSL_STYLE_DIR="/usr/share/xml/docbook/stylesheet/nwalsh"</code> doc-html-docbook 40048fb7bfaSmrg </code></strong> 40148fb7bfaSmrg </pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.debug"></a>Debugging Generation</h4></div></div></div><p> 40248fb7bfaSmrg Sometimes, mis-configuration of the pre-requisite tools can 40348fb7bfaSmrg lead to errors when attempting to build the 40448fb7bfaSmrg documentation. Here are some of the obvious errors, and ways 40548fb7bfaSmrg to fix some common issues that may appear quite cryptic. 40648fb7bfaSmrg </p><p> 40748fb7bfaSmrg First, if using a rule like <code class="code">make pdf</code>, try to 40848fb7bfaSmrg narrow down the scope of the error to either docbook 40948fb7bfaSmrg (<code class="code">make doc-pdf-docbook</code>) or doxygen (<code class="code">make 41048fb7bfaSmrg doc-pdf-doxygen</code>). 41148fb7bfaSmrg </p><p> 41248fb7bfaSmrg Working on the docbook path only, closely examine the 41348fb7bfaSmrg contents of the following build directory: 41448fb7bfaSmrg <code class="filename">build/target/libstdc++-v3/doc/docbook/latex</code>. 41548fb7bfaSmrg Pay attention to three files enclosed within, annotated as follows. 41648fb7bfaSmrg </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> 41748fb7bfaSmrg <span class="emphasis"><em>spine.tex</em></span> 41848fb7bfaSmrg </p><p> 41948fb7bfaSmrg The actual latex file, or partial latex file. This is generated 42048fb7bfaSmrg via <span class="command"><strong>dblatex</strong></span>, and is the LaTeX version of the 42148fb7bfaSmrg DocBook XML file <code class="filename">spine.xml</code>. Go to a specific 4224d5abbe8Smrg line, and look at the generated LaTeX, and try to deduce what 42348fb7bfaSmrg markup in <code class="filename">spine.xml</code> is causing it. 42448fb7bfaSmrg </p></li><li class="listitem"><p> 42548fb7bfaSmrg <span class="emphasis"><em>spine.out</em></span> 42648fb7bfaSmrg </p><p> 42748fb7bfaSmrg A log of the conversion from the XML form to the LaTeX form. This 42848fb7bfaSmrg is a linear list, from the beginning of the 42948fb7bfaSmrg <code class="filename">spine.xml</code> file: the last entry of this file 43048fb7bfaSmrg should be the end of the DocBook file. If it is truncated, then 43148fb7bfaSmrg you know that the last entry is the last part of the XML source 43248fb7bfaSmrg file that is valid. The error is after this point. 43348fb7bfaSmrg </p></li><li class="listitem"><p> 43448fb7bfaSmrg <span class="emphasis"><em>spine.log</em></span> 43548fb7bfaSmrg </p><p> 43648fb7bfaSmrg A log of the compilation of the converted LaTeX form to pdf. This 43748fb7bfaSmrg is a linear list, from the beginning of the 43848fb7bfaSmrg <code class="filename">spine.tex</code> file: the last entry of this file 43948fb7bfaSmrg should be the end of the LaTeX file. If it is truncated, then you 44048fb7bfaSmrg know that the last entry is the last part of the generated LaTeX 44148fb7bfaSmrg source file that is valid. Often this file contains an error with 44248fb7bfaSmrg a specific line number of <code class="filename">spine.tex</code> that is 44348fb7bfaSmrg incorrect. 44448fb7bfaSmrg </p></li></ul></div><p> 44548fb7bfaSmrg If the error at hand is not obvious after examination, or if one 44648fb7bfaSmrg encounters the inscruitable <span class="quote">“<span class="quote">Incomplete 44748fb7bfaSmrg \ifmmode</span>”</span> error, a fall-back strategy is to start 44848fb7bfaSmrg commenting out parts of the XML document (regardless of what 44948fb7bfaSmrg this does to over-all document validity). Start by 45048fb7bfaSmrg commenting out each of the largest parts of the 45148fb7bfaSmrg <code class="filename">spine.xml</code> file, section by section, 45248fb7bfaSmrg until the offending section is identified. 45348fb7bfaSmrg </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.validation"></a>Editing and Validation</h4></div></div></div><p> 45448fb7bfaSmrg After editing the xml sources, please make sure that the XML 45548fb7bfaSmrg documentation and markup is still valid. This can be 45648fb7bfaSmrg done easily, with the following validation rule: 45748fb7bfaSmrg </p><pre class="screen"> 45848fb7bfaSmrg <strong class="userinput"><code>make doc-xml-validate-docbook</code></strong> 45948fb7bfaSmrg </pre><p> 46048fb7bfaSmrg This is equivalent to doing: 46148fb7bfaSmrg </p><pre class="screen"> 46248fb7bfaSmrg <strong class="userinput"><code> 46348fb7bfaSmrg xmllint --noout --valid <code class="filename">xml/index.xml</code> 46448fb7bfaSmrg </code></strong> 46548fb7bfaSmrg </pre><p> 46648fb7bfaSmrg Please note that individual sections and chapters of the 46748fb7bfaSmrg manual can be validated by substituting the file desired for 46848fb7bfaSmrg <code class="filename">xml/index.xml</code> in the command 46948fb7bfaSmrg above. Reducing scope in this manner can be helpful when 47048fb7bfaSmrg validation on the entire manual fails. 47148fb7bfaSmrg </p><p> 47248fb7bfaSmrg All Docbook xml sources should always validate. No excuses! 47348fb7bfaSmrg </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.examples"></a>File Organization and Basics</h4></div></div></div><div class="literallayout"><p><br /> 47448fb7bfaSmrg <span class="emphasis"><em>Which files are important</em></span><br /> 47548fb7bfaSmrg<br /> 47648fb7bfaSmrg All Docbook files are in the directory<br /> 47748fb7bfaSmrg libstdc++-v3/doc/xml<br /> 47848fb7bfaSmrg<br /> 47948fb7bfaSmrg Inside this directory, the files of importance:<br /> 48048fb7bfaSmrg spine.xml - index to documentation set<br /> 48148fb7bfaSmrg manual/spine.xml - index to manual<br /> 48248fb7bfaSmrg manual/*.xml - individual chapters and sections of the manual<br /> 48348fb7bfaSmrg faq.xml - index to FAQ<br /> 48448fb7bfaSmrg api.xml - index to source level / API<br /> 48548fb7bfaSmrg<br /> 48648fb7bfaSmrg All *.txml files are template xml files, i.e., otherwise empty files with<br /> 48748fb7bfaSmrg the correct structure, suitable for filling in with new information.<br /> 48848fb7bfaSmrg<br /> 48948fb7bfaSmrg <span class="emphasis"><em>Canonical Writing Style</em></span><br /> 49048fb7bfaSmrg<br /> 49148fb7bfaSmrg class template<br /> 49248fb7bfaSmrg function template<br /> 49348fb7bfaSmrg member function template<br /> 49448fb7bfaSmrg (via C++ Templates, Vandevoorde)<br /> 49548fb7bfaSmrg<br /> 49648fb7bfaSmrg class in namespace std: allocator, not std::allocator<br /> 49748fb7bfaSmrg<br /> 49848fb7bfaSmrg header file: iostream, not <iostream><br /> 49948fb7bfaSmrg<br /> 50048fb7bfaSmrg<br /> 50148fb7bfaSmrg <span class="emphasis"><em>General structure</em></span><br /> 50248fb7bfaSmrg<br /> 50348fb7bfaSmrg <set><br /> 50448fb7bfaSmrg <book><br /> 50548fb7bfaSmrg </book><br /> 50648fb7bfaSmrg<br /> 50748fb7bfaSmrg <book><br /> 50848fb7bfaSmrg <chapter><br /> 50948fb7bfaSmrg </chapter><br /> 51048fb7bfaSmrg </book><br /> 51148fb7bfaSmrg<br /> 51248fb7bfaSmrg <book><br /> 51348fb7bfaSmrg <part><br /> 51448fb7bfaSmrg <chapter><br /> 51548fb7bfaSmrg <section><br /> 51648fb7bfaSmrg </section><br /> 51748fb7bfaSmrg<br /> 51848fb7bfaSmrg <sect1><br /> 51948fb7bfaSmrg </sect1><br /> 52048fb7bfaSmrg<br /> 52148fb7bfaSmrg <sect1><br /> 52248fb7bfaSmrg <sect2><br /> 52348fb7bfaSmrg </sect2><br /> 52448fb7bfaSmrg </sect1><br /> 52548fb7bfaSmrg </chapter><br /> 52648fb7bfaSmrg<br /> 52748fb7bfaSmrg <chapter><br /> 52848fb7bfaSmrg </chapter><br /> 52948fb7bfaSmrg </part><br /> 53048fb7bfaSmrg </book><br /> 53148fb7bfaSmrg<br /> 53248fb7bfaSmrg </set><br /> 53348fb7bfaSmrg </p></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.markup"></a>Markup By Example</h4></div></div></div><p> 534b17d1066Smrg Complete details on Docbook markup can be found in the 535a3e9eb18Smrg <a class="link" href="https://tdg.docbook.org/tdg/5.0/ref-elements.html" target="_top">DocBook Element Reference</a>. 53648fb7bfaSmrg An incomplete reference for HTML to Docbook conversion is 53748fb7bfaSmrg detailed in the table below. 538d79abf08Smrg </p><div class="table"><a id="table.docbook_cmp"></a><p class="title"><strong>Table B.4. HTML to Docbook XML Markup Comparison</strong></p><div class="table-contents"><table class="table" summary="HTML to Docbook XML Markup Comparison" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">HTML</th><th align="left">Docbook</th></tr></thead><tbody><tr><td align="left"><p></td><td align="left"><para></td></tr><tr><td align="left"><pre></td><td align="left"><computeroutput>, <programlisting>, 53948fb7bfaSmrg <literallayout></td></tr><tr><td align="left"><ul></td><td align="left"><itemizedlist></td></tr><tr><td align="left"><ol></td><td align="left"><orderedlist></td></tr><tr><td align="left"><il></td><td align="left"><listitem></td></tr><tr><td align="left"><dl></td><td align="left"><variablelist></td></tr><tr><td align="left"><dt></td><td align="left"><term></td></tr><tr><td align="left"><dd></td><td align="left"><listitem></td></tr><tr><td align="left"><a href=""></td><td align="left"><ulink url=""></td></tr><tr><td align="left"><code></td><td align="left"><literal>, <programlisting></td></tr><tr><td align="left"><strong></td><td align="left"><emphasis></td></tr><tr><td align="left"><em></td><td align="left"><emphasis></td></tr><tr><td align="left">"</td><td align="left"><quote></td></tr></tbody></table></div></div><br class="table-break" /><p> 54048fb7bfaSmrg And examples of detailed markup for which there are no real HTML 54148fb7bfaSmrg equivalents are listed in the table below. 542d79abf08Smrg</p><div class="table"><a id="table.docbook_elem"></a><p class="title"><strong>Table B.5. Docbook XML Element Use</strong></p><div class="table-contents"><table class="table" summary="Docbook XML Element Use" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Element</th><th align="left">Use</th></tr></thead><tbody><tr><td align="left"><structname></td><td align="left"><structname>char_traits</structname></td></tr><tr><td align="left"><classname></td><td align="left"><classname>string</classname></td></tr><tr><td align="left"><function></td><td align="left"> 54348fb7bfaSmrg <p><function>clear()</function></p> 54448fb7bfaSmrg <p><function>fs.clear()</function></p> 54548fb7bfaSmrg </td></tr><tr><td align="left"><type></td><td align="left"><type>long long</type></td></tr><tr><td align="left"><varname></td><td align="left"><varname>fs</varname></td></tr><tr><td align="left"><literal></td><td align="left"> 54648fb7bfaSmrg <p><literal>-Weffc++</literal></p> 54748fb7bfaSmrg <p><literal>rel_ops</literal></p> 54848fb7bfaSmrg </td></tr><tr><td align="left"><constant></td><td align="left"> 54948fb7bfaSmrg <p><constant>_GNU_SOURCE</constant></p> 55048fb7bfaSmrg <p><constant>3.0</constant></p> 55148fb7bfaSmrg </td></tr><tr><td align="left"><command></td><td align="left"><command>g++</command></td></tr><tr><td align="left"><errortext></td><td align="left"><errortext>In instantiation of</errortext></td></tr><tr><td align="left"><filename></td><td align="left"> 55248fb7bfaSmrg <p><filename class="headerfile">ctype.h</filename></p> 55348fb7bfaSmrg <p><filename class="directory">/home/gcc/build</filename></p> 55448fb7bfaSmrg <p><filename class="libraryfile">libstdc++.so</filename></p> 55548fb7bfaSmrg </td></tr></tbody></table></div></div><br class="table-break" /></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="appendix_porting.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendix_porting.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="internals.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Appendix B. 55648fb7bfaSmrg Porting and Maintenance 55748fb7bfaSmrg 55848fb7bfaSmrg </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Porting to New Hardware or Operating Systems</td></tr></table></div></body></html>