6fee699059
Merged revisions 47362 via svnmerge from https://svn.boost.org/svn/boost/trunk ........ r47362 | danieljames | 2008-07-12 20:16:17 +0100 (Sat, 12 Jul 2008) | 1 line Update link to table tutorial. ........ [SVN r47363]
255 lines
11 KiB
XML
255 lines
11 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!--
|
|
Copyright (c) 2002 Douglas Gregor <doug.gregor -at- gmail.com>
|
|
|
|
Distributed under the Boost Software License, Version 1.0.
|
|
(See accompanying file LICENSE_1_0.txt or copy at
|
|
http://www.boost.org/LICENSE_1_0.txt)
|
|
-->
|
|
<!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.documenting"
|
|
last-revision="$Date$">
|
|
<title>Documenting libraries</title>
|
|
|
|
<para>BoostBook is an extension to <ulink
|
|
url="http://www.docbook.org">DocBook</ulink>, an XML format for
|
|
representing documentation. BoostBook inherits much of its
|
|
functionality and many elements from DocBook that are not
|
|
redocumented here. When writing BoostBook documentation, please
|
|
refer also to <ulink
|
|
url="http://docbook.org/tdg/en/index.html">DocBook: The Definitive
|
|
Guide</ulink>.</para>
|
|
|
|
<section id="boostbook.defining">
|
|
<title>Defining a BoostBook library</title>
|
|
|
|
<para>BoostBook library documentation is contained entirely within
|
|
a <library> XML element. To create a skeletal library, we
|
|
need to create a new XML document (call it <code>any.xml</code>)
|
|
that contains basic information about the library. The following
|
|
<link linkend="boostbook.documenting.skeletal">BoostBook XML
|
|
example</link> describes basic information about the <ulink
|
|
url="http://www.boost.org/libs/any/index.html">Boost.Any</ulink>
|
|
library:</para>
|
|
|
|
<example id="boostbook.documenting.skeletal">
|
|
<title>A Skeletal BoostBook Library</title>
|
|
<programlisting>
|
|
<?xml version="1.0" encoding="utf-8"?>
|
|
<!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>
|
|
<surname>Henney</surname>
|
|
</author>
|
|
<librarypurpose>
|
|
Safe, generic container for single values of different value types
|
|
</librarypurpose>
|
|
<librarycategory name="category:data-structures"/>
|
|
</libraryinfo>
|
|
</library>
|
|
</programlisting>
|
|
</example>
|
|
|
|
<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, 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
|
|
<library> element are:</para>
|
|
|
|
<variablelist>
|
|
<title>Attributes for the <library> element</title>
|
|
<varlistentry>
|
|
<term><code>name</code></term>
|
|
<listitem>
|
|
<simpara>The full name of the library, e.g., "Any"</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><code>dirname</code></term>
|
|
<listitem>
|
|
<simpara>The name of the directory, relative to
|
|
<code>boost/libs</code>, in which the library
|
|
resides. This name may be a relative path, such as
|
|
<code>math/octonion</code>, using "/" for the directory
|
|
separator.</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><code>id</code></term>
|
|
<listitem>
|
|
<simpara>A short, unique name for the library. For libraries
|
|
with simple directory names (e.g., ones that do not contain
|
|
a "/"), this should be the same as the
|
|
<code>dirname</code>. This <code>id</code> will be used to
|
|
identify libraries and, for HTML output, will be used as the
|
|
base name for the HTML file in which the library's
|
|
documentation resides, so it should use only lowercase
|
|
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
|
|
<libraryinfo> element, which gives information about the
|
|
library itself. It contains the author's name (there may be more
|
|
than one <author> element), followed by the purpose of the
|
|
library and the list of categorizations. The
|
|
<librarypurpose> element should always contain a very short
|
|
(single sentence) description of the library's purpose, and should
|
|
<emphasis>not</emphasis> terminate with a period.</para>
|
|
|
|
<para>The list of categories is specified by a set of
|
|
<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>doc/src/boost.xml</filename>.
|
|
</para>
|
|
|
|
<para>At this point, we can apply the BoostBook XSL stylesheets to
|
|
<code>any.xml</code> (to DocBook) followed by a DocBook XSL
|
|
stylesheet to generate HTML output, as described in <xref
|
|
linkend="boostbook.getting.started"/>.</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>From HTML to BoostBook</title>
|
|
|
|
<para>Most library authors are comfortable with writing HTML
|
|
documentation. Writing <ulink
|
|
url="http://www.docbook.org">DocBook</ulink> documentation (and,
|
|
by extension, BoostBook documentation) is quite similar to writing
|
|
HTML, except that BoostBook uses different element names from HTML
|
|
(see <xref linkend="html.to.boostbook"/>) and BoostBook XML is a
|
|
much more rigid format than HTML.</para>
|
|
|
|
<para>One of the easiest ways to convert HTML documentation into
|
|
BoostBook documentation is to use <ulink
|
|
url="http://tidy.sourceforge.net/">HTML Tidy</ulink> to transform
|
|
your HTML into valid XHTML, which will make sure that all elements
|
|
are properly closed, then apply the transformations in <xref
|
|
linkend="html.to.boostbook"/> to the body of the XHTML
|
|
document. The following command uses HTML Tidy to transform HTML
|
|
into valid XHTML:</para>
|
|
|
|
<programlisting>
|
|
tidy -asxhtml input.html > output.xhtml</programlisting>
|
|
|
|
<para>When converting documentation from HTML to BoostBook, note
|
|
that some redundant information that has to be manually maintained
|
|
in HTML is automatically generated in BoostBook: for instance, the
|
|
library categorizations, purpose, and author list described in
|
|
<xref linkend="boostbook.defining"/> are used both in the
|
|
documentation for the library and to build alphabetical and
|
|
categorized lists of known libraries; similarly, tables of
|
|
contents are built automatically from the titles of sections in
|
|
the BoostBook document.</para>
|
|
|
|
<table id="html.to.boostbook">
|
|
<title>Converting HTML elements to BoostBook</title>
|
|
<tgroup cols="2" align="left">
|
|
<thead>
|
|
<row>
|
|
<entry>HTML</entry>
|
|
<entry>BoostBook</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><simpara><h1>, <h2>, etc.</simpara></entry>
|
|
<entry>
|
|
<simpara><section>, <title>; See <xref
|
|
linkend="boostbook.sectioning"/></simpara>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><simpara><i>, <em></simpara></entry>
|
|
<entry><simpara><emphasis></simpara></entry>
|
|
</row>
|
|
<row>
|
|
<entry><simpara><b></simpara></entry>
|
|
<entry><simpara><emphasis role="bold"></simpara></entry>
|
|
</row>
|
|
<row>
|
|
<entry><simpara><ol></simpara></entry>
|
|
<entry><simpara><orderedlist></simpara></entry>
|
|
</row>
|
|
<row>
|
|
<entry><simpara><ul></simpara></entry>
|
|
<entry><simpara><itemizedlist></simpara></entry>
|
|
</row>
|
|
<row>
|
|
<entry><simpara><li></simpara></entry>
|
|
<entry><simpara><listitem></simpara></entry>
|
|
</row>
|
|
<row>
|
|
<entry><simpara><pre></simpara></entry>
|
|
<entry><simpara><programlisting></simpara></entry>
|
|
</row>
|
|
<row>
|
|
<entry><simpara><code></simpara></entry>
|
|
<entry><simpara><computeroutput>,<code></simpara></entry>
|
|
</row>
|
|
<row>
|
|
<entry><simpara><p></simpara></entry>
|
|
<entry><simpara><para>, <simpara></simpara></entry>
|
|
</row>
|
|
<row>
|
|
<entry><simpara><a></simpara></entry>
|
|
<entry>
|
|
<simpara><xref>, <link>, <ulink>;, See <xref
|
|
linkend="boostbook.linking"/></simpara></entry>
|
|
</row>
|
|
<row>
|
|
<entry><simpara><table>, <tr>, <th>, <td></simpara></entry>
|
|
<entry><simpara><table>, <informaltable>, <tgroup>, <thead>, <tfoot>, <tbody>, <row>, <entry>, <entrytbl>; BoostBook tables are equivalent to DocBook tables, for which there is a good <ulink url="http://opensource.bureau-cornavin.com/crash-course/en/tables.html">tutorial here</ulink></simpara></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</section>
|
|
|
|
<section id="boostbook.sectioning">
|
|
<title>Sectioning in BoostBook</title>
|
|
<para>"Sectioning" refers to organization of a document into separate sections, each with a title, some text, and possibly subsections. Each section is described in BoostBook via a <section> element. An introduction section may look like this:</para>
|
|
<programlisting>
|
|
<section id="any.intro">
|
|
<title>Introduction</title>
|
|
|
|
<para>Introduction to a library...</para>
|
|
|
|
<section>
|
|
<title>A Subsection</title>
|
|
<para>Subsection information...</para>
|
|
</section>
|
|
</section>
|
|
</programlisting>
|
|
<para>The <section> element contains all information that
|
|
should logically be grouped within that section. The title of the
|
|
section is placed within the <title> element, and any
|
|
paragraphs, programs, lists, tables, or subsections can occur
|
|
within the section. The <code>id</code> attribute of the
|
|
<section> element gives a unique ID to each section, so that
|
|
it may later be identified for linking. It is suggested that all
|
|
IDs start with the short name of a library followed by a period,
|
|
so that IDs do not conflict between libraries.</para>
|
|
</section>
|
|
</chapter>
|
|
|