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