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

BoostBook documentation

Browse Source 
[SVN r17863]
This commit is contained in:
Douglas Gregor 2003-03-12 22:02:01 +00:00
parent df433e64bd
commit 5c62149ef7
4 changed files with 812 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

222
doc/boostbook.xml Normal file
View File

@ -0,0 +1,222 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE chapter SYSTEM "../../dtd/boostbook.dtd">
<chapter xmlns:xi="http://www.w3.org/2001/XInclude" id="boostbook">
<chapterinfo>
<author>
<firstname>Douglas</firstname>
<surname>Gregor</surname>
</author>
<copyright>
<year>2003</year>
<holder>Douglas Gregor</holder>
</copyright>
<legalnotice>
<para>Permission to copy, use, sell and distribute this software
is granted provided this copyright notice appears in all copies.
Permission to modify the code and to distribute modified code is
granted provided this copyright notice appears in all copies,
and a notice that the code was modified is included with the
copyright notice. </para>
<para> This software is provided "as is" without express or
implied warranty, and with no claim as to its suitability for
any purpose. </para>
</legalnotice>
</chapterinfo>
<title>The BoostBook Documentation Format</title>
<section>
<title>Introduction</title>
<para>The BoostBook documentation format is an extension of <ulink
url="http://www.docbook.org">DocBook</ulink>, an SGML- or
XML-based format for describing documentation. BoostBook augments
DocBook with semantic markup that aids in the documentation of C++
libraries, specifically the <ulink
url="http://www.boost.org">Boost C++ libraries</ulink>, by
providing the ability to express and refer to C++ constructs such
as namespaces, classes, overloaded functions, templates, and
specializations.</para>
<para>
BoostBook offers additional features more specific to its use for
documenting the <ulink url="http://www.boost.org">Boost C++
libraries</ulink>. These features are intended to eliminate or
reduce the need for duplication of information and to aid in
documenting portions of Boost that might otherwise not be
documented. Examples of Boost-centric features include:
<itemizedlist>
<listitem>
<para><emphasis role="bold">Testsuites</emphasis>:
Testsuites in Boost are created by writing an appropriate
Jamfile and including that Jamfile in the list of Jamfiles
including for testing. If the testsuites are documented
(<ulink
url="http://www.boost.org/libs/multi_array/doc/test_cases.html">as
in the MultiArray library</ulink>), the documentation is
maintained separately from the testcase Jamfile, leading to
duplication of information and the possibility of having the
documentation out of sync with the Jamfile. BoostBook
contains elements that describe a testsuite for both
purposes: the BoostBook stylesheets can generate
documentation for the testcases and also generate an
appropriate Jamfile to integrate the testcases with the
regression testing system.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Example programs</emphasis>:
Example programs in documentation need to be duplicated in
testcases to ensure that the examples compile and execute
correctly. Keeping the two copies in sync is a tedious and
error-prone task. For instance, the following code snippet
persisted for six months:</para>
<programlisting>
std::cout &lt;&lt; f(5, 3) &gt;&gt; std::endl;
</programlisting>
<para>The BoostBook format allows testcases to be generated
by weaving together program fragments from example programs
in the documentation. This capability is integrated with
testsuite generation so that example programs are normal
tests in BoostBook.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Library
categorization</emphasis>: BoostBook contains primitives for
placing libraries into categories and generating categorized
and alphabetized lists of libraries.</para>
</listitem>
</itemizedlist>
</para>
</section>
<section id="boostbook.getting.started">
<title>Getting Started</title>
<para>To use the Boost documentation tools, you will need an
<ulink url="http://www.w3c.org/Style/XSL/">XSLT</ulink>
processor. There are many XSLT processors available, but for now
we suggest that you use <code>xsltproc</code>, part of <ulink
url="http://xmlsoft.org/XSLT/">libxslt</ulink>. There are several
ways to get libxslt, depending on your platform:</para>
<itemizedlist>
<listitem>
<para>On Unix: Build and install <ulink
url="http://xmlsoft.org/">libxml2</ulink>) and then <ulink
url="http://xmlsoft.org/XSLT/">libxslt</ulink>)</para>
</listitem>
<listitem>
<para>On Windows:</para>
<itemizedlist>
<listitem>
<para>With <ulink
url="http://www.cygwin.com/">Cygwin</ulink>, select the
libxml2 and libxslt packages</para>
</listitem>
<listitem>
<para>Without Cygwin, you can at <ulink
url="http://www.zlatkovic.com/projects/libxml/binaries.html">download
the libxml2, libxslt, and iconv binaries</ulink>. Or, use
my <ulink
url="http://www.cs.rpi.edu/~gregod/boost/doc/xsltproc-win32.zip">minimal
repackaged version</ulink>.</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<para>You will also need a recent checkout of Boost from <ulink
url="http://www.boost.org/more/download.html#CVS">CVS</ulink> and
a very recent checkout from the <ulink
url="http://www.boost.org/more/mailing_lists.htm#sandbox">Boost
Sandbox CVS</ulink>. Finally, you will need Norman Walsh's DocBook
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
libraries. The documentation for these libraries is stored in the
directory
<code>boost-sandbox/libs/documentation/examples</code>. From that
directory, we can generate DocBook XML from the BoostBook XML by
invoking <code>xsltproc</code>:</para>
<programlisting>
xsltproc --xinclude ../boostbook-xsl/docbook.xsl boost.xml > boost.docbook
</programlisting>
<para>This command parses the BoostBook XML in the file
<code>boost.xml</code>, using <ulink
url="http://www.w3.org/TR/xinclude/">XIncludes</ulink> to bring in
other library documentation (e.g.,
<code>function/function.xml</code> for the Function library), and
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>
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
tools cannot find documentation for functions, methods, or classes
that are referenced in the source, and are not harmful in any
way.</para>
<para>With DocBook XML, we can generate several other
documentation formats. To generate HTML, we invoke xsltproc to
transform the DocBook XML into HTML with the following command
(replace <code>&lt;html-output-dir&gt;</code> with a directory of your
choice):</para>
<programlisting>
xsltproc -o &lt;html-output-dir&gt; &lt;DOCBOOK_XSL_PATH&gt;/html/chunk.xsl boost.docbook
</programlisting>
<para>Once this command completes, you will have HTML
documentation. There are many options that can be used to
customize the output HTML; please see the Makefile for the set of
commands used to generate the <ulink
url="http://www.cs.rpi.edu/~gregod/boost/doc/html/libraries.html">nightly
documentation</ulink>.</para>
<para>The DocBook XSL stylesheets support other output formats,
such as Unix man pages, XHTML, HTML as a single file, and XSL
Formatting Objects (which can in turn be used to generate, e.g.,
PDF or PostScript documentation). To generate these other formats,
please refer to the <ulink
url="http://docbook.sourceforge.net">DocBook XSL stylesheets
documentation</ulink>.</para>
<para>For users of Unix-based systems, the Makefile supplied in
the <code>examples/</code> directory can help generate DocBook,
HTML, man pages, and FO. To generate the necessary files
(<code>Makefile.def</code> and <code>catalog.xml</code>),
invoke:</para>
<programlisting>
./configure DOCBOOK_XSL_PATH
</programlisting>
<para>Now run any of:</para>
<programlisting>
make html
make fo
make man
make docbook
</programlisting>
</section>
<xi:include href="documenting.xml"/>
<xi:include href="reference_doc.xml"/>
<xi:include href="together.xml"/>
</chapter>

