From patchwork Wed Jul 21 02:07:53 2010 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: [v3] doc-xml Date: Tue, 20 Jul 2010 16:07:53 -0000 From: Benjamin Kosnik X-Patchwork-Id: 59397 Message-Id: <20100720190753.5cb376d7@shotwell> To: libstdc++@gcc.gnu.org, gcc-patches@gcc.gnu.org ... here is the patch 2010-07-19 Benjamin Kosnik * doc/xml/manual/appendix_contributing.xml: Update for new reality. * doc/Makefile.am (doc-xml): New default rule for XML output. (doc-xml-single-doxygen): Standardize output names. * doc/Makefile.in: Regenerate. * doc/doxygen/user.cfg.in: Tweak. Index: doc/xml/manual/appendix_contributing.xml =================================================================== --- doc/xml/manual/appendix_contributing.xml (revision 162360) +++ doc/xml/manual/appendix_contributing.xml (working copy) @@ -974,10 +974,18 @@ Generating the Doxygen Files The following Makefile rules run Doxygen to generate HTML - docs, XML docs, PDF docs, and the man pages. + docs, XML docs, XML docs as a single file, PDF docs, and the man pages. + Generated files are output into separate sub directores of + doc/doxygen/ in the + build directory, based on the output format. For instance, the + HTML docs will be in doc/doxygen/html. + + + make doc-html-doxygen @@ -986,6 +994,10 @@ + make doc-xml-single-doxygen + + + make doc-pdf-doxygen @@ -1236,23 +1248,30 @@ - For PDF output, something that transforms valid XML to PDF is - required. Possible solutions include - dblatex, - xmlto, or prince. Other - options are listed on the DocBook - web pages. Please + For PDF output, something that transforms valid Docbook XML to PDF is + required. Possible solutions include dblatex, + xmlto, or prince. Of + these, dblatex is the default. Other + options are listed on the DocBook web pages. Please consult the libstdc++@gcc.gnu.org list when preparing printed manuals for current best practice and suggestions. - Make sure that the XML documentation and markup is valid for - any change. This can be done easily, with the validation rules - in the Makefile, which is equivalent to doing: + For Texinfo output, something that transforms valid Docbook + XML to Texinfo is required. The default choice is docbook2X. + + Please make sure that the XML documentation and markup is valid for + any change. This can be done easily, with the validation rule + detailed below, which is equivalent to doing: + + xmllint --noout --valid xml/index.xml @@ -1271,6 +1290,14 @@ + Generated files are output into separate sub directores of + doc/docbook/ in the + build directory, based on the output format. For instance, the + HTML docs will be in doc/docbook/html. + + + make doc-html-docbook @@ -1524,20 +1551,90 @@ The following Makefile rules are defaults, and are usually - aliased to variable rules. + aliased to more detailed rules. They are shortcuts for + generating HTML, PDF, Texinfo, XML, or man files and then collecting + the generated files into the build directory's doc directory. + + + + make doc-html + + - make doc-html + Generates multi-page HTML documentation in the following directories: + + doc/libstdc++-api.html + + + doc/libstdc++-manual.html + + + + + make doc-man + + - make doc-man + Generates man pages in the following directory: + + doc/libstdc++-api.man + + + + + make doc-pdf + + - make doc-pdf + Generates indexed PDF documentation in the following files: + + doc/libstdc++-api.pdf + + + doc/libstdc++-manual.pdf + + + + + + make doc-texinfo + + + + Generates Texinfo documentation in the following files: + + + doc/libstdc++-manual.texinfo + + + + + + make doc-xml + + + + Generates single-file XML documentation in the following files: + + + doc/libstdc++-api.xml + + + doc/libstdc++-manual.xml + + + + + + + Index: doc/Makefile.am =================================================================== --- doc/Makefile.am (revision 162360) +++ doc/Makefile.am (working copy) @@ -28,7 +28,7 @@ # The first is the doxygen markup in libstdc++ sources, which is a # reference to the API. And the second is the docbook markup in # doc/xml/. -# +# # A third and more obscure option deals with charting # performance tests, and should be considered experimental. @@ -38,23 +38,29 @@ # create, and then copy into toplevel directory with standardized names # and layouts. +# HTML +doc-html: doc-html-docbook doc-html-doxygen + cp -R ${docbook_outdir}/html ./libstdc++-manual.html + cp -R ${doxygen_outdir}/html ./libstdc++-api.html + # MAN doc-man: doc-man-doxygen cp -R ${doxygen_outdir}/man ./libstdc++-api.man # PDF doc-pdf: doc-pdf-docbook doc-pdf-doxygen - cp ${docbook_outdir}/pdf/libstdc++-manual.pdf . + cp ${docbook_outdir}/pdf/libstdc++-manual.pdf . cp ${doxygen_outdir}/pdf/libstdc++-api.pdf . -# HTML -doc-html: doc-html-docbook doc-html-doxygen - cp -R ${docbook_outdir}/html ./libstdc++-manual.html - cp -R ${doxygen_outdir}/html ./libstdc++-api.html - # TEXINFO doc-texinfo: doc-texinfo-docbook +# XML +doc-xml: doc-xml-single-docbook doc-xml-single-doxygen + cp ${manual_xml} . + cp ${api_xml} . + + # Doxygen configuration # Assumes doxygen, graphviz (with dot), pdflatex installed doxygen_script=${top_srcdir}/scripts/run_doxygen @@ -78,10 +84,11 @@ ${SHELL} ${doxygen_script} \ --host_alias=${host_alias} --mode=xml $${srcdir} $${builddir} NO) -doc-xml-single-doxygen: +api_xml = ${doxygen_outdir}/xml/libstdc++-api-single.xml +doc-xml-single-doxygen: doc-xml-doxygen @echo "Generating doxygen xml single file..." $(XSLTPROC) ${doxygen_outdir}/xml/combine.xslt \ - ${doxygen_outdir}/xml/index.xml > ${doxygen_outdir}/xml/api-spine.xml; + ${doxygen_outdir}/xml/index.xml > ${api_xml}; doc-latex-doxygen: -(srcdir=`cd ${top_srcdir}; ${PWD_COMMAND}`; \ @@ -287,7 +294,7 @@ --encoding=utf-8//TRANSLIT \ --string-param output-file="libstdc++-manual" \ --string-param directory-category="GNU C++ Library" \ - --string-param explicit-node-names=true + --string-param explicit-node-names=true doc-texinfo-docbook: doc-xml-single-docbook ${docbook_outdir}/texinfo @echo "Generating texinfo files..." db2x_docbook2texi $(DB2TEXI_FLAGS) ${manual_xml} Index: doc/doxygen/user.cfg.in =================================================================== --- doc/doxygen/user.cfg.in (revision 162360) +++ doc/doxygen/user.cfg.in (working copy) @@ -247,7 +247,7 @@ # setting a simple type. If this is not the case, or you want to show the # methods anyway, you should set this option to NO. -IDL_PROPERTY_SUPPORT = YES +IDL_PROPERTY_SUPPORT = NO # If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC # tag is set to YES, then doxygen will reuse the documentation of the first @@ -1035,17 +1035,18 @@ # reverse domain-name style string, e.g. com.mycompany.MyDocSet. Doxygen # will append .docset to the name. -DOCSET_BUNDLE_ID = org.doxygen.Project +DOCSET_BUNDLE_ID = org.gnu.libstdc++ -# When GENERATE_PUBLISHER_ID tag specifies a string that should uniquely identify -# the documentation publisher. This should be a reverse domain-name style -# string, e.g. com.mycompany.MyDocSet.documentation. +# When GENERATE_PUBLISHER_ID tag specifies a string that should +# uniquely identify the documentation publisher. This should be a +# reverse domain-name style string, +# e.g. com.mycompany.MyDocSet.documentation. -DOCSET_PUBLISHER_ID = org.doxygen.Publisher +DOCSET_PUBLISHER_ID = org.fsf # The GENERATE_PUBLISHER_NAME tag identifies the documentation publisher. -DOCSET_PUBLISHER_NAME = Publisher +DOCSET_PUBLISHER_NAME = libstdc++ # If the GENERATE_HTMLHELP tag is set to YES, additional index files # will be generated that can be used as input for tools like the