From 7d8cafcde8aee5ccd585b17d33d5a8389351a20f Mon Sep 17 00:00:00 2001 From: Benjamin Kosnik Date: Wed, 21 Jul 2010 02:02:42 +0000 Subject: [PATCH] appendix_contributing.xml: Update for new reality. 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. From-SVN: r162361 --- libstdc++-v3/ChangeLog | 9 ++ libstdc++-v3/doc/Makefile.am | 27 ++-- libstdc++-v3/doc/Makefile.in | 27 ++-- libstdc++-v3/doc/doxygen/user.cfg.in | 15 +- .../doc/xml/manual/appendix_contributing.xml | 129 +++++++++++++++--- 5 files changed, 163 insertions(+), 44 deletions(-) diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index ac0c6183571..fd528b7f128 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,12 @@ +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. + 2010-07-20 Paolo Carlini * libsupc++/unwind-cxx.h: Minor formatting / stylistic tweaks. diff --git a/libstdc++-v3/doc/Makefile.am b/libstdc++-v3/doc/Makefile.am index 1454140c943..79325caffa0 100644 --- a/libstdc++-v3/doc/Makefile.am +++ b/libstdc++-v3/doc/Makefile.am @@ -28,7 +28,7 @@ include $(top_srcdir)/fragment.am # 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 @@ include $(top_srcdir)/fragment.am # 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 @@ doc-xml-doxygen: ${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 @@ DB2TEXI_FLAGS = \ --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} diff --git a/libstdc++-v3/doc/Makefile.in b/libstdc++-v3/doc/Makefile.in index fbdfb51ec01..485aac4fba5 100644 --- a/libstdc++-v3/doc/Makefile.in +++ b/libstdc++-v3/doc/Makefile.in @@ -267,6 +267,7 @@ AM_CPPFLAGS = $(GLIBCXX_INCLUDES) # Assumes doxygen, graphviz (with dot), pdflatex installed doxygen_script = ${top_srcdir}/scripts/run_doxygen doxygen_outdir = ${glibcxx_builddir}/doc/doxygen +api_xml = ${doxygen_outdir}/xml/libstdc++-api-single.xml # Chance of loooooonnggg creation time on this rule. Iff this fails, # look at refman.log and see if TeX's memory is exhausted. Symptoms @@ -389,7 +390,7 @@ DB2TEXI_FLAGS = \ --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 # Performance doc and graph configuration. @@ -560,7 +561,7 @@ uninstall-am: # 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. @@ -570,23 +571,28 @@ uninstall-am: # 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} . + doc-html-doxygen: -(srcdir=`cd ${top_srcdir}; ${PWD_COMMAND}`; \ builddir=`cd ..; ${PWD_COMMAND}`; \ @@ -604,11 +610,10 @@ doc-xml-doxygen: builddir=`cd ..; ${PWD_COMMAND}`; \ ${SHELL} ${doxygen_script} \ --host_alias=${host_alias} --mode=xml $${srcdir} $${builddir} NO) - -doc-xml-single-doxygen: +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}`; \ diff --git a/libstdc++-v3/doc/doxygen/user.cfg.in b/libstdc++-v3/doc/doxygen/user.cfg.in index 89a1d4a0899..c9e86a51884 100644 --- a/libstdc++-v3/doc/doxygen/user.cfg.in +++ b/libstdc++-v3/doc/doxygen/user.cfg.in @@ -247,7 +247,7 @@ SIP_SUPPORT = NO # 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 @@ DOCSET_FEEDNAME = "Doxygen generated docs" # 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 diff --git a/libstdc++-v3/doc/xml/manual/appendix_contributing.xml b/libstdc++-v3/doc/xml/manual/appendix_contributing.xml index b73b8f4c3fb..a9d32814df0 100644 --- a/libstdc++-v3/doc/xml/manual/appendix_contributing.xml +++ b/libstdc++-v3/doc/xml/manual/appendix_contributing.xml @@ -974,7 +974,15 @@ indicate a place that may require attention for multi-thread safety. 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. @@ -985,6 +993,10 @@ indicate a place that may require attention for multi-thread safety. make doc-xml-doxygen + + make doc-xml-single-doxygen + + make doc-pdf-doxygen @@ -1236,21 +1248,28 @@ indicate a place that may require attention for multi-thread safety. - 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: @@ -1270,6 +1289,14 @@ xmllint --noout --valid xml/index.xml document. + + 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 @@ xmllint --noout --valid xml/index.xml 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 + + - make doc-man + Generates multi-page HTML documentation in the following directories: + + doc/libstdc++-api.html + + + doc/libstdc++-manual.html + + + + + make doc-man + + - make doc-pdf + Generates man pages in the following directory: + + doc/libstdc++-api.man + + + + + + 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 + + + + + + +