reference.dtdxml

Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work

    <pcdata/>
    <element-name name="snippet"/>
  </or-group>
</content-model>
<purpose>Defines source code for a test</purpose>

<description>
  <para>This element will contain the source code for a testcase that
  will be generated from the documentation. To reduce the amount of escaping in the text, it is recommended to use CDATA sections, which look like this:

    <programlisting>&lt;![CDATA[
&lt;your program text here: no escaping needed!&gt;
]]&gt;</programlisting>
  </para>

  <para>In addition to CDATA sections, code snippets can be pulled in
  from <sgmltag>programlisting</sgmltag> elements using the <link
  linkend="boostbook.dtd.snippet"><sgmltag>snippet</sgmltag></link>
  element.</para>
</description>

</element>

<element name="function"
         content-type="element">
<content-model-expanded>
  <sequence-group>
    <element-name name="template" occurrence="?"/>
    <element-name name="type"/>
    <element-name name="parameter" occurrence="*"/>
    <element-name name="purpose" occurrence="?"/>
    <element-name name="description" occurrence="?"/>
    <element-name name="requires" occurrence="?"/>
    <element-name name="effects" occurrence="?"/>
    <element-name name="postconditions" occurrence="?"/>
    <element-name name="returns" occurrence="?"/>
    <element-name name="throws" occurrence="?"/>
    <element-name name="complexity" occurrence="?"/>
    <element-name name="notes" occurrence="?"/>
    <element-name name="rationale" occurrence="?"/>
  </sequence-group>
</content-model-expanded>
<content-model>
  <sequence-group>
    <element-name name="template" occurrence="?"/>
    <element-name name="type"/>
    <element-name name="parameter" occurrence="*"/>
    <parament-name name="boost.function.semantics"/>
  </sequence-group>
</content-model>
<purpose>Declares a function</purpose>
<description>
  <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.</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.</para>

  <para>The following example illustrates some constructors and a
  destructor for <classname>boost::any</classname>. 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>
</description>
</element>

<attlist name="function">
<attdecl>
    name         CDATA  #REQUIRED
    specifiers   CDATA  #IMPLIED
    %boost.common.attrib;</attdecl>
<attribute name="last-revision"
           type="#IMPLIED"
           value="CDATA"
           default=""/>
<attribute name="specifiers"
           type="#IMPLIED"
           value="CDATA"
           default=""/>
<attribute name="name"
           type="#REQUIRED"
           value="CDATA"
           default=""/>
<attribute name="id"
           type="#IMPLIED"
           value="CDATA"
           default=""/>
<attribute name="xml:base"
           type="#IMPLIED"
           value="CDATA"
           default=""/>
</attlist>

<element name="postconditions"
         content-type="element">
<content-model-expanded>
  <sequence-group>
    <any/>
  </sequence-group>
</content-model-expanded>
<content-model>
  <sequence-group>
    <any/>
  </sequence-group>
</content-model>
<purpose>Conditions that must hold after the function returns</purpose>
</element>

<attlist name="postconditions">
<attdecl> %boost.common.attrib;</attdecl>
<attribute name="last-revision"
           type="#IMPLIED"
           value="CDATA"
           default=""/>
<attribute name="id"
           type="#IMPLIED"
           value="CDATA"
           default=""/>
<attribute name="xml:base"
           type="#IMPLIED"
           value="CDATA"
           default=""/>
</attlist>

<element name="compile-test"
         content-type="element">
<content-model-expanded>
  <sequence-group>
    <element-name name="source" occurrence="*"/>
    <element-name name="lib" occurrence="*"/>
    <element-name name="requirement" occurrence="*"/>
    <element-name name="purpose"/>
    <element-name name="if-fails" occurrence="?"/>
  </sequence-group>
</content-model-expanded>
<content-model>
  <sequence-group>
    <parament-name name="boost.testsuite.test.content"/>
  </sequence-group>
</content-model>
<purpose>A testcase that should compile correctly</purpose>
</element>

<attlist name="compile-test">
<attdecl>
     filename CDATA #REQUIRED
     name     CDATA #IMPLIED</attdecl>
<attribute name="filename"
           type="#REQUIRED"
           value="CDATA"
           default=""/>
<attribute name="name"
           type="#IMPLIED"
           value="CDATA"
           default=""/>
</attlist>

<element name="method"
         content-type="element">
<content-model-expanded>
  <sequence-group>
    <element-name name="template" occurrence="?"/>
    <element-name name="type"/>
    <element-name name="parameter" occurrence="*"/>
    <element-name name="purpose" occurrence="?"/>
    <element-name name="description" occurrence="?"/>
    <element-name name="requires" occurrence="?"/>
    <element-name name="effects" occurrence="?"/>
    <element-name name="postconditions" occurrence="?"/>
    <element-name name="returns" occurrence="?"/>
    <element-name name="throws" occurrence="?"/>
    <element-name name="complexity" occurrence="?"/>
    <element-name name="notes" occurrence="?"/>
    <element-name name="rationale" occurrence="?"/>
  </sequence-group>
</content-model-expanded>
<content-model>
  <sequence-group>
    <element-name name="template" occurrence="?"/>
    <element-name name="type"/>
    <element-name name="parameter" occurrence="*"/>
    <parament-name name="boost.function.semantics"/>
  </sequence-group>
</content-model>
<purpose>Declares a method, i.e., a member function</purpose>
<description>
  <para>General documentation on functions in BoostBook is provided in
  the <link
  linkend="boostbook.dtd.function"><sgmltag>function</sgmltag></link>
  element documentation.</para>
