OSDN Git Service

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