255 lines
14 KiB
HTML
255 lines
14 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
||
<html>
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
||
<title>Documenting libraries</title>
|
||
<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
|
||
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
|
||
<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
|
||
<link rel="up" href="../boostbook.html" title="Chapter 50. The BoostBook Documentation Format">
|
||
<link rel="prev" href="getting/started.html" title="Getting Started">
|
||
<link rel="next" href="together.html" title="Bringing Together a BoostBook Document">
|
||
</head>
|
||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||
<table cellpadding="2" width="100%"><tr>
|
||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
|
||
<td align="center"><a href="../../../index.html">Home</a></td>
|
||
<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
|
||
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
|
||
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
|
||
<td align="center"><a href="../../../more/index.htm">More</a></td>
|
||
</tr></table>
|
||
<hr>
|
||
<div class="spirit-nav">
|
||
<a accesskey="p" href="getting/started.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../boostbook.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="together.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||
<a name="boostbook.documenting"></a>Documenting libraries</h2></div></div></div>
|
||
<div class="toc"><dl class="toc">
|
||
<dt><span class="section"><a href="documenting.html#boostbook.defining">Defining a BoostBook library</a></span></dt>
|
||
<dt><span class="section"><a href="documenting.html#id-1.4.3.5.4">From HTML to BoostBook</a></span></dt>
|
||
<dt><span class="section"><a href="documenting.html#boostbook.sectioning">Sectioning in BoostBook</a></span></dt>
|
||
</dl></div>
|
||
<p>BoostBook is an extension to <a href="http://www.docbook.org" target="_top">DocBook</a>, 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 <a href="http://docbook.org/tdg/en/index.html" target="_top">DocBook: The Definitive
|
||
Guide</a>.</p>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="boostbook.defining"></a>Defining a BoostBook library</h3></div></div></div>
|
||
<p>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 class="computeroutput">any.xml</code>)
|
||
that contains basic information about the library. The following
|
||
<a class="link" href="documenting.html#boostbook.documenting.skeletal" title="Example 50.1. A Skeletal BoostBook Library">BoostBook XML
|
||
example</a> describes basic information about the <a href="http://www.boost.org/libs/any/index.html" target="_top">Boost.Any</a>
|
||
library:</p>
|
||
<div class="example">
|
||
<a name="boostbook.documenting.skeletal"></a><p class="title"><b>Example 50.1. A Skeletal BoostBook Library</b></p>
|
||
<div class="example-contents"><pre class="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>
|
||
</pre></div>
|
||
</div>
|
||
<br class="example-break"><p>The first three lines identify this document as a BoostBook
|
||
<a href="http://www.w3.org/XML/" target="_top">XML</a> document. The
|
||
DOCTYPE line states that the document conforms to the BoostBook
|
||
DTD, and that the top-level element is a BoostBook
|
||
<library>.</p>
|
||
<p>The <library> element actually describes the aspects
|
||
of BoostBook library documentation. The attributes for the
|
||
<library> element are:</p>
|
||
<div class="variablelist">
|
||
<p class="title"><b>Attributes for the <library> element</b></p>
|
||
<dl class="variablelist">
|
||
<dt><span class="term"><code class="computeroutput">name</code></span></dt>
|
||
<dd>The full name of the library, e.g., "Any"</dd>
|
||
<dt><span class="term"><code class="computeroutput">dirname</code></span></dt>
|
||
<dd>The name of the directory, relative to
|
||
<code class="computeroutput">boost/libs</code>, in which the library
|
||
resides. This name may be a relative path, such as
|
||
<code class="computeroutput">math/octonion</code>, using "/" for the directory
|
||
separator.</dd>
|
||
<dt><span class="term"><code class="computeroutput">id</code></span></dt>
|
||
<dd>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 class="computeroutput">dirname</code>. This <code class="computeroutput">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.</dd>
|
||
<dt><span class="term"><code class="computeroutput">last-revision</code></span></dt>
|
||
<dd>Always set to <code class="computeroutput">$Date$</code>, which is
|
||
expanded by CVS to include the date and time that the file
|
||
was last modified.</dd>
|
||
</dl>
|
||
</div>
|
||
<p>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
|
||
<span class="emphasis"><em>not</em></span> terminate with a period.</p>
|
||
<p>The list of categories is specified by a set of
|
||
<librarycategory> elements. Each <librarycategory>
|
||
element has a <code class="computeroutput">name</code> element that identifies one of the
|
||
categories. The actual list of categories is in the file
|
||
<code class="filename">doc/src/boost.xml</code>.
|
||
</p>
|
||
<p>At this point, we can apply the BoostBook XSL stylesheets to
|
||
<code class="computeroutput">any.xml</code> (to DocBook) followed by a DocBook XSL
|
||
stylesheet to generate HTML output, as described in <a class="xref" href="getting/started.html" title="Getting Started">the section called “Getting Started”</a>.</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="id-1.4.3.5.4"></a>From HTML to BoostBook</h3></div></div></div>
|
||
<p>Most library authors are comfortable with writing HTML
|
||
documentation. Writing <a href="http://www.docbook.org" target="_top">DocBook</a> documentation (and,
|
||
by extension, BoostBook documentation) is quite similar to writing
|
||
HTML, except that BoostBook uses different element names from HTML
|
||
(see <a class="xref" href="documenting.html#html.to.boostbook" title="Table 50.2. Converting HTML elements to BoostBook">Table 50.2, “Converting HTML elements to BoostBook”</a>) and BoostBook XML is a
|
||
much more rigid format than HTML.</p>
|
||
<p>One of the easiest ways to convert HTML documentation into
|
||
BoostBook documentation is to use <a href="http://tidy.sourceforge.net/" target="_top">HTML Tidy</a> to transform
|
||
your HTML into valid XHTML, which will make sure that all elements
|
||
are properly closed, then apply the transformations in <a class="xref" href="documenting.html#html.to.boostbook" title="Table 50.2. Converting HTML elements to BoostBook">Table 50.2, “Converting HTML elements to BoostBook”</a> to the body of the XHTML
|
||
document. The following command uses HTML Tidy to transform HTML
|
||
into valid XHTML:</p>
|
||
<pre class="programlisting">
|
||
tidy -asxhtml input.html > output.xhtml</pre>
|
||
<p>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
|
||
<a class="xref" href="documenting.html#boostbook.defining" title="Defining a BoostBook library">the section called “Defining a BoostBook library”</a> 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.</p>
|
||
<div class="table">
|
||
<a name="html.to.boostbook"></a><p class="title"><b>Table 50.2. Converting HTML elements to BoostBook</b></p>
|
||
<div class="table-contents"><table class="table" summary="Converting HTML elements to BoostBook">
|
||
<colgroup>
|
||
<col>
|
||
<col>
|
||
</colgroup>
|
||
<thead><tr>
|
||
<th align="left">HTML</th>
|
||
<th align="left">BoostBook</th>
|
||
</tr></thead>
|
||
<tbody>
|
||
<tr>
|
||
<td align="left"><p><h1>, <h2>, etc.</p></td>
|
||
<td align="left">
|
||
<p><section>, <title>; See <a class="xref" href="documenting.html#boostbook.sectioning" title="Sectioning in BoostBook">the section called “Sectioning in BoostBook”</a></p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td align="left"><p><i>, <em></p></td>
|
||
<td align="left"><p><emphasis></p></td>
|
||
</tr>
|
||
<tr>
|
||
<td align="left"><p><b></p></td>
|
||
<td align="left"><p><emphasis role="bold"></p></td>
|
||
</tr>
|
||
<tr>
|
||
<td align="left"><p><ol></p></td>
|
||
<td align="left"><p><orderedlist></p></td>
|
||
</tr>
|
||
<tr>
|
||
<td align="left"><p><ul></p></td>
|
||
<td align="left"><p><itemizedlist></p></td>
|
||
</tr>
|
||
<tr>
|
||
<td align="left"><p><li></p></td>
|
||
<td align="left"><p><listitem></p></td>
|
||
</tr>
|
||
<tr>
|
||
<td align="left"><p><pre></p></td>
|
||
<td align="left"><p><programlisting></p></td>
|
||
</tr>
|
||
<tr>
|
||
<td align="left"><p><code></p></td>
|
||
<td align="left"><p><computeroutput>,<code></p></td>
|
||
</tr>
|
||
<tr>
|
||
<td align="left"><p><p></p></td>
|
||
<td align="left"><p><para>, <simpara></p></td>
|
||
</tr>
|
||
<tr>
|
||
<td align="left"><p><a></p></td>
|
||
<td align="left">
|
||
<p><xref>, <link>, <ulink>;, See <a class="xref" href="together.html#boostbook.linking" title="Linking in BoostBook">the section called “Linking in BoostBook”</a></p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td align="left"><p><table>, <tr>, <th>, <td></p></td>
|
||
<td align="left"><p><table>, <informaltable>, <tgroup>, <thead>, <tfoot>, <tbody>, <row>, <entry>, <entrytbl>; BoostBook tables are equivalent to DocBook tables, for which there is a good <a href="http://opensource.bureau-cornavin.com/crash-course/en/tables.html" target="_top">tutorial here</a></p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table></div>
|
||
</div>
|
||
<br class="table-break">
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="boostbook.sectioning"></a>Sectioning in BoostBook</h3></div></div></div>
|
||
<p>"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:</p>
|
||
<pre class="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>
|
||
</pre>
|
||
<p>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 class="computeroutput">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.</p>
|
||
</div>
|
||
</div>
|
||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||
<td align="left"></td>
|
||
<td align="right"><div class="copyright-footer">Copyright © 2003-2005 Douglas Gregor<p>Distributed under the Boost Software License, Version 1.0.
|
||
(See accompanying file LICENSE_1_0.txt or copy at
|
||
<a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>).
|
||
</p>
|
||
</div></td>
|
||
</tr></table>
|
||
<hr>
|
||
<div class="spirit-nav">
|
||
<a accesskey="p" href="getting/started.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../boostbook.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="together.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
|
||
</div>
|
||
</body>
|
||
</html>
|