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.1all
@@ -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