OSDN Git Service

2012-02-07 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 class="directory">
106               doc/libstdc++/libstdc++-api.html
107             </filename>
108           </para>
109           <para>
110             <filename class="directory">
111               doc/libstdc++/libstdc++-manual.html
112             </filename>
113           </para>
114         </listitem>
115       </varlistentry>
116
117       <varlistentry>
118         <term>
119           <emphasis>make pdf</emphasis>
120         </term>
121         <term>
122           <emphasis>make install-pdf</emphasis>
123         </term>
124         <listitem>
125           <para>
126             Generates indexed PDF documentation, and installs it as
127             the following files:
128           </para>
129           <para>
130             <filename>doc/libstdc++/libstdc++-api.pdf</filename>
131           </para>
132           <para>
133             <filename>doc/libstdc++/libstdc++-manual.pdf</filename>
134           </para>
135         </listitem>
136       </varlistentry>
137       
138       <varlistentry>
139         <term>
140           <emphasis>make man</emphasis>
141         </term>
142         <term>
143           <emphasis>make install-man</emphasis>
144         </term>
145         <listitem>
146           <para>
147             Generates man pages, and installs it in the following directory:
148           </para>
149           <para>
150             <filename class="directory">man/man3/</filename>
151           </para>
152           <para>
153             The generated man pages are namespace-qualified, so to look at
154             the man page for <classname>vector</classname>, one would use
155             <command>man std::vector</command>.
156           </para>
157         </listitem>
158       </varlistentry>
159
160       <varlistentry>
161         <term>
162           <emphasis>make epub</emphasis>
163         </term>
164         <term>
165           <emphasis>make install-epub</emphasis>
166         </term>
167         <listitem>
168           <para>
169             Generates documentation in the ebook/portable electronic
170             reader format called Epub, and installs it as the
171             following file.
172           </para>
173           <para>
174             <filename>doc/libstdc++/libstdc++-manual.epub</filename>
175           </para>
176         </listitem>
177       </varlistentry>      
178
179       <varlistentry>
180         <term>
181           <emphasis>make xml</emphasis>
182         </term>
183         <term>
184           <emphasis>make install-xml</emphasis>
185         </term>
186         <listitem>
187           <para>
188             Generates single-file XML documentation, and installs it
189             as the following files:
190           </para>
191           <para>
192             <filename>doc/libstdc++/libstdc++-api-single.xml</filename>
193           </para>
194           <para>
195             <filename>doc/libstdc++/libstdc++-manual-single.xml</filename>
196           </para>
197         </listitem>
198       </varlistentry>
199     </variablelist>
200
201     <para>
202       Makefile rules for several other formats are explicitly not
203       supported, and are always aliased to dummy rules. These
204       unsupported formats are: <emphasis>info</emphasis>,
205       <emphasis>ps</emphasis>, and <emphasis>dvi</emphasis>.
206     </para>
207   </section>
208
209   <section xml:id="doc.doxygen"><info><title>Doxygen</title></info>
210     
211     <section xml:id="doxygen.prereq"><info><title>Prerequisites</title></info>
212       
213  <table frame="all">
214 <title>Doxygen Prerequisites</title>
215
216 <tgroup cols="3" align="center" colsep="1" rowsep="1">
217 <colspec colname="c1"/>
218 <colspec colname="c2"/>
219 <colspec colname="c3"/>
220
221   <thead>
222     <row>
223       <entry>Tool</entry>
224       <entry>Version</entry>
225       <entry>Required By</entry>
226     </row>
227   </thead>
228
229   <tbody>
230
231     <row>
232       <entry>coreutils</entry>
233       <entry>8.5</entry>
234       <entry>all</entry>
235     </row>
236
237     <row>
238       <entry>bash</entry>
239       <entry>4.1</entry>
240       <entry>all</entry>
241     </row>
242
243     <row>
244       <entry>doxygen</entry>
245       <entry>1.7.6.1</entry>
246       <entry>all</entry>
247     </row>
248
249     <row>
250       <entry>graphviz</entry>
251       <entry>2.26</entry>
252       <entry>graphical hierarchies</entry>
253     </row>
254
255     <row>
256       <entry>pdflatex</entry>
257       <entry>2007-59</entry>
258       <entry>pdf output</entry>
259     </row>
260
261   </tbody>
262 </tgroup>
263 </table>
264
265
266       <para>
267         Prerequisite tools are Bash 2.0 or later,
268         <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.doxygen.org/">Doxygen</link>, and
269         the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.gnu.org/software/coreutils/">GNU
270         coreutils</link>. (GNU versions of find, xargs, and possibly
271         sed and grep are used, just because the GNU versions make
272         things very easy.) 
273       </para>
274
275       <para>
276         To generate the pretty pictures and hierarchy
277         graphs, the
278         <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.graphviz.org">Graphviz</link> package
279         will need to be installed. For PDF
280         output, <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.tug.org/applications/pdftex/">
281         pdflatex</link> is required.
282       </para>
283
284       <para>
285         Be warned the PDF file generated via doxygen is extremely
286         large. At last count, the PDF file is over three thousand
287         pages. Generating this document taxes the underlying TeX
288         formatting system, and will require the expansion of TeX's memory
289         capacity. Specifically, the <literal>pool_size</literal>
290         variable in the configuration file <filename>texmf.cnf</filename> may
291         need to be increased by a minimum factor of two.
292       </para>
293     </section>
294
295     <section xml:id="doxygen.rules"><info><title>Generating the Doxygen Files</title></info>
296       
297       <para>
298         The following Makefile rules run Doxygen to generate HTML
299         docs, XML docs, XML docs as a single file, PDF docs, and the
300         man pages. These rules are not conditional! If the required
301         tools are not found, or are the wrong versions, the rule may
302         end in an error.
303       </para>
304
305       <para>
306       <screen><userinput>make doc-html-doxygen</userinput></screen>
307       </para>
308
309       <para>
310       <screen><userinput>make doc-xml-doxygen</userinput></screen>
311       </para>
312
313       <para>
314       <screen><userinput>make doc-xml-single-doxygen</userinput></screen>
315       </para>
316
317       <para>
318       <screen><userinput>make doc-pdf-doxygen</userinput></screen>
319       </para>
320
321       <para>
322       <screen><userinput>make doc-man-doxygen</userinput></screen>
323       </para>
324
325       <para>
326         Generated files are output into separate sub directories of
327         <filename class="directory">doc/doxygen/</filename> in the
328         build directory, based on the output format. For instance, the
329         HTML docs will be in <filename class="directory">doc/doxygen/html</filename>.
330       </para>
331
332       <para>
333         Careful observers will see that the Makefile rules simply call
334         a script from the source tree, <filename>run_doxygen</filename>, which
335         does the actual work of running Doxygen and then (most
336         importantly) massaging the output files. If for some reason
337         you prefer to not go through the Makefile, you can call this
338         script directly. (Start by passing <literal>--help</literal>.)
339       </para>
340
341       <para>
342         If you wish to tweak the Doxygen settings, do so by editing
343         <filename>doc/doxygen/user.cfg.in</filename>. Notes to fellow
344         library hackers are written in triple-# comments.
345       </para>
346
347     </section>
348
349     <section xml:id="doxygen.markup"><info><title>Markup</title></info>
350       
351
352       <para>
353         In general, libstdc++ files should be formatted according to
354         the rules found in the
355         <link linkend="contrib.coding_style">Coding Standard</link>. Before
356         any doxygen-specific formatting tweaks are made, please try to
357         make sure that the initial formatting is sound.
358       </para>
359
360       <para>
361         Adding Doxygen markup to a file (informally called
362         <quote>doxygenating</quote>) is very simple. The Doxygen manual can be
363         found
364         <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.stack.nl/~dimitri/doxygen/download.html#latestman">here</link>.
365         We try to use a very-recent version of Doxygen.
366       </para>
367
368       <para>
369         For classes, use
370         <classname>deque</classname>/<classname>vector</classname>/<classname>list</classname>
371         and <classname>std::pair</classname> as examples.  For
372         functions, see their member functions, and the free functions
373         in <filename>stl_algobase.h</filename>. Member functions of
374         other container-like types should read similarly to these
375         member functions.
376       </para>
377
378       <para>
379         Some commentary to accompany
380         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
381         Documentation Blocks</link> section of
382         the Doxygen manual:
383       </para>
384
385       <orderedlist inheritnum="ignore" continuation="restarts">
386         <listitem>
387           <para>For longer comments, use the Javadoc style...</para>
388         </listitem>
389
390         <listitem>
391           <para>
392             ...not the Qt style. The intermediate *'s are preferred.
393           </para>
394         </listitem>
395
396         <listitem>
397           <para>
398             Use the triple-slash style only for one-line comments (the
399             <quote>brief</quote> mode).
400           </para>
401         </listitem>
402
403         <listitem>
404           <para>
405             This is disgusting. Don't do this.
406           </para>
407         </listitem>
408       </orderedlist>
409
410       <para>
411         Some specific guidelines:
412       </para>
413
414       <para>
415         Use the @-style of commands, not the !-style. Please be
416         careful about whitespace in your markup comments. Most of the
417         time it doesn't matter; doxygen absorbs most whitespace, and
418         both HTML and *roff are agnostic about whitespace. However,
419         in &lt;pre&gt; blocks and @code/@endcode sections, spacing can
420         have <quote>interesting</quote> effects.
421       </para>
422
423       <para>
424         Use either kind of grouping, as
425         appropriate. <filename>doxygroups.cc</filename> exists for this
426         purpose. See <filename>stl_iterator.h</filename> for a good example
427         of the <quote>other</quote> kind of grouping.
428       </para>
429
430       <para>
431         Please use markup tags like @p and @a when referring to things
432         such as the names of function parameters. Use @e for emphasis
433         when necessary. Use @c to refer to other standard names.
434         (Examples of all these abound in the present code.)
435       </para>
436
437       <para>
438         Complicated math functions should use the multi-line
439         format. An example from <filename>random.h</filename>:
440       </para>
441
442       <para>
443 <literallayout class="normal">
444 /**
445  * @brief A model of a linear congruential random number generator.
446  *
447  * @f[
448  *     x_{i+1}\leftarrow(ax_{i} + c) \bmod m
449  * @f]
450  */
451 </literallayout>
452       </para>
453
454       <para>
455         One area of note is the markup required for
456         <literal>@file</literal> markup in header files. Two details
457         are important: for filenames that have the same name in
458         multiple directories, include part of the installed path to
459         disambiguate. For example:
460       </para>
461
462       <para>
463 <literallayout class="normal">
464 /** @file debug/vector
465  *  This file is a GNU debug extension to the Standard C++ Library.
466  */
467 </literallayout>
468       </para>
469
470       <para>
471         The other relevant detail for header files is the use of a
472         libstdc++-specific doxygen alias that helps distinguish
473         between public header files (like <filename>random</filename>)
474         from implementation or private header files (like
475         <filename>bits/c++config.h</filename>.) This alias is spelled
476         <literal>@headername</literal> and can take one or two
477         arguments that detail the public header file or files that
478         should be included to use the contents of the file. All header
479         files that are not intended for direct inclusion must use
480         <literal>headername</literal> in the <literal>file</literal>
481         block. An example:
482       </para>
483
484       <para>
485 <literallayout class="normal">
486 /** @file bits/basic_string.h
487  *  This is an internal header file, included by other library headers.
488  *  Do not attempt to use it directly. @headername{string}
489  */
490 </literallayout>
491       </para>
492
493       <para>
494         Be careful about using certain, special characters when
495         writing Doxygen comments. Single and double quotes, and
496         separators in filenames are two common trouble spots. When in
497         doubt, consult the following table.
498       </para>
499
500 <table frame="all">
501 <title>HTML to Doxygen Markup Comparison</title>
502
503 <tgroup cols="2" align="left" colsep="1" rowsep="1">
504 <colspec colname="c1"/>
505 <colspec colname="c2"/>
506
507   <thead>
508     <row>
509       <entry>HTML</entry>
510       <entry>Doxygen</entry>
511     </row>
512   </thead>
513
514   <tbody>
515     <row>
516       <entry>\</entry>
517       <entry>\\</entry>
518     </row>
519
520     <row>
521       <entry>"</entry>
522       <entry>\"</entry>
523     </row>
524
525     <row>
526       <entry>'</entry>
527       <entry>\'</entry>
528     </row>
529
530     <row>
531       <entry>&lt;i&gt;</entry>
532       <entry>@a word</entry>
533     </row>
534
535     <row>
536       <entry>&lt;b&gt;</entry>
537       <entry>@b word</entry>
538     </row>
539
540     <row>
541       <entry>&lt;code&gt;</entry>
542       <entry>@c word</entry>
543     </row>
544
545     <row>
546       <entry>&lt;em&gt;</entry>
547       <entry>@a word</entry>
548     </row>
549
550     <row>
551       <entry>&lt;em&gt;</entry>
552       <entry>&lt;em&gt;two words or more&lt;/em&gt;</entry>
553     </row>
554   </tbody>
555
556 </tgroup>
557 </table>
558
559
560     </section>
561
562   </section>
563
564   <section xml:id="doc.docbook"><info><title>Docbook</title></info>
565     
566
567     <section xml:id="docbook.prereq"><info><title>Prerequisites</title></info>
568       
569       
570  <table frame="all">
571 <title>Docbook Prerequisites</title>
572
573 <tgroup cols="3" align="center" colsep="1" rowsep="1">
574 <colspec colname="c1"/>
575 <colspec colname="c2"/>
576 <colspec colname="c3"/>
577
578   <thead>
579     <row>
580       <entry>Tool</entry>
581       <entry>Version</entry>
582       <entry>Required By</entry>
583     </row>
584   </thead>
585
586   <tbody>
587
588     <row>
589       <entry>docbook5-style-xsl</entry>
590       <entry>1.76.1</entry>
591       <entry>all</entry>
592     </row>
593
594     <row>
595       <entry>xsltproc</entry>
596       <entry>1.1.26</entry>
597       <entry>all</entry>
598     </row>
599
600     <row>
601       <entry>xmllint</entry>
602       <entry>2.7.7</entry>
603       <entry>validation</entry>
604     </row>
605
606     <row>
607       <entry>dblatex</entry>
608       <entry>0.3</entry>
609       <entry>pdf output</entry>
610     </row>
611
612     <row>
613       <entry>pdflatex</entry>
614       <entry>2007-59</entry>
615       <entry>pdf output</entry>
616     </row>
617
618     <row>
619       <entry>docbook2X</entry>
620       <entry>0.8.8</entry>
621       <entry>info output</entry>
622     </row>
623
624     <row>
625       <entry>epub3 stylesheets</entry>
626       <entry>b3</entry>
627       <entry>epub output</entry>
628     </row>
629
630   </tbody>
631 </tgroup>
632 </table>
633
634       <para>
635         Editing the DocBook sources requires an XML editor. Many
636         exist: some notable options
637         include <command>emacs</command>, <application>Kate</application>,
638         or <application>Conglomerate</application>.
639       </para>
640
641       <para>
642         Some editors support special <quote>XML Validation</quote>
643         modes that can validate the file as it is
644         produced. Recommended is the <command>nXML Mode</command>
645         for <command>emacs</command>.
646       </para>
647
648       <para>
649         Besides an editor, additional DocBook files and XML tools are
650         also required.
651       </para>
652
653       <para>
654         Access to the DocBook 5.0 stylesheets and schema is required. The
655         stylesheets are usually packaged by vendor, in something
656         like <filename>docbook5-style-xsl</filename>. To exactly match
657         generated output, please use a version of the stylesheets
658         equivalent
659         to <filename>docbook5-style-xsl-1.75.2-3</filename>. The
660         installation directory for this package corresponds to
661         the <literal>XSL_STYLE_DIR</literal>
662         in <filename>doc/Makefile.am</filename> and defaults
663         to <filename class="directory">/usr/share/sgml/docbook/xsl-ns-stylesheets</filename>.
664       </para>
665
666       <para>
667         For processing XML, an XSLT processor and some style
668         sheets are necessary. Defaults are <command>xsltproc</command>
669         provided by <filename>libxslt</filename>.
670       </para>
671
672       <para>
673         For validating the XML document, you'll need
674         something like <command>xmllint</command> and access to the
675         relevant DocBook schema. These are provided
676         by a vendor package like <filename>libxml2</filename> and <filename>docbook5-schemas-5.0-4</filename>
677       </para>
678
679       <para>
680         For PDF output, something that transforms valid Docbook XML to PDF is
681         required. Possible solutions include <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://dblatex.sourceforge.net">dblatex</link>,
682         <command>xmlto</command>, or <command>prince</command>. Of
683         these, <command>dblatex</command> is the default. Other
684         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
685         consult the <email>libstdc++@gcc.gnu.org</email> list when
686         preparing printed manuals for current best practice and
687         suggestions.
688       </para>
689
690       <para>
691         For Texinfo output, something that transforms valid Docbook
692         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>.
693       </para>
694
695       <para>
696         For epub output, the <link xmlns:xlink="http://www.w3.org/1999/xlink" xmlns: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" xmlns:href="https://code.google.com/p/epubcheck/">epubcheck</link> is necessary.
697       </para>
698     </section>
699
700     <section xml:id="docbook.rules"><info><title>Generating the DocBook Files</title></info>
701       
702
703       <para>
704         The following Makefile rules generate (in order): an HTML
705         version of all the DocBook documentation, a PDF version of the
706         same, and a single XML document.  These rules are not
707         conditional! If the required tools are not found, or are the
708         wrong versions, the rule may end in an error.
709       </para>
710
711       <para>
712       <screen><userinput>make doc-html-docbook</userinput></screen>
713       </para>
714
715       <para>
716       <screen><userinput>make doc-pdf-docbook</userinput></screen>
717       </para>
718
719       <para>
720       <screen><userinput>make doc-xml-single-docbook</userinput></screen>
721       </para>
722
723       <para>
724         Generated files are output into separate sub directores of
725         <filename class="directory">doc/docbook/</filename> in the
726         build directory, based on the output format. For instance, the
727         HTML docs will be in <filename
728         class="directory">doc/docbook/html</filename>.
729       </para>
730
731       <para>
732         If the Docbook stylesheets are installed in a custom location,
733         one can use the variable <literal>XSL_STYLE_DIR</literal> to
734         override the Makefile defaults. For example:
735       </para>
736
737       <screen>
738         <userinput>
739 make <literal>XSL_STYLE_DIR="/usr/share/xml/docbook/stylesheet/nwalsh"</literal> doc-html-docbook
740         </userinput>
741       </screen>
742
743       </section>
744
745     <section xml:id="docbook.validation"><info><title>Editing and Validation</title></info>
746
747       <para>
748         After editing the xml sources, please make sure that the XML
749         documentation and markup is still valid. This can be
750         done easily, with the following validation rule:
751       </para>
752
753       <screen>
754         <userinput>make doc-xml-validate-docbook</userinput>
755       </screen>
756
757       <para>
758         This is equivalent to doing:
759       </para>
760       
761       <screen>
762         <userinput>
763           xmllint --noout --valid <filename>xml/index.xml</filename>
764         </userinput>
765       </screen>
766
767       <para>
768         Please note that individual sections and chapters of the
769         manual can be validated by substituting the file desired for
770         <filename>xml/index.xml</filename> in the command
771         above. Reducing scope in this manner can be helpful when
772         validation on the entire manual fails.
773       </para>
774
775       <para>
776         All Docbook xml sources should always validate. No excuses!
777       </para>
778
779     </section>
780
781     <section xml:id="docbook.examples"><info><title>File Organization and Basics</title></info>
782       
783
784     <literallayout class="normal">
785       <emphasis>Which files are important</emphasis>
786
787       All Docbook files are in the directory
788       libstdc++-v3/doc/xml
789
790       Inside this directory, the files of importance:
791       spine.xml         - index to documentation set
792       manual/spine.xml  - index to manual
793       manual/*.xml      - individual chapters and sections of the manual
794       faq.xml           - index to FAQ
795       api.xml           - index to source level / API
796
797       All *.txml files are template xml files, i.e., otherwise empty files with
798       the correct structure, suitable for filling in with new information.
799
800       <emphasis>Canonical Writing Style</emphasis>
801
802       class template
803       function template
804       member function template
805       (via C++ Templates, Vandevoorde)
806
807       class in namespace std: allocator, not std::allocator
808
809       header file: iostream, not &lt;iostream&gt;
810
811
812       <emphasis>General structure</emphasis>
813
814       &lt;set&gt;
815       &lt;book&gt;
816       &lt;/book&gt;
817
818       &lt;book&gt;
819       &lt;chapter&gt;
820       &lt;/chapter&gt;
821       &lt;/book&gt;
822
823       &lt;book&gt;
824       &lt;part&gt;
825       &lt;chapter&gt;
826       &lt;section&gt;
827       &lt;/section&gt;
828
829       &lt;sect1&gt;
830       &lt;/sect1&gt;
831
832       &lt;sect1&gt;
833       &lt;sect2&gt;
834       &lt;/sect2&gt;
835       &lt;/sect1&gt;
836       &lt;/chapter&gt;
837
838       &lt;chapter&gt;
839       &lt;/chapter&gt;
840       &lt;/part&gt;
841       &lt;/book&gt;
842
843       &lt;/set&gt;
844     </literallayout>
845     </section>
846
847     <section xml:id="docbook.markup"><info><title>Markup By Example</title></info>
848       
849
850       <para>
851         Complete details on Docbook markup can be found in the DocBook
852         Element Reference,
853         <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.docbook.org/tdg/en/html/part2.html">online</link>.
854         An incomplete reference for HTML to Docbook conversion is
855         detailed in the table below.
856       </para>
857
858 <table frame="all">
859 <title>HTML to Docbook XML Markup Comparison</title>
860
861 <tgroup cols="2" align="left" colsep="1" rowsep="1">
862 <colspec colname="c1"/>
863 <colspec colname="c2"/>
864
865   <thead>
866     <row>
867       <entry>HTML</entry>
868       <entry>Docbook</entry>
869     </row>
870   </thead>
871
872   <tbody>
873     <row>
874       <entry>&lt;p&gt;</entry>
875       <entry>&lt;para&gt;</entry>
876     </row>
877     <row>
878       <entry>&lt;pre&gt;</entry>
879       <entry>&lt;computeroutput&gt;, &lt;programlisting&gt;,
880         &lt;literallayout&gt;</entry>
881     </row>
882     <row>
883       <entry>&lt;ul&gt;</entry>
884       <entry>&lt;itemizedlist&gt;</entry>
885     </row>
886     <row>
887       <entry>&lt;ol&gt;</entry>
888       <entry>&lt;orderedlist&gt;</entry>
889     </row>
890     <row>
891       <entry>&lt;il&gt;</entry>
892       <entry>&lt;listitem&gt;</entry>
893     </row>
894     <row>
895       <entry>&lt;dl&gt;</entry>
896       <entry>&lt;variablelist&gt;</entry>
897     </row>
898     <row>
899       <entry>&lt;dt&gt;</entry>
900       <entry>&lt;term&gt;</entry>
901     </row>
902     <row>
903       <entry>&lt;dd&gt;</entry>
904       <entry>&lt;listitem&gt;</entry>
905     </row>
906
907     <row>
908       <entry>&lt;a href=""&gt;</entry>
909       <entry>&lt;ulink url=""&gt;</entry>
910     </row>
911     <row>
912       <entry>&lt;code&gt;</entry>
913       <entry>&lt;literal&gt;, &lt;programlisting&gt;</entry>
914     </row>
915     <row>
916       <entry>&lt;strong&gt;</entry>
917       <entry>&lt;emphasis&gt;</entry>
918     </row>
919     <row>
920       <entry>&lt;em&gt;</entry>
921       <entry>&lt;emphasis&gt;</entry>
922     </row>
923     <row>
924       <entry>"</entry>
925       <entry>&lt;quote&gt;</entry>
926     </row>
927    </tbody>
928 </tgroup>
929 </table>
930
931 <para>
932   And examples of detailed markup for which there are no real HTML
933   equivalents are listed in the table below.
934 </para>
935
936 <table frame="all">
937 <title>Docbook XML Element Use</title>
938
939 <tgroup cols="2" align="left" colsep="1" rowsep="1">
940 <colspec colname="c1"/>
941 <colspec colname="c2"/>
942
943   <thead>
944     <row>
945       <entry>Element</entry>
946       <entry>Use</entry>
947     </row>
948   </thead>
949
950   <tbody>
951     <row>
952       <entry>&lt;structname&gt;</entry>
953       <entry>&lt;structname&gt;char_traits&lt;/structname&gt;</entry>
954     </row>
955     <row>
956       <entry>&lt;classname&gt;</entry>
957       <entry>&lt;classname&gt;string&lt;/classname&gt;</entry>
958     </row>
959     <row>
960       <entry>&lt;function&gt;</entry>
961       <entry>
962         <para>&lt;function&gt;clear()&lt;/function&gt;</para>
963         <para>&lt;function&gt;fs.clear()&lt;/function&gt;</para>
964       </entry>
965     </row>
966     <row>
967       <entry>&lt;type&gt;</entry>
968       <entry>&lt;type&gt;long long&lt;/type&gt;</entry>
969     </row>
970     <row>
971       <entry>&lt;varname&gt;</entry>
972       <entry>&lt;varname&gt;fs&lt;/varname&gt;</entry>
973     </row>
974     <row>
975       <entry>&lt;literal&gt;</entry>
976       <entry>
977         <para>&lt;literal&gt;-Weffc++&lt;/literal&gt;</para>
978         <para>&lt;literal&gt;rel_ops&lt;/literal&gt;</para>
979       </entry>
980     </row>
981     <row>
982       <entry>&lt;constant&gt;</entry>
983       <entry>
984         <para>&lt;constant&gt;_GNU_SOURCE&lt;/constant&gt;</para>
985         <para>&lt;constant&gt;3.0&lt;/constant&gt;</para>
986       </entry>
987     </row>
988     <row>
989       <entry>&lt;command&gt;</entry>
990       <entry>&lt;command&gt;g++&lt;/command&gt;</entry>
991     </row>
992     <row>
993       <entry>&lt;errortext&gt;</entry>
994       <entry>&lt;errortext&gt;In instantiation of&lt;/errortext&gt;</entry>
995     </row>
996     <row>
997       <entry>&lt;filename&gt;</entry>
998       <entry>
999         <para>&lt;filename class="headerfile"&gt;ctype.h&lt;/filename&gt;</para>
1000         <para>&lt;filename class="directory"&gt;/home/gcc/build&lt;/filename&gt;</para>
1001         <para>&lt;filename class="libraryfile"&gt;libstdc++.so&lt;/filename&gt;</para>
1002       </entry>
1003     </row>
1004    </tbody>
1005 </tgroup>
1006 </table>
1007
1008 </section>
1009 </section>
1010 </section>