diff options
| author | Anas Nashif <anas.nashif@intel.com> | 2012-10-30 12:57:26 -0700 |
|---|---|---|
| committer | Anas Nashif <anas.nashif@intel.com> | 2012-10-30 12:57:26 -0700 |
| commit | 1a78a62555be32868418fe52f8e330c9d0f95d5a (patch) | |
| tree | d3765a80e7d3b9640ec2e930743630cd6b9fce2b /doc/html/boostbook/documenting.html | |
| download | boost-1a78a62555be32868418fe52f8e330c9d0f95d5a.tar.gz boost-1a78a62555be32868418fe52f8e330c9d0f95d5a.tar.bz2 boost-1a78a62555be32868418fe52f8e330c9d0f95d5a.zip | |
Imported Upstream version 1.49.0upstream/1.49.0
Diffstat (limited to 'doc/html/boostbook/documenting.html')
| -rwxr-xr-x | doc/html/boostbook/documenting.html | 253 |
1 files changed, 253 insertions, 0 deletions
diff --git a/doc/html/boostbook/documenting.html b/doc/html/boostbook/documenting.html new file mode 100755 index 0000000000..f986dc3053 --- /dev/null +++ b/doc/html/boostbook/documenting.html @@ -0,0 +1,253 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Documenting libraries</title> +<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> +<link rel="up" href="../boostbook.html" title="Chapter 36. 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> +<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#id3852549">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 36.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 36.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: 2008-07-12 20:30:45 +0100 (Sat, 12 Jul 2008) $"> + <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> +<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: 2008-07-12 20:30:45 +0100 (Sat, 12 Jul 2008) $</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="id3852549"></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 36.2. Converting HTML elements to BoostBook">Table 36.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 36.2. Converting HTML elements to BoostBook">Table 36.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 36.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> |