This is the mail archive of the
gcc-patches@gcc.gnu.org
mailing list for the GCC project.
[v3] doc-xml
- From: Benjamin Kosnik <bkoz at redhat dot com>
- To: libstdc++ at gcc dot gnu dot org, gcc-patches at gcc dot gnu dot org
- Date: Tue, 20 Jul 2010 19:07:53 -0700
- Subject: [v3] doc-xml
... here is the patch
2010-07-19 Benjamin Kosnik <bkoz@redhat.com>
* 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 @@
<title>Generating the Doxygen Files</title>
<para>
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.
</para>
<para>
+ Generated files are output into separate sub directores of
+ <filename class="directory">doc/doxygen/</filename> in the
+ build directory, based on the output format. For instance, the
+ HTML docs will be in <filename
+ class="directory">doc/doxygen/html</filename>.
+ </para>
+
+ <para>
<screen><userinput>make doc-html-doxygen</userinput></screen>
</para>
@@ -986,6 +994,10 @@
</para>
<para>
+ <screen><userinput>make doc-xml-single-doxygen</userinput></screen>
+ </para>
+
+ <para>
<screen><userinput>make doc-pdf-doxygen</userinput></screen>
</para>
@@ -1236,23 +1248,30 @@
</para>
<para>
- For PDF output, something that transforms valid XML to PDF is
- required. Possible solutions include
- <ulink url="http://dblatex.sourceforge.net";>dblatex</ulink>,
- <command>xmlto</command>, or <command>prince</command>. Other
- options are listed on the DocBook
- web <ulink url="http://wiki.docbook.org/topic/DocBookPublishingTools";>pages</ulink>. Please
+ For PDF output, something that transforms valid Docbook XML to PDF is
+ required. Possible solutions include <ulink
+ url="http://dblatex.sourceforge.net";>dblatex</ulink>,
+ <command>xmlto</command>, or <command>prince</command>. Of
+ these, <command>dblatex</command> is the default. Other
+ options are listed on the DocBook web <ulink
+ url="http://wiki.docbook.org/topic/DocBookPublishingTools";>pages</ulink>. Please
consult the <email>libstdc++@gcc.gnu.org</email> list when
preparing printed manuals for current best practice and
suggestions.
</para>
<para>
- Make sure that the XML documentation and markup is valid for
- any change. This can be done easily, with the validation rules
- in the <filename>Makefile</filename>, which is equivalent to doing:
+ For Texinfo output, something that transforms valid Docbook
+ XML to Texinfo is required. The default choice is <ulink
+ url="http://docbook2x.sourceforge.net/";>docbook2X</ulink>.
</para>
+ <para>
+ 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:
+ </para>
+
<screen>
<userinput>
xmllint --noout --valid <filename>xml/index.xml</filename>
@@ -1271,6 +1290,14 @@
</para>
<para>
+ Generated files are output into separate sub directores of
+ <filename class="directory">doc/docbook/</filename> in the
+ build directory, based on the output format. For instance, the
+ HTML docs will be in <filename
+ class="directory">doc/docbook/html</filename>.
+ </para>
+
+ <para>
<screen><userinput>make doc-html-docbook</userinput></screen>
</para>
@@ -1524,20 +1551,90 @@
<para>
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.
</para>
+<variablelist>
+
+<varlistentry><term>
+ <emphasis>make doc-html</emphasis>
+ </term>
+<listitem>
<para>
- <screen><userinput>make doc-html</userinput></screen>
+ Generates multi-page HTML documentation in the following directories:
</para>
+ <para>
+ <filename class="directory">doc/libstdc++-api.html</filename>
+ </para>
+ <para>
+ <filename class="directory">doc/libstdc++-manual.html</filename>
+ </para>
+</listitem>
+</varlistentry>
+<varlistentry><term>
+ <emphasis>make doc-man</emphasis>
+ </term>
+<listitem>
<para>
- <screen><userinput>make doc-man</userinput></screen>
+ Generates man pages in the following directory:
</para>
+ <para>
+ <filename class="directory">doc/libstdc++-api.man</filename>
+ </para>
+</listitem>
+</varlistentry>
+<varlistentry><term>
+ <emphasis>make doc-pdf</emphasis>
+ </term>
+<listitem>
<para>
- <screen><userinput>make doc-pdf</userinput></screen>
+ Generates indexed PDF documentation in the following files:
</para>
+ <para>
+ <filename>doc/libstdc++-api.pdf</filename>
+ </para>
+ <para>
+ <filename>doc/libstdc++-manual.pdf</filename>
+ </para>
+</listitem>
+</varlistentry>
+
+<varlistentry><term>
+ <emphasis>make doc-texinfo</emphasis>
+ </term>
+<listitem>
+ <para>
+ Generates Texinfo documentation in the following files:
+ </para>
+ <para>
+ <filename>doc/libstdc++-manual.texinfo</filename>
+ </para>
+</listitem>
+</varlistentry>
+
+<varlistentry><term>
+ <emphasis>make doc-xml</emphasis>
+ </term>
+<listitem>
+ <para>
+ Generates single-file XML documentation in the following files:
+ </para>
+ <para>
+ <filename>doc/libstdc++-api.xml</filename>
+ </para>
+ <para>
+ <filename>doc/libstdc++-manual.xml</filename>
+ </para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+
</sect3>
</sect2>
</sect1>
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