mirror of
git://gcc.gnu.org/git/gcc.git
synced 2025-04-13 09:00:40 +08:00
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
This commit is contained in:
Benjamin Kosnik
Benjamin Kosnik
parent
eb061dfbca
commit
7d8cafcde8
libstdc++-v3
@ -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.
|
||||
|
||||
@ -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}
|
||||
|
||||
@ -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}`; \
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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>
|
||||
@ -985,6 +993,10 @@ indicate a place that may require attention for multi-thread safety.
|
||||
<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>
|
||||
@ -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>
|
||||
@ -1270,6 +1289,14 @@ xmllint --noout --valid <filename>xml/index.xml</filename>
|
||||
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>
|
||||
@ -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>
|
||||
|
||||
<para>
|
||||
<screen><userinput>make doc-html</userinput></screen>
|
||||
</para>
|
||||
<variablelist>
|
||||
|
||||
<varlistentry><term>
|
||||
<emphasis>make doc-html</emphasis>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
<screen><userinput>make doc-man</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-pdf</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>
|
||||
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>
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user