Patchwork [v3] doc-xml

login
register
mail settings
Submitter Benjamin Kosnik
Date July 21, 2010, 2:07 a.m.
Message ID <20100720190753.5cb376d7@shotwell>
Download mbox | patch
Permalink /patch/59397/
State New
Headers show

Comments

Benjamin Kosnik - July 21, 2010, 2:07 a.m.
... here is the patch

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