237
doc/documenting.xml Normal file
View File

@ -0,0 +1,237 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE section SYSTEM "../../dtd/boostbook.dtd">
<section xmlns:xi="http://www.w3.org/2001/XInclude">
<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 &lt;library&gt; 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>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!DOCTYPE library SYSTEM "../../dtd/boostbook.dtd"&gt;
&lt;library name="Any" dirname="any" xmlns:xi="http://www.w3.org/2001/XInclude" id="any"&gt;
&lt;libraryinfo&gt;
&lt;author&gt;
&lt;firstname&gt;Kevlin&lt;/firstname&gt;
&lt;surname&gt;Henney&lt;/surname&gt;
&lt;/author&gt;
&lt;librarypurpose&gt;
Safe, generic container for single values of different value types
&lt;/librarypurpose&gt;
&lt;librarycategory name="category:data-structures"/&gt;
&lt;/libraryinfo&gt;
&lt;/library&gt;
</programlisting>
</example>
<para>The first two 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 (here accessed via the relative path
<code>../../dtd/boostbook.dtd</code>, though this path may change
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
of BoostBook library documentation. The attributes for the
&lt;library&gt; element are:</para>
<variablelist>
<title>Attributes for the &lt;library&gt; 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>
</variablelist>
<para>Inside the &lt;library&gt; element we have the
&lt;libraryinfo&gt; element, which gives information about the
library itself. It contains the author's name (there may be more
than one &lt;author&gt; element), followed by the purpose of the
library and the list of categorizations. The
&lt;librarypurpose&gt; 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
&lt;librarycategory&gt; elements. Each &lt;librarycategory&gt;
element has a <code>name</code> element that identifies one of the
categories. The actual list of categories is in the file
<filename>boost-sandbox/libs/documentation/examples/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 &gt; 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>&lt;h1&gt;, &lt;h2&gt;, etc.</simpara></entry>
<entry>
<simpara>&lt;section&gt;, &lt;title&gt;; See <xref
linkend="boostbook.sectioning"/></simpara>
</entry>
</row>
<row>
<entry><simpara>&lt;i&gt;, &lt;em&gt;</simpara></entry>
<entry><simpara>&lt;emphasis&gt;</simpara></entry>
</row>
<row>
<entry><simpara>&lt;b&gt;</simpara></entry>
<entry><simpara>&lt;emphasis role="bold"&gt;</simpara></entry>
</row>
<row>
<entry><simpara>&lt;ol&gt;</simpara></entry>
<entry><simpara>&lt;orderedlist&gt;</simpara></entry>
</row>
<row>
<entry><simpara>&lt;ul&gt;</simpara></entry>
<entry><simpara>&lt;itemizedlist&gt;</simpara></entry>
</row>
<row>
<entry><simpara>&lt;li&gt;</simpara></entry>
<entry><simpara>&lt;listitem&gt;</simpara></entry>
</row>
<row>
<entry><simpara>&lt;pre&gt;</simpara></entry>
<entry><simpara>&lt;programlisting&gt;</simpara></entry>
</row>
<row>
<entry><simpara>&lt;code&gt;</simpara></entry>
<entry><simpara>&lt;computeroutput&gt;,&lt;code&gt;</simpara></entry>
</row>
<row>
<entry><simpara>&lt;p&gt;</simpara></entry>
<entry><simpara>&lt;para&gt;, &lt;simpara&gt;</simpara></entry>
</row>
<row>
<entry><simpara>&lt;a&gt;</simpara></entry>
<entry>
<simpara>&lt;xref&gt;, &lt;link&gt;, &lt;ulink&gt;;, See <xref
linkend="boostbook.linking"/></simpara></entry>
</row>
<row>
<entry><simpara>&lt;table&gt;, &lt;tr&gt;, &lt;th&gt;, &lt;td&gt;</simpara></entry>
<entry><simpara>&lt;table&gt;, &lt;informaltable&gt;, &lt;tgroup&gt;, &lt;thead&gt;, &lt;tfoot&gt;, &lt;tbody&gt;, &lt;row&gt;, &lt;entry&gt;, &lt;entrytbl&gt;; BoostBook tables are equivalent to DocBook tables, for which there is a good <ulink url="http://opensource.bureau-cornavin.com/crash-course/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 &lt;section&gt; element. An introduction section may look like this:</para>
<programlisting>
&lt;section id="any.intro"&gt;
&lt;title&gt;Introduction&lt;/title&gt;
&lt;para&gt;Introduction to a library...&lt;/para&gt;
&lt;section&gt;
&lt;title&gt;A Subsection&lt;/title&gt;
&lt;para&gt;Subsection information...&lt;/para&gt;
&lt;/section&gt;
&lt;/section&gt;
</programlisting>
<para>The &lt;section&gt; element contains all information that
should logically be grouped within that section. The title of the
section is placed within the &lt;title&gt; element, and any
paragraphs, programs, lists, tables, or subsections can occur
within the section. The <code>id</code> attribute of the
&lt;section&gt; 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>
</section>

