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 155 additions and 36 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> 2010-07-20 Paolo Carlini <paolo.carlini@oracle.com>
* libsupc++/unwind-cxx.h: Minor formatting / stylistic tweaks. * libsupc++/unwind-cxx.h: Minor formatting / stylistic tweaks.
......
libstdc++-v3/doc/Makefile.am
...@@ -38,6 +38,11 @@ include $(top_srcdir)/fragment.am ...@@ -38,6 +38,11 @@ include $(top_srcdir)/fragment.am
# create, and then copy into toplevel directory with standardized names # create, and then copy into toplevel directory with standardized names
# and layouts. # 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 # MAN
doc-man: doc-man-doxygen doc-man: doc-man-doxygen
cp -R ${doxygen_outdir}/man ./libstdc++-api.man cp -R ${doxygen_outdir}/man ./libstdc++-api.man
...@@ -47,14 +52,15 @@ doc-pdf: doc-pdf-docbook doc-pdf-doxygen ...@@ -47,14 +52,15 @@ 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 . 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 # TEXINFO
doc-texinfo: doc-texinfo-docbook doc-texinfo: doc-texinfo-docbook
# XML
doc-xml: doc-xml-single-docbook doc-xml-single-doxygen
cp ${manual_xml} .
cp ${api_xml} .
# Doxygen configuration # Doxygen configuration
# Assumes doxygen, graphviz (with dot), pdflatex installed # Assumes doxygen, graphviz (with dot), pdflatex installed
doxygen_script=${top_srcdir}/scripts/run_doxygen doxygen_script=${top_srcdir}/scripts/run_doxygen
...@@ -78,10 +84,11 @@ doc-xml-doxygen: ...@@ -78,10 +84,11 @@ doc-xml-doxygen:
${SHELL} ${doxygen_script} \ ${SHELL} ${doxygen_script} \
--host_alias=${host_alias} --mode=xml $${srcdir} $${builddir} NO) --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..." @echo "Generating doxygen xml single file..."
$(XSLTPROC) ${doxygen_outdir}/xml/combine.xslt \ $(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: doc-latex-doxygen:
-(srcdir=`cd ${top_srcdir}; ${PWD_COMMAND}`; \ -(srcdir=`cd ${top_srcdir}; ${PWD_COMMAND}`; \
......
libstdc++-v3/doc/Makefile.in
...@@ -267,6 +267,7 @@ AM_CPPFLAGS = $(GLIBCXX_INCLUDES) ...@@ -267,6 +267,7 @@ AM_CPPFLAGS = $(GLIBCXX_INCLUDES)
# Assumes doxygen, graphviz (with dot), pdflatex installed # Assumes doxygen, graphviz (with dot), pdflatex installed
doxygen_script = ${top_srcdir}/scripts/run_doxygen doxygen_script = ${top_srcdir}/scripts/run_doxygen
doxygen_outdir = ${glibcxx_builddir}/doc/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, # Chance of loooooonnggg creation time on this rule. Iff this fails,
# look at refman.log and see if TeX's memory is exhausted. Symptoms # look at refman.log and see if TeX's memory is exhausted. Symptoms
...@@ -570,6 +571,11 @@ uninstall-am: ...@@ -570,6 +571,11 @@ uninstall-am:
# create, and then copy into toplevel directory with standardized names # create, and then copy into toplevel directory with standardized names
# and layouts. # 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 # MAN
doc-man: doc-man-doxygen doc-man: doc-man-doxygen
cp -R ${doxygen_outdir}/man ./libstdc++-api.man cp -R ${doxygen_outdir}/man ./libstdc++-api.man
...@@ -579,14 +585,14 @@ doc-pdf: doc-pdf-docbook doc-pdf-doxygen ...@@ -579,14 +585,14 @@ 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 . 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 # TEXINFO
doc-texinfo: doc-texinfo-docbook 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: doc-html-doxygen:
-(srcdir=`cd ${top_srcdir}; ${PWD_COMMAND}`; \ -(srcdir=`cd ${top_srcdir}; ${PWD_COMMAND}`; \
builddir=`cd ..; ${PWD_COMMAND}`; \ builddir=`cd ..; ${PWD_COMMAND}`; \
...@@ -604,11 +610,10 @@ doc-xml-doxygen: ...@@ -604,11 +610,10 @@ doc-xml-doxygen:
builddir=`cd ..; ${PWD_COMMAND}`; \ builddir=`cd ..; ${PWD_COMMAND}`; \
${SHELL} ${doxygen_script} \ ${SHELL} ${doxygen_script} \
--host_alias=${host_alias} --mode=xml $${srcdir} $${builddir} NO) --host_alias=${host_alias} --mode=xml $${srcdir} $${builddir} NO)
doc-xml-single-doxygen: doc-xml-doxygen
doc-xml-single-doxygen:
@echo "Generating doxygen xml single file..." @echo "Generating doxygen xml single file..."
$(XSLTPROC) ${doxygen_outdir}/xml/combine.xslt \ $(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: doc-latex-doxygen:
-(srcdir=`cd ${top_srcdir}; ${PWD_COMMAND}`; \ -(srcdir=`cd ${top_srcdir}; ${PWD_COMMAND}`; \
......
libstdc++-v3/doc/doxygen/user.cfg.in
...@@ -247,7 +247,7 @@ SIP_SUPPORT = NO ...@@ -247,7 +247,7 @@ SIP_SUPPORT = NO
# setting a simple type. If this is not the case, or you want to show the # 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. # 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 # 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 # tag is set to YES, then doxygen will reuse the documentation of the first
...@@ -1035,17 +1035,18 @@ DOCSET_FEEDNAME = "Doxygen generated docs" ...@@ -1035,17 +1035,18 @@ DOCSET_FEEDNAME = "Doxygen generated docs"
# reverse domain-name style string, e.g. com.mycompany.MyDocSet. Doxygen # reverse domain-name style string, e.g. com.mycompany.MyDocSet. Doxygen
# will append .docset to the name. # 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 # When GENERATE_PUBLISHER_ID tag specifies a string that should
# the documentation publisher. This should be a reverse domain-name style # uniquely identify the documentation publisher. This should be a
# string, e.g. com.mycompany.MyDocSet.documentation. # 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. # 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 # 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 # 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. ...@@ -974,7 +974,15 @@ indicate a place that may require attention for multi-thread safety.
<title>Generating the Doxygen Files</title> <title>Generating the Doxygen Files</title>
<para> <para>
The following Makefile rules run Doxygen to generate HTML 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>
<para> <para>
...@@ -986,6 +994,10 @@ indicate a place that may require attention for multi-thread safety. ...@@ -986,6 +994,10 @@ indicate a place that may require attention for multi-thread safety.
</para> </para>
<para> <para>
<screen><userinput>make doc-xml-single-doxygen</userinput></screen>
</para>
<para>
<screen><userinput>make doc-pdf-doxygen</userinput></screen> <screen><userinput>make doc-pdf-doxygen</userinput></screen>
</para> </para>
...@@ -1236,21 +1248,28 @@ indicate a place that may require attention for multi-thread safety. ...@@ -1236,21 +1248,28 @@ indicate a place that may require attention for multi-thread safety.
</para> </para>
<para> <para>
For PDF output, something that transforms valid XML to PDF is For PDF output, something that transforms valid Docbook XML to PDF is
required. Possible solutions include required. Possible solutions include <ulink
<ulink url="http://dblatex.sourceforge.net">dblatex</ulink>, url="http://dblatex.sourceforge.net">dblatex</ulink>,
<command>xmlto</command>, or <command>prince</command>. Other <command>xmlto</command>, or <command>prince</command>. Of
options are listed on the DocBook these, <command>dblatex</command> is the default. Other
web <ulink url="http://wiki.docbook.org/topic/DocBookPublishingTools">pages</ulink>. Please 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 consult the <email>libstdc++@gcc.gnu.org</email> list when
preparing printed manuals for current best practice and preparing printed manuals for current best practice and
suggestions. suggestions.
</para> </para>
<para> <para>
Make sure that the XML documentation and markup is valid for For Texinfo output, something that transforms valid Docbook
any change. This can be done easily, with the validation rules XML to Texinfo is required. The default choice is <ulink
in the <filename>Makefile</filename>, which is equivalent to doing: 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> </para>
<screen> <screen>
...@@ -1271,6 +1290,14 @@ xmllint --noout --valid <filename>xml/index.xml</filename> ...@@ -1271,6 +1290,14 @@ xmllint --noout --valid <filename>xml/index.xml</filename>
</para> </para>
<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> <screen><userinput>make doc-html-docbook</userinput></screen>
</para> </para>
...@@ -1524,20 +1551,90 @@ xmllint --noout --valid <filename>xml/index.xml</filename> ...@@ -1524,20 +1551,90 @@ xmllint --noout --valid <filename>xml/index.xml</filename>
<para> <para>
The following Makefile rules are defaults, and are usually 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> </para>
</listitem>
</varlistentry>
<varlistentry><term>
<emphasis>make doc-man</emphasis>
</term>
<listitem>
<para>
Generates man pages in the following directory:
</para>
<para> <para>
<screen><userinput>make doc-html</userinput></screen> <filename class="directory">doc/libstdc++-api.man</filename>
</para> </para>
</listitem>
</varlistentry>
<varlistentry><term>
<emphasis>make doc-pdf</emphasis>
</term>
<listitem>
<para>
Generates indexed PDF documentation in the following files:
</para>
<para> <para>
<screen><userinput>make doc-man</userinput></screen> <filename>doc/libstdc++-api.pdf</filename>
</para> </para>
<para>
<filename>doc/libstdc++-manual.pdf</filename>
</para>
</listitem>
</varlistentry>
<varlistentry><term>
<emphasis>make doc-texinfo</emphasis>
</term>
<listitem>
<para> <para>
<screen><userinput>make doc-pdf</userinput></screen> Generates Texinfo documentation in the following files:
</para> </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> </sect3>
</sect2> </sect2>
</sect1> </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