OSDN Git Service

2012-12-12 Benjamin Kosnik <bkoz@redhat.com>
[pf3gnuchains/gcc-fork.git] / libstdc++-v3 / doc / xml / manual / documentation_hacking.xml
1 <section xmlns="http://docbook.org/ns/docbook" version="5.0" 
2          xml:id="appendix.porting.doc" xreflabel="Documentation Hacking">
3 <?dbhtml filename="documentation_hacking.html"?>
4
5 <info><title>Writing and Generating Documentation</title>
6   <keywordset>
7     <keyword>ISO C++</keyword>
8     <keyword>documentation</keyword>
9     <keyword>style</keyword>
10     <keyword>docbook</keyword>
11     <keyword>doxygen</keyword>
12   </keywordset>
13 </info>
14
15   <section xml:id="doc.intro">
16     <info>
17     <title>Introduction</title>
18     </info>
19     <para>
20       Documentation for the GNU C++ Library is created from three
21       independent sources: a manual, a FAQ, and an API reference.
22     </para>
23     <para>
24       The sub-directory <filename class="directory">doc</filename>
25       within the main source directory contains
26       <filename>Makefile.am</filename> and
27       <filename>Makefile.in</filename>, which provide rules for
28       generating documentation, described in excruciating detail
29       below. The <filename class="directory">doc</filename>
30       sub-directory also contains three directories: <filename
31       class="directory">doxygen</filename>, which contains scripts and
32       fragments for <command>doxygen</command>, <filename
33       class="directory">html</filename>, which contains an html
34       version of the manual, and <filename
35       class="directory">xml</filename>, which contains an xml version
36       of the manual.
37     </para>
38     <para>
39       Diverging from established documentation conventions in the rest
40       of the GCC project, libstdc++ does not use Texinfo as a markup
41       language. Instead, Docbook is used to create the manual and the
42       FAQ, and Doxygen is used to construct the API
43       reference. Although divergent, this conforms to the GNU Project
44       recommendations as long as the output is of sufficient quality,
45       as per
46       <link xmlns:xlink="http://www.w3.org/1999/xlink" 
47       xlink:href="http://www.gnu.org/prep/standards/standards.html#Documentation">
48       GNU Manuals</link>.
49     </para>
50   </section>
51
52   <section xml:id="doc.generation">
53     <info>
54     <title>Generating Documentation</title>
55     </info>
56     
57     <para>
58       Certain Makefile rules are required by the GNU Coding
59       Standards. These standard rules generate HTML, PDF, XML, or man
60       files. For each of the generative rules, there is an additional
61       install rule that is used to install any generated documentation
62       files into the prescribed installation directory. Files are
63       installed into <filename class="directory">share/doc</filename>
64       or <filename class="directory">share/man</filename> directories.
65     </para>
66
67     <para>
68       The standard Makefile rules are conditionally supported, based
69       on the results of examining the host environment for
70       prerequisites at configuration time. If requirements are not
71       found, the rule is aliased to a dummy rule that does nothing,
72       and produces no documentation. If the requirements are found,
73       the rule forwards to a private rule that produces the requested
74       documentation.
75     </para>
76
77     <para>
78       For more details on what prerequisites were found and where,
79       please consult the file <filename>config.log</filename> in the
80       libstdc++ build directory. Compare this log to what is expected
81       for the relevant Makefile conditionals:
82       <literal>BUILD_INFO</literal>, <literal>BUILD_XML</literal>,
83       <literal>BUILD_HTML</literal>, <literal>BUILD_MAN</literal>,
84       <literal>BUILD_PDF</literal>, and <literal>BUILD_EPUB</literal>.
85     </para>
86
87     <para>
88       Supported Makefile rules:
89     </para>
90
91     <variablelist>
92       <varlistentry>
93         <term>
94           <emphasis>make html</emphasis>
95         </term>
96         <term>
97           <emphasis>make install-html</emphasis>
98         </term>
99         <listitem>
100           <para>
101             Generates multi-page HTML documentation, and installs it
102             in the following directories:
103           </para>
104           <para>
105             <filename>doc/libstdc++/libstdc++-api.html</filename>
106           </para>
107           <para>
108             <filename>doc/libstdc++/libstdc++-manual.html</filename>
109           </para>
110         </listitem>
111       </varlistentry>
112
113       <varlistentry>
114         <term>
115           <emphasis>make pdf</emphasis>
116         </term>
117         <term>
118           <emphasis>make install-pdf</emphasis>
119         </term>
120         <listitem>
121           <para>
122             Generates indexed PDF documentation, and installs it as
123             the following files:
124           </para>
125           <para>
126             <filename>doc/libstdc++/libstdc++-api.pdf</filename>
127           </para>
128           <para>
129             <filename>doc/libstdc++/libstdc++-manual.pdf</filename>
130           </para>
131         </listitem>
132       </varlistentry>
133       
134       <varlistentry>
135         <term>
136           <emphasis>make man</emphasis>
137         </term>
138         <term>
139           <emphasis>make install-man</emphasis>
140         </term>
141         <listitem>
142           <para>
143             Generates man pages, and installs it in the following directory:
144           </para>
145           <para>
146             <filename class="directory">man/man3/</filename>
147           </para>
148           <para>
149             The generated man pages are namespace-qualified, so to look at
150             the man page for <classname>vector</classname>, one would use
151             <command>man std::vector</command>.
152           </para>
153         </listitem>
154       </varlistentry>
155
156       <varlistentry>
157         <term>
158           <emphasis>make epub</emphasis>
159         </term>
160         <term>
161           <emphasis>make install-epub</emphasis>
162         </term>
163         <listitem>
164           <para>
165             Generates documentation in the ebook/portable electronic
166             reader format called Epub, and installs it as the
167             following file.
168           </para>
169           <para>
170             <filename>doc/libstdc++/libstdc++-manual.epub</filename>
171           </para>
172         </listitem>
173       </varlistentry>      
174
175       <varlistentry>
176         <term>
177           <emphasis>make xml</emphasis>
178         </term>
179         <term>
180           <emphasis>make install-xml</emphasis>
181         </term>
182         <listitem>
183           <para>
184             Generates single-file XML documentation, and installs it
185             as the following files:
186           </para>
187           <para>
188             <filename>doc/libstdc++/libstdc++-api-single.xml</filename>
189           </para>
190           <para>
191             <filename>doc/libstdc++/libstdc++-manual-single.xml</filename>
192           </para>
193         </listitem>
194       </varlistentry>
195     </variablelist>
196
197     <para>
198       Makefile rules for several other formats are explicitly not
199       supported, and are always aliased to dummy rules. These
200       unsupported formats are: <emphasis>info</emphasis>,
201       <emphasis>ps</emphasis>, and <emphasis>dvi</emphasis>.
202     </para>
203   </section>
204
205   <section xml:id="doc.doxygen"><info><title>Doxygen</title></info>
206     
207     <section xml:id="doxygen.prereq"><info><title>Prerequisites</title></info>
208       
209  <table frame="all">
210 <title>Doxygen Prerequisites</title>
211
212 <tgroup cols="3" align="center" colsep="1" rowsep="1">
213 <colspec colname="c1"/>
214 <colspec colname="c2"/>
215 <colspec colname="c3"/>
216
217   <thead>
218     <row>
219       <entry>Tool</entry>
220       <entry>Version</entry>
221       <entry>Required By</entry>
222     </row>
223   </thead>
224
225   <tbody>
226
227     <row>
228       <entry>coreutils</entry>
229       <entry>8.5</entry>
230       <entry>all</entry>
231     </row>
232
233     <row>
234       <entry>bash</entry>
235       <entry>4.1</entry>
236       <entry>all</entry>
237     </row>
238
239     <row>
240       <entry>doxygen</entry>
241       <entry>1.7.6.1</entry>
242       <entry>all</entry>
243     </row>
244
245     <row>
246       <entry>graphviz</entry>
247       <entry>2.26</entry>
248       <entry>graphical hierarchies</entry>
249     </row>
250
251     <row>
252       <entry>pdflatex</entry>
253       <entry>2007-59</entry>
254       <entry>pdf output</entry>
255     </row>
256
257   </tbody>
258 </tgroup>
259 </table>
260
261
262       <para>
263         Prerequisite tools are Bash 2.0 or later,
264         <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.doxygen.org/">Doxygen</link>, and
265         the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.gnu.org/software/coreutils/">GNU
266         coreutils</link>. (GNU versions of find, xargs, and possibly
267         sed and grep are used, just because the GNU versions make
268         things very easy.) 
269       </para>
270
271       <para>
272         To generate the pretty pictures and hierarchy
273         graphs, the
274         <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.graphviz.org">Graphviz</link> package
275         will need to be installed. For PDF
276         output, <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.tug.org/applications/pdftex/">
277         pdflatex</link> is required.
278       </para>
279
280       <para>
281         Be warned the PDF file generated via doxygen is extremely
282         large. At last count, the PDF file is over three thousand
283         pages. Generating this document taxes the underlying TeX
284         formatting system, and will require the expansion of TeX's memory
285         capacity. Specifically, the <literal>pool_size</literal>
286         variable in the configuration file <filename>texmf.cnf</filename> may
287         need to be increased by a minimum factor of two.
288       </para>
289     </section>
290
291     <section xml:id="doxygen.rules"><info><title>Generating the Doxygen Files</title></info>
292       
293       <para>
294         The following Makefile rules run Doxygen to generate HTML
295         docs, XML docs, XML docs as a single file, PDF docs, and the
296         man pages. These rules are not conditional! If the required
297         tools are not found, or are the wrong versions, the rule may
298         end in an error.
299       </para>
300
301       <para>
302       <screen><userinput>make doc-html-doxygen</userinput></screen>
303       </para>
304
305       <para>
306       <screen><userinput>make doc-xml-doxygen</userinput></screen>
307       </para>
308
309       <para>
310       <screen><userinput>make doc-xml-single-doxygen</userinput></screen>
311       </para>
312
313       <para>
314       <screen><userinput>make doc-pdf-doxygen</userinput></screen>
315       </para>
316
317       <para>
318       <screen><userinput>make doc-man-doxygen</userinput></screen>
319       </para>
320
321       <para>
322         Generated files are output into separate sub directories of
323         <filename class="directory">doc/doxygen/</filename> in the
324         build directory, based on the output format. For instance, the
325         HTML docs will be in <filename class="directory">doc/doxygen/html</filename>.
326       </para>
327
328       <para>
329         Careful observers will see that the Makefile rules simply call
330         a script from the source tree, <filename>run_doxygen</filename>, which
331         does the actual work of running Doxygen and then (most
332         importantly) massaging the output files. If for some reason
333         you prefer to not go through the Makefile, you can call this
334         script directly. (Start by passing <literal>--help</literal>.)
335       </para>
336
337       <para>
338         If you wish to tweak the Doxygen settings, do so by editing
339         <filename>doc/doxygen/user.cfg.in</filename>. Notes to fellow
340         library hackers are written in triple-# comments.
341       </para>
342
343     </section>
344
345  <section xml:id="doxygen.debug">
346    <info><title>Debugging Generation</title></info>
347    
348         <para>
349           Sometimes, mis-configuration of the pre-requisite tools can
350           lead to errors when attempting to build the
351           documentation. Here are some of the obvious errors, and ways
352           to fix some common issues that may appear quite cryptic.
353         </para>
354         
355         <para>
356           First, if using a rule like <code>make pdf</code>, try to
357           narrow down the scope of the error to either docbook
358           (<code>make doc-pdf-docbook</code>) or doxygen (<code>make
359           doc-pdf-doxygen</code>).
360         </para>
361         <para>
362           Working on the doxygen path only, closely examine the
363           contents of the following build directory:
364           <filename>build/target/libstdc++-v3/doc/doxygen/latex</filename>.
365           Pay attention to three files enclosed within, annotated as follows.
366         </para>
367 <itemizedlist>
368
369 <listitem>
370   <para>
371    <emphasis>refman.tex</emphasis>
372   </para>
373
374   <para>
375     The actual latex file, or partial latex file. This is generated
376     via <command>doxygen</command>, and is the LaTeX version of the
377     Doxygen XML file <filename>libstdc++-api.xml</filename>. Go to a specific
378     line, and look at the genrated LaTeX, and try to deduce what
379     markup in <filename>libstdc++-api.xml</filename> is causing it.
380   </para>
381 </listitem>
382
383 <listitem>
384   <para>
385    <emphasis>refman.out</emphasis>
386   </para>
387
388   <para>
389     A log of the compilation of the converted LaTeX form to pdf. This
390     is a linear list, from the beginning of the
391     <filename>refman.tex</filename> file: the last entry of this file
392     should be the end of the LaTeX file. If it is truncated, then you
393     know that the last entry is the last part of the generated LaTeX
394     source file that is valid. Often this file contains an error with
395     a specific line number of <filename>refman.tex</filename> that is
396     incorrect, or will have clues at the end of the file with the dump
397     of the memory usage of LaTeX.
398   </para>
399 </listitem>
400 </itemizedlist>
401
402         <para>
403           If the error at hand is not obvious after examination, a
404           fall-back strategy is to start commenting out the doxygen
405           input sources, which can be found in
406           <filename>doc/doxygen/user.cfg.in</filename>, look for the
407           <literal>INPUT</literal> tag. Start by commenting out whole
408           directories of header files, until the offending header is
409           identified. Then, read the latex log files to try and find
410           surround text, and look for that in the offending header.
411         </para>
412
413  </section>
414
415     <section xml:id="doxygen.markup"><info><title>Markup</title></info>
416       
417
418       <para>
419         In general, libstdc++ files should be formatted according to
420         the rules found in the
421         <link linkend="contrib.coding_style">Coding Standard</link>. Before
422         any doxygen-specific formatting tweaks are made, please try to
423         make sure that the initial formatting is sound.
424       </para>
425
426       <para>
427         Adding Doxygen markup to a file (informally called
428         <quote>doxygenating</quote>) is very simple. The Doxygen manual can be
429         found
430         <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.stack.nl/~dimitri/doxygen/download.html#latestman">here</link>.
431         We try to use a very-recent version of Doxygen.
432       </para>
433
434       <para>
435         For classes, use
436         <classname>deque</classname>/<classname>vector</classname>/<classname>list</classname>
437         and <classname>std::pair</classname> as examples.  For
438         functions, see their member functions, and the free functions
439         in <filename>stl_algobase.h</filename>. Member functions of
440         other container-like types should read similarly to these
441         member functions.
442       </para>
443
444       <para>
445         Some commentary to accompany
446         the first list in the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.stack.nl/~dimitri/doxygen/docblocks.html">Special
447         Documentation Blocks</link> section of
448         the Doxygen manual:
449       </para>
450
451       <orderedlist inheritnum="ignore" continuation="restarts">
452         <listitem>
453           <para>For longer comments, use the Javadoc style...</para>
454         </listitem>
455
456         <listitem>
457           <para>
458             ...not the Qt style. The intermediate *'s are preferred.
459           </para>
460         </listitem>
461
462         <listitem>
463           <para>
464             Use the triple-slash style only for one-line comments (the
465             <quote>brief</quote> mode).
466           </para>
467         </listitem>
468
469         <listitem>
470           <para>
471             This is disgusting. Don't do this.
472           </para>
473         </listitem>
474       </orderedlist>
475
476       <para>
477         Some specific guidelines:
478       </para>
479
480       <para>
481         Use the @-style of commands, not the !-style. Please be
482         careful about whitespace in your markup comments. Most of the
483         time it doesn't matter; doxygen absorbs most whitespace, and
484         both HTML and *roff are agnostic about whitespace. However,
485         in &lt;pre&gt; blocks and @code/@endcode sections, spacing can
486         have <quote>interesting</quote> effects.
487       </para>
488
489       <para>
490         Use either kind of grouping, as
491         appropriate. <filename>doxygroups.cc</filename> exists for this
492         purpose. See <filename>stl_iterator.h</filename> for a good example
493         of the <quote>other</quote> kind of grouping.
494       </para>
495
496       <para>
497         Please use markup tags like @p and @a when referring to things
498         such as the names of function parameters. Use @e for emphasis
499         when necessary. Use @c to refer to other standard names.
500         (Examples of all these abound in the present code.)
501       </para>
502
503       <para>
504         Complicated math functions should use the multi-line
505         format. An example from <filename>random.h</filename>:
506       </para>
507
508       <para>
509 <literallayout class="normal">
510 /**
511  * @brief A model of a linear congruential random number generator.
512  *
513  * @f[
514  *     x_{i+1}\leftarrow(ax_{i} + c) \bmod m
515  * @f]
516  */
517 </literallayout>
518       </para>
519
520       <para>
521         One area of note is the markup required for
522         <literal>@file</literal> markup in header files. Two details
523         are important: for filenames that have the same name in
524         multiple directories, include part of the installed path to
525         disambiguate. For example:
526       </para>
527
528       <para>
529 <literallayout class="normal">
530 /** @file debug/vector
531  *  This file is a GNU debug extension to the Standard C++ Library.
532  */
533 </literallayout>
534       </para>
535
536       <para>
537         The other relevant detail for header files is the use of a
538         libstdc++-specific doxygen alias that helps distinguish
539         between public header files (like <filename>random</filename>)
540         from implementation or private header files (like
541         <filename>bits/c++config.h</filename>.) This alias is spelled
542         <literal>@headername</literal> and can take one or two
543         arguments that detail the public header file or files that
544         should be included to use the contents of the file. All header
545         files that are not intended for direct inclusion must use
546         <literal>headername</literal> in the <literal>file</literal>
547         block. An example:
548       </para>
549
550       <para>
551 <literallayout class="normal">
552 /** @file bits/basic_string.h
553  *  This is an internal header file, included by other library headers.
554  *  Do not attempt to use it directly. @headername{string}
555  */
556 </literallayout>
557       </para>
558
559       <para>
560         Be careful about using certain, special characters when
561         writing Doxygen comments. Single and double quotes, and
562         separators in filenames are two common trouble spots. When in
563         doubt, consult the following table.
564       </para>
565
566 <table frame="all">
567 <title>HTML to Doxygen Markup Comparison</title>
568
569 <tgroup cols="2" align="left" colsep="1" rowsep="1">
570 <colspec colname="c1"/>
571 <colspec colname="c2"/>
572
573   <thead>
574     <row>
575       <entry>HTML</entry>
576       <entry>Doxygen</entry>
577     </row>
578   </thead>
579
580   <tbody>
581     <row>
582       <entry>\</entry>
583       <entry>\\</entry>
584     </row>
585
586     <row>
587       <entry>"</entry>
588       <entry>\"</entry>
589     </row>
590
591     <row>
592       <entry>'</entry>
593       <entry>\'</entry>
594     </row>
595
596     <row>
597       <entry>&lt;i&gt;</entry>
598       <entry>@a word</entry>
599     </row>
600
601     <row>
602       <entry>&lt;b&gt;</entry>
603       <entry>@b word</entry>
604     </row>
605
606     <row>
607       <entry>&lt;code&gt;</entry>
608       <entry>@c word</entry>
609     </row>
610
611     <row>
612       <entry>&lt;em&gt;</entry>
613       <entry>@a word</entry>
614     </row>
615
616     <row>
617       <entry>&lt;em&gt;</entry>
618       <entry>&lt;em&gt;two words or more&lt;/em&gt;</entry>
619     </row>
620   </tbody>
621
622 </tgroup>
623 </table>
624
625
626     </section>
627
628   </section>
629
630   <section xml:id="doc.docbook"><info><title>Docbook</title></info>
631     
632
633     <section xml:id="docbook.prereq"><info><title>Prerequisites</title></info>
634       
635       
636  <table frame="all">
637 <title>Docbook Prerequisites</title>
638
639 <tgroup cols="3" align="center" colsep="1" rowsep="1">
640 <colspec colname="c1"/>
641 <colspec colname="c2"/>
642 <colspec colname="c3"/>
643
644   <thead>
645     <row>
646       <entry>Tool</entry>
647       <entry>Version</entry>
648       <entry>Required By</entry>
649     </row>
650   </thead>
651
652   <tbody>
653
654     <row>
655       <entry>docbook5-style-xsl</entry>
656       <entry>1.76.1</entry>
657       <entry>all</entry>
658     </row>
659
660     <row>
661       <entry>xsltproc</entry>
662       <entry>1.1.26</entry>
663       <entry>all</entry>
664     </row>
665
666     <row>
667       <entry>xmllint</entry>
668       <entry>2.7.7</entry>
669       <entry>validation</entry>
670     </row>
671
672     <row>
673       <entry>dblatex</entry>
674       <entry>0.3</entry>
675       <entry>pdf output</entry>
676     </row>
677
678     <row>
679       <entry>pdflatex</entry>
680       <entry>2007-59</entry>
681       <entry>pdf output</entry>
682     </row>
683
684     <row>
685       <entry>docbook2X</entry>
686       <entry>0.8.8</entry>
687       <entry>info output</entry>
688     </row>
689
690     <row>
691       <entry>epub3 stylesheets</entry>
692       <entry>b3</entry>
693       <entry>epub output</entry>
694     </row>
695
696   </tbody>
697 </tgroup>
698 </table>
699
700       <para>
701         Editing the DocBook sources requires an XML editor. Many
702         exist: some notable options
703         include <command>emacs</command>, <application>Kate</application>,
704         or <application>Conglomerate</application>.
705       </para>
706
707       <para>
708         Some editors support special <quote>XML Validation</quote>
709         modes that can validate the file as it is
710         produced. Recommended is the <command>nXML Mode</command>
711         for <command>emacs</command>.
712       </para>
713
714       <para>
715         Besides an editor, additional DocBook files and XML tools are
716         also required.
717       </para>
718
719       <para>
720         Access to the DocBook 5.0 stylesheets and schema is required. The
721         stylesheets are usually packaged by vendor, in something
722         like <filename>docbook5-style-xsl</filename>. To exactly match
723         generated output, please use a version of the stylesheets
724         equivalent
725         to <filename>docbook5-style-xsl-1.75.2-3</filename>. The
726         installation directory for this package corresponds to
727         the <literal>XSL_STYLE_DIR</literal>
728         in <filename>doc/Makefile.am</filename> and defaults
729         to <filename class="directory">/usr/share/sgml/docbook/xsl-ns-stylesheets</filename>.
730       </para>
731
732       <para>
733         For processing XML, an XSLT processor and some style
734         sheets are necessary. Defaults are <command>xsltproc</command>
735         provided by <filename>libxslt</filename>.
736       </para>
737
738       <para>
739         For validating the XML document, you'll need
740         something like <command>xmllint</command> and access to the
741         relevant DocBook schema. These are provided
742         by a vendor package like <filename>libxml2</filename> and <filename>docbook5-schemas-5.0-4</filename>
743       </para>
744
745       <para>
746         For PDF output, something that transforms valid Docbook XML to PDF is
747         required. Possible solutions include <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://dblatex.sourceforge.net">dblatex</link>,
748         <command>xmlto</command>, or <command>prince</command>. Of
749         these, <command>dblatex</command> is the default. Other
750         options are listed on the DocBook web <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://wiki.docbook.org/topic/DocBookPublishingTools">pages</link>. Please
751         consult the <email>libstdc++@gcc.gnu.org</email> list when
752         preparing printed manuals for current best practice and
753         suggestions.
754       </para>
755
756       <para>
757         For Texinfo output, something that transforms valid Docbook
758         XML to Texinfo is required. The default choice is <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://docbook2x.sourceforge.net/">docbook2X</link>.
759       </para>
760
761       <para>
762         For epub output, the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://sourceforge.net/projects/docbook/files/epub3/">stylesheets</link> for EPUB3 are required. These stylesheets are still in development. To validate the created file, <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://code.google.com/p/epubcheck/">epubcheck</link> is necessary.
763       </para>
764     </section>
765
766     <section xml:id="docbook.rules"><info><title>Generating the DocBook Files</title></info>
767       
768
769       <para>
770         The following Makefile rules generate (in order): an HTML
771         version of all the DocBook documentation, a PDF version of the
772         same, and a single XML document.  These rules are not
773         conditional! If the required tools are not found, or are the
774         wrong versions, the rule may end in an error.
775       </para>
776
777       <para>
778       <screen><userinput>make doc-html-docbook</userinput></screen>
779       </para>
780
781       <para>
782       <screen><userinput>make doc-pdf-docbook</userinput></screen>
783       </para>
784
785       <para>
786       <screen><userinput>make doc-xml-single-docbook</userinput></screen>
787       </para>
788
789       <para>
790         Generated files are output into separate sub directores of
791         <filename class="directory">doc/docbook/</filename> in the
792         build directory, based on the output format. For instance, the
793         HTML docs will be in <filename
794         class="directory">doc/docbook/html</filename>.
795       </para>
796
797       <para>
798         If the Docbook stylesheets are installed in a custom location,
799         one can use the variable <literal>XSL_STYLE_DIR</literal> to
800         override the Makefile defaults. For example:
801       </para>
802
803       <screen>
804         <userinput>
805 make <literal>XSL_STYLE_DIR="/usr/share/xml/docbook/stylesheet/nwalsh"</literal> doc-html-docbook
806         </userinput>
807       </screen>
808
809       </section>
810
811     <section xml:id="docbook.debug">
812         <info><title>Debugging Generation</title></info>
813
814         <para>
815           Sometimes, mis-configuration of the pre-requisite tools can
816           lead to errors when attempting to build the
817           documentation. Here are some of the obvious errors, and ways
818           to fix some common issues that may appear quite cryptic.
819         </para>
820         
821         <para>
822           First, if using a rule like <code>make pdf</code>, try to
823           narrow down the scope of the error to either docbook
824           (<code>make doc-pdf-docbook</code>) or doxygen (<code>make
825           doc-pdf-doxygen</code>).
826         </para>
827
828         <para>
829           Working on the docbook path only, closely examine the
830           contents of the following build directory:
831           <filename>build/target/libstdc++-v3/doc/docbook/latex</filename>.
832           Pay attention to three files enclosed within, annotated as follows.
833         </para>
834
835 <itemizedlist>
836
837 <listitem>
838   <para>
839    <emphasis>spine.tex</emphasis>
840   </para>
841
842   <para>
843     The actual latex file, or partial latex file. This is generated
844     via <command>dblatex</command>, and is the LaTeX version of the
845     DocBook XML file <filename>spine.xml</filename>. Go to a specific
846     line, and look at the genrated LaTeX, and try to deduce what
847     markup in <filename>spine.xml</filename> is causing it.
848   </para>
849 </listitem>
850
851 <listitem>
852   <para>
853    <emphasis>spine.out</emphasis>
854   </para>
855
856   <para>
857     A log of the conversion from the XML form to the LaTeX form. This
858     is a linear list, from the beginning of the
859     <filename>spine.xml</filename> file: the last entry of this file
860     should be the end of the DocBook file. If it is truncated, then
861     you know that the last entry is the last part of the XML source
862     file that is valid. The error is after this point.
863   </para>
864 </listitem>
865
866
867 <listitem>
868   <para>
869    <emphasis>spine.log</emphasis>
870   </para>
871
872   <para>
873     A log of the compilation of the converted LaTeX form to pdf. This
874     is a linear list, from the beginning of the
875     <filename>spine.tex</filename> file: the last entry of this file
876     should be the end of the LaTeX file. If it is truncated, then you
877     know that the last entry is the last part of the generated LaTeX
878     source file that is valid. Often this file contains an error with
879     a specific line number of <filename>spine.tex</filename> that is
880     incorrect.
881   </para>
882 </listitem>
883
884 </itemizedlist>
885
886         <para>
887           If the error at hand is not obvious after examination, or if one
888           encounters the inscruitable <quote>Incomplete
889           \ifmmode</quote> error, a fall-back strategy is to start
890           commenting out parts of the XML document (regardless of what
891           this does to over-all document validity). Start by
892           commenting out each of the largest parts of the
893           <filename>spine.xml</filename> file, section by section,
894           until the offending section is identified.
895         </para>
896
897
898     </section>
899
900     <section xml:id="docbook.validation"><info><title>Editing and Validation</title></info>
901
902       <para>
903         After editing the xml sources, please make sure that the XML
904         documentation and markup is still valid. This can be
905         done easily, with the following validation rule:
906       </para>
907
908       <screen>
909         <userinput>make doc-xml-validate-docbook</userinput>
910       </screen>
911
912       <para>
913         This is equivalent to doing:
914       </para>
915       
916       <screen>
917         <userinput>
918           xmllint --noout --valid <filename>xml/index.xml</filename>
919         </userinput>
920       </screen>
921
922       <para>
923         Please note that individual sections and chapters of the
924         manual can be validated by substituting the file desired for
925         <filename>xml/index.xml</filename> in the command
926         above. Reducing scope in this manner can be helpful when
927         validation on the entire manual fails.
928       </para>
929
930       <para>
931         All Docbook xml sources should always validate. No excuses!
932       </para>
933
934     </section>
935
936     <section xml:id="docbook.examples"><info><title>File Organization and Basics</title></info>
937       
938
939     <literallayout class="normal">
940       <emphasis>Which files are important</emphasis>
941
942       All Docbook files are in the directory
943       libstdc++-v3/doc/xml
944
945       Inside this directory, the files of importance:
946       spine.xml         - index to documentation set
947       manual/spine.xml  - index to manual
948       manual/*.xml      - individual chapters and sections of the manual
949       faq.xml           - index to FAQ
950       api.xml           - index to source level / API
951
952       All *.txml files are template xml files, i.e., otherwise empty files with
953       the correct structure, suitable for filling in with new information.
954
955       <emphasis>Canonical Writing Style</emphasis>
956
957       class template
958       function template
959       member function template
960       (via C++ Templates, Vandevoorde)
961
962       class in namespace std: allocator, not std::allocator
963
964       header file: iostream, not &lt;iostream&gt;
965
966
967       <emphasis>General structure</emphasis>
968
969       &lt;set&gt;
970       &lt;book&gt;
971       &lt;/book&gt;
972
973       &lt;book&gt;
974       &lt;chapter&gt;
975       &lt;/chapter&gt;
976       &lt;/book&gt;
977
978       &lt;book&gt;
979       &lt;part&gt;
980       &lt;chapter&gt;
981       &lt;section&gt;
982       &lt;/section&gt;
983
984       &lt;sect1&gt;
985       &lt;/sect1&gt;
986
987       &lt;sect1&gt;
988       &lt;sect2&gt;
989       &lt;/sect2&gt;
990       &lt;/sect1&gt;
991       &lt;/chapter&gt;
992
993       &lt;chapter&gt;
994       &lt;/chapter&gt;
995       &lt;/part&gt;
996       &lt;/book&gt;
997
998       &lt;/set&gt;
999     </literallayout>
1000     </section>
1001
1002     <section xml:id="docbook.markup"><info><title>Markup By Example</title></info>
1003       
1004
1005       <para>
1006         Complete details on Docbook markup can be found in the DocBook
1007         Element Reference,
1008         <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.docbook.org/tdg/en/html/part2.html">online</link>.
1009         An incomplete reference for HTML to Docbook conversion is
1010         detailed in the table below.
1011       </para>
1012
1013 <table frame="all">
1014 <title>HTML to Docbook XML Markup Comparison</title>
1015
1016 <tgroup cols="2" align="left" colsep="1" rowsep="1">
1017 <colspec colname="c1"/>
1018 <colspec colname="c2"/>
1019
1020   <thead>
1021     <row>
1022       <entry>HTML</entry>
1023       <entry>Docbook</entry>
1024     </row>
1025   </thead>
1026
1027   <tbody>
1028     <row>
1029       <entry>&lt;p&gt;</entry>
1030       <entry>&lt;para&gt;</entry>
1031     </row>
1032     <row>
1033       <entry>&lt;pre&gt;</entry>
1034       <entry>&lt;computeroutput&gt;, &lt;programlisting&gt;,
1035         &lt;literallayout&gt;</entry>
1036     </row>
1037     <row>
1038       <entry>&lt;ul&gt;</entry>
1039       <entry>&lt;itemizedlist&gt;</entry>
1040     </row>
1041     <row>
1042       <entry>&lt;ol&gt;</entry>
1043       <entry>&lt;orderedlist&gt;</entry>
1044     </row>
1045     <row>
1046       <entry>&lt;il&gt;</entry>
1047       <entry>&lt;listitem&gt;</entry>
1048     </row>
1049     <row>
1050       <entry>&lt;dl&gt;</entry>
1051       <entry>&lt;variablelist&gt;</entry>
1052     </row>
1053     <row>
1054       <entry>&lt;dt&gt;</entry>
1055       <entry>&lt;term&gt;</entry>
1056     </row>
1057     <row>
1058       <entry>&lt;dd&gt;</entry>
1059       <entry>&lt;listitem&gt;</entry>
1060     </row>
1061
1062     <row>
1063       <entry>&lt;a href=""&gt;</entry>
1064       <entry>&lt;ulink url=""&gt;</entry>
1065     </row>
1066     <row>
1067       <entry>&lt;code&gt;</entry>
1068       <entry>&lt;literal&gt;, &lt;programlisting&gt;</entry>
1069     </row>
1070     <row>
1071       <entry>&lt;strong&gt;</entry>
1072       <entry>&lt;emphasis&gt;</entry>
1073     </row>
1074     <row>
1075       <entry>&lt;em&gt;</entry>
1076       <entry>&lt;emphasis&gt;</entry>
1077     </row>
1078     <row>
1079       <entry>"</entry>
1080       <entry>&lt;quote&gt;</entry>
1081     </row>
1082    </tbody>
1083 </tgroup>
1084 </table>
1085
1086 <para>
1087   And examples of detailed markup for which there are no real HTML
1088   equivalents are listed in the table below.
1089 </para>
1090
1091 <table frame="all">
1092 <title>Docbook XML Element Use</title>
1093
1094 <tgroup cols="2" align="left" colsep="1" rowsep="1">
1095 <colspec colname="c1"/>
1096 <colspec colname="c2"/>
1097
1098   <thead>
1099     <row>
1100       <entry>Element</entry>
1101       <entry>Use</entry>
1102     </row>
1103   </thead>
1104
1105   <tbody>
1106     <row>
1107       <entry>&lt;structname&gt;</entry>
1108       <entry>&lt;structname&gt;char_traits&lt;/structname&gt;</entry>
1109     </row>
1110     <row>
1111       <entry>&lt;classname&gt;</entry>
1112       <entry>&lt;classname&gt;string&lt;/classname&gt;</entry>
1113     </row>
1114     <row>
1115       <entry>&lt;function&gt;</entry>
1116       <entry>
1117         <para>&lt;function&gt;clear()&lt;/function&gt;</para>
1118         <para>&lt;function&gt;fs.clear()&lt;/function&gt;</para>
1119       </entry>
1120     </row>
1121     <row>
1122       <entry>&lt;type&gt;</entry>
1123       <entry>&lt;type&gt;long long&lt;/type&gt;</entry>
1124     </row>
1125     <row>
1126       <entry>&lt;varname&gt;</entry>
1127       <entry>&lt;varname&gt;fs&lt;/varname&gt;</entry>
1128     </row>
1129     <row>
1130       <entry>&lt;literal&gt;</entry>
1131       <entry>
1132         <para>&lt;literal&gt;-Weffc++&lt;/literal&gt;</para>
1133         <para>&lt;literal&gt;rel_ops&lt;/literal&gt;</para>
1134       </entry>
1135     </row>
1136     <row>
1137       <entry>&lt;constant&gt;</entry>
1138       <entry>
1139         <para>&lt;constant&gt;_GNU_SOURCE&lt;/constant&gt;</para>
1140         <para>&lt;constant&gt;3.0&lt;/constant&gt;</para>
1141       </entry>
1142     </row>
1143     <row>
1144       <entry>&lt;command&gt;</entry>
1145       <entry>&lt;command&gt;g++&lt;/command&gt;</entry>
1146     </row>
1147     <row>
1148       <entry>&lt;errortext&gt;</entry>
1149       <entry>&lt;errortext&gt;In instantiation of&lt;/errortext&gt;</entry>
1150     </row>
1151     <row>
1152       <entry>&lt;filename&gt;</entry>
1153       <entry>
1154         <para>&lt;filename class="headerfile"&gt;ctype.h&lt;/filename&gt;</para>
1155         <para>&lt;filename class="directory"&gt;/home/gcc/build&lt;/filename&gt;</para>
1156         <para>&lt;filename class="libraryfile"&gt;libstdc++.so&lt;/filename&gt;</para>
1157       </entry>
1158     </row>
1159    </tbody>
1160 </tgroup>
1161 </table>
1162
1163 </section>
1164 </section>
1165 </section>