</description>
</element>

<attlist name="method">
<attdecl>
    name         CDATA  #REQUIRED
    cv           CDATA  #IMPLIED
    specifiers   CDATA  #IMPLIED
    %boost.common.attrib;</attdecl>
<attribute name="last-revision"
           type="#IMPLIED"
           value="CDATA"
           default=""/>
<attribute name="cv"
           type="#IMPLIED"
           value="CDATA"
           default=""/>
<attribute name="specifiers"
           type="#IMPLIED"
           value="CDATA"
           default=""/>
<attribute name="name"
           type="#REQUIRED"
           value="CDATA"
           default=""/>
<attribute name="id"
           type="#IMPLIED"
           value="CDATA"
           default=""/>
<attribute name="xml:base"
           type="#IMPLIED"
           value="CDATA"
           default=""/>
</attlist>

<element name="snippet"
         content-type="element">
<content-model-expanded>
  <empty/>
</content-model-expanded>
<content-model>
  <empty/>
</content-model>
<purpose>Pulls in a code snippet from a <sgmltag>programlisting</sgmltag> element</purpose>
</element>

<attlist name="snippet">
<attdecl>
     name CDATA #REQUIRED</attdecl>
<attribute name="name"
           type="#REQUIRED"
           value="CDATA"
           default="">
  <purpose>The name of the <sgmltag>programlisting</sgmltag> element to insert</purpose>
</attribute>
</attlist>

<element name="constructor"
         content-type="element">
<content-model-expanded>
  <sequence-group>
    <element-name name="template" occurrence="?"/>
    <element-name name="parameter" occurrence="*"/>
    <element-name name="purpose" occurrence="?"/>
    <element-name name="description" occurrence="?"/>
    <element-name name="requires" occurrence="?"/>
    <element-name name="effects" occurrence="?"/>
    <element-name name="postconditions" occurrence="?"/>
    <element-name name="returns" occurrence="?"/>
    <element-name name="throws" occurrence="?"/>
    <element-name name="complexity" occurrence="?"/>
    <element-name name="notes" occurrence="?"/>
    <element-name name="rationale" occurrence="?"/>
  </sequence-group>
</content-model-expanded>
<content-model>
  <sequence-group>
    <element-name name="template" occurrence="?"/>
    <element-name name="parameter" occurrence="*"/>
    <parament-name name="boost.function.semantics"/>
  </sequence-group>
</content-model>
<purpose>Declares a constructor of the enclosing class</purpose>
<description>
  <para>General documentation on functions in BoostBook is provided in
  the <link
  linkend="boostbook.dtd.function"><sgmltag>function</sgmltag></link>
  element documentation.</para>
</description>
</element>

<attlist name="constructor">
<attdecl>
    specifiers   CDATA  #IMPLIED
    %boost.common.attrib;</attdecl>
<attribute name="last-revision"
           type="#IMPLIED"
           value="CDATA"
           default=""/>
<attribute name="specifiers"
           type="#IMPLIED"
           value="CDATA"
           default=""/>
<attribute name="id"
           type="#IMPLIED"
           value="CDATA"
           default=""/>
<attribute name="xml:base"
           type="#IMPLIED"
           value="CDATA"
           default=""/>
</attlist>

<element name="namespace"
         content-type="element">
<content-model-expanded>
  <or-group occurrence="*">
    <element-name name="class"/>
    <element-name name="class-specialization"/>
    <element-name name="struct"/>
    <element-name name="struct-specialization"/>
    <element-name name="union"/>
    <element-name name="union-specialization"/>
    <element-name name="typedef"/>
    <element-name name="enum"/>
    <element-name name="free-function-group"/>
    <element-name name="function"/>
    <element-name name="overloaded-function"/>
    <element-name name="namespace"/>
  </or-group>
</content-model-expanded>
<content-model>
  <sequence-group occurrence="*">
    <parament-name name="boost.namespace.mix"/>
  </sequence-group>
</content-model>
<purpose>Declares a namespace</purpose>

<description>
  <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>
</description>
</element>

<attlist name="namespace">
<attdecl>
    name  CDATA  #REQUIRED
    %boost.common.attrib;</attdecl>
<attribute name="last-revision"
           type="#IMPLIED"
           value="CDATA"
           default=""/>
<attribute name="name"
           type="#REQUIRED"
           value="CDATA"
           default=""/>
<attribute name="id"
           type="#IMPLIED"
           value="CDATA"
           default=""/>
<attribute name="xml:base"
           type="#IMPLIED"
           value="CDATA"
           default=""/>
</attlist>

<element name="if-fails"
         content-type="element">
<content-model-expanded>
  <sequence-group>
    <any/>
  </sequence-group>
</content-model-expanded>
<content-model>
  <sequence-group>
    <any/>
  </sequence-group>
</content-model>
<purpose>What it means when a testcase fails</purpose>
<description>
  <para>
    Describes to the user the effect a certain failing testcase will
    have on the usefulness of a library. This field is useful in cases
    where a failed testcase does not mean that the library won't be
    useful, but may mean that certain library features will not be
    available.
  </para>
</description>
</element>

<element name="free-function-group"
         content-type="element">
<content-model-expanded>
  <or-group occurrence="*">
    <element-name name="function"/>
    <element-name name="overloaded-function"/>
  </or-group>
</content-model-expanded>
<content-model>
  <or-group occurrence="*">
    <element-name name="function"/>
    <element-name name="overloaded-function"/>
  </or-group>
</content-model>
<purpose>A set of functions that are grouped together under one name</purpose>
</element>

<attlist name="free-function-group">