appendix_contributing.xml: Update for new reality.

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.

From-SVN: r162361

5 files changed, 161 insertions, 42 deletions

diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog
index ac0c618..fd528b7 100644
--- a/libstdc++-v3/ChangeLog
+++ b/libstdc++-v3/ChangeLog
@@ -1,3 +1,12 @@
+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.
+
 2010-07-20  Paolo Carlini  <paolo.carlini@oracle.com>
 
 	* libsupc++/unwind-cxx.h: Minor formatting / stylistic tweaks.
diff --git a/libstdc++-v3/doc/Makefile.am b/libstdc++-v3/doc/Makefile.am
index 1454140..79325ca 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 fbdfb51..485aac4 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 89a1d4a..c9e86a5 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 b73b8f4..a9d3281 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.
       <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>
@@ -986,6 +994,10 @@ indicate a place that may require attention for multi-thread safety.
       </para>
 
       <para>
+      <screen><userinput>make doc-xml-single-doxygen</userinput></screen>
+      </para>
+
+      <para>
       <screen><userinput>make doc-pdf-doxygen</userinput></screen>
       </para>
 
@@ -1236,21 +1248,28 @@ indicate a place that may require attention for multi-thread safety.
       </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>
@@ -1271,6 +1290,14 @@ xmllint --noout --valid <filename>xml/index.xml</filename>
       </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 @@ xmllint --noout --valid <filename>xml/index.xml</filename>
 
       <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>
+	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>
+	Generates man pages in the following directory:
+      </para>
       <para>
-      <screen><userinput>make doc-html</userinput></screen>
+	<filename class="directory">doc/libstdc++-api.man</filename>
       </para>
+</listitem>
+</varlistentry>
 
+<varlistentry><term>
+      <emphasis>make doc-pdf</emphasis>
+    </term>
+<listitem>
+      <para>
+	Generates indexed PDF documentation in the following files:
+      </para>
       <para>
-      <screen><userinput>make doc-man</userinput></screen>
+	<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>
-      <screen><userinput>make doc-pdf</userinput></screen>
+	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>