+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.
# 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.
# 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
${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}`; \
--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}
# 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
--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.
# 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.
# 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}`; \
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}`; \
# 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
# 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
<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-xml-doxygen</userinput></screen>
</para>
+ <para>
+ <screen><userinput>make doc-xml-single-doxygen</userinput></screen>
+ </para>
+
<para>
<screen><userinput>make doc-pdf-doxygen</userinput></screen>
</para>
</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>
document.
</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>
<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>
projects / thirdparty / gcc.git / commitdiff
