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