X-Git-Url: http://git.sourceforge.jp/view?p=pf3gnuchains%2Fgcc-fork.git;a=blobdiff_plain;f=libstdc%2B%2B-v3%2Fdoc%2Fxml%2Fmanual%2Fdocumentation_hacking.xml;h=05c05a636ec0bc0435e6acf50c2434ae8c7ec1cf;hp=7b2ed7c09b8d501804b3a909a729a183a474c642;hb=2ab835d38bf119317e4b3fe434c9b7155ec96863;hpb=390372e5ac217b7a5a563a040105029d1e0da198 diff --git a/libstdc++-v3/doc/xml/manual/documentation_hacking.xml b/libstdc++-v3/doc/xml/manual/documentation_hacking.xml index 7b2ed7c09b8..05c05a636ec 100644 --- a/libstdc++-v3/doc/xml/manual/documentation_hacking.xml +++ b/libstdc++-v3/doc/xml/manual/documentation_hacking.xml @@ -102,14 +102,10 @@ in the following directories: - - doc/libstdc++/libstdc++-api.html - + doc/libstdc++/libstdc++-api.html - - doc/libstdc++/libstdc++-manual.html - + doc/libstdc++/libstdc++-manual.html @@ -242,7 +238,7 @@ doxygen - 1.7.0 + 1.7.6.1 all @@ -280,6 +276,16 @@ output, pdflatex is required. + + + Be warned the PDF file generated via doxygen is extremely + large. At last count, the PDF file is over three thousand + pages. Generating this document taxes the underlying TeX + formatting system, and will require the expansion of TeX's memory + capacity. Specifically, the pool_size + variable in the configuration file texmf.cnf may + need to be increased by a minimum factor of two. +
Generating the Doxygen Files @@ -336,6 +342,76 @@
+
+ Debugging Generation + + + Sometimes, mis-configuration of the pre-requisite tools can + lead to errors when attempting to build the + documentation. Here are some of the obvious errors, and ways + to fix some common issues that may appear quite cryptic. + + + + First, if using a rule like make pdf, try to + narrow down the scope of the error to either docbook + (make doc-pdf-docbook) or doxygen (make + doc-pdf-doxygen). + + + Working on the doxygen path only, closely examine the + contents of the following build directory: + build/target/libstdc++-v3/doc/doxygen/latex. + Pay attention to three files enclosed within, annotated as follows. + + + + + + refman.tex + + + + The actual latex file, or partial latex file. This is generated + via doxygen, and is the LaTeX version of the + Doxygen XML file libstdc++-api.xml. Go to a specific + line, and look at the genrated LaTeX, and try to deduce what + markup in libstdc++-api.xml is causing it. + + + + + + refman.out + + + + A log of the compilation of the converted LaTeX form to pdf. This + is a linear list, from the beginning of the + refman.tex file: the last entry of this file + should be the end of the LaTeX file. If it is truncated, then you + know that the last entry is the last part of the generated LaTeX + source file that is valid. Often this file contains an error with + a specific line number of refman.tex that is + incorrect, or will have clues at the end of the file with the dump + of the memory usage of LaTeX. + + + + + + If the error at hand is not obvious after examination, a + fall-back strategy is to start commenting out the doxygen + input sources, which can be found in + doc/doxygen/user.cfg.in, look for the + INPUT tag. Start by commenting out whole + directories of header files, until the offending header is + identified. Then, read the latex log files to try and find + surround text, and look for that in the offending header. + + +
+
Markup @@ -611,6 +687,12 @@ info output + + epub3 stylesheets + b3 + epub output + + @@ -648,7 +730,7 @@ - For processing XML, an XML processor and some style + For processing XML, an XSLT processor and some style sheets are necessary. Defaults are xsltproc provided by libxslt. @@ -675,6 +757,10 @@ For Texinfo output, something that transforms valid Docbook XML to Texinfo is required. The default choice is docbook2X. + + + For epub output, the stylesheets for EPUB3 are required. These stylesheets are still in development. To validate the created file, epubcheck is necessary. +
Generating the DocBook Files @@ -711,7 +797,7 @@ If the Docbook stylesheets are installed in a custom location, one can use the variable XSL_STYLE_DIR to - over-ride the Makefile defaults. As so: + override the Makefile defaults. For example: @@ -722,6 +808,95 @@ make XSL_STYLE_DIR="/usr/share/xml/docbook/stylesheet/nwalsh"
+
+ Debugging Generation + + + Sometimes, mis-configuration of the pre-requisite tools can + lead to errors when attempting to build the + documentation. Here are some of the obvious errors, and ways + to fix some common issues that may appear quite cryptic. + + + + First, if using a rule like make pdf, try to + narrow down the scope of the error to either docbook + (make doc-pdf-docbook) or doxygen (make + doc-pdf-doxygen). + + + + Working on the docbook path only, closely examine the + contents of the following build directory: + build/target/libstdc++-v3/doc/docbook/latex. + Pay attention to three files enclosed within, annotated as follows. + + + + + + + spine.tex + + + + The actual latex file, or partial latex file. This is generated + via dblatex, and is the LaTeX version of the + DocBook XML file spine.xml. Go to a specific + line, and look at the genrated LaTeX, and try to deduce what + markup in spine.xml is causing it. + + + + + + spine.out + + + + A log of the conversion from the XML form to the LaTeX form. This + is a linear list, from the beginning of the + spine.xml file: the last entry of this file + should be the end of the DocBook file. If it is truncated, then + you know that the last entry is the last part of the XML source + file that is valid. The error is after this point. + + + + + + + spine.log + + + + A log of the compilation of the converted LaTeX form to pdf. This + is a linear list, from the beginning of the + spine.tex file: the last entry of this file + should be the end of the LaTeX file. If it is truncated, then you + know that the last entry is the last part of the generated LaTeX + source file that is valid. Often this file contains an error with + a specific line number of spine.tex that is + incorrect. + + + + + + + If the error at hand is not obvious after examination, or if one + encounters the inscruitable Incomplete + \ifmmode error, a fall-back strategy is to start + commenting out parts of the XML document (regardless of what + this does to over-all document validity). Start by + commenting out each of the largest parts of the + spine.xml file, section by section, + until the offending section is identified. + + + +
+
Editing and Validation