292
doc/reference_doc.xml Normal file
View File

@ -0,0 +1,292 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE section SYSTEM "../../dtd/boostbook.dtd">
<section xmlns:xi="http://www.w3.org/2001/XInclude">
<title>Documenting C++ Constructs</title>
<para>This section describes the documentation of C++ constructs
within BoostBook. BoostBook provides elements that describe C++
classes, functions, namespaces, and other declarative constructs in
a presentation-independent manner. From these descriptions, the
BoostBook XSL stylesheets generate cross-referenced reference
documentation for C++ libraries with a consistent look and
feel.</para>
<section>
<title>Library references and headers</title>
<para>Reference documentation for a library is contained with a
&lt;library-reference&gt; element. The &lt;library-reference&gt;
element has no attributes, and contains as children only
&lt;header&gt; elements.</para>
<para>The &lt;header&gt; element defines a C++ header file. Within
each C++ header file lie the definitions of C++ constructs to be
documented. The <code>name</code> attribute of the &lt;header&gt;
element gives the name of the header, as one would specify when
including the header. For instance, the &lt;library-reference&gt;
for the <libraryname>Any</libraryname> library may look like
this:</para>
<programlisting>
&lt;library-reference&gt;
&lt;header name="boost/any.hpp"&gt;
&lt;!-- C++ constructs in this header --&gt;
&lt;/header&gt;
&lt;/library-reference&gt;
</programlisting>
<para>If the <libraryname>Any</libraryname> library contained
multiple headers, we would list them all as children of the
&lt;library-reference&gt; element.</para>
</section>
<section>
<title>Namespaces</title>
<para>BoostBook namespaces are declared via the &lt;namespace&gt;
element. As in C++, namespaces can be nested and contain other C++
constructs, such as classes or functions. The <code>name</code>
attribute of a &lt;namespace&gt; element gives the namespace name
(e.g., "boost"). The <libraryname>Any</libraryname> library is
defined entirely within namespace boost by:</para>
<programlisting>
&lt;library-reference&gt;
&lt;header name="boost/any.hpp"&gt;
&lt;namespace name="boost"&gt;
&lt;!-- C++ constructs in the boost namespace --&gt;
&lt;/namespace&gt;
&lt;/header&gt;
&lt;/library-reference&gt;
</programlisting>
</section>
<section id="boostbook.classes">
<title>Classes</title>
<para>C++ classes and class templates are described via the
&lt;class&gt; element. Each class has a name (e.g., "any") given
by the <code>name</code> attribute, a purpose given by the
&lt;purpose&gt; element, documentation, and a set of types,
functions, base classes, and data members. Here is a minimal
definition of the <classname>boost::any</classname> class:</para>
<programlisting>
&lt;namespace name="boost"&gt;
&lt;class name="any"&gt;
&lt;purpose&gt;
A class whose instances can hold instances of any type that satisfies
ValueType requirements.
&lt;/purpose&gt;
&lt;/class&gt;
&lt;/namespace&gt;
</programlisting>
<para>Additional class documentation can be contained in
&lt;para&gt; elements following the &lt;purpose&gt; element. This
documentation will be typeset prior to documentation for specific
elements in the class (e.g., constructors or methods).</para>
<para>Class inheritance is described via the &lt;inherit&gt;
element. The &lt;inherit&gt; element requires an
<code>access</code> attribute which must be one of
<emphasis>public</emphasis>, <emphasis>protected</emphasis>, or
<emphasis>private</emphasis>. The content of the &lt;inherited&gt;
element in C++ code that names the class inherited, and may
contain markup to link to the class. The following description of
the class <classname>boost::bad_any_cast</classname> describes
public inheritance from the class
<classname>std::bad_cast</classname>. It also defines the
&lt;purpose&gt; element, which contains a short description of the
use of the class.</para>
<programlisting>
&lt;class name="bad_any_cast"&gt;
&lt;inherit access="public"&gt;&lt;classname&gt;std::bad_cast&lt;/classname&gt;&lt;/inherit&gt;
&lt;purpose&gt;&lt;para&gt;The exception thrown in the event of a failed
&lt;functionname&gt;any_cast&lt;/functionname&gt; of an
&lt;classname&gt;any&lt;/classname&gt; value.&lt;/para&gt;&lt;/purpose&gt;
&lt;/class&gt;
</programlisting>
<para>Information about constructors, methods, and other functions
can be found in <xref linkend="boostbook.functions"/>. Note that
free functions and free function groups are allowed at class
level, and will be documented along with the class, for instance
see the documentation of
<functionname>boost::any_cast</functionname>.</para>
<para>Class templates are defined by &lt;class&gt; elements with a
&lt;template&gt; child element at the beginning. Templates are
discussed <xref linkend="boostbook.templates"/>.</para>
</section>
<section id="boostbook.functions">
<title>Functions</title>
<para>BoostBook functions are documented by specifying the
function's interface (e.g., its C++ signature) and its
behavior. Constructors, destructors, member functions, and free
functions all use the same documentation method, although the
top-level tags differ; <xref linkend="boostbook.function.types"/>
gives the elements for each C++ function type.</para>
<para>The behavior of functions in BoostBook is documenting using
a style similar to that of the C++ standard, with clauses
describing the requirements, effects, postconditions, exception
behavior, and return values of functions. The names and uses of
the XML elements for each clause type are given in <xref
linkend="boostbook.function.clauses"/>.</para>
<para>The following example illustrates some constructors and a
destructor for <classname>boost::any</classname>. We note that in
each of the clauses from <xref
linkend="boostbook.function.clauses"/> there is a (required!)
&lt;simpara&gt; element containing the text for that clause. We
also note that one of the constructors takes a single parameter
whose name is "other" and whose type, <code>const any&amp;</code>
is contained in the &lt;paramtype&gt; element; any number of
parameters may be specified in this way.</para>
<programlisting>
&lt;class name="any"&gt;
&lt;constructor&gt;
&lt;postconditions&gt;&lt;para&gt;&lt;this-&gt;empty()&gt;&lt;/para&gt;&lt;/postconditions&gt;
&lt;/constructor&gt;
&lt;constructor&gt;
&lt;parameter name="other"&gt;
&lt;paramtype&gt;const &lt;classname&gt;any&lt;/classname&gt;&amp;amp;&lt;/paramtype&gt;
&lt;/parameter&gt;
&lt;effects&gt;
&lt;simpara&gt; Copy constructor that copies
content of &lt;code&gt;other&lt;/code&gt; into the new instance,
so that any content is equivalent in both type and value to the
content of &lt;code&gt;other&lt;/code&gt;, or empty if
&lt;code&gt;other&lt;/code&gt; is
empty.
&lt;/simpara&gt;
&lt;/effects&gt;
&lt;throws&gt;
&lt;simpara&gt;May fail with a
&lt;classname&gt;std::bad_alloc&lt;/classname&gt; exception or any
exceptions arising from the copy constructor of the
contained type.
&lt;/simpara&gt;
&lt;/throws&gt;
&lt;/constructor&gt;
&lt;destructor&gt;
&lt;effects&gt;&lt;simpara&gt;Releases any and all resources used in
management of instance.&lt;/simpara&gt;&lt;/effects&gt;
&lt;throws&gt;&lt;simpara&gt;Nothing.&lt;/simpara&gt;&lt;/throws&gt;
&lt;/destructor&gt;
&lt;/class&gt;
</programlisting>
<table id="boostbook.function.types">
<title>BoostBook Function Types</title>
<tgroup cols="2">
<thead>
<row>
<entry><simpara>C++ Function</simpara></entry>
<entry><simpara>BoostBook Element</simpara></entry>
</row>
</thead>
<tbody>
<row>
<entry><simpara>Constructor</simpara></entry>
<entry><simpara>&lt;constructor&gt;</simpara></entry>
</row>
<row>
<entry><simpara>Destructor</simpara></entry>
<entry><simpara>&lt;destructor&gt;</simpara></entry>
</row>
<row>
<entry><simpara>Copy assignment operator</simpara></entry>
<entry><simpara>&lt;copy-assignment&gt;</simpara></entry>
</row>
<row>
<entry><simpara>Member function</simpara></entry>
<entry><simpara>&lt;method&gt;</simpara></entry>
</row>
<row>
<entry><simpara>Free function</simpara></entry>
<entry><simpara>&lt;function&gt;</simpara></entry>
</row>
</tbody>
</tgroup>
</table>
<table id="boostbook.function.clauses">
<title>BoostBook Function Semantics Clauses</title>
<tgroup cols="2">
<thead>
<row>
<entry><simpara>BoostBook element</simpara></entry>
<entry><simpara>Description</simpara></entry>
</row>
</thead>
<tbody>
<row>
<entry><simpara>&lt;requires&gt;</simpara></entry>
<entry><simpara>A set of requirements that must be met
prior to execution of the function (a.k.a.,
preconditions). If any of these requirements is not met
and the function is executed, then the behavior is
undefined.</simpara></entry>
</row>
<row>
<entry><simpara>&lt;effects&gt;</simpara></entry>
<entry><simpara>The effects of executing the function. For
instance, this may include documenting changes in state,
other functions executed, or output written to
files.</simpara></entry>
</row>
<row>
<entry><simpara>&lt;postconditions&gt;</simpara></entry>
<entry><simpara>Conditions that are guaranteed to hold
after execution of the function, assuming that all
requirements have been met.</simpara></entry>
</row>
<row>
<entry><simpara>&lt;returns&gt;</simpara></entry>
<entry><simpara>A description of the value returned from
the function.</simpara></entry>
</row>
<row>
<entry><simpara>&lt;throws&gt;</simpara></entry>
<entry><simpara>A description of the exceptions that may
be thrown from this function.</simpara></entry>
</row>
<row>
<entry><simpara>&lt;complexity&gt;</simpara></entry>
<entry><simpara>The computational complexity of this
function.</simpara></entry>
</row>
<row>
<entry><simpara>&lt;notes&gt;</simpara></entry>
<entry><simpara>Additional notes that clarify the behavior
of the function.</simpara></entry>
</row>
<row>
<entry><simpara>&lt;rationale&gt;</simpara></entry>
<entry><simpara>Reasons for the current semantics,
including an explanation of potential alternative
semantics and reasons why the alternatives have not bee
used.</simpara></entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section id="boostbook.templates">
<title>Templates</title>
<para>To be written...</para>
</section>
</section>

