Jamfile.v2: Generate tribool documentation

tribool.boostbook:
	- tribool documentation, now (obviously) in BoostBook


[SVN r1584]

doc/Jamfile.v2

@@ -0,0 +1,6 @@
+project boost-sandbox/utility/doc ;
+import boostbook ;
+import doxygen ;
+
+doxygen reference : ../../../boost/tribool.hpp ;
+boostbook tribool : tribool.boostbook ;

doc/tribool.boostbook

@@ -0,0 +1,153 @@
+<?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="Tribool" dirname="utility/tribool" id="tribool"
+         last-revision="$Date$" xmlns:xi="http://www.w3.org/2001/XInclude">
+  <libraryinfo>
+    <author>
+      <firstname>Douglas</firstname>
+      <surname>Gregor</surname>
+      <email>gregod@cs.rpi.edu</email>
+    </author>
+
+    <copyright>
+      <year>2002</year>
+      <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>
+
+    <librarypurpose>Three-state boolean type</librarypurpose>
+    <librarycategory name="category:misc"/>
+  </libraryinfo>
+
+  <section id="tribool.introduction">
+    <title>Introduction</title>
+
+    <para>The 3-state boolean library contains a single class,
+    <code><classname>boost::tribool</classname></code>, along with
+    support functions and operator overloads that implement 3-state
+    boolean logic. </para>
+  </section>
+
+  <section id="tribool.tutorial">
+    <title>Tutorial</title>
+
+    <using-namespace name="boost"/>
+
+    <para> The <code><classname>tribool</classname></code> class acts
+    like the built-in <code>bool</code> type, but for 3-state boolean
+    logic. The three states are <code>true</code>, <code>false</code>,
+    and <code><functionname>indeterminate</functionname></code>, where
+    the first two states are equivalent to those of the C++
+    <code>bool</code> type and the last state represents an unknown
+    boolean value (that may be <code>true</code> or
+    <code>false</code>, we don't know).</para>
+
+    <para> The <code><classname>tribool</classname></code> class
+    supports conversion from <code>bool</code> values and literals
+    along with its own
+    <code><functionname>indeterminate</functionname></code>
+    keyword:</para>
+
+    <programlisting><classname>tribool</classname> b(true);
+b = false;
+b = <functionname>indeterminate</functionname>;
+<classname>tribool</classname> b2(b);</programlisting>
+
+    <para> <code><classname>tribool</classname></code> supports
+    conversions to <code>bool</code> for use in conditional
+    statements. The conversion to <code>bool</code> will be
+    <code>true</code> when the value of the
+    <code><classname>tribool</classname></code> is always true, and
+    <code>false</code> otherwise.</para>
+
+<programlisting><classname>tribool</classname> b = some_operation();
+if (b) {
+  // b is true
+}
+else if (!b) {
+  // b is false
+}
+else {
+  // b is indeterminate
+}</programlisting>
+
+  <para> <code><classname>tribool</classname></code> supports the
+  3-state logic operators <code>!</code> (negation),
+  <code>&amp;&amp;</code> (AND), and <code>||</code> (OR), with
+  <code>bool</code> and <code><classname>tribool</classname></code>
+  values. For instance:</para>
+
+  <programlisting><classname>tribool</classname> x = some_op();
+<classname>tribool</classname> y = some_other_op();
+if (x &amp;&amp; y) {
+  // both x and y are true
+}
+else if (!(x &amp;&amp; y)) {
+  // either x or y is false
+}
+else {
+  // neither x nor y is false, but we don't know that both are true
+
+  if (x || y) {
+    // either x or y is true, or both
+  }
+}</programlisting>
+
+  <para> Similarly, <code><classname>tribool</classname></code>
+  supports 3-state equality comparisons via the operators
+  <code>==</code> and <code>!=</code>. These operators differ from
+  "normal" equality operators in C++ because they return a
+  <code><classname>tribool</classname></code>, because potentially we
+  might not know the result of a comparison (try to compare
+  <code>true</code> and
+  <code><functionname>indeterminate</functionname></code>). For
+  example:</para>
+
+<programlisting><classname>tribool</classname> x(true);
+<classname>tribool</classname> y(<functionname>indeterminate</functionname>);
+
+assert(x == x); // okay, x == x returns true
+assert(!(y == y)); // okay, because y == y is <functionname>indeterminate</functionname> 
+assert(x == true); // okay, can compare <classname>tribool</classname>s and bools</programlisting>
+
+  <para> The <code><functionname>indeterminate</functionname></code> keyword (representing the
+  <functionname>indeterminate</functionname>&nbsp;<code><classname>tribool</classname></code> value)
+  doubles as a function to check if the value of a
+  <code><classname>tribool</classname></code> is indeterminate,
+  e.g.,</para>
+ 
+  <programlisting><classname>tribool</classname> x = try_to_do_something_tricky();
+if (<functionname>indeterminate</functionname>(x)) {
+  // value of x is indeterminate
+}
+else {
+  // report success or failure of x
+}</programlisting>
+
+  <para> Users may introduce additional keywords for the indeterminate
+  value in addition to the implementation-supplied
+  <code><functionname>indeterminate</functionname></code> using the
+  <code><macroname>BOOST_TRIBOOL_THIRD_STATE</macroname></code>
+  macro. For instance, the following macro instantiation (at the
+  global scope) will introduce the keyword <code>maybe</code> as a
+  synonym for <code><functionname>indeterminate</functionname></code>
+  (also residing in the <code>boost</code> namespace):</para>
+  <programlisting><macroname>BOOST_TRIBOOL_THIRD_STATE</macroname>(maybe)</programlisting>
+  </section>
+
+  <xi:include href="reference.boostbook"/>
+</library>