OSDN Git Service

2012-12-10 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     A log of the compilation of the converted LaTeX form to pdf. This
388     is a linear list, from the beginning of the
389     <filename>refman.tex</filename> file: the last entry of this file
390     should be the end of the LaTeX file. If it is truncated, then you
391     know that the last entry is the last part of the generated LaTeX
392     source file that is valid. Often this file contains an error with
393     a specific line number of <filename>refman.tex</filename> that is
394     incorrect, or will have clues at the end of the file with the dump
395     of the memory usage of LaTeX.
396   </para>
397   </para>
398 </listitem>
399 </itemizedlist>
400
401  </section>
402
403     <section xml:id="doxygen.markup"><info><title>Markup</title></info>
404       
405
406       <para>
407         In general, libstdc++ files should be formatted according to
408         the rules found in the
409         <link linkend="contrib.coding_style">Coding Standard</link>. Before
410         any doxygen-specific formatting tweaks are made, please try to
411         make sure that the initial formatting is sound.
412       </para>
413
414       <para>
415         Adding Doxygen markup to a file (informally called
416         <quote>doxygenating</quote>) is very simple. The Doxygen manual can be
417         found
418         <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.stack.nl/~dimitri/doxygen/download.html#latestman">here</link>.
419         We try to use a very-recent version of Doxygen.
420       </para>
421
422       <para>
423         For classes, use
424         <classname>deque</classname>/<classname>vector</classname>/<classname>list</classname>
425         and <classname>std::pair</classname> as examples.  For
426         functions, see their member functions, and the free functions
427         in <filename>stl_algobase.h</filename>. Member functions of
428         other container-like types should read similarly to these
429         member functions.
430       </para>
431
432       <para>
433         Some commentary to accompany
434         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
435         Documentation Blocks</link> section of
436         the Doxygen manual:
437       </para>
438
439       <orderedlist inheritnum="ignore" continuation="restarts">
440         <listitem>
441           <para>For longer comments, use the Javadoc style...</para>
442         </listitem>
443
444         <listitem>
445           <para>
446             ...not the Qt style. The intermediate *'s are preferred.
447           </para>
448         </listitem>
449
450         <listitem>
451           <para>
452             Use the triple-slash style only for one-line comments (the
453             <quote>brief</quote> mode).
454           </para>
455         </listitem>
456
457         <listitem>
458           <para>
459             This is disgusting. Don't do this.
460           </para>
461         </listitem>
462       </orderedlist>
463
464       <para>
465         Some specific guidelines:
466       </para>
467
468       <para>
469         Use the @-style of commands, not the !-style. Please be
470         careful about whitespace in your markup comments. Most of the
471         time it doesn't matter; doxygen absorbs most whitespace, and
472         both HTML and *roff are agnostic about whitespace. However,
473         in &lt;pre&gt; blocks and @code/@endcode sections, spacing can
474         have <quote>interesting</quote> effects.
475       </para>
476
477       <para>
478         Use either kind of grouping, as
479         appropriate. <filename>doxygroups.cc</filename> exists for this
480         purpose. See <filename>stl_iterator.h</filename> for a good example
481         of the <quote>other</quote> kind of grouping.
482       </para>
483
484       <para>
485         Please use markup tags like @p and @a when referring to things
486         such as the names of function parameters. Use @e for emphasis
487         when necessary. Use @c to refer to other standard names.
488         (Examples of all these abound in the present code.)
489       </para>
490
491       <para>
492         Complicated math functions should use the multi-line
493         format. An example from <filename>random.h</filename>:
494       </para>
495
496       <para>
497 <literallayout class="normal">
498 /**
499  * @brief A model of a linear congruential random number generator.
500  *
501  * @f[
502  *     x_{i+1}\leftarrow(ax_{i} + c) \bmod m
503  * @f]
504  */
505 </literallayout>
506       </para>
507
508       <para>
509         One area of note is the markup required for
510         <literal>@file</literal> markup in header files. Two details
511         are important: for filenames that have the same name in
512         multiple directories, include part of the installed path to
513         disambiguate. For example:
514       </para>
515
516       <para>
517 <literallayout class="normal">
518 /** @file debug/vector
519  *  This file is a GNU debug extension to the Standard C++ Library.
520  */
521 </literallayout>
522       </para>
523
524       <para>
525         The other relevant detail for header files is the use of a
526         libstdc++-specific doxygen alias that helps distinguish
527         between public header files (like <filename>random</filename>)
528         from implementation or private header files (like
529         <filename>bits/c++config.h</filename>.) This alias is spelled
530         <literal>@headername</literal> and can take one or two
531         arguments that detail the public header file or files that
532         should be included to use the contents of the file. All header
533         files that are not intended for direct inclusion must use
534         <literal>headername</literal> in the <literal>file</literal>
535         block. An example:
536       </para>
537
538       <para>
539 <literallayout class="normal">
540 /** @file bits/basic_string.h
541  *  This is an internal header file, included by other library headers.
542  *  Do not attempt to use it directly. @headername{string}
543  */
544 </literallayout>
545       </para>
546
547       <para>
548         Be careful about using certain, special characters when
549         writing Doxygen comments. Single and double quotes, and
550         separators in filenames are two common trouble spots. When in
551         doubt, consult the following table.
552       </para>
553
554 <table frame="all">
555 <title>HTML to Doxygen Markup Comparison</title>
556
557 <tgroup cols="2" align="left" colsep="1" rowsep="1">
558 <colspec colname="c1"/>
559 <colspec colname="c2"/>
560
561   <thead>
562     <row>
563       <entry>HTML</entry>
564       <entry>Doxygen</entry>
565     </row>
566   </thead>
567
568   <tbody>
569     <row>
570       <entry>\</entry>
571       <entry>\\</entry>
572     </row>
573
574     <row>
575       <entry>"</entry>
576       <entry>\"</entry>
577     </row>
578
579     <row>
580       <entry>'</entry>
581       <entry>\'</entry>
582     </row>
583
584     <row>
585       <entry>&lt;i&gt;</entry>
586       <entry>@a word</entry>
587     </row>
588
589     <row>
590       <entry>&lt;b&gt;</entry>
591       <entry>@b word</entry>
592     </row>
593
594     <row>
595       <entry>&lt;code&gt;</entry>
596       <entry>@c word</entry>
597     </row>
598
599     <row>
600       <entry>&lt;em&gt;</entry>
601       <entry>@a word</entry>
602     </row>
603
604     <row>
605       <entry>&lt;em&gt;</entry>
606       <entry>&lt;em&gt;two words or more&lt;/em&gt;</entry>
607     </row>
608   </tbody>
609
610 </tgroup>
611 </table>
612
613
614     </section>
615
616   </section>
617
618   <section xml:id="doc.docbook"><info><title>Docbook</title></info>
619     
620
621     <section xml:id="docbook.prereq"><info><title>Prerequisites</title></info>
622       
623       
624  <table frame="all">
625 <title>Docbook Prerequisites</title>
626
627 <tgroup cols="3" align="center" colsep="1" rowsep="1">
628 <colspec colname="c1"/>
629 <colspec colname="c2"/>
630 <colspec colname="c3"/>
631
632   <thead>
633     <row>
634       <entry>Tool</entry>
635       <entry>Version</entry>
636       <entry>Required By</entry>
637     </row>
638   </thead>
639
640   <tbody>
641
642     <row>
643       <entry>docbook5-style-xsl</entry>
644       <entry>1.76.1</entry>
645       <entry>all</entry>
646     </row>
647
648     <row>
649       <entry>xsltproc</entry>
650       <entry>1.1.26</entry>
651       <entry>all</entry>
652     </row>
653
654     <row>
655       <entry>xmllint</entry>
656       <entry>2.7.7</entry>
657       <entry>validation</entry>
658     </row>
659
660     <row>
661       <entry>dblatex</entry>
662       <entry>0.3</entry>
663       <entry>pdf output</entry>
664     </row>
665
666     <row>
667       <entry>pdflatex</entry>
668       <entry>2007-59</entry>
669       <entry>pdf output</entry>
670     </row>
671
672     <row>
673       <entry>docbook2X</entry>
674       <entry>0.8.8</entry>
675       <entry>info output</entry>
676     </row>
677
678     <row>
679       <entry>epub3 stylesheets</entry>
680       <entry>b3</entry>
681       <entry>epub output</entry>
682     </row>
683
684   </tbody>
685 </tgroup>
686 </table>
687
688       <para>
689         Editing the DocBook sources requires an XML editor. Many
690         exist: some notable options
691         include <command>emacs</command>, <application>Kate</application>,
692         or <application>Conglomerate</application>.
693       </para>
694
695       <para>
696         Some editors support special <quote>XML Validation</quote>
697         modes that can validate the file as it is
698         produced. Recommended is the <command>nXML Mode</command>
699         for <command>emacs</command>.
700       </para>
701
702       <para>
703         Besides an editor, additional DocBook files and XML tools are
704         also required.
705       </para>
706
707       <para>
708         Access to the DocBook 5.0 stylesheets and schema is required. The
709         stylesheets are usually packaged by vendor, in something
710         like <filename>docbook5-style-xsl</filename>. To exactly match
711         generated output, please use a version of the stylesheets
712         equivalent
713         to <filename>docbook5-style-xsl-1.75.2-3</filename>. The
714         installation directory for this package corresponds to
715         the <literal>XSL_STYLE_DIR</literal>
716         in <filename>doc/Makefile.am</filename> and defaults
717         to <filename class="directory">/usr/share/sgml/docbook/xsl-ns-stylesheets</filename>.
718       </para>
719
720       <para>
721         For processing XML, an XSLT processor and some style
722         sheets are necessary. Defaults are <command>xsltproc</command>
723         provided by <filename>libxslt</filename>.
724       </para>
725
726       <para>
727         For validating the XML document, you'll need
728         something like <command>xmllint</command> and access to the
729         relevant DocBook schema. These are provided
730         by a vendor package like <filename>libxml2</filename> and <filename>docbook5-schemas-5.0-4</filename>
731       </para>
732
733       <para>
734         For PDF output, something that transforms valid Docbook XML to PDF is
735         required. Possible solutions include <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://dblatex.sourceforge.net">dblatex</link>,
736         <command>xmlto</command>, or <command>prince</command>. Of
737         these, <command>dblatex</command> is the default. Other
738         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
739         consult the <email>libstdc++@gcc.gnu.org</email> list when
740         preparing printed manuals for current best practice and
741         suggestions.
742       </para>
743
744       <para>
745         For Texinfo output, something that transforms valid Docbook
746         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>.
747       </para>
748
749       <para>
750         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.
751       </para>
752     </section>
753
754     <section xml:id="docbook.rules"><info><title>Generating the DocBook Files</title></info>
755       
756
757       <para>
758         The following Makefile rules generate (in order): an HTML
759         version of all the DocBook documentation, a PDF version of the
760         same, and a single XML document.  These rules are not
761         conditional! If the required tools are not found, or are the
762         wrong versions, the rule may end in an error.
763       </para>
764
765       <para>
766       <screen><userinput>make doc-html-docbook</userinput></screen>
767       </para>
768
769       <para>
770       <screen><userinput>make doc-pdf-docbook</userinput></screen>
771       </para>
772
773       <para>
774       <screen><userinput>make doc-xml-single-docbook</userinput></screen>
775       </para>
776
777       <para>
778         Generated files are output into separate sub directores of
779         <filename class="directory">doc/docbook/</filename> in the
780         build directory, based on the output format. For instance, the
781         HTML docs will be in <filename
782         class="directory">doc/docbook/html</filename>.
783       </para>
784
785       <para>
786         If the Docbook stylesheets are installed in a custom location,
787         one can use the variable <literal>XSL_STYLE_DIR</literal> to
788         override the Makefile defaults. For example:
789       </para>
790
791       <screen>
792         <userinput>
793 make <literal>XSL_STYLE_DIR="/usr/share/xml/docbook/stylesheet/nwalsh"</literal> doc-html-docbook
794         </userinput>
795       </screen>
796
797       </section>
798
799     <section xml:id="docbook.debug">
800         <info><title>Debugging Generation</title></info>
801
802         <para>
803           Sometimes, mis-configuration of the pre-requisite tools can
804           lead to errors when attempting to build the
805           documentation. Here are some of the obvious errors, and ways
806           to fix some common issues that may appear quite cryptic.
807         </para>
808         
809         <para>
810           First, if using a rule like <code>make pdf</code>, try to
811           narrow down the scope of the error to either docbook
812           (<code>make doc-pdf-docbook</code>) or doxygen (<code>make
813           doc-pdf-doxygen</code>).
814         </para>
815
816         <para>
817           Working on the docbook path only, closely examine the
818           contents of the following build directory:
819           <filename>build/target/libstdc++-v3/doc/docbook/latex</filename>.
820           Pay attention to three files enclosed within, annotated as follows.
821         </para>
822
823 <itemizedlist>
824
825 <listitem>
826   <para>
827    <emphasis>spine.tex</emphasis>
828   </para>
829
830   <para>
831     The actual latex file, or partial latex file. This is generated
832     via <command>dblatex</command>, and is the LaTeX version of the
833     DocBook XML file <filename>spine.xml</filename>. Go to a specific
834     line, and look at the genrated LaTeX, and try to deduce what
835     markup in <filename>spine.xml</filename> is causing it.
836   </para>
837 </listitem>
838
839 <listitem>
840   <para>
841    <emphasis>spine.out</emphasis>
842   </para>
843
844   <para>
845     A log of the conversion from the XML form to the LaTeX form. This
846     is a linear list, from the beginning of the
847     <filename>spine.xml</filename> file: the last entry of this file
848     should be the end of the DocBook file. If it is truncated, then
849     you know that the last entry is the last part of the XML source
850     file that is valid. The error is after this point.
851   </para>
852 </listitem>
853
854
855 <listitem>
856   <para>
857    <emphasis>spine.log</emphasis>
858   </para>
859
860   <para>
861     A log of the compilation of the converted LaTeX form to pdf. This
862     is a linear list, from the beginning of the
863     <filename>spine.tex</filename> file: the last entry of this file
864     should be the end of the LaTeX file. If it is truncated, then you
865     know that the last entry is the last part of the generated LaTeX
866     source file that is valid. Often this file contains an error with
867     a specific line number of <filename>spine.tex</filename> that is
868     incorrect.
869   </para>
870 </listitem>
871
872 </itemizedlist>
873
874         <para>
875           If the issue is not obvious after examination, or if one
876           encounters the inscruitable <quote>Incomplete
877           \ifmmode</quote> error, a fall-back strategy is to start
878           commenting out parts of the XML document (regardless of what
879           this does to over-all document validity). Start by
880           commenting out each of the largest parts of the
881           <filename>spine.xml</filename> file, section by section,
882           until the offending section is identified.
883         </para>
884
885
886     </section>
887
888     <section xml:id="docbook.validation"><info><title>Editing and Validation</title></info>
889
890       <para>
891         After editing the xml sources, please make sure that the XML
892         documentation and markup is still valid. This can be
893         done easily, with the following validation rule:
894       </para>
895
896       <screen>
897         <userinput>make doc-xml-validate-docbook</userinput>
898       </screen>
899
900       <para>
901         This is equivalent to doing:
902       </para>
903       
904       <screen>
905         <userinput>
906           xmllint --noout --valid <filename>xml/index.xml</filename>
907         </userinput>
908       </screen>
909
910       <para>
911         Please note that individual sections and chapters of the
912         manual can be validated by substituting the file desired for
913         <filename>xml/index.xml</filename> in the command
914         above. Reducing scope in this manner can be helpful when
915         validation on the entire manual fails.
916       </para>
917
918       <para>
919         All Docbook xml sources should always validate. No excuses!
920       </para>
921
922     </section>
923
924     <section xml:id="docbook.examples"><info><title>File Organization and Basics</title></info>
925       
926
927     <literallayout class="normal">
928       <emphasis>Which files are important</emphasis>
929
930       All Docbook files are in the directory
931       libstdc++-v3/doc/xml
932
933       Inside this directory, the files of importance:
934       spine.xml         - index to documentation set
935       manual/spine.xml  - index to manual
936       manual/*.xml      - individual chapters and sections of the manual
937       faq.xml           - index to FAQ
938       api.xml           - index to source level / API
939
940       All *.txml files are template xml files, i.e., otherwise empty files with
941       the correct structure, suitable for filling in with new information.
942
943       <emphasis>Canonical Writing Style</emphasis>
944
945       class template
946       function template
947       member function template
948       (via C++ Templates, Vandevoorde)
949
950       class in namespace std: allocator, not std::allocator
951
952       header file: iostream, not &lt;iostream&gt;
953
954
955       <emphasis>General structure</emphasis>
956
957       &lt;set&gt;
958       &lt;book&gt;
959       &lt;/book&gt;
960
961       &lt;book&gt;
962       &lt;chapter&gt;
963       &lt;/chapter&gt;
964       &lt;/book&gt;
965
966       &lt;book&gt;
967       &lt;part&gt;
968       &lt;chapter&gt;
969       &lt;section&gt;
970       &lt;/section&gt;
971
972       &lt;sect1&gt;
973       &lt;/sect1&gt;
974
975       &lt;sect1&gt;
976       &lt;sect2&gt;
977       &lt;/sect2&gt;
978       &lt;/sect1&gt;
979       &lt;/chapter&gt;
980
981       &lt;chapter&gt;
982       &lt;/chapter&gt;
983       &lt;/part&gt;
984       &lt;/book&gt;
985
986       &lt;/set&gt;
987     </literallayout>
988     </section>
989
990     <section xml:id="docbook.markup"><info><title>Markup By Example</title></info>
991       
992
993       <para>
994         Complete details on Docbook markup can be found in the DocBook
995         Element Reference,
996         <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.docbook.org/tdg/en/html/part2.html">online</link>.
997         An incomplete reference for HTML to Docbook conversion is
998         detailed in the table below.
999       </para>
1000
1001 <table frame="all">
1002 <title>HTML to Docbook XML Markup Comparison</title>
1003
1004 <tgroup cols="2" align="left" colsep="1" rowsep="1">
1005 <colspec colname="c1"/>
1006 <colspec colname="c2"/>
1007
1008   <thead>
1009     <row>
1010       <entry>HTML</entry>
1011       <entry>Docbook</entry>
1012     </row>
1013   </thead>
1014
1015   <tbody>
1016     <row>
1017       <entry>&lt;p&gt;</entry>
1018       <entry>&lt;para&gt;</entry>
1019     </row>
1020     <row>
1021       <entry>&lt;pre&gt;</entry>
1022       <entry>&lt;computeroutput&gt;, &lt;programlisting&gt;,
1023         &lt;literallayout&gt;</entry>
1024     </row>
1025     <row>
1026       <entry>&lt;ul&gt;</entry>
1027       <entry>&lt;itemizedlist&gt;</entry>
1028     </row>
1029     <row>
1030       <entry>&lt;ol&gt;</entry>
1031       <entry>&lt;orderedlist&gt;</entry>
1032     </row>
1033     <row>
1034       <entry>&lt;il&gt;</entry>
1035       <entry>&lt;listitem&gt;</entry>
1036     </row>
1037     <row>
1038       <entry>&lt;dl&gt;</entry>
1039       <entry>&lt;variablelist&gt;</entry>
1040     </row>
1041     <row>
1042       <entry>&lt;dt&gt;</entry>
1043       <entry>&lt;term&gt;</entry>
1044     </row>
1045     <row>
1046       <entry>&lt;dd&gt;</entry>
1047       <entry>&lt;listitem&gt;</entry>
1048     </row>
1049
1050     <row>
1051       <entry>&lt;a href=""&gt;</entry>
1052       <entry>&lt;ulink url=""&gt;</entry>
1053     </row>
1054     <row>
1055       <entry>&lt;code&gt;</entry>
1056       <entry>&lt;literal&gt;, &lt;programlisting&gt;</entry>
1057     </row>
1058     <row>
1059       <entry>&lt;strong&gt;</entry>
1060       <entry>&lt;emphasis&gt;</entry>
1061     </row>
1062     <row>
1063       <entry>&lt;em&gt;</entry>
1064       <entry>&lt;emphasis&gt;</entry>
1065     </row>
1066     <row>
1067       <entry>"</entry>
1068       <entry>&lt;quote&gt;</entry>
1069     </row>
1070    </tbody>
1071 </tgroup>
1072 </table>
1073
1074 <para>
1075   And examples of detailed markup for which there are no real HTML
1076   equivalents are listed in the table below.
1077 </para>
1078
1079 <table frame="all">
1080 <title>Docbook XML Element Use</title>
1081
1082 <tgroup cols="2" align="left" colsep="1" rowsep="1">
1083 <colspec colname="c1"/>
1084 <colspec colname="c2"/>
1085
1086   <thead>
1087     <row>
1088       <entry>Element</entry>
1089       <entry>Use</entry>
1090     </row>
1091   </thead>
1092
1093   <tbody>
1094     <row>
1095       <entry>&lt;structname&gt;</entry>
1096       <entry>&lt;structname&gt;char_traits&lt;/structname&gt;</entry>
1097     </row>
1098     <row>
1099       <entry>&lt;classname&gt;</entry>
1100       <entry>&lt;classname&gt;string&lt;/classname&gt;</entry>
1101     </row>
1102     <row>
1103       <entry>&lt;function&gt;</entry>
1104       <entry>
1105         <para>&lt;function&gt;clear()&lt;/function&gt;</para>
1106         <para>&lt;function&gt;fs.clear()&lt;/function&gt;</para>
1107       </entry>
1108     </row>
1109     <row>
1110       <entry>&lt;type&gt;</entry>
1111       <entry>&lt;type&gt;long long&lt;/type&gt;</entry>
1112     </row>
1113     <row>
1114       <entry>&lt;varname&gt;</entry>
1115       <entry>&lt;varname&gt;fs&lt;/varname&gt;</entry>
1116     </row>
1117     <row>
1118       <entry>&lt;literal&gt;</entry>
1119       <entry>
1120         <para>&lt;literal&gt;-Weffc++&lt;/literal&gt;</para>
1121         <para>&lt;literal&gt;rel_ops&lt;/literal&gt;</para>
1122       </entry>
1123     </row>
1124     <row>
1125       <entry>&lt;constant&gt;</entry>
1126       <entry>
1127         <para>&lt;constant&gt;_GNU_SOURCE&lt;/constant&gt;</para>
1128         <para>&lt;constant&gt;3.0&lt;/constant&gt;</para>
1129       </entry>
1130     </row>
1131     <row>
1132       <entry>&lt;command&gt;</entry>
1133       <entry>&lt;command&gt;g++&lt;/command&gt;</entry>
1134     </row>
1135     <row>
1136       <entry>&lt;errortext&gt;</entry>
1137       <entry>&lt;errortext&gt;In instantiation of&lt;/errortext&gt;</entry>
1138     </row>
1139     <row>
1140       <entry>&lt;filename&gt;</entry>
1141       <entry>
1142         <para>&lt;filename class="headerfile"&gt;ctype.h&lt;/filename&gt;</para>
1143         <para>&lt;filename class="directory"&gt;/home/gcc/build&lt;/filename&gt;</para>
1144         <para>&lt;filename class="libraryfile"&gt;libstdc++.so&lt;/filename&gt;</para>
1145       </entry>
1146     </row>
1147    </tbody>
1148 </tgroup>
1149 </table>
1150
1151 </section>
1152 </section>
1153 </section>