Skip to content

R
riscv-gcc-1
Commit 7d8cafcd by Benjamin Kosnik Committed by Benjamin Kosnik
Options

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
parent eb061dfb
Showing with 161 additions and 42 deletions
libstdc++-v3/ChangeLog
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.
......
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}
......
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}`; \
......
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
......
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>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment