From patchwork Wed Jul 21 02:07:53 2010 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Benjamin Kosnik X-Patchwork-Id: 59397 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from sourceware.org (server1.sourceware.org [209.132.180.131]) by ozlabs.org (Postfix) with SMTP id 784D9B70BB for ; Wed, 21 Jul 2010 12:08:11 +1000 (EST) Received: (qmail 4085 invoked by alias); 21 Jul 2010 02:08:05 -0000 Received: (qmail 3989 invoked by uid 22791); 21 Jul 2010 02:08:03 -0000 X-SWARE-Spam-Status: No, hits=-5.2 required=5.0 tests=AWL, BAYES_00, RCVD_IN_DNSWL_HI, SPF_HELO_PASS, TW_PH, T_RP_MATCHES_RCVD X-Spam-Check-By: sourceware.org Received: from mx1.redhat.com (HELO mx1.redhat.com) (209.132.183.28) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Wed, 21 Jul 2010 02:07:56 +0000 Received: from int-mx02.intmail.prod.int.phx2.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) by mx1.redhat.com (8.13.8/8.13.8) with ESMTP id o6L27sp1022907 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Tue, 20 Jul 2010 22:07:54 -0400 Received: from shotwell (ovpn-113-72.phx2.redhat.com [10.3.113.72]) by int-mx02.intmail.prod.int.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id o6L27rw3006079; Tue, 20 Jul 2010 22:07:54 -0400 Date: Tue, 20 Jul 2010 19:07:53 -0700 From: Benjamin Kosnik To: libstdc++@gcc.gnu.org, gcc-patches@gcc.gnu.org Subject: [v3] doc-xml Message-ID: <20100720190753.5cb376d7@shotwell> Mime-Version: 1.0 Mailing-List: contact gcc-patches-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Archive: List-Post: List-Help: Sender: gcc-patches-owner@gcc.gnu.org Delivered-To: mailing list 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