mirror of
https://github.com/boostorg/boostbook.git
synced 2025-05-09 15:03:57 +00:00
*.xml: Fix DTD location, write a little, remove a little
Jamfile.v2: for building BoostBook documentation [SVN r18018]
This commit is contained in:
Douglas Gregor
parent
027ee4e6e9
commit
add1fe71fb
5
doc/Jamfile.v2
Normal file
5
doc/Jamfile.v2
Normal file
@ -0,0 +1,5 @@
|
||||
project boost/doc ;
|
||||
import boostbook : boostbook ;
|
||||
|
||||
boostbook boostbook : boostbook.xml ;
|
||||
|
||||
@ -1,6 +1,8 @@
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE chapter SYSTEM "../../dtd/boostbook.dtd">
|
||||
<chapter xmlns:xi="http://www.w3.org/2001/XInclude" id="boostbook">
|
||||
<!DOCTYPE chapter PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
|
||||
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
|
||||
<chapter xmlns:xi="http://www.w3.org/2001/XInclude" id="boostbook"
|
||||
last-revision="$Date$">
|
||||
<chapterinfo>
|
||||
<author>
|
||||
<firstname>Douglas</firstname>
|
||||
@ -106,7 +108,9 @@ std::cout << f(5, 3) >> std::endl;
|
||||
<listitem>
|
||||
<para>On Unix: Build and install <ulink
|
||||
url="http://xmlsoft.org/">libxml2</ulink>) and then <ulink
|
||||
url="http://xmlsoft.org/XSLT/">libxslt</ulink>)</para>
|
||||
url="http://xmlsoft.org/XSLT/">libxslt</ulink>). Both
|
||||
libraries are part of the <ulink
|
||||
url="http://www.gnome.org">GNOME</ulink> project.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>On Windows:</para>
|
||||
@ -129,91 +133,103 @@ std::cout << f(5, 3) >> std::endl;
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>You will also need a recent checkout of Boost from <ulink
|
||||
url="http://www.boost.org/more/download.html#CVS">CVS</ulink> and
|
||||
a very recent checkout from the <ulink
|
||||
url="http://www.boost.org/more/mailing_lists.htm#sandbox">Boost
|
||||
Sandbox CVS</ulink>. Finally, you will need Norman Walsh's DocBook
|
||||
XSL stylesheets, available at the (<ulink
|
||||
url="http://docbook.sourceforge.net">DocBook sourceforge
|
||||
site</ulink>. Extract the DocBook XSL stylesheets to a directory
|
||||
on your hard disk (which we'll refer to as the
|
||||
<code>DOCBOOK_XSL_PATH</code>).</para>
|
||||
<para>There are a few other requirements:
|
||||
<itemizedlist>
|
||||
<listitem><para>A recent checkout of Boost from <ulink
|
||||
url="http://www.boost.org/more/download.html#CVS">CVS</ulink>.</para>
|
||||
</listitem>
|
||||
|
||||
<para>The current BoostBook documentation encompasses only a few
|
||||
libraries. The documentation for these libraries is stored in the
|
||||
directory
|
||||
<code>boost-sandbox/libs/documentation/examples</code>. From that
|
||||
directory, we can generate DocBook XML from the BoostBook XML by
|
||||
invoking <code>xsltproc</code>:</para>
|
||||
<listitem><para>Norman Walsh's DocBook XSL stylesheets,
|
||||
available at the <ulink
|
||||
url="http://docbook.sourceforge.net">DocBook sourceforge
|
||||
site</ulink>. Extract the DocBook XSL stylesheets to a
|
||||
directory on your hard disk (which we'll refer to as the
|
||||
<code>DOCBOOK_XSL_DIR</code>).</para>
|
||||
</listitem>
|
||||
|
||||
<programlisting>
|
||||
xsltproc --xinclude ../boostbook-xsl/docbook.xsl boost.xml > boost.docbook
|
||||
</programlisting>
|
||||
<listitem><para>The DocBook DTD, available at the <ulink
|
||||
url="http://www.oasis-open.org/docbook/xml/4.2/index.shtml">OASIS
|
||||
DocBook site</ulink>. Extract the DocBook DTD to a directory
|
||||
on your hard disk (which we'll refer to as the
|
||||
<code>DOCBOOK_DTD_DIR</code>).</para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>This command parses the BoostBook XML in the file
|
||||
<code>boost.xml</code>, using <ulink
|
||||
url="http://www.w3.org/TR/xinclude/">XIncludes</ulink> to bring in
|
||||
other library documentation (e.g.,
|
||||
<code>function/function.xml</code> for the Function library), and
|
||||
then translates the XML via the XSL stylesheet docbook.xsl into
|
||||
DocBook XML, which is written to <code>boost.docbook</code>. You
|
||||
will probably see several warnings like these while
|
||||
<code>xsltproc</code> executes:</para>
|
||||
The latter two items aren't strictly required, but they make
|
||||
processing faster. If you have a fast Internet connection and
|
||||
don't mind waiting a bit longer when building BoostBook
|
||||
documentation, don't bother to download the DocBook DTD and XSL
|
||||
stylesheets: the XSLT processor will download them on-the-fly.</para>
|
||||
|
||||
<programlisting>
|
||||
Cannot find function named 'checked_delete'
|
||||
Cannot find function named 'checked_array_delete'
|
||||
Cannot find function named 'next'
|
||||
</programlisting>
|
||||
<para>Next we configure Boost.Build with the DocBook DTD and XSL stylesheets. In the directory <code>tools/build/new</code> is a file named <filename>user-config.jam</filename>. Copy it to your home directory (or edit it in-place), and add a directive telling Boost.Build where to find the DocBook DTD and XSL stylesheets, replacing <code>DOCBOOK_XSL_DIR</code> and <code>DOCBOOK_DTD_DIR</code> with the paths of the DocBook XSL stylsheets and DTD, respectively:
|
||||
<programlisting># BoostBook configuration
|
||||
using boostbook : DOCBOOK_XSL_DIR
|
||||
: DOCBOOK_DTD_DIR
|
||||
;
|
||||
</programlisting></para>
|
||||
|
||||
<para>Now we can build some documentation. Change to the directory
|
||||
<code>$BOOST_ROOT/doc</code> and run <code>bjam --v2</code> to
|
||||
build HTML documentation. You should see several warnings like
|
||||
these while DocBook documentation is being built from BoostBook
|
||||
documentation:</para>
|
||||
|
||||
<programlisting>Cannot find function named 'checked_delete'
|
||||
Cannot find function named 'checked_array_delete'
|
||||
Cannot find function named 'next'</programlisting>
|
||||
|
||||
<para>These warnings are emitted when the Boost documentation
|
||||
tools cannot find documentation for functions, methods, or classes
|
||||
that are referenced in the source, and are not harmful in any
|
||||
way.</para>
|
||||
way. Once Boost.Jam has completed its execution, HTML
|
||||
documentation for Boost will be available in
|
||||
<code>$BOOST_ROOT/doc/html</code>. You can also create HTML
|
||||
documentation in a single (large!) HTML file with the command line
|
||||
<code>bjam --v2 onehtml</code>, or Unix man pages with the command
|
||||
line <code>bjam --v2 man</code>. The complete list of output
|
||||
formats is listed in <xref
|
||||
linkend="boostbook.output.formats"/>. Several output formats can
|
||||
be passed to a single invocation of <code>bjam</code>, e.g.,
|
||||
<code>bjam --v2 html man docbook</code> would generate HTML
|
||||
(multiple files), man pages, and DocBook documentation.</para>
|
||||
|
||||
<para>With DocBook XML, we can generate several other
|
||||
documentation formats. To generate HTML, we invoke xsltproc to
|
||||
transform the DocBook XML into HTML with the following command
|
||||
(replace <code><html-output-dir></code> with a directory of your
|
||||
choice):</para>
|
||||
|
||||
<programlisting>
|
||||
xsltproc -o <html-output-dir> <DOCBOOK_XSL_PATH>/html/chunk.xsl boost.docbook
|
||||
</programlisting>
|
||||
|
||||
<para>Once this command completes, you will have HTML
|
||||
documentation. There are many options that can be used to
|
||||
customize the output HTML; please see the Makefile for the set of
|
||||
commands used to generate the <ulink
|
||||
url="http://www.cs.rpi.edu/~gregod/boost/doc/html/libraries.html">nightly
|
||||
documentation</ulink>.</para>
|
||||
|
||||
<para>The DocBook XSL stylesheets support other output formats,
|
||||
such as Unix man pages, XHTML, HTML as a single file, and XSL
|
||||
Formatting Objects (which can in turn be used to generate, e.g.,
|
||||
PDF or PostScript documentation). To generate these other formats,
|
||||
please refer to the <ulink
|
||||
url="http://docbook.sourceforge.net">DocBook XSL stylesheets
|
||||
documentation</ulink>.</para>
|
||||
|
||||
<para>For users of Unix-based systems, the Makefile supplied in
|
||||
the <code>examples/</code> directory can help generate DocBook,
|
||||
HTML, man pages, and FO. To generate the necessary files
|
||||
(<code>Makefile.def</code> and <code>catalog.xml</code>),
|
||||
invoke:</para>
|
||||
|
||||
<programlisting>
|
||||
./configure DOCBOOK_XSL_PATH
|
||||
</programlisting>
|
||||
|
||||
<para>Now run any of:</para>
|
||||
<programlisting>
|
||||
make html
|
||||
make fo
|
||||
make man
|
||||
make docbook
|
||||
</programlisting>
|
||||
<table id="boostbook.output.formats">
|
||||
<title>BoostBook Output Formats</title>
|
||||
<tgroup cols="2">
|
||||
<thead>
|
||||
<row><entry>Format</entry><entry>Description</entry></row>
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>html</entry>
|
||||
<entry><simpara>HTML output (multiple files). This is the default</simpara></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>onehtml</entry>
|
||||
<entry><simpara>HTML output in a single HTML file.</simpara></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>man</entry>
|
||||
<entry><simpara>Unix man pages.</simpara></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>pdf</entry>
|
||||
<entry><simpara>PDF. Requires <ulink url="http://xml.apache.org/fop/index.html">Apache FOP</ulink>.</simpara></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>ps</entry>
|
||||
<entry><simpara>Postscript. Requires <ulink url="http://xml.apache.org/fop/index.html">Apache FOP</ulink>.</simpara></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>docbook</entry>
|
||||
<entry><ulink url="http://www.docbook.org/">DocBook</ulink>.</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>fo</entry>
|
||||
<entry><ulink url="http://www.w3.org/TR/xsl/">XSL Formatting Objects</ulink></entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
</section>
|
||||
|
||||
<xi:include href="documenting.xml"/>
|
||||
|
||||
@ -1,6 +1,8 @@
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE section SYSTEM "../../dtd/boostbook.dtd">
|
||||
<section xmlns:xi="http://www.w3.org/2001/XInclude">
|
||||
<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
|
||||
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
|
||||
<section xmlns:xi="http://www.w3.org/2001/XInclude" id="boostbook.documenting"
|
||||
last-revision="$Date$">
|
||||
<title>Documenting libraries</title>
|
||||
|
||||
<para>BoostBook is an extension to <ulink
|
||||
@ -28,8 +30,10 @@
|
||||
<title>A Skeletal BoostBook Library</title>
|
||||
<programlisting>
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE library SYSTEM "../../dtd/boostbook.dtd">
|
||||
<library name="Any" dirname="any" xmlns:xi="http://www.w3.org/2001/XInclude" id="any">
|
||||
<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
|
||||
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
|
||||
<library name="Any" dirname="any" xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
id="any" last-revision="$Date$">
|
||||
<libraryinfo>
|
||||
<author>
|
||||
<firstname>Kevlin</firstname>
|
||||
@ -44,13 +48,11 @@
|
||||
</programlisting>
|
||||
</example>
|
||||
|
||||
<para>The first two lines identify this document as a BoostBook
|
||||
<para>The first three lines identify this document as a BoostBook
|
||||
<ulink url="http://www.w3.org/XML/">XML</ulink> document. The
|
||||
DOCTYPE line states that the document conforms to the BoostBook
|
||||
DTD (here accessed via the relative path
|
||||
<code>../../dtd/boostbook.dtd</code>, though this path may change
|
||||
depending on the location of <code>any.xml</code>) and that the
|
||||
top-level element is a BoostBook <library>.</para>
|
||||
DTD, and that the top-level element is a BoostBook
|
||||
<library>.</para>
|
||||
|
||||
<para>The <library> element actually describes the aspects
|
||||
of BoostBook library documentation. The attributes for the
|
||||
@ -87,6 +89,14 @@
|
||||
alphanumeric characters and underscores.</simpara>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><code>last-revision</code></term>
|
||||
<listitem>
|
||||
<simpara>Always set to <code>$Date$</code>, which is
|
||||
expanded by CVS to include the date and time that the file
|
||||
was last modified.</simpara>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
<para>Inside the <library> element we have the
|
||||
@ -102,7 +112,7 @@
|
||||
<librarycategory> elements. Each <librarycategory>
|
||||
element has a <code>name</code> element that identifies one of the
|
||||
categories. The actual list of categories is in the file
|
||||
<filename>boost-sandbox/libs/documentation/examples/boost.xml</filename>.
|
||||
<filename>doc/src/boost.xml</filename>.
|
||||
</para>
|
||||
|
||||
<para>At this point, we can apply the BoostBook XSL stylesheets to
|
||||
|
||||
@ -1,6 +1,8 @@
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE section SYSTEM "../../dtd/boostbook.dtd">
|
||||
<section xmlns:xi="http://www.w3.org/2001/XInclude">
|
||||
<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
|
||||
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
|
||||
<section xmlns:xi="http://www.w3.org/2001/XInclude" id="boostbook.reference"
|
||||
last-revision="$Date$">
|
||||
<title>Documenting C++ Constructs</title>
|
||||
|
||||
<para>This section describes the documentation of C++ constructs
|
||||
@ -11,6 +13,22 @@
|
||||
documentation for C++ libraries with a consistent look and
|
||||
feel.</para>
|
||||
|
||||
<para>The basic scheme for documenting C++ elements in BoostBook is
|
||||
that the name of the XML element for a particular C++ construct
|
||||
matches the name of the C++ keyword (e.g.,
|
||||
<sgmltag>typedef</sgmltag>, <sgmltag>template</sgmltag>,
|
||||
<sgmltag>enum</sgmltag>) or concept (e.g.,
|
||||
<sgmltag>constructor</sgmltag>,
|
||||
<sgmltag>class-specialization</sgmltag>). Each attribute for a named
|
||||
declaration requires a <code>name</code> attribute that gives the
|
||||
name of the entity in C++. The content model of the elements then
|
||||
follows from the information provided in a C++ declaration, e.g.,
|
||||
function parameter lists, type, default values, but each element may
|
||||
also contain a <sgmltag>purpose</sgmltag> element, containing a
|
||||
short description of the purpose of the entity begin described,
|
||||
and/or a <sgmltag>description</sgmltag> element, containing extended
|
||||
documentation.</para>
|
||||
|
||||
<section>
|
||||
<title>Library references and headers</title>
|
||||
|
||||
@ -116,8 +134,7 @@
|
||||
<functionname>boost::any_cast</functionname>.</para>
|
||||
|
||||
<para>Class templates are defined by <class> elements with a
|
||||
<template> child element at the beginning. Templates are
|
||||
discussed <xref linkend="boostbook.templates"/>.</para>
|
||||
<template> child element at the beginning.</para>
|
||||
</section>
|
||||
|
||||
<section id="boostbook.functions">
|
||||
@ -284,9 +301,4 @@
|
||||
</tgroup>
|
||||
</table>
|
||||
</section>
|
||||
|
||||
<section id="boostbook.templates">
|
||||
<title>Templates</title>
|
||||
<para>To be written...</para>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
@ -1,6 +1,8 @@
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE section SYSTEM "../../dtd/boostbook.dtd">
|
||||
<section xmlns:xi="http://www.w3.org/2001/XInclude" id="boostbook.together">
|
||||
<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
|
||||
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
|
||||
<section xmlns:xi="http://www.w3.org/2001/XInclude" id="boostbook.together"
|
||||
last-revision="$Date$">
|
||||
<title>Bringing Together a BoostBook Document</title>
|
||||
|
||||
<section id="boostbook.linking">
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user