boost_mirror/boostbook
1
0
Fork 0
mirror of https://github.com/boostorg/boostbook.git synced 2025-05-09 23:13:58 +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 ;

170
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
<listitem><para>Norman Walsh's DocBook XSL stylesheets,
available at the <ulink
url="http://docbook.sourceforge.net">DocBook sourceforge url="http://docbook.sourceforge.net">DocBook sourceforge
site</ulink>. Extract the DocBook XSL stylesheets to a directory 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>
<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 on your hard disk (which we'll refer to as the
<code>DOCBOOK_XSL_PATH</code>).</para> <code>DOCBOOK_DTD_DIR</code>).</para></listitem>
</itemizedlist>
<para>The current BoostBook documentation encompasses only a few The latter two items aren't strictly required, but they make
libraries. The documentation for these libraries is stored in the processing faster. If you have a fast Internet connection and
directory don't mind waiting a bit longer when building BoostBook
<code>boost-sandbox/libs/documentation/examples</code>. From that documentation, don't bother to download the DocBook DTD and XSL
directory, we can generate DocBook XML from the BoostBook XML by stylesheets: the XSLT processor will download them on-the-fly.</para>
invoking <code>xsltproc</code>:</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:
xsltproc --xinclude ../boostbook-xsl/docbook.xsl boost.xml > boost.docbook <programlisting># BoostBook configuration
</programlisting> using boostbook : DOCBOOK_XSL_DIR
: DOCBOOK_DTD_DIR
;
</programlisting></para>
<para>This command parses the BoostBook XML in the file <para>Now we can build some documentation. Change to the directory
<code>boost.xml</code>, using <ulink <code>$BOOST_ROOT/doc</code> and run <code>bjam --v2</code> to
url="http://www.w3.org/TR/xinclude/">XIncludes</ulink> to bring in build HTML documentation. You should see several warnings like
other library documentation (e.g., these while DocBook documentation is being built from BoostBook
<code>function/function.xml</code> for the Function library), and documentation:</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> <programlisting>Cannot find function named 'checked_delete'
Cannot find function named 'checked_delete' Cannot find function named 'checked_array_delete'
Cannot find function named 'checked_array_delete' Cannot find function named 'next'</programlisting>
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
<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 <table id="boostbook.output.formats">
documentation formats. To generate HTML, we invoke xsltproc to <title>BoostBook Output Formats</title>
transform the DocBook XML into HTML with the following command <tgroup cols="2">
(replace <code>&lt;html-output-dir&gt;</code> with a directory of your <thead>
choice):</para> <row><entry>Format</entry><entry>Description</entry></row>
</thead>
<programlisting> <tbody>
xsltproc -o &lt;html-output-dir&gt; &lt;DOCBOOK_XSL_PATH&gt;/html/chunk.xsl boost.docbook <row>
</programlisting> <entry>html</entry>
<entry><simpara>HTML output (multiple files). This is the default</simpara></entry>
<para>Once this command completes, you will have HTML </row>
documentation. There are many options that can be used to <row>
customize the output HTML; please see the Makefile for the set of <entry>onehtml</entry>
commands used to generate the <ulink <entry><simpara>HTML output in a single HTML file.</simpara></entry>
url="http://www.cs.rpi.edu/~gregod/boost/doc/html/libraries.html">nightly </row>
documentation</ulink>.</para> <row>
<entry>man</entry>
<para>The DocBook XSL stylesheets support other output formats, <entry><simpara>Unix man pages.</simpara></entry>
such as Unix man pages, XHTML, HTML as a single file, and XSL </row>
Formatting Objects (which can in turn be used to generate, e.g., <row>
PDF or PostScript documentation). To generate these other formats, <entry>pdf</entry>
please refer to the <ulink <entry><simpara>PDF. Requires <ulink url="http://xml.apache.org/fop/index.html">Apache FOP</ulink>.</simpara></entry>
url="http://docbook.sourceforge.net">DocBook XSL stylesheets </row>
documentation</ulink>.</para> <row>
<entry>ps</entry>
<para>For users of Unix-based systems, the Makefile supplied in <entry><simpara>Postscript. Requires <ulink url="http://xml.apache.org/fop/index.html">Apache FOP</ulink>.</simpara></entry>
the <code>examples/</code> directory can help generate DocBook, </row>
HTML, man pages, and FO. To generate the necessary files <row>
(<code>Makefile.def</code> and <code>catalog.xml</code>), <entry>docbook</entry>
invoke:</para> <entry><ulink url="http://www.docbook.org/">DocBook</ulink>.</entry>
</row>
<programlisting> <row>
./configure DOCBOOK_XSL_PATH <entry>fo</entry>
</programlisting> <entry><ulink url="http://www.w3.org/TR/xsl/">XSL Formatting Objects</ulink></entry>
</row>
<para>Now run any of:</para> </tbody>
<programlisting> </tgroup>
make html </table>
make fo
make man
make docbook
</programlisting>
</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">