boost_mirror/boostbook
1
0
Fork 0
mirror of https://github.com/boostorg/boostbook.git synced 2025-05-09 15:03:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

*.xml: Fix DTD location, write a little, remove a little

Browse Source 
Jamfile.v2: for building BoostBook documentation


[SVN r18018]
This commit is contained in:
Douglas Gregor 2003-03-19 20:23:16 +00:00
parent 027ee4e6e9
commit add1fe71fb
5 changed files with 146 additions and 101 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
doc/Jamfile.v2 Normal file
View File

@ -0,0 +1,5 @@
project boost/doc ;
import boostbook : boostbook ;
boostbook boostbook : boostbook.xml ;

176
doc/boostbook.xml
View File

@ -1,6 +1,8 @@
<?xml version="1.0" encoding="utf-8"?> <?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE chapter SYSTEM "../../dtd/boostbook.dtd"> <!DOCTYPE chapter PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
<chapter xmlns:xi="http://www.w3.org/2001/XInclude" id="boostbook"> "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
<chapter xmlns:xi="http://www.w3.org/2001/XInclude" id="boostbook"
last-revision="$Date$">
<chapterinfo> <chapterinfo>
<author> <author>
<firstname>Douglas</firstname> <firstname>Douglas</firstname>
@ -106,7 +108,9 @@ std::cout &lt;&lt; f(5, 3) &gt;&gt; std::endl;
<listitem> <listitem>
<para>On Unix: Build and install <ulink <para>On Unix: Build and install <ulink
url="http://xmlsoft.org/">libxml2</ulink>) and then <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>
<listitem> <listitem>
<para>On Windows:</para> <para>On Windows:</para>
@ -129,91 +133,103 @@ std::cout &lt;&lt; f(5, 3) &gt;&gt; std::endl;
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para>You will also need a recent checkout of Boost from <ulink <para>There are a few other requirements:
url="http://www.boost.org/more/download.html#CVS">CVS</ulink> and <itemizedlist>
a very recent checkout from the <ulink <listitem><para>A recent checkout of Boost from <ulink
url="http://www.boost.org/more/mailing_lists.htm#sandbox">Boost url="http://www.boost.org/more/download.html#CVS">CVS</ulink>.</para>
Sandbox CVS</ulink>. Finally, you will need Norman Walsh's DocBook </listitem>
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>The current BoostBook documentation encompasses only a few <listitem><para>Norman Walsh's DocBook XSL stylesheets,
libraries. The documentation for these libraries is stored in the available at the <ulink
directory url="http://docbook.sourceforge.net">DocBook sourceforge
<code>boost-sandbox/libs/documentation/examples</code>. From that site</ulink>. Extract the DocBook XSL stylesheets to a
directory, we can generate DocBook XML from the BoostBook XML by directory on your hard disk (which we'll refer to as the
invoking <code>xsltproc</code>:</para> <code>DOCBOOK_XSL_DIR</code>).</para>
</listitem>
<programlisting> <listitem><para>The DocBook DTD, available at the <ulink
xsltproc --xinclude ../boostbook-xsl/docbook.xsl boost.xml > boost.docbook url="http://www.oasis-open.org/docbook/xml/4.2/index.shtml">OASIS
</programlisting> 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 The latter two items aren't strictly required, but they make
<code>boost.xml</code>, using <ulink processing faster. If you have a fast Internet connection and
url="http://www.w3.org/TR/xinclude/">XIncludes</ulink> to bring in don't mind waiting a bit longer when building BoostBook
other library documentation (e.g., documentation, don't bother to download the DocBook DTD and XSL
<code>function/function.xml</code> for the Function library), and stylesheets: the XSLT processor will download them on-the-fly.</para>
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>
<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:
Cannot find function named 'checked_delete' <programlisting># BoostBook configuration
Cannot find function named 'checked_array_delete' using boostbook : DOCBOOK_XSL_DIR
Cannot find function named 'next' : DOCBOOK_DTD_DIR
</programlisting> ;
</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 <para>These warnings are emitted when the Boost documentation
tools cannot find documentation for functions, methods, or classes tools cannot find documentation for functions, methods, or classes
that are referenced in the source, and are not harmful in any 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
<para>With DocBook XML, we can generate several other <code>$BOOST_ROOT/doc/html</code>. You can also create HTML
documentation formats. To generate HTML, we invoke xsltproc to documentation in a single (large!) HTML file with the command line
transform the DocBook XML into HTML with the following command <code>bjam --v2 onehtml</code>, or Unix man pages with the command
(replace <code>&lt;html-output-dir&gt;</code> with a directory of your line <code>bjam --v2 man</code>. The complete list of output
choice):</para> formats is listed in <xref
linkend="boostbook.output.formats"/>. Several output formats can
<programlisting> be passed to a single invocation of <code>bjam</code>, e.g.,
xsltproc -o &lt;html-output-dir&gt; &lt;DOCBOOK_XSL_PATH&gt;/html/chunk.xsl boost.docbook <code>bjam --v2 html man docbook</code> would generate HTML
</programlisting> (multiple files), man pages, and DocBook documentation.</para>
<para>Once this command completes, you will have HTML <table id="boostbook.output.formats">
documentation. There are many options that can be used to <title>BoostBook Output Formats</title>
customize the output HTML; please see the Makefile for the set of <tgroup cols="2">
commands used to generate the <ulink <thead>
url="http://www.cs.rpi.edu/~gregod/boost/doc/html/libraries.html">nightly <row><entry>Format</entry><entry>Description</entry></row>
documentation</ulink>.</para> </thead>
<tbody>
<para>The DocBook XSL stylesheets support other output formats, <row>
such as Unix man pages, XHTML, HTML as a single file, and XSL <entry>html</entry>
Formatting Objects (which can in turn be used to generate, e.g., <entry><simpara>HTML output (multiple files). This is the default</simpara></entry>
PDF or PostScript documentation). To generate these other formats, </row>
please refer to the <ulink <row>
url="http://docbook.sourceforge.net">DocBook XSL stylesheets <entry>onehtml</entry>
documentation</ulink>.</para> <entry><simpara>HTML output in a single HTML file.</simpara></entry>
</row>
<para>For users of Unix-based systems, the Makefile supplied in <row>
the <code>examples/</code> directory can help generate DocBook, <entry>man</entry>
HTML, man pages, and FO. To generate the necessary files <entry><simpara>Unix man pages.</simpara></entry>
(<code>Makefile.def</code> and <code>catalog.xml</code>), </row>
invoke:</para> <row>
<entry>pdf</entry>
<programlisting> <entry><simpara>PDF. Requires <ulink url="http://xml.apache.org/fop/index.html">Apache FOP</ulink>.</simpara></entry>
./configure DOCBOOK_XSL_PATH </row>
</programlisting> <row>
<entry>ps</entry>
<para>Now run any of:</para> <entry><simpara>Postscript. Requires <ulink url="http://xml.apache.org/fop/index.html">Apache FOP</ulink>.</simpara></entry>
<programlisting> </row>
make html <row>
make fo <entry>docbook</entry>
make man <entry><ulink url="http://www.docbook.org/">DocBook</ulink>.</entry>
make docbook </row>
</programlisting> <row>
<entry>fo</entry>
<entry><ulink url="http://www.w3.org/TR/xsl/">XSL Formatting Objects</ulink></entry>
</row>
</tbody>
</tgroup>
</table>
</section> </section>
<xi:include href="documenting.xml"/> <xi:include href="documenting.xml"/>

