diff --git a/doc/boostbook.xml b/doc/boostbook.xml new file mode 100644 index 0000000..24b66e4 --- /dev/null +++ b/doc/boostbook.xml @@ -0,0 +1,222 @@ + + + + + + Douglas + Gregor + + + + 2003 + Douglas Gregor + + + + 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. + + This software is provided "as is" without express or + implied warranty, and with no claim as to its suitability for + any purpose. + + + + The BoostBook Documentation Format + +
+ Introduction + + The BoostBook documentation format is an extension of DocBook, 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 Boost C++ libraries, by + providing the ability to express and refer to C++ constructs such + as namespaces, classes, overloaded functions, templates, and + specializations. + + + BoostBook offers additional features more specific to its use for + documenting the Boost C++ + libraries. 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: + + + Testsuites: + 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 + (as + in the MultiArray library), 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. + + + Example programs: + 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: + +std::cout << f(5, 3) >> std::endl; + + 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. + + + Library + categorization: BoostBook contains primitives for + placing libraries into categories and generating categorized + and alphabetized lists of libraries. + + + +
+ +
+ Getting Started + + To use the Boost documentation tools, you will need an + XSLT + processor. There are many XSLT processors available, but for now + we suggest that you use xsltproc, part of libxslt. There are several + ways to get libxslt, depending on your platform: + + + + On Unix: Build and install libxml2) and then libxslt) + + + On Windows: + + + + With Cygwin, select the + libxml2 and libxslt packages + + + Without Cygwin, you can at download + the libxml2, libxslt, and iconv binaries. Or, use + my minimal + repackaged version. + + + + + + You will also need a recent checkout of Boost from CVS and + a very recent checkout from the Boost + Sandbox CVS. Finally, you will need Norman Walsh's DocBook + XSL stylesheets, available at the (DocBook sourceforge + site. Extract the DocBook XSL stylesheets to a directory + on your hard disk (which we'll refer to as the + DOCBOOK_XSL_PATH). + + The current BoostBook documentation encompasses only a few + libraries. The documentation for these libraries is stored in the + directory + boost-sandbox/libs/documentation/examples. From that + directory, we can generate DocBook XML from the BoostBook XML by + invoking xsltproc: + + + xsltproc --xinclude ../boostbook-xsl/docbook.xsl boost.xml > boost.docbook + + + This command parses the BoostBook XML in the file + boost.xml, using XIncludes to bring in + other library documentation (e.g., + function/function.xml for the Function library), and + then translates the XML via the XSL stylesheet docbook.xsl into + DocBook XML, which is written to boost.docbook. You + will probably see several warnings like these while + xsltproc executes: + + + Cannot find function named 'checked_delete' + Cannot find function named 'checked_array_delete' + Cannot find function named 'next' + + + 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. + + 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 <html-output-dir> with a directory of your + choice): + + + xsltproc -o <html-output-dir> <DOCBOOK_XSL_PATH>/html/chunk.xsl boost.docbook + + + 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 nightly + documentation. + + 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 DocBook XSL stylesheets + documentation. + + For users of Unix-based systems, the Makefile supplied in + the examples/ directory can help generate DocBook, + HTML, man pages, and FO. To generate the necessary files + (Makefile.def and catalog.xml), + invoke: + + + ./configure DOCBOOK_XSL_PATH + + + Now run any of: + + make html + make fo + make man + make docbook + +
+ + + + + \ No newline at end of file diff --git a/doc/documenting.xml b/doc/documenting.xml new file mode 100644 index 0000000..7345b10 --- /dev/null +++ b/doc/documenting.xml @@ -0,0 +1,237 @@ + + +
+ Documenting libraries + + BoostBook is an extension to DocBook, 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 DocBook: The Definitive + Guide. + +
+ Defining a BoostBook library + + 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 any.xml) + that contains basic information about the library. The following + BoostBook XML + example describes basic information about the Boost.Any + library: + + + A Skeletal BoostBook Library + +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE library SYSTEM "../../dtd/boostbook.dtd"> +<library name="Any" dirname="any" xmlns:xi="http://www.w3.org/2001/XInclude" id="any"> + <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> + + + + The first two lines identify this document as a BoostBook + XML document. The + DOCTYPE line states that the document conforms to the BoostBook + DTD (here accessed via the relative path + ../../dtd/boostbook.dtd, though this path may change + depending on the location of any.xml) and that the + top-level element is a BoostBook <library>. + + The <library> element actually describes the aspects + of BoostBook library documentation. The attributes for the + <library> element are: + + + Attributes for the <library> element + + name + + The full name of the library, e.g., "Any" + + + + dirname + + The name of the directory, relative to + boost/libs, in which the library + resides. This name may be a relative path, such as + math/octonion, using "/" for the directory + separator. + + + + id + + 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 + dirname. This id 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. + + + + + 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 + not terminate with a period. + + The list of categories is specified by a set of + <librarycategory> elements. Each <librarycategory> + element has a name element that identifies one of the + categories. The actual list of categories is in the file + boost-sandbox/libs/documentation/examples/boost.xml. + + + At this point, we can apply the BoostBook XSL stylesheets to + any.xml (to DocBook) followed by a DocBook XSL + stylesheet to generate HTML output, as described in . +
+ +
+ From HTML to BoostBook + + Most library authors are comfortable with writing HTML + documentation. Writing DocBook documentation (and, + by extension, BoostBook documentation) is quite similar to writing + HTML, except that BoostBook uses different element names from HTML + (see ) and BoostBook XML is a + much more rigid format than HTML. + + One of the easiest ways to convert HTML documentation into + BoostBook documentation is to use HTML Tidy to transform + your HTML into valid XHTML, which will make sure that all elements + are properly closed, then apply the transformations in to the body of the XHTML + document. The following command uses HTML Tidy to transform HTML + into valid XHTML: + + + tidy -asxhtml input.html > output.xhtml + + 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 + 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. + + + Converting HTML elements to BoostBook + + + + HTML + BoostBook + + + + + <h1>, <h2>, etc. + +<section>, <title>; See + + + + <i>, <em> + <emphasis> + + + <b> + <emphasis role="bold"> + + + <ol> + <orderedlist> + + + <ul> + <itemizedlist> + + + <li> + <listitem> + + + <pre> + <programlisting> + + + <code> + <computeroutput>,<code> + + + <p> + <para>, <simpara> + + + <a> + +<xref>, <link>, <ulink>;, See + + + <table>, <tr>, <th>, <td> + <table>, <informaltable>, <tgroup>, <thead>, <tfoot>, <tbody>, <row>, <entry>, <entrytbl>; BoostBook tables are equivalent to DocBook tables, for which there is a good tutorial here + + + +
+
+ +
+ Sectioning in BoostBook + "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: + +<section id="any.intro"> + <title>Introduction</title> + + <para>Introduction to a library...</para> + + <section> + <title>A Subsection</title> + <para>Subsection information...</para> + </section> +</section> + + 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 id 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. +
+
+ diff --git a/doc/reference_doc.xml b/doc/reference_doc.xml new file mode 100644 index 0000000..a35d665 --- /dev/null +++ b/doc/reference_doc.xml @@ -0,0 +1,292 @@ + + +
+ Documenting C++ Constructs + + 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. + +
+ Library references and headers + + Reference documentation for a library is contained with a + <library-reference> element. The <library-reference> + element has no attributes, and contains as children only + <header> elements. + + The <header> element defines a C++ header file. Within + each C++ header file lie the definitions of C++ constructs to be + documented. The name attribute of the <header> + element gives the name of the header, as one would specify when + including the header. For instance, the <library-reference> + for the Any library may look like + this: + + +<library-reference> + <header name="boost/any.hpp"> + <!-- C++ constructs in this header --> + </header> +</library-reference> + + + If the Any library contained + multiple headers, we would list them all as children of the + <library-reference> element. +
+ +
+ Namespaces + + BoostBook namespaces are declared via the <namespace> + element. As in C++, namespaces can be nested and contain other C++ + constructs, such as classes or functions. The name + attribute of a <namespace> element gives the namespace name + (e.g., "boost"). The Any library is + defined entirely within namespace boost by: + + +<library-reference> + <header name="boost/any.hpp"> + <namespace name="boost"> + <!-- C++ constructs in the boost namespace --> + </namespace> + </header> +</library-reference> + +
+ +
+ Classes + + C++ classes and class templates are described via the + <class> element. Each class has a name (e.g., "any") given + by the name attribute, a purpose given by the + <purpose> element, documentation, and a set of types, + functions, base classes, and data members. Here is a minimal + definition of the boost::any class: + +<namespace name="boost"> + <class name="any"> + <purpose> + A class whose instances can hold instances of any type that satisfies + ValueType requirements. + </purpose> + </class> +</namespace> + + + Additional class documentation can be contained in + <para> elements following the <purpose> element. This + documentation will be typeset prior to documentation for specific + elements in the class (e.g., constructors or methods). + + Class inheritance is described via the <inherit> + element. The <inherit> element requires an + access attribute which must be one of + public, protected, or + private. The content of the <inherited> + element in C++ code that names the class inherited, and may + contain markup to link to the class. The following description of + the class boost::bad_any_cast describes + public inheritance from the class + std::bad_cast. It also defines the + <purpose> element, which contains a short description of the + use of the class. + + +<class name="bad_any_cast"> + <inherit access="public"><classname>std::bad_cast</classname></inherit> + <purpose><para>The exception thrown in the event of a failed + <functionname>any_cast</functionname> of an + <classname>any</classname> value.</para></purpose> +</class> + + + Information about constructors, methods, and other functions + can be found in . 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 + boost::any_cast. + + Class templates are defined by <class> elements with a + <template> child element at the beginning. Templates are + discussed . +
+ +
+ Functions + + 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; + gives the elements for each C++ function type. + + 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 . + + The following example illustrates some constructors and a + destructor for boost::any. We note that in + each of the clauses from there is a (required!) + <simpara> 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, const any& + is contained in the <paramtype> element; any number of + parameters may be specified in this way. + + +<class name="any"> + <constructor> + <postconditions><para><this->empty()></para></postconditions> + </constructor> + + <constructor> + <parameter name="other"> + <paramtype>const <classname>any</classname>&amp;</paramtype> + </parameter> + + <effects> + <simpara> Copy constructor that copies + content of <code>other</code> into the new instance, + so that any content is equivalent in both type and value to the + content of <code>other</code>, or empty if + <code>other</code> is + empty. + </simpara> + </effects> + + <throws> + <simpara>May fail with a + <classname>std::bad_alloc</classname> exception or any + exceptions arising from the copy constructor of the + contained type. + </simpara> + </throws> + </constructor> + + <destructor> + <effects><simpara>Releases any and all resources used in + management of instance.</simpara></effects> + + <throws><simpara>Nothing.</simpara></throws> + </destructor> +</class> + + + + BoostBook Function Types + + + + + C++ Function + BoostBook Element + + + + + Constructor + <constructor> + + + Destructor + <destructor> + + + Copy assignment operator + <copy-assignment> + + + Member function + <method> + + + Free function + <function> + + + +
+ + + BoostBook Function Semantics Clauses + + + + + BoostBook element + Description + + + + + <requires> + 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. + + + <effects> + The effects of executing the function. For + instance, this may include documenting changes in state, + other functions executed, or output written to + files. + + + <postconditions> + Conditions that are guaranteed to hold + after execution of the function, assuming that all + requirements have been met. + + + <returns> + A description of the value returned from + the function. + + + <throws> + A description of the exceptions that may + be thrown from this function. + + + <complexity> + The computational complexity of this + function. + + + <notes> + Additional notes that clarify the behavior + of the function. + + + <rationale> + Reasons for the current semantics, + including an explanation of potential alternative + semantics and reasons why the alternatives have not bee + used. + + + +
+
+ +
+ Templates + To be written... +
+
diff --git a/doc/together.xml b/doc/together.xml new file mode 100644 index 0000000..20e1923 --- /dev/null +++ b/doc/together.xml @@ -0,0 +1,61 @@ + + +
+ Bringing Together a BoostBook Document + +
+ Linking in BoostBook + + 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: + <xref>, <link>, and >ulink>. Additionally, there + are linking elements for referencing specific types of entities, + such as classes (<classname>), functions + (<functionname>), or libraries (<libraryname>). + + The <xref> element references elements that have an + id 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 <xref> element with the + linkend attribute set to the ID of the intended + target. For instance, this section's ID is + boostbook.linking, so we create a reference it to + with <xref linkend="boostbook.linking"/>, which + will look like this in the text: . + + The <link> element references an ID in the same way as + <xref>, except that <link> 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 <link + linkend="boostbook.linking">like this</link>. This + markup will result in a link to this chapter that looks like this. + + The <ulink> element references a URL that is outside + of the DocBook document. The url 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 + <ulink + url="http://www.boost.org">Boost</ulink>, which + appears in the document like this: Boost. + + The <classname>, <functionname>, + <methodname>, and <libraryname> 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 + <libraryname>Function</libraryname>, + which results in the following: + Function. In cases where the displayed + text is different from the actual name, the alt + attribute can be specified. For instance, the following XML + element references the boost::function + class template but displays the text function: <classname + alt="boost::function">function</classname>. +
+
\ No newline at end of file