OSDN Git Service

2011-02-08 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   </tbody>
615 </tgroup>
616 </table>
617
618       <para>
619         Editing the DocBook sources requires an XML editor. Many
620         exist: some notable options
621         include <command>emacs</command>, <application>Kate</application>,
622         or <application>Conglomerate</application>.
623       </para>
624
625       <para>
626         Some editors support special <quote>XML Validation</quote>
627         modes that can validate the file as it is
628         produced. Recommended is the <command>nXML Mode</command>
629         for <command>emacs</command>.
630       </para>
631
632       <para>
633         Besides an editor, additional DocBook files and XML tools are
634         also required.
635       </para>
636
637       <para>
638         Access to the DocBook 5.0 stylesheets and schema is required. The
639         stylesheets are usually packaged by vendor, in something
640         like <filename>docbook5-style-xsl</filename>. To exactly match
641         generated output, please use a version of the stylesheets
642         equivalent
643         to <filename>docbook5-style-xsl-1.75.2-3</filename>. The
644         installation directory for this package corresponds to
645         the <literal>XSL_STYLE_DIR</literal>
646         in <filename>doc/Makefile.am</filename> and defaults
647         to <filename class="directory">/usr/share/sgml/docbook/xsl-ns-stylesheets</filename>.
648       </para>
649
650       <para>
651         For processing XML, an XML processor and some style
652         sheets are necessary. Defaults are <command>xsltproc</command>
653         provided by <filename>libxslt</filename>.
654       </para>
655
656       <para>
657         For validating the XML document, you'll need
658         something like <command>xmllint</command> and access to the
659         relevant DocBook schema. These are provided
660         by a vendor package like <filename>libxml2</filename> and <filename>docbook5-schemas-5.0-4</filename>
661       </para>
662
663       <para>
664         For PDF output, something that transforms valid Docbook XML to PDF is
665         required. Possible solutions include <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://dblatex.sourceforge.net">dblatex</link>,
666         <command>xmlto</command>, or <command>prince</command>. Of
667         these, <command>dblatex</command> is the default. Other
668         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
669         consult the <email>libstdc++@gcc.gnu.org</email> list when
670         preparing printed manuals for current best practice and
671         suggestions.
672       </para>
673
674       <para>
675         For Texinfo output, something that transforms valid Docbook
676         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>.
677       </para>
678     </section>
679
680     <section xml:id="docbook.rules"><info><title>Generating the DocBook Files</title></info>
681       
682
683       <para>
684         The following Makefile rules generate (in order): an HTML
685         version of all the DocBook documentation, a PDF version of the
686         same, and a single XML document.  These rules are not
687         conditional! If the required tools are not found, or are the
688         wrong versions, the rule may end in an error.
689       </para>
690
691       <para>
692       <screen><userinput>make doc-html-docbook</userinput></screen>
693       </para>
694
695       <para>
696       <screen><userinput>make doc-pdf-docbook</userinput></screen>
697       </para>
698
699       <para>
700       <screen><userinput>make doc-xml-single-docbook</userinput></screen>
701       </para>
702
703       <para>
704         Generated files are output into separate sub directores of
705         <filename class="directory">doc/docbook/</filename> in the
706         build directory, based on the output format. For instance, the
707         HTML docs will be in <filename
708         class="directory">doc/docbook/html</filename>.
709       </para>
710
711       <para>
712         If the Docbook stylesheets are installed in a custom location,
713         one can use the variable <literal>XSL_STYLE_DIR</literal> to
714         over-ride the Makefile defaults. As so:
715       </para>
716
717       <screen>
718         <userinput>
719 make <literal>XSL_STYLE_DIR="/usr/share/xml/docbook/stylesheet/nwalsh"</literal> doc-html-docbook
720         </userinput>
721       </screen>
722
723       </section>
724
725     <section xml:id="docbook.validation"><info><title>Editing and Validation</title></info>
726
727       <para>
728         After editing the xml sources, please make sure that the XML
729         documentation and markup is still valid. This can be
730         done easily, with the following validation rule:
731       </para>
732
733       <screen>
734         <userinput>make doc-xml-validate-docbook</userinput>
735       </screen>
736
737       <para>
738         This is equivalent to doing:
739       </para>
740       
741       <screen>
742         <userinput>
743           xmllint --noout --valid <filename>xml/index.xml</filename>
744         </userinput>
745       </screen>
746
747       <para>
748         Please note that individual sections and chapters of the
749         manual can be validated by substiuting the file desired for
750         <filename>xml/index.xml</filename> in the command
751         above. Reducing scope in this manner can be helpful when
752         validation on the entire manual fails.
753       </para>
754
755       <para>
756         All Docbook xml sources should always validate. No excuses!
757       </para>
758
759     </section>
760
761     <section xml:id="docbook.examples"><info><title>File Organization and Basics</title></info>
762       
763
764     <literallayout class="normal">
765       <emphasis>Which files are important</emphasis>
766
767       All Docbook files are in the directory
768       libstdc++-v3/doc/xml
769
770       Inside this directory, the files of importance:
771       spine.xml         - index to documentation set
772       manual/spine.xml  - index to manual
773       manual/*.xml      - individual chapters and sections of the manual
774       faq.xml           - index to FAQ
775       api.xml           - index to source level / API
776
777       All *.txml files are template xml files, i.e., otherwise empty files with
778       the correct structure, suitable for filling in with new information.
779
780       <emphasis>Canonical Writing Style</emphasis>
781
782       class template
783       function template
784       member function template
785       (via C++ Templates, Vandevoorde)
786
787       class in namespace std: allocator, not std::allocator
788
789       header file: iostream, not &lt;iostream&gt;
790
791
792       <emphasis>General structure</emphasis>
793
794       &lt;set&gt;
795       &lt;book&gt;
796       &lt;/book&gt;
797
798       &lt;book&gt;
799       &lt;chapter&gt;
800       &lt;/chapter&gt;
801       &lt;/book&gt;
802
803       &lt;book&gt;
804       &lt;part&gt;
805       &lt;chapter&gt;
806       &lt;section&gt;
807       &lt;/section&gt;
808
809       &lt;sect1&gt;
810       &lt;/sect1&gt;
811
812       &lt;sect1&gt;
813       &lt;sect2&gt;
814       &lt;/sect2&gt;
815       &lt;/sect1&gt;
816       &lt;/chapter&gt;
817
818       &lt;chapter&gt;
819       &lt;/chapter&gt;
820       &lt;/part&gt;
821       &lt;/book&gt;
822
823       &lt;/set&gt;
824     </literallayout>
825     </section>
826
827     <section xml:id="docbook.markup"><info><title>Markup By Example</title></info>
828       
829
830       <para>
831         Complete details on Docbook markup can be found in the DocBook
832         Element Reference,
833         <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.docbook.org/tdg/en/html/part2.html">online</link>.
834         An incomplete reference for HTML to Docbook conversion is
835         detailed in the table below.
836       </para>
837
838 <table frame="all">
839 <title>HTML to Docbook XML Markup Comparison</title>
840
841 <tgroup cols="2" align="left" colsep="1" rowsep="1">
842 <colspec colname="c1"/>
843 <colspec colname="c2"/>
844
845   <thead>
846     <row>
847       <entry>HTML</entry>
848       <entry>Docbook</entry>
849     </row>
850   </thead>
851
852   <tbody>
853     <row>
854       <entry>&lt;p&gt;</entry>
855       <entry>&lt;para&gt;</entry>
856     </row>
857     <row>
858       <entry>&lt;pre&gt;</entry>
859       <entry>&lt;computeroutput&gt;, &lt;programlisting&gt;,
860         &lt;literallayout&gt;</entry>
861     </row>
862     <row>
863       <entry>&lt;ul&gt;</entry>
864       <entry>&lt;itemizedlist&gt;</entry>
865     </row>
866     <row>
867       <entry>&lt;ol&gt;</entry>
868       <entry>&lt;orderedlist&gt;</entry>
869     </row>
870     <row>
871       <entry>&lt;il&gt;</entry>
872       <entry>&lt;listitem&gt;</entry>
873     </row>
874     <row>
875       <entry>&lt;dl&gt;</entry>
876       <entry>&lt;variablelist&gt;</entry>
877     </row>
878     <row>
879       <entry>&lt;dt&gt;</entry>
880       <entry>&lt;term&gt;</entry>
881     </row>
882     <row>
883       <entry>&lt;dd&gt;</entry>
884       <entry>&lt;listitem&gt;</entry>
885     </row>
886
887     <row>
888       <entry>&lt;a href=""&gt;</entry>
889       <entry>&lt;ulink url=""&gt;</entry>
890     </row>
891     <row>
892       <entry>&lt;code&gt;</entry>
893       <entry>&lt;literal&gt;, &lt;programlisting&gt;</entry>
894     </row>
895     <row>
896       <entry>&lt;strong&gt;</entry>
897       <entry>&lt;emphasis&gt;</entry>
898     </row>
899     <row>
900       <entry>&lt;em&gt;</entry>
901       <entry>&lt;emphasis&gt;</entry>
902     </row>
903     <row>
904       <entry>"</entry>
905       <entry>&lt;quote&gt;</entry>
906     </row>
907    </tbody>
908 </tgroup>
909 </table>
910
911 <para>
912   And examples of detailed markup for which there are no real HTML
913   equivalents are listed in the table below.
914 </para>
915
916 <table frame="all">
917 <title>Docbook XML Element Use</title>
918
919 <tgroup cols="2" align="left" colsep="1" rowsep="1">
920 <colspec colname="c1"/>
921 <colspec colname="c2"/>
922
923   <thead>
924     <row>
925       <entry>Element</entry>
926       <entry>Use</entry>
927     </row>
928   </thead>
929
930   <tbody>
931     <row>
932       <entry>&lt;structname&gt;</entry>
933       <entry>&lt;structname&gt;char_traits&lt;/structname&gt;</entry>
934     </row>
935     <row>
936       <entry>&lt;classname&gt;</entry>
937       <entry>&lt;classname&gt;string&lt;/classname&gt;</entry>
938     </row>
939     <row>
940       <entry>&lt;function&gt;</entry>
941       <entry>
942         <para>&lt;function&gt;clear()&lt;/function&gt;</para>
943         <para>&lt;function&gt;fs.clear()&lt;/function&gt;</para>
944       </entry>
945     </row>
946     <row>
947       <entry>&lt;type&gt;</entry>
948       <entry>&lt;type&gt;long long&lt;/type&gt;</entry>
949     </row>
950     <row>
951       <entry>&lt;varname&gt;</entry>
952       <entry>&lt;varname&gt;fs&lt;/varname&gt;</entry>
953     </row>
954     <row>
955       <entry>&lt;literal&gt;</entry>
956       <entry>
957         <para>&lt;literal&gt;-Weffc++&lt;/literal&gt;</para>
958         <para>&lt;literal&gt;rel_ops&lt;/literal&gt;</para>
959       </entry>
960     </row>
961     <row>
962       <entry>&lt;constant&gt;</entry>
963       <entry>
964         <para>&lt;constant&gt;_GNU_SOURCE&lt;/constant&gt;</para>
965         <para>&lt;constant&gt;3.0&lt;/constant&gt;</para>
966       </entry>
967     </row>
968     <row>
969       <entry>&lt;command&gt;</entry>
970       <entry>&lt;command&gt;g++&lt;/command&gt;</entry>
971     </row>
972     <row>
973       <entry>&lt;errortext&gt;</entry>
974       <entry>&lt;errortext&gt;In instantiation of&lt;/errortext&gt;</entry>
975     </row>
976     <row>
977       <entry>&lt;filename&gt;</entry>
978       <entry>
979         <para>&lt;filename class="headerfile"&gt;ctype.h&lt;/filename&gt;</para>
980         <para>&lt;filename class="directory"&gt;/home/gcc/build&lt;/filename&gt;</para>
981         <para>&lt;filename class="libraryfile"&gt;libstdc++.so&lt;/filename&gt;</para>
982       </entry>
983     </row>
984    </tbody>
985 </tgroup>
986 </table>
987
988 </section>
989 </section>
990 </section>