30
doc/documenting.xml
View File

@ -1,6 +1,8 @@
<?xml version="1.0" encoding="utf-8"?> <?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE section SYSTEM "../../dtd/boostbook.dtd"> <!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
<section xmlns:xi="http://www.w3.org/2001/XInclude"> "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> <title>Documenting libraries</title>
<para>BoostBook is an extension to <ulink <para>BoostBook is an extension to <ulink
@ -28,8 +30,10 @@
<title>A Skeletal BoostBook Library</title> <title>A Skeletal BoostBook Library</title>
<programlisting> <programlisting>
&lt;?xml version="1.0" encoding="utf-8"?&gt; &lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!DOCTYPE library SYSTEM "../../dtd/boostbook.dtd"&gt; &lt;!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
&lt;library name="Any" dirname="any" xmlns:xi="http://www.w3.org/2001/XInclude" id="any"&gt; "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"&gt;
&lt;library name="Any" dirname="any" xmlns:xi="http://www.w3.org/2001/XInclude"
id="any" last-revision="$Date$"&gt;
&lt;libraryinfo&gt; &lt;libraryinfo&gt;
&lt;author&gt; &lt;author&gt;
&lt;firstname&gt;Kevlin&lt;/firstname&gt; &lt;firstname&gt;Kevlin&lt;/firstname&gt;
@ -44,13 +48,11 @@
</programlisting> </programlisting>
</example> </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 <ulink url="http://www.w3.org/XML/">XML</ulink> document. The
DOCTYPE line states that the document conforms to the BoostBook DOCTYPE line states that the document conforms to the BoostBook
DTD (here accessed via the relative path DTD, and that the top-level element is a BoostBook
<code>../../dtd/boostbook.dtd</code>, though this path may change &lt;library&gt;.</para>
depending on the location of <code>any.xml</code>) and that the
top-level element is a BoostBook &lt;library&gt;.</para>
<para>The &lt;library&gt; element actually describes the aspects <para>The &lt;library&gt; element actually describes the aspects
of BoostBook library documentation. The attributes for the of BoostBook library documentation. The attributes for the
@ -87,6 +89,14 @@
alphanumeric characters and underscores.</simpara> alphanumeric characters and underscores.</simpara>
</listitem> </listitem>
</varlistentry> </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> </variablelist>
<para>Inside the &lt;library&gt; element we have the <para>Inside the &lt;library&gt; element we have the
@ -102,7 +112,7 @@
&lt;librarycategory&gt; elements. Each &lt;librarycategory&gt; &lt;librarycategory&gt; elements. Each &lt;librarycategory&gt;
element has a <code>name</code> element that identifies one of the element has a <code>name</code> element that identifies one of the
categories. The actual list of categories is in the file 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>
<para>At this point, we can apply the BoostBook XSL stylesheets to <para>At this point, we can apply the BoostBook XSL stylesheets to

