This is the mail archive of the
gcc-patches@gcc.gnu.org
mailing list for the GCC project.
[v3] doc-latex-doxygen, doc-pdf-doxygen
- From: Benjamin Kosnik <bkoz at redhat dot com>
- To: gcc-patches at gcc dot gnu dot org, libstdc++ at gcc dot gnu dot org
- Date: Wed, 3 Mar 2010 19:28:52 -0800
- Subject: [v3] doc-latex-doxygen, doc-pdf-doxygen
Adds an option, doc-pdf-doxygen, that builds a pdf version of the
doxygen API reference. This generated document is quite large (4k
pages, 20MB). See it here:
http://people.redhat.com/bkoz/documentation/20100303-libstdc++-api.pdf.bz2
I was really trying to solve the intra-linking issue, where docbook can
link directly into a stable doxygen link, and did this while
investigating potential solutions.
Fixes in run_doxygen.sh as I was add the latex support, to remove
doxygen workarounds that are not present in current (1.6.1) releases.
I "tested" the generated pdf manual to make sure it could be opened and
read on fedora 12, and mac. Some of the index nesting for various
groups is not nested (sequence should be under containers) but that
seems minor considering the sheer number of Makefile hacks necessary to
get to this point.
tested x86/linux
-benjamin
2010-03-03 Benjamin Kosnik <bkoz@redhat.com>
* doc/Makefile.am: Re-organize xml sources.
(doc-latex-doxygen): New.
(doc-pdf-doxygen): New.
(stamp-xml-doxygen, stamp-latex-doxygen): New.
* doc/Makefile.in: Regenerate.
* doc/doxygen/user.cfg.in: Add support here.
* doc/xml/manual/appendix_contributing.xml: Add specifics.
* doc/xml/manual/concurrency.xml: New.
* doc/xml/manual/atomics.xml: New.
* doc/xml/manual/spine.xml: Adjust.
* doc/xml/manual/diagnostics.xml: Adjust.
Index: scripts/run_doxygen
===================================================================
--- scripts/run_doxygen (revision 157213)
+++ scripts/run_doxygen (working copy)
@@ -1,10 +1,10 @@
#!/bin/bash
# Runs doxygen and massages the output files.
-# Copyright (C) 2001, 2002, 2003, 2004, 2008, 2009
+# Copyright (C) 2001, 2002, 2003, 2004, 2008, 2009, 2010
# Free Software Foundation, Inc.
#
-# Synopsis: run_doxygen --mode=[html|man|xml] --host_alias=<alias> \
+# Synopsis: run_doxygen --mode=[html|latex|man|xml] --host_alias=<alias> \
# v3srcdir \
# v3builddir \
# shortname
@@ -17,7 +17,7 @@
find_doxygen() {
local -r v_required=`echo $DOXYVER | \
- awk -F. '{if(NF<3)$3=0;print ($1*100+$2)*100+$3}'`
+ awk -F. '{if(NF<3)$3=0;print ($1*100+$2)*100+$3}'`
local testing_version doxygen maybedoxy v_found
# thank you goat book
set `IFS=:; X="$PATH:/usr/local/bin:/bin:/usr/bin"; echo $X`
@@ -28,16 +28,16 @@
test -f "$maybedoxy" && testing_version=`$maybedoxy --version`
if test -n "$testing_version"; then
v_found=`echo $testing_version | \
- awk -F. '{if(NF<3)$3=0;print ($1*100+$2)*100+$3}'`
+ awk -F. '{if(NF<3)$3=0;print ($1*100+$2)*100+$3}'`
if test $v_found -ge $v_required; then
- doxygen="$maybedoxy"
- break
+ doxygen="$maybedoxy"
+ break
fi
fi
done
if test -z "$doxygen"; then
- echo run_doxygen error: Could not find Doxygen $DOXYVER in path. 1>&2
- print_usage
+ echo run_doxygen error: Could not find Doxygen $DOXYVER in path. 1>&2
+ print_usage
fi
# We need to use other tools from the same package/version.
echo :: Using Doxygen tools from ${dir}.
@@ -48,11 +48,12 @@
print_usage() {
cat 1>&2 <<EOF
Usage: run_doxygen --mode=MODE --host_alias=BUILD_ALIAS [<options>]
- <v3-src-dir> <v3-build-dir> <shortnamesp>
+ <v3-src-dir> <v3-build-dir> <shortnamesp>
MODE is one of:
- html Generate user-level HTML library documentation.
- man Generate user-level man pages.
- xml Generate user-level XML pages.
+ html Generate user-level HTML library documentation.
+ man Generate user-level man pages.
+ xml Generate user-level XML pages.
+ latex Generate user-level LaTeX pages.
BUILD_ALIAS is the GCC build alias set at configure time.
@@ -75,25 +76,25 @@
case "$o" in
--mode=*)
- mode=$arg ;;
+ mode=$arg ;;
--host_alias=*)
- host_alias=$arg ;;
+ host_alias=$arg ;;
--mode | --host_alias | --help | -h)
- print_usage ;;
+ print_usage ;;
*)
- # this turned out to be a mess, maybe change to --srcdir=, etc
- if test $srcdir = unset; then
- srcdir=$o
- elif test $outdir = unset; then
- builddir=${o}
- outdir=${o}/doc/doxygen
- elif test $shortname = unset; then
- shortname=$o
- else
- echo run_doxygen error: Too many arguments 1>&2
- exit 1
- fi
- ;;
+ # this turned out to be a mess, maybe change to --srcdir=, etc
+ if test $srcdir = unset; then
+ srcdir=$o
+ elif test $outdir = unset; then
+ builddir=${o}
+ outdir=${o}/doc/doxygen
+ elif test $shortname = unset; then
+ shortname=$o
+ else
+ echo run_doxygen error: Too many arguments 1>&2
+ exit 1
+ fi
+ ;;
esac
done
}
@@ -106,8 +107,9 @@
outdir=unset
shortname=unset
do_html=false
-do_man=false
-do_xml=false
+do_man=false
+do_xml=false
+do_latex=false
enabled_sections=
generate_tagfile=
DATEtext=`date '+%Y-%m-%d'`
@@ -130,6 +132,10 @@
enabled_sections=maint
generate_tagfile="$outdir/html/libstdc++.tag"
;;
+ xlatex)
+ do_latex=true
+ enabled_sections=maint
+ ;;
xman)
do_man=true
;;
@@ -156,12 +162,6 @@
mkdir -p $outdir
chmod u+w $outdir
-# work around a stupid doxygen bug
-if $do_man; then
- mkdir -p $outdir/man/man3/ext
- chmod -R u+w $outdir/man/man3/ext
-fi
-
if $do_xml; then
mkdir -p $outdir/xml
fi
@@ -176,6 +176,7 @@
-e "s=@host_alias@=${host_alias}=g" \
-e "s=@enabled_sections@=${enabled_sections}=" \
-e "s=@do_html@=${do_html}=" \
+ -e "s=@do_latex@=${do_latex}=" \
-e "s=@do_man@=${do_man}=" \
-e "s=@do_xml@=${do_xml}=" \
-e "s=@generate_tagfile@=${generate_tagfile}=" \
@@ -188,6 +189,40 @@
ret=$?
test $ret -ne 0 && exit $ret
+if $do_latex; then
+ mkdir -p $outdir/latex
+fi
+
+(
+ set -e
+ cd $builddir
+ sed -e "s=@outdir@=${outdir}=g" \
+ -e "s=@srcdir@=${srcdir}=g" \
+ -e "s=@shortname@=${shortname}=g" \
+ -e "s=@builddir@=${builddir}=g" \
+ -e "s=@host_alias@=${host_alias}=g" \
+ -e "s=@enabled_sections@=${enabled_sections}=" \
+ -e "s=@do_html@=${do_html}=" \
+ -e "s=@do_latex@=${do_latex}=" \
+ -e "s=@do_man@=${do_man}=" \
+ -e "s=@do_xml@=${do_xml}=" \
+ -e "s=@generate_tagfile@=${generate_tagfile}=" \
+ ${srcdir}/doc/doxygen/user.cfg.in > ${outdir}/${mode}.cfg
+ echo :: NOTE that this may take some time...
+ echo doxygen ${outdir}/${mode}.cfg
+ doxygen ${outdir}/${mode}.cfg
+
+ # Also drop in the header file and style sheet
+ cd ${outdir}/${mode}
+ doxygen -w latex header.tex doxygen.sty
+ echo :: Finished, exit code was $?
+ echo ::
+ echo :: LaTeX pages begin with
+ echo :: ${outdir}/latex/refman.tex
+)
+ret=$?
+test $ret -ne 0 && exit $ret
+
if $do_html; then
cd ${outdir}/html
@@ -206,13 +241,6 @@
sed -e 's=\(::[[:alnum:]_]*\)< .* >=\1=' annotated.html > annstrip.html
mv annstrip.html annotated.html
- # Work around a bug in doxygen 1.3.
-# for f in class*html struct*html; do
- for f in class*html; do
- sed '1,10s!^<title> Template!<title>Template !' $f > TEMP
- mv TEMP $f
- done
-
cp ${srcdir}/doc/doxygen/tables.html tables.html
echo ::
echo :: HTML pages begin with
@@ -229,9 +257,6 @@
echo :: Fixing up the man pages...
cd $outdir/man/man3
-# here's the other end of the "stupid doxygen bug" mentioned above
-rm -rf ext
-
# File names with embedded spaces (EVIL!) need to be....? renamed or removed?
find . -name "* *" -print0 | xargs -0r rm # requires GNU tools
@@ -370,18 +395,18 @@
# Generic removal bits, where there are things in the generated man
# pages that need to be killed.
for f in *_libstdc__-v3_*; do
- rm $f
+ rm $f
done
for f in *_src_*; do
- rm $f
+ rm $f
done
# Also, for some reason, typedefs don't get their own man pages. Sigh.
for f in ios streambuf istream ostream iostream stringbuf \
- istringstream ostringstream stringstream filebuf ifstream \
- ofstream fstream string;
+ istringstream ostringstream stringstream filebuf ifstream \
+ ofstream fstream string;
do
echo ".so man3/std::basic_${f}.3" > std::${f}.3
echo ".so man3/std::basic_${f}.3" > std::w${f}.3
Index: doc/xml/manual/concurrency.xml
===================================================================
--- doc/xml/manual/concurrency.xml (revision 0)
+++ doc/xml/manual/concurrency.xml (revision 0)
@@ -0,0 +1,85 @@
+<?xml version='1.0'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd";
+[ ]>
+
+<chapter id="std.concurrency" xreflabel="Concurrency">
+<?dbhtml filename="concurrency.html"?>
+
+<chapterinfo>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ library
+ </keyword>
+ <keyword>
+ mutex
+ </keyword>
+ <keyword>
+ thread
+ </keyword>
+ <keyword>
+ future
+ </keyword>
+ <keyword>
+ condition_variable
+ </keyword>
+ </keywordset>
+</chapterinfo>
+
+<title>
+ Concurrency
+ <indexterm><primary>Concurrency</primary></indexterm>
+</title>
+
+<para>
+ Facilities for concurrent operation, and control thereof.
+</para>
+
+
+<!-- Sect1 01 : API -->
+<sect1 id="std.concurrency.api">
+ <title>API Reference</title>
+
+ <para>
+ All items are declared in one of four standard header files.
+ </para>
+
+ <para>
+ In header <filename>mutex</filename>, class
+ template <classname>mutex</classname> and variants,
+ class <classname>once_flag</classname>, and class
+ template <classname>unique_lock</classname>.
+ </para>
+
+ <para>
+ In header <filename>condition_variable</filename>,
+ classes <classname>condition_variable</classname>
+ and <classname>condition_variable_any</classname>.
+ </para>
+
+ <para>
+ In header <filename>thread</filename>,
+ class <classname>thread</classname> and
+ namespace <code>this_thread</code>.
+ </para>
+
+ <para>
+ In header <filename>future</filename>, class
+ template <classname>future</classname> and class
+ template <classname>shared_future</classname>, class
+ template <classname>promise</classname>,
+ and <classname>packaged_task</classname>.
+ </para>
+
+ <para>
+ Full API details.
+ </para>
+
+ <!-- Doxygen XML: api/group__concurrency.xml -->
+
+</sect1>
+
+</chapter>
Index: doc/xml/manual/atomics.xml
===================================================================
--- doc/xml/manual/atomics.xml (revision 0)
+++ doc/xml/manual/atomics.xml (revision 0)
@@ -0,0 +1,61 @@
+<?xml version='1.0'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd";
+[ ]>
+
+<chapter id="std.atomics" xreflabel="Atomics">
+<?dbhtml filename="atomics.html"?>
+
+<chapterinfo>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ library
+ </keyword>
+ <keyword>
+ atomic
+ </keyword>
+ </keywordset>
+</chapterinfo>
+
+<title>
+ Atomics
+ <indexterm><primary>Atomics</primary></indexterm>
+</title>
+
+<para>
+ Facilities for atomic operations.
+</para>
+
+<!-- Sect1 01 : API -->
+<sect1 id="std.atomics.api">
+ <title>API Reference</title>
+
+ <para>
+ All items are declared in the standard header
+ file <filename>atomic</filename>.
+ </para>
+
+ <para>
+ Set of typedefs that map <type>int</type> to
+ <classname>atomic_int</classname>, and so on for all builtin
+ integral types. Global enumeration <type>memory_order</type> to
+ control memory ordering. Also includes
+ <classname>atomic</classname>, a class template with member
+ functions such as <function>load</function> and
+ <function>store</function> that is instantiable such that
+ <classname>atomic_int</classname> is the base class of
+ <classname>atomic<int></classname>.
+ </para>
+
+ <para>
+ Full API details.
+ </para>
+
+ <!-- Doxygen XML: api/group__atomics.xml -->
+
+</sect1>
+
+</chapter>
Index: doc/xml/manual/appendix_contributing.xml
===================================================================
--- doc/xml/manual/appendix_contributing.xml (revision 157213)
+++ doc/xml/manual/appendix_contributing.xml (working copy)
@@ -925,14 +925,16 @@
the <ulink url="http://www.gnu.org/software/coreutils/";>GNU
coreutils</ulink>. (GNU versions of find, xargs, and possibly
sed and grep are used, just because the GNU versions make
- things very easy.)
+ things very easy.)
</para>
<para>
To generate the pretty pictures and hierarchy
graphs, the
- <ulink url="http://www.graphviz.org";>Graphviz</ulink>
- package will need to be installed.
+ <ulink url="http://www.graphviz.org";>Graphviz</ulink> package
+ will need to be installed. For PDF
+ output, <ulink url="http://www.tug.org/applications/pdftex/";>
+ pdflatex</ulink> is required.
</para>
</sect3>
@@ -940,7 +942,7 @@
<title>Generating the Doxygen Files</title>
<para>
The following Makefile rules run Doxygen to generate HTML
- docs, XML docs, and the man pages.
+ docs, XML docs, PDF docs, and the man pages.
</para>
<para>
@@ -952,6 +954,10 @@
</para>
<para>
+ <screen><userinput>make doc-pdf-doxygen</userinput></screen>
+ </para>
+
+ <para>
<screen><userinput>make doc-man-doxygen</userinput></screen>
</para>
@@ -1199,13 +1205,14 @@
<para>
For PDF output, something that transforms valid XML to PDF is
- required. Possible solutions include <command>xmlto</command>,
- <ulink url="http://xmlgraphics.apache.org/fop/";>Apache
- FOP</ulink>, or <command>prince</command>. Other options are
- listed on the DocBook web <ulink
- url="http://wiki.docbook.org/topic/DocBookPublishingTools";>pages</ulink>. Please
+ 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
consult the <email>libstdc++@gcc.gnu.org</email> list when
- preparing printed manuals for current best practice and suggestions.
+ preparing printed manuals for current best practice and
+ suggestions.
</para>
<para>
@@ -1499,20 +1506,6 @@
<para>
<screen><userinput>make doc-pdf</userinput></screen>
</para>
-
- <para>
- The following Makefile rules generate (in order): an HTML
- version of all the DocBook documentation with links into an
- local Doxygen cache, and a PDF version of the same.
- </para>
-
- <para>
- <screen><userinput>make doc-html-combine</userinput></screen>
- </para>
-
- <para>
- <screen><userinput>make doc-pdf-combine</userinput></screen>
- </para>
</sect3>
</sect2>
</sect1>
Index: doc/xml/manual/diagnostics.xml
===================================================================
--- doc/xml/manual/diagnostics.xml (revision 157213)
+++ doc/xml/manual/diagnostics.xml (working copy)
@@ -26,8 +26,8 @@
<?dbhtml filename="exceptions.html"?>
<title>Exceptions</title>
- <sect2 id="std.diagnostics.exceptions.hierarchy" xreflabel="Exception Classes">
- <title>Exception Classes</title>
+ <sect2 id="std.diagnostics.exceptions.api">
+ <title>API Reference</title>
<para>
All exception objects are defined in one of the standard header
files: <filename>exception</filename>,
@@ -44,12 +44,18 @@
<para>
Derived from this are several classes that may have a
<classname>string</classname> member: a full hierarchy can be
- found in the <ulink url="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a00460.html";>source documentation</ulink>.
+ found in the source documentation.
</para>
-
+
+ <para>
+ Full API details.
+ </para>
+
+ <!-- Doxygen XML: api/group__exceptions.xml -->
+
</sect2>
<sect2 id="std.diagnostics.exceptions.data" xreflabel="Adding Data to Exceptions">
- <title>Adding Data to Exceptions</title>
+ <title>Adding Data to <classname>exception</classname></title>
<para>
The standard exception classes carry with them a single string as
data (usually describing what went wrong or where the 'throw' took
Index: doc/xml/manual/spine.xml
===================================================================
--- doc/xml/manual/spine.xml (revision 157213)
+++ doc/xml/manual/spine.xml (working copy)
@@ -85,6 +85,16 @@
parse="xml" href="io.xml">
</xi:include>
+<!-- Chapter 11 : Atomics -->
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude";
+ parse="xml" href="atomics.xml">
+</xi:include>
+
+<!-- Chapter 12 : Concurrency -->
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude";
+ parse="xml" href="concurrency.xml">
+</xi:include>
+
</part>
<!-- Part 03 : Extensions -->
Index: doc/doxygen/user.cfg.in
===================================================================
--- doc/doxygen/user.cfg.in (revision 157213)
+++ doc/doxygen/user.cfg.in (working copy)
@@ -1169,7 +1169,7 @@
# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will
# generate Latex output.
-GENERATE_LATEX = NO
+GENERATE_LATEX = @do_latex@
# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put.
# If a relative path is entered the value of OUTPUT_DIRECTORY will be
@@ -1180,7 +1180,7 @@
# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be
# invoked. If left blank `latex' will be used as the default command name.
-LATEX_CMD_NAME = latex
+LATEX_CMD_NAME = pdflatex
# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to
# generate index for LaTeX. If left blank `makeindex' will be used as the
@@ -1217,13 +1217,13 @@
# contain links (just like the HTML output) instead of page references
# This makes the output suitable for online browsing using a pdf viewer.
-PDF_HYPERLINKS = NO
+PDF_HYPERLINKS = YES
# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of
# plain latex in the generated Makefile. Set this option to YES to get a
# higher quality PDF documentation.
-USE_PDFLATEX = NO
+USE_PDFLATEX = YES
# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the
# \\batchmode. command to the generated LaTeX files. This will
@@ -1231,13 +1231,13 @@
# the user for help. This option is also used when generating
# formulas in HTML.
-LATEX_BATCHMODE = NO
+LATEX_BATCHMODE = YES
# If LATEX_HIDE_INDICES is set to YES then doxygen will not
# include the index chapters (such as File Index, Compound Index, etc.)
# in the output.
-LATEX_HIDE_INDICES = NO
+LATEX_HIDE_INDICES = YES
# If LATEX_SOURCE_CODE is set to YES then doxygen will include source
# code with syntax highlighting in the LaTeX output. Note that which