61
doc/together.xml Normal file
View File

@ -0,0 +1,61 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE section SYSTEM "../../dtd/boostbook.dtd">
<section xmlns:xi="http://www.w3.org/2001/XInclude" id="boostbook.together">
<title>Bringing Together a BoostBook Document</title>
<section id="boostbook.linking">
<title>Linking in BoostBook</title>
<para>How one links to another element in BoostBook depends
greatly on the nature of the element linked and how the link
should appear. There are three general linking elements:
&lt;xref&gt;, &lt;link&gt;, and &gt;ulink&gt;. Additionally, there
are linking elements for referencing specific types of entities,
such as classes (&lt;classname&gt;), functions
(&lt;functionname&gt;), or libraries (&lt;libraryname&gt;).</para>
<para>The &lt;xref&gt; element references elements that have an
<code>id</code> attribute and a title. The actual link text is
composed from title and type of the element referenced. To link to
a particular ID, create an &lt;xref&gt; element with the
<code>linkend</code> attribute set to the ID of the intended
target. For instance, this section's ID is
<code>boostbook.linking</code>, so we create a reference it to
with <code>&lt;xref linkend="boostbook.linking"/&gt;</code>, which
will look like this in the text: <xref
linkend="boostbook.linking"/>.</para>
<para>The &lt;link&gt; element references an ID in the same way as
&lt;xref&gt;, except that &lt;link&gt; does not generate any text
for the link, so text must be supplied within the element. For
instance, we can again link to this chapter but this time specify
our own text with <code>&lt;link
linkend="boostbook.linking"&gt;like this&lt;/link&gt;</code>. This
markup will result in a link to this chapter that looks <link
linkend="boostbook.linking">like this</link>.</para>
<para>The &lt;ulink&gt; element references a URL that is outside
of the DocBook document. The <code>url</code> attribute contains
the URL to link to, and the element data provides the link
text.For instance, we can link to the the Boost web site with
<code>&lt;ulink
url="http://www.boost.org"&gt;Boost&lt;/ulink&gt;,</code> which
appears in the document like this: <ulink
url="http://www.boost.org">Boost</ulink>.</para>
<para>The &lt;classname&gt;, &lt;functionname&gt;,
&lt;methodname&gt;, and &lt;libraryname&gt; link to classes,
functions, methods, and libraries, respectively. The text of each
element gives both the name of the element to link to and the link
text. For instance, we can link to the Function library with
<code>&lt;libraryname&gt;Function&lt;/libraryname&gt;</code>,
which results in the following:
<libraryname>Function</libraryname>. In cases where the displayed
text is different from the actual name, the <code>alt</code>
attribute can be specified. For instance, the following XML
element references the <classname>boost::function</classname>
class template but displays the text <classname
alt="boost::function">function</classname>: <code>&lt;classname
alt="boost::function"&gt;function&lt;/classname&gt;</code>.</para>
</section>
</section>