30
doc/reference_doc.xml
View File

@ -1,6 +1,8 @@
<?xml version="1.0" encoding="utf-8"?> <?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE section SYSTEM "../../dtd/boostbook.dtd"> <!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
<section xmlns:xi="http://www.w3.org/2001/XInclude"> "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> <title>Documenting C++ Constructs</title>
<para>This section describes the documentation of C++ constructs <para>This section describes the documentation of C++ constructs
@ -11,6 +13,22 @@
documentation for C++ libraries with a consistent look and documentation for C++ libraries with a consistent look and
feel.</para> 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> <section>
<title>Library references and headers</title> <title>Library references and headers</title>
@ -116,8 +134,7 @@
<functionname>boost::any_cast</functionname>.</para> <functionname>boost::any_cast</functionname>.</para>
<para>Class templates are defined by &lt;class&gt; elements with a <para>Class templates are defined by &lt;class&gt; elements with a
&lt;template&gt; child element at the beginning. Templates are &lt;template&gt; child element at the beginning.</para>
discussed <xref linkend="boostbook.templates"/>.</para>
</section> </section>
<section id="boostbook.functions"> <section id="boostbook.functions">
@ -284,9 +301,4 @@
</tgroup> </tgroup>
</table> </table>
</section> </section>
<section id="boostbook.templates">
<title>Templates</title>
<para>To be written...</para>
</section>
</section> </section>

6
doc/together.xml
View File

@ -1,6 +1,8 @@
<?xml version="1.0" encoding="utf-8"?> <?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE section SYSTEM "../../dtd/boostbook.dtd"> <!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
<section xmlns:xi="http://www.w3.org/2001/XInclude" id="boostbook.together"> "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> <title>Bringing Together a BoostBook Document</title>
<section id="boostbook.linking"> <section id="boostbook.linking">