[Boost-commit] svn:boost r7346

From: johnmaddock_at_[hidden]
Date: 2007-07-03 04:47:26

Author: johnmaddock
Date: 2007-07-03 04:47:25 EDT (Tue, 03 Jul 2007)
New Revision: 7346
URL: http://svn.boost.org/trac/boost/changeset/7346

Log:
Added sample Remez article

Added:
   sandbox/boost_docs/trunk/doc/doc_test/doc/html/images/remez-2.png   (contents, props changed)
   sandbox/boost_docs/trunk/doc/doc_test/doc/html/images/remez-3.png   (contents, props changed)
   sandbox/boost_docs/trunk/doc/doc_test/doc/html/images/remez-4.png   (contents, props changed)
   sandbox/boost_docs/trunk/doc/doc_test/doc/html/images/remez-5.png   (contents, props changed)
   sandbox/boost_docs/trunk/doc/doc_test/doc/remez.qbk
Text files modified: 
   sandbox/boost_docs/trunk/doc/doc_test/doc/test.qbk |  1185 ++++++++++++++++++++------------------- 
   1 files changed, 594 insertions(+), 591 deletions(-)

Added: sandbox/boost_docs/trunk/doc/doc_test/doc/html/images/remez-2.png
==============================================================================
Binary file. No diff available.

Added: sandbox/boost_docs/trunk/doc/doc_test/doc/html/images/remez-3.png
==============================================================================
Binary file. No diff available.

Added: sandbox/boost_docs/trunk/doc/doc_test/doc/html/images/remez-4.png
==============================================================================
Binary file. No diff available.

Added: sandbox/boost_docs/trunk/doc/doc_test/doc/html/images/remez-5.png
==============================================================================
Binary file. No diff available.

Added: sandbox/boost_docs/trunk/doc/doc_test/doc/remez.qbk
==============================================================================
--- (empty file)
+++ sandbox/boost_docs/trunk/doc/doc_test/doc/remez.qbk	2007-07-03 04:47:25 EDT (Tue, 03 Jul 2007)
@@ -0,0 +1,372 @@
+[section:remez Sample Article (The Remez Method)]
+
+The [@http://en.wikipedia.org/wiki/Remez_algorithm Remez algorithm]
+is a methodology for locating the minimax rational approximation
+to a function.  This short article gives a brief overview of the method, but
+it should not be regarded as a thorough theoretical treatment, for that you
+should consult your favorite textbook.
+
+Imagine that you want to approximate some function f(x) by way of a rational
+function R(x), where R(x) may be either a polynomial P(x) or a ratio of two
+polynomials P(x)/Q(x) (a rational function).  Initially we'll concentrate on the 
+polynomial case, as it's by far the easier to deal with, later we'll extend 
+to the full rational function case.  
+
+We want to find the "best" rational approximation, where
+"best" is defined to be the approximation that has the least deviation
+from f(x).  We can measure the deviation by way of an error function:
+
+E[sub abs](x) = f(x) - R(x)
+
+which is expressed in terms of absolute error, but we can equally use
+relative error:
+
+E[sub rel](x) = (f(x) - R(x)) / |f(x)|
+
+And indeed in general we can scale the error function in any way we want, it
+makes no difference to the maths, although the two forms above cover almost
+every practical case that you're likely to encounter.
+
+The minimax rational function R(x) is then defined to be the function that
+yields the smallest maximal value of the error function.  Chebyshev showed
+that there is a unique minimax solution for R(x) that has the following
+properties:
+
+* If R(x) is a polynomial of degree N, then there are N+2 unknowns:
+the N+1 coefficients of the polynomial, and maximal value of the error
+function.
+* The error function has N+1 roots, and N+2 extrema (minima and maxima).
+* The extrema alternate in sign, and all have the same magnitude.
+
+That means that if we know the location of the extrema of the error function
+then we can write N+2 simultaneous equations:
+
+R(x[sub i]) + (-1)[super i]E = f(x[sub i])
+
+where E is the maximal error term, and x[sub i] are the abscissa values of the
+N+2 extrema of the error function.  It is then trivial to solve the simultaneous
+equations to obtain the polynomial coefficients and the error term.
+
+['Unfortunately we don't know where the extrema of the error function are located!]
+
+[h4 The Remez Method]
+
+The Remez method is an iterative technique which, given a broad range of
+assumptions, will converge on the extrema of the error function, and therefore
+the minimax solution.
+
+In the following discussion we'll use a concrete example to illustrate
+the Remez method: an approximation to the function e[super x][space] over
+the range \[-1, 1\].
+
+Before we can begin the Remez method, we must obtain an initial value
+for the location of the extrema of the error function.  We could "guess"
+these, but a much closer first approximation can be obtained by first  
+constructing an interpolated polynomial approximation to f(x).
+
+In order to obtain the N+1 coefficients of the interpolated polynomial
+we need N+1 points (x[sub 0]...x[sub N]): with our interpolated form 
+passing through each of those points
+that yields N+1 simultaneous equations:
+
+f(x[sub i]) = P(x[sub i]) = c[sub 0] + c[sub 1]x[sub i] ... + c[sub N]x[sub i][super N]
+
+Which can be solved for the coefficients c[sub 0]...c[sub N] in P(x).
+
+Obviously this is not a minimax solution, indeed our only guarantee is that f(x) and 
+P(x) touch at N+1 locations, away from those points the error may be arbitrarily
+large.  However, we would clearly like this initial approximation to be as close to
+f(x) as possible, and it turns out that using the zeros of an orthogonal polynomial
+as the initial interpolation points is a good choice.  In our example we'll use the 
+zeros of a Chebyshev polynomial as these are particularly easy to calculate, 
+interpolating for a polynomial of degree 4, and measuring /relative error/
+we get the following error function:
+
+[$images/remez-2.png]
+
+Which has a peak relative error of 1.2x10[super -3].
+
+While this is a pretty good approximation already, judging by the 
+shape of the error function we can clearly do better.  Before starting
+on the Remez method propper, we have one more step to perform: locate
+all the extrema of the error function, and store
+these locations as our initial ['Chebyshev control points].
+
+[note
+In the simple case of a polynomial approximation, by interpolating through
+the roots of a Chebyshev polynomial we have in fact created a ['Chebyshev
+approximation] to the function: in terms of /absolute error/
+this is the best a priori choice for the interpolated form we can
+achieve, and typically is very close to the minimax solution.
+
+However, if we want to optimise for /relative error/, or if the approximation
+is a rational function, then the initial Chebyshev solution can be quite far
+from the ideal minimax solution.  
+
+A more technical discussion of the theory involved can be found in this
+[@http://math.fullerton.edu/mathews/n2003/ChebyshevPolyMod.html online course].]
+
+[h4 Remez Step 1]
+
+The first step in the Remez method, given our current set of
+N+2 Chebyshev control points x[sub i], is to solve the N+2 simultaneous
+equations:
+
+P(x[sub i]) + (-1)[super i]E = f(x[sub i])
+
+To obtain the error term E, and the coefficients of the polynomial P(x).
+
+This gives us a new approximation to f(x) that has the same error /E/ at
+each of the control points, and whose error function ['alternates in sign]
+at the control points.  This is still not necessarily the minimax 
+solution though: since the control points may not be at the extrema of the error
+function.  After this first step here's what our approximation's error
+function looks like:
+
+[$images/remez-3.png]
+
+Clearly this is still not the minimax solution since the control points
+are not located at the extrema, but the maximum relative error has now
+dropped to 5.6x10[super -4].
+
+[h4 Remez Step 2]
+
+The second step is to locate the extrema of the new approximation, which we do 
+in two stages:  first, since the error function changes sign at each
+control point, we must have N+1 roots of the error function located between
+each pair of N+2 control points.  Once these roots are found by standard root finding 
+techniques, we know that N extrema are bracketed between each pair of
+roots, plus two more between the endpoints of the range and the first and last roots.
+The N+2 extrema can then be found using standard function minimisation techniques.
+
+We now have a choice: multi-point exchange, or single point exchange.
+
+In single point exchange, we move the control point nearest to the largest extrema to
+the absissa value of the extrema.
+
+In multi-point exchange we swap all the current control points, for the locations
+of the extrema.
+
+In our example we perform multi-point exchange.
+
+[h4 Iteration]
+
+The Remez method then performs steps 1 and 2 above iteratively until the control
+points are located at the extrema of the error function: this is then
+the minimax solution.
+
+For our current example, two more iterations converges on a minimax
+solution with a peak relative error of
+5x10[super -4] and an error function that looks like:
+
+[$images/remez-4.png]
+
+[h4 Rational Approximations]
+
+If we wish to extend the Remez method to a rational approximation of the form
+
+f(x) = R(x) = P(x) / Q(x)
+
+where P(x) and Q(x) are polynomials, then we proceed as before, except that now
+we have N+M+2 unknowns if P(x) is of order N and Q(x) is of order M.  This assumes
+that Q(x) is normalised so that it's leading coefficient is 1, giving
+N+M+1 polynomial coefficients in total, plus the error term E.
+
+The simultaneous equations to be solved are now:
+
+P(x[sub i]) / Q(x[sub i]) + (-1)[super i]E = f(x[sub i])
+
+Evaluated at the N+M+2 control points x[sub i].
+
+Unfortunately these equations are non-linear in the error term E: we can only
+solve them if we know E, and yet E is one of the unknowns!
+
+The method usually adopted to solve these equations is an iterative one: we guess the
+value of E, solve the equations to obtain a new value for E (as well as the polynomial
+coefficients), then use the new value of E as the next guess.  The method is
+repeated until E converges on a stable value.
+
+These complications extend the running time required for the development
+of rational approximations quite considerably. It is often desirable
+to obtain a rational rather than polynomial approximation none the less:
+rational approximations will often match more difficult to approximate
+functions, to greater accuracy, and with greater efficiency, than their
+polynomial alternatives.  For example, if we takes our previous example
+of an approximation to e[super x], we obtained 5x10[super -4] accuracy
+with an order 4 polynomial.  If we move two of the unknowns into the denominator
+to give a pair of order 2 polynomials, and re-minimise, then the peak relative error drops
+to 8.7x10[super -5].  That's a 5 fold increase in accuracy, for the same number 
+of terms overall.
+
+[h4 Practical Considerations]
+
+Most treatises on approximation theory stop at this point.  However, from
+a practical point of view, most of the work involves finding the right
+approximating form, and then persuading the Remez method to converge
+on a solution.
+
+So far we have used a direct approximation:
+
+f(x) = R(x)
+
+But this will converge to a useful approximation only if f(x) is smooth.  In
+addition round-off errors when evaluating the rational form mean that this
+will never get closer than within a few epsilon of machine precision.  
+Therefore this form of direct approximation is often reserved for situations
+where we want efficiency, rather than accuracy.
+
+The first step in improving the situation is generally to split f(x) into
+a dominant part that we can compute accurately by another method, and a 
+slowly changing remainder which can be approximated by a rational approximation.
+We might be tempted to write:
+
+f(x) = g(x) + R(x)
+
+where g(x) is the dominant part of f(x), but if f(x)\/g(x) is approximately
+constant over the interval of interest then:
+
+f(x) = g(x)(c + R(x))
+
+Will yield a much better solution: here /c/ is a constant that is the approximate
+value of f(x)\/g(x) and R(x) is typically tiny compared to /c/.  In this situation
+if R(x) is optimised for absolute error, then as long as its error is small compared
+to the constant /c/, that error will effectively get wiped out when R(x) is added to
+/c/.
+
+The difficult part is obviously finding the right g(x) to extract from your
+function: often the asymptotic behaviour of the function will give a clue, so
+for example the function __erfc becomes proportional to 
+e[super -x[super 2]]\/x as x becomes large.  Therefore using:
+
+erfc(z) = (C + R(x)) e[super -x[super 2]]/x
+
+as the approximating form seems like an obvious thing to try, and does indeed
+yield a useful approximation.
+
+However, the difficulty then becomes one of converging the minimax solution.
+Unfortunately, it is known that for some functions the Remez method can lead
+to divergent behaviour, even when the initial starting approximation is quite good.
+Furthermore, it is not uncommon for the solution obtained in the first Remez step
+above to be a bad one: the equations to be solved are generally "stiff", often
+very close to being singular, and assuming a solution is found at all, round-off
+errors and a rapidly changing error function, can lead to a situation where the
+error function does not in fact change sign at each control point as required.
+If this occurs, it is fatal to the Remez method.  It is also possible to
+obtain solutions that are perfectly valid mathematically, but which are
+quite useless computationally: either because there is an unavoidable amount
+of roundoff error in the computation of the rational function, or because
+the denominator has one or more roots over the interval of the approximation.
+In the latter case while the approximation may have the correct limiting value at
+the roots, the approximation is nonetheless useless.
+
+Assuming that the approximation does not have any fatal errors, and that the only
+issue is converging adequately on the minimax solution, the aim is to
+get as close as possible to the minimax solution before beginning the Remez method.
+Using the zeros of a Chebyshev polynomial for the initial interpolation is a 
+good start, but may not be ideal when dealing with relative errors and\/or
+rational (rather than polynomial) approximations.  One approach is to skew
+the initial interpolation points to one end: for example if we raise the
+roots of the Chebyshev polynomial to a positive power greater than 1 
+then the roots will be skewed towards the middle of the \[-1,1\] interval, 
+while a positive power less than one
+will skew them towards either end.  More usefully, if we initially rescale the
+points over \[0,1\] and then raise to a positive power, we can skew them to the left 
+or right.  Returning to our example of e[super x][space] over \[-1,1\], the initial
+interpolated form was some way from the minimax solution:
+
+[$images/remez-2.png]
+
+However, if we first skew the interpolation points to the left (rescale them
+to \[0, 1\], raise to the power 1.3, and then rescale back to \[-1,1\]) we
+reduce the error from 1.3x10[super -3][space]to 6x10[super -4]:
+
+[$images/remez-5.png]
+
+It's clearly still not ideal, but it is only a few percent away from
+our desired minimax solution (5x10[super -4]).
+
+[h4 Remez Method Checklist]
+
+The following lists some of the things to check if the Remez method goes wrong, 
+it is by no means an exhaustive list, but is provided in the hopes that it will
+prove useful.
+
+* Is the function smooth enough?  Can it be better separated into
+a rapidly changing part, and an asymptotic part?
+* Does the function being approximated have any "blips" in it?  Check
+for problems as the function changes computation method, or
+if a root, or an infinity has been divided out.  The telltale
+sign is if there is a narrow region where the Remez method will
+not converge.
+* Check you have enough accuracy in your calculations: remember that
+the Remez method works on the difference between the approximation
+and the function being approximated: so you must have more digits of
+precision available than the precision of the approximation
+being constructed.  So for example at double precision, you
+shouldn't expect to be able to get better than a float precision
+approximation.
+* Try skewing the initial interpolated approximation to minimise the
+error before you begin the Remez steps.
+* If the approximation won't converge or is ill-conditioned from one starting
+location, try starting from a different location.
+* If a rational function won't converge, one can minimise a polynomial
+(which presents no problems), then rotate one term from the numerator to
+the denominator and minimise again.  In theory one can continue moving
+terms one at a time from numerator to denominator, and then re-minimising, 
+retaining the last set of control points at each stage.
+* Try using a smaller interval.  It may also be possible to optimise over
+one (small) interval, rescale the control points over a larger interval,
+and then re-minimise.
+* Keep absissa values small: use a change of variable to keep the abscissa
+over, say \[0, b\], for some smallish value /b/.
+
+[h4 References]
+
+The original references for the Remez Method and it's extension
+to rational functions are unfortunately in Russian:
+
+Remez, E.Ya., ['Fundamentals of numerical methods for Chebyshev approximations], 
+"Naukova Dumka", Kiev, 1969.
+
+Remez, E.Ya., Gavrilyuk, V.T., ['Computer development of certain approaches 
+to the approximate construction of solutions of Chebyshev problems 
+nonlinearly depending on parameters], Ukr. Mat. Zh. 12 (1960), 324-338.
+
+Gavrilyuk, V.T., ['Generalization of the first polynomial algorithm of 
+E.Ya.Remez for the problem of constructing rational-fractional 
+Chebyshev approximations], Ukr. Mat. Zh. 16 (1961), 575-585.
+
+Some English language sources include:
+
+Fraser, W., Hart, J.F., ['On the computation of rational approximations 
+to continuous functions], Comm. of the ACM 5 (1962), 401-403, 414.
+
+Ralston, A., ['Rational Chebyshev approximation by Remes' algorithms], 
+Numer.Math. 7 (1965), no. 4, 322-330.
+
+A. Ralston, ['Rational Chebyshev approximation, Mathematical 
+Methods for Digital Computers v. 2] (Ralston A., Wilf H., eds.), 
+Wiley, New York, 1967, pp. 264-284.
+
+Hart, J.F. e.a., ['Computer approximations], Wiley, New York a.o., 1968.
+
+Cody, W.J., Fraser, W., Hart, J.F., ['Rational Chebyshev approximation 
+using linear equations], Numer.Math. 12 (1968), 242-251.
+
+Cody, W.J., ['A survey of practical rational and polynomial 
+approximation of functions], SIAM Review 12 (1970), no. 3, 400-423.
+
+Barrar, R.B., Loeb, H.J., ['On the Remez algorithm for non-linear 
+families], Numer.Math. 15 (1970), 382-391.
+
+Dunham, Ch.B., ['Convergence of the Fraser-Hart algorithm for rational 
+Chebyshev approximation], Math. Comp. 29 (1975), no. 132, 1078-1082.
+
+G. L. Litvinov, ['Approximate construction of rational
+approximations and the effect of error autocorrection],
+Russian Journal of Mathematical Physics, vol.1, No. 3, 1994.
+
+[endsect][/section:remez The Remez Method]
+
+
+

Modified: sandbox/boost_docs/trunk/doc/doc_test/doc/test.qbk
==============================================================================
--- sandbox/boost_docs/trunk/doc/doc_test/doc/test.qbk	(original)
+++ sandbox/boost_docs/trunk/doc/doc_test/doc/test.qbk	2007-07-03 04:47:25 EDT (Tue, 03 Jul 2007)
@@ -1,591 +1,594 @@
-[article Document To Test Formatting
-    [quickbook 1.4]
-    [copyright 2007 John Maddock, Joel de Guzman, Eric Niebler and Matias Capeletto]
-    [purpose Test Formatting Document]
-    [license
-        Distributed under the Boost Software License, Version 1.0.
-        (See accompanying file LICENSE_1_0.txt or copy at
-        [@http://www.boost.org/LICENSE_1_0.txt])
-    ]
-    [authors [Maddock, John], [de Guzman, Joel], [Niebler, Eric], [Capeletto, Matias] ]
-    [category math]
-    [/last-revision $Date: 2007-05-07 10:21:52 +0100 (Mon, 07 May 2007) $]
-]
-
-[include HTML4_symbols.qbk]
-
-[/ Some composite templates]
-[template super[x]'''<superscript>'''[x]'''</superscript>''']
-[template sub[x]'''<subscript>'''[x]'''</subscript>''']
-[template floor[x]'''&#x230A;'''[x]'''&#x230B;''']
-[template floorlr[x][lfloor][x][rfloor]]
-[template ceil[x] '''&#x2308;'''[x]'''&#x2309;''']
-
-[section Introduction]
-
-This document is purely a test case to test out HTML and PDF generation and style.
-
-This is some body text.
-
-    int main()
-    {
-        double d = 2.345;
-        return d;
-    }
-
-We can count in Greek too: [alpha], [beta], [gamma].
-
-Try some superscrips and subscripts: x[super 2], x[sub i][super 3], [alpha][super 2], 
-[beta][super [alpha]], [floor x], [floor [alpha]], [ceil a].
-
-[endsect]
-
-[section Code Blocks]
-
-[section Embedded code]
-
-These should be syntax highlighted:
-
-   #include <iostream>
-
-   int main()
-   {
-       // Sample code
-       std::cout << "Hello, World\n";
-       return 0;
-   }
-
-[endsect]
-
-[section Imported code and callouts]
-
-[import stub.cpp]
-
-Here's some code with left-placed callouts:
-
-[class_]
-
-And again with callouts placed exactly where we put them:
-
-[foo_bar]
-
-[endsect]
-
-[section Larger example]
-
-Now let's include a larger example, this may span several pages
-and should not be chopped off half way through... some FO processors
-get this wrong!
-
-   namespace boost{
-
-   template <class BidirectionalIterator>
-   class sub_match;
-
-   typedef sub_match<const char*>                    csub_match;
-   typedef sub_match<const wchar_t*>                 wcsub_match;
-   typedef sub_match<std::string::const_iterator>    ssub_match;
-   typedef sub_match<std::wstring::const_iterator>   wssub_match;
-
-   template <class BidirectionalIterator>
-   class sub_match : public std::pair<BidirectionalIterator, BidirectionalIterator>
-   {
-   public:
-      typedef typename iterator_traits<BidirectionalIterator>::value_type value_type;
-      typedef typename iterator_traits<BidirectionalIterator>::difference_type   difference_type;
-      typedef          BidirectionalIterator                                    iterator;
-
-      bool  matched;
-
-      difference_type length()const;
-      operator basic_string<value_type>()const;
-      basic_string<value_type> str()const;
-
-      int compare(const sub_match& s)const;
-      int compare(const basic_string<value_type>& s)const;
-      int compare(const value_type* s)const;
-   #ifdef BOOST_REGEX_MATCH_EXTRA
-      typedef implementation-private capture_sequence_type;
-      const capture_sequence_type& captures()const;
-   #endif
-   };
-   //
-   // comparisons to another sub_match:
-   //
-   template <class BidirectionalIterator>
-   bool operator == (const sub_match<BidirectionalIterator>& lhs,
-                     const sub_match<BidirectionalIterator>& rhs);
-   template <class BidirectionalIterator>
-   bool operator != (const sub_match<BidirectionalIterator>& lhs,
-                     const sub_match<BidirectionalIterator>& rhs);
-   template <class BidirectionalIterator>
-   bool operator < (const sub_match<BidirectionalIterator>& lhs,
-                  const sub_match<BidirectionalIterator>& rhs);
-   template <class BidirectionalIterator>
-   bool operator <= (const sub_match<BidirectionalIterator>& lhs,
-                     const sub_match<BidirectionalIterator>& rhs);
-   template <class BidirectionalIterator>
-   bool operator >= (const sub_match<BidirectionalIterator>& lhs,
-                     const sub_match<BidirectionalIterator>& rhs);
-   template <class BidirectionalIterator>
-   bool operator > (const sub_match<BidirectionalIterator>& lhs,
-                  const sub_match<BidirectionalIterator>& rhs);
-
-
-   //
-   // comparisons to a basic_string:
-   //
-   template <class BidirectionalIterator, class traits, class Allocator> 
-   bool operator == (const std::basic_string<iterator_traits<BidirectionalIterator>::value_type,
-                                             traits, 
-                                             Allocator>& lhs,
-                     const sub_match<BidirectionalIterator>& rhs);
-   template <class BidirectionalIterator, class traits, class Allocator> 
-   bool operator != (const std::basic_string<iterator_traits<BidirectionalIterator>::value_type,
-                                             traits, 
-                                             Allocator>& lhs,
-                     const sub_match<BidirectionalIterator>& rhs);
-   template <class BidirectionalIterator, class traits, class Allocator> 
-   bool operator < (const std::basic_string<iterator_traits<BidirectionalIterator>::value_type,
-                                             traits, 
-                                             Allocator>& lhs,
-                     const sub_match<BidirectionalIterator>& rhs);
-   template <class BidirectionalIterator, class traits, class Allocator> 
-   bool operator > (const std::basic_string<iterator_traits<BidirectionalIterator>::value_type,
-                                             traits, 
-                                             Allocator>& lhs,
-                     const sub_match<BidirectionalIterator>& rhs);
-   template <class BidirectionalIterator, class traits, class Allocator> 
-   bool operator >= (const std::basic_string<iterator_traits<BidirectionalIterator>::value_type,
-                                             traits, 
-                                             Allocator>& lhs,
-                     const sub_match<BidirectionalIterator>& rhs);
-   template <class BidirectionalIterator, class traits, class Allocator> 
-   bool operator <= (const std::basic_string<iterator_traits<BidirectionalIterator>::value_type,
-                                             traits, 
-                                             Allocator>& lhs,
-                     const sub_match<BidirectionalIterator>& rhs);
-
-   template <class BidirectionalIterator, class traits, class Allocator> 
-   bool operator == (const sub_match<BidirectionalIterator>& lhs,
-                     const std::basic_string<iterator_traits<BidirectionalIterator>::value_type, 
-                                             traits, 
-                                             Allocator>& rhs);
-   template <class BidirectionalIterator, class traits, class Allocator> 
-   bool operator != (const sub_match<BidirectionalIterator>& lhs,
-                     const std::basic_string<iterator_traits<BidirectionalIterator>::value_type, 
-                                             traits, 
-                                             Allocator>& rhs);
-   template <class BidirectionalIterator, class traits, class Allocator> 
-   bool operator < (const sub_match<BidirectionalIterator>& lhs,
-                  const std::basic_string<iterator_traits<BidirectionalIterator>::value_type, 
-                                          traits, 
-                                          Allocator>& rhs);
-   template <class BidirectionalIterator, class traits, class Allocator> 
-   bool operator > (const sub_match<BidirectionalIterator>& lhs,
-                  const std::basic_string<iterator_traits<BidirectionalIterator>::value_type, 
-                                          traits, 
-                                          Allocator>& rhs);
-   template <class BidirectionalIterator, class traits, class Allocator> 
-   bool operator >= (const sub_match<BidirectionalIterator>& lhs,
-                     const std::basic_string<iterator_traits<BidirectionalIterator>::value_type, 
-                                          traits, 
-                                          Allocator>& rhs);
-   template <class BidirectionalIterator, class traits, class Allocator> 
-   bool operator <= (const sub_match<BidirectionalIterator>& lhs,
-                     const std::basic_string<iterator_traits<BidirectionalIterator>::value_type, 
-                                             traits, 
-                                             Allocator>& rhs);
-
-   //
-   // comparisons to a pointer to a character array:
-   //
-   template <class BidirectionalIterator> 
-   bool operator == (typename iterator_traits<BidirectionalIterator>::value_type const* lhs,
-                     const sub_match<BidirectionalIterator>& rhs); 
-   template <class BidirectionalIterator> 
-   bool operator != (typename iterator_traits<BidirectionalIterator>::value_type const* lhs,
-                     const sub_match<BidirectionalIterator>& rhs); 
-   template <class BidirectionalIterator> 
-   bool operator < (typename iterator_traits<BidirectionalIterator>::value_type const* lhs,
-                  const sub_match<BidirectionalIterator>& rhs); 
-   template <class BidirectionalIterator> 
-   bool operator > (typename iterator_traits<BidirectionalIterator>::value_type const* lhs,
-                  const sub_match<BidirectionalIterator>& rhs); 
-   template <class BidirectionalIterator> 
-   bool operator >= (typename iterator_traits<BidirectionalIterator>::value_type const* lhs,
-                     const sub_match<BidirectionalIterator>& rhs); 
-   template <class BidirectionalIterator> 
-   bool operator <= (typename iterator_traits<BidirectionalIterator>::value_type const* lhs,
-                     const sub_match<BidirectionalIterator>& rhs); 
-
-   template <class BidirectionalIterator> 
-   bool operator == (const sub_match<BidirectionalIterator>& lhs,
-                     typename iterator_traits<BidirectionalIterator>::value_type const* rhs); 
-   template <class BidirectionalIterator> 
-   bool operator != (const sub_match<BidirectionalIterator>& lhs,
-                     typename iterator_traits<BidirectionalIterator>::value_type const* rhs); 
-   template <class BidirectionalIterator> 
-   bool operator < ]``(const sub_match<BidirectionalIterator>& lhs,
-                  typename iterator_traits<BidirectionalIterator>::value_type const* rhs); 
-   template <class BidirectionalIterator> 
-   bool operator > (const sub_match<BidirectionalIterator>& lhs,
-                  typename iterator_traits<BidirectionalIterator>::value_type const* rhs); 
-   template <class BidirectionalIterator> 
-   bool operator >= (const sub_match<BidirectionalIterator>& lhs,
-                     typename iterator_traits<BidirectionalIterator>::value_type const* rhs); 
-   template <class BidirectionalIterator> 
-   bool operator <= (const sub_match<BidirectionalIterator>& lhs,
-                     typename iterator_traits<BidirectionalIterator>::value_type const* rhs); 
-
-   //
-   // comparisons to a single character:
-   //
-   template <class BidirectionalIterator> 
-   bool operator == (typename iterator_traits<BidirectionalIterator>::value_type const& lhs,
-                     const sub_match<BidirectionalIterator>& rhs); 
-   template <class BidirectionalIterator> 
-   bool operator != (typename iterator_traits<BidirectionalIterator>::value_type const& lhs,
-                     const sub_match<BidirectionalIterator>& rhs); 
-   template <class BidirectionalIterator> 
-   bool operator < (typename iterator_traits<BidirectionalIterator>::value_type const& lhs,
-                  const sub_match<BidirectionalIterator>& rhs); 
-   template <class BidirectionalIterator> 
-   bool operator > (typename iterator_traits<BidirectionalIterator>::value_type const& lhs,
-                  const sub_match<BidirectionalIterator>& rhs); 
-   template <class BidirectionalIterator> 
-   bool operator >= (typename iterator_traits<BidirectionalIterator>::value_type const& lhs,
-                     const sub_match<BidirectionalIterator>& rhs); 
-   template <class BidirectionalIterator> 
-   bool operator <= (typename iterator_traits<BidirectionalIterator>::value_type const& lhs,
-                     const sub_match<BidirectionalIterator>& rhs); 
-
-   template <class BidirectionalIterator> 
-   bool operator == (const sub_match<BidirectionalIterator>& lhs,
-                     typename iterator_traits<BidirectionalIterator>::value_type const& rhs); 
-   template <class BidirectionalIterator> 
-   bool operator != (const sub_match<BidirectionalIterator>& lhs,
-                     typename iterator_traits<BidirectionalIterator>::value_type const& rhs); 
-   template <class BidirectionalIterator> 
-   bool operator < (const sub_match<BidirectionalIterator>& lhs,
-                  typename iterator_traits<BidirectionalIterator>::value_type const& rhs); 
-   template <class BidirectionalIterator> 
-   bool operator > (const sub_match<BidirectionalIterator>& lhs,
-                  typename iterator_traits<BidirectionalIterator>::value_type const& rhs); 
-   template <class BidirectionalIterator> 
-   bool operator >= (const sub_match<BidirectionalIterator>& lhs,
-                     typename iterator_traits<BidirectionalIterator>::value_type const& rhs); 
-   template <class BidirectionalIterator> 
-   bool operator <= (const sub_match<BidirectionalIterator>& lhs,
-                     typename iterator_traits<BidirectionalIterator>::value_type const& rhs); 
-   // 
-   // addition operators: 
-   //
-   template <class BidirectionalIterator, class traits, class Allocator> 
-   std::basic_string<typename iterator_traits<BidirectionalIterator>::value_type, traits, Allocator> 
-      operator + (const std::basic_string<typename iterator_traits<BidirectionalIterator>::value_type,
-                                          traits, 
-                                          Allocator>& s, 
-                  const sub_match<BidirectionalIterator>& m); 
-   template <class BidirectionalIterator, class traits, class Allocator> 
-   std::basic_string<typename iterator_traits<BidirectionalIterator>::value_type, traits, Allocator>
-      operator + (const sub_match<BidirectionalIterator>& m,
-                  const std::basic_string<typename iterator_traits<BidirectionalIterator>::value_type, 
-                                          traits, 
-                                          Allocator>& s); 
-   template <class BidirectionalIterator> 
-   std::basic_string<typename iterator_traits<BidirectionalIterator>::value_type> 
-      operator + (typename iterator_traits<BidirectionalIterator>::value_type const* s,
-                  const sub_match<BidirectionalIterator>& m); 
-   template <class BidirectionalIterator> 
-   std::basic_string<typename iterator_traits<BidirectionalIterator>::value_type> 
-      operator + (const sub_match<BidirectionalIterator>& m,
-                  typename iterator_traits<BidirectionalIterator>::value_type const * s);
-   template <class BidirectionalIterator> 
-   std::basic_string<typename iterator_traits<BidirectionalIterator>::value_type> 
-      operator + (typename iterator_traits<BidirectionalIterator>::value_type const& s,
-                  const sub_match<BidirectionalIterator>& m); 
-   template <class BidirectionalIterator> 
-   std::basic_string<typename iterator_traits<BidirectionalIterator>::value_type> 
-      operator + (const sub_match<BidirectionalIterator>& m,
-                  typename iterator_traits<BidirectionalIterator>::value_type const& s); 
-   template <class BidirectionalIterator> 
-   std::basic_string<typename iterator_traits<BidirectionalIterator>::value_type> 
-      operator + (const sub_match<BidirectionalIterator>& m1,
-                  const sub_match<BidirectionalIterator>& m2);
-
-   //
-   // stream inserter:
-   //
-   template <class charT, class traits, class BidirectionalIterator>
-   basic_ostream<charT, traits>&
-      operator << (basic_ostream<charT, traits>& os,
-                  const sub_match<BidirectionalIterator>& m);
-
-   } // namespace boost
-
-[endsect]
-
-[endsect]
-
-[section Basic Formatting]
-
-[section Font Styles]
-
-Here we go with some inline formatting: 
-['italic], [*bold], [_underline], [^teletype], [-strikethrough],
-we can combine styles as well: ['[*bold italic]], [_[^teletype with underline]].
-
-[endsect]
-
-[section Replaceable Text]
-
-Text that is intended to be user-replaceable is [~rendered like this].
-
-[endsect]
-
-[section Quotations]
-
-Here we go: ["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein
-
-Note the proper left and right quote marks. Also, while you can simply use ordinary quote marks like "quoted", our quotation, above, will generate correct DocBook quotations (e.g. <quote>quoted</quote>).
-
-Like all phrase elements, quotations may be nested. Example:
-
-["Here's the rule for bargains: ["Do other men, for they would do you.] That's
-the true business precept.]
-
-[endsect]
-
-[section Inline Code]
-
-This text has inlined code `int main() { return 0; }`  in it. 
-The code should be syntax highlighted.
-
-[endsect]
-
-[section Links]
-
-Try this: [@http://www.boost.org this is [*boost's] website....] it should
-be visible as a link.
-
-[endsect]
-
-[section Footnotes]
-
-Here's one [footnote A sample footnote].
-
-And here's another [footnote Another sample footnote].
-
-[endsect]
-
-[section Blockquote]
-
-Lets indent the next paragraph:
-
-[:Here we go!!!]
-
-[endsect]
-
-[section Headings]
-
-Now try rendering some heading styles:
-
-[h1 Heading 1]
-
-[h2 Heading 2]
-
-[h3 Heading 3]
-
-[h4 Heading 4]
-
-[h5 Heading 5]
-
-[h6 Heading 6]
-
-[endsect]
-
-[endsect]
-
-[section Blurbs]
-
-[section Preformatted text]
-
-Here's some sample program output:
-
-[pre
-'''F test for equal standard deviations
-____________________________________
-
-Sample 1:
-Number of Observations                                 =  240
-Sample Standard Deviation                              =  65.549
-
-Sample 2:
-Number of Observations                                 =  240
-Sample Standard Deviation                              =  61.854
-
-Test Statistic                                         =  1.123
-
-CDF of test statistic:                                 =  8.148e-001
-Upper Critical Value at alpha:                         =  1.238e+000
-Upper Critical Value at alpha/2:                       =  1.289e+000
-Lower Critical Value at alpha:                         =  8.080e-001
-Lower Critical Value at alpha/2:                       =  7.756e-001
-
-Results for Alternative Hypothesis and alpha           =  0.0500
-
-Alternative Hypothesis                                    Conclusion
-Standard deviations are unequal (two sided test)          REJECTED
-Standard deviation 1 is less than standard deviation 2    REJECTED
-Standard deviation 1 is greater than standard deviation 2 REJECTED'''
-]
-
-[endsect]
-
-[section Admonishments]
-
-There are four admonishments supported by Docbook XML:
-
-[note This is a note]
-
-[tip This is a tip]
-
-[important This is important]
-
-[caution This is a caution]
-
-[warning This is a warning
-
-They can contain more than one paragraph.
-]
-
-[endsect]
-
-[section Blurbs]
-
-[blurb [*An eye catching advertisement or note...]
-
-These should be rendered in a manner similar to admonishments.
-
-They can contain more than one paragraph.
-]
-
-[endsect]
-
-[endsect]
-
-[section Lists and Tables]
-
-[section Lists]
-
-A numbered list:
-
-# One
-# Two
-# Three
-    # Three.a
-    # Three.b
-    # Three.c
-# Four
-    # Four.a
-        # Four.a.i
-        # Four.a.ii
-# Five
-
-An unordered list:
-
-* First
-* Second
-* Third
-
-A mixture of the two:
-
-# 1
-    * 1.a
-        # 1.a.1
-        # 1.a.2
-    * 1.b
-# 2
-    * 2.a
-    * 2.b
-        # 2.b.1
-        # 2.b.2
-            * 2.b.2.a
-            * 2.b.2.b
-
-
-[endsect]
-
-[section Variable Lists]
-
-[variablelist A Variable List
-    [[term 1] [The definition of term 1]]
-    [[term 2] [The definition of term 2]]
-    [[term 3] [The definition of term 3]]
-]
-
-[endsect]
-
-[section Tables]
-
-Here's a big table with code and other tricky things:
-
-[table Notes on the Implementation of the Beta Distribution
-[[Function][Implementation Notes]]
-[[pdf]
-   [f(x;[alpha],[beta]) = x[super[alpha] - 1] (1 - x)[super[beta] -1] / B([alpha], [beta])
-
-    Implemented using ibeta_derivative(a, b, x).]]
-
-[[cdf][Using the incomplete beta function ibeta(a, b, x)]]
-[[cdf complement][ibetac(a, b, x)]]
-[[quantile][Using the inverse incomplete beta function ibeta_inv(a, b, p)]]
-[[quantile from the complement][ibetac_inv(a, b, q)]]
-[[mean][`a/(a+b)`]]
-[[variance][`a * b / (a+b)^2 * (a + b + 1)`]]
-[[mode][`(a-1) / (a + b + 2)`]]
-[[skewness][`2 (b-a) sqrt(a+b+1)/(a+b+2) * sqrt(a * b)`]]
-[[kurtosis excess][ [$../beta_dist_kurtosis.png]  ]]
-[[kurtosis][`kurtosis + 3`]]
-[[parameter estimation][ ]]
-[[alpha
-
-   from mean and variance][`mean * (( (mean * (1 - mean)) / variance)- 1)`]]
-[[beta
-
-  from mean and variance][`(1 - mean) * (((mean * (1 - mean)) /variance)-1)`]]
-[[The member functions `estimate_alpha` and `estimate_beta`
-
-  from cdf and probability x
-  
-  and *either* `alpha` or `beta`]
-      [Implemented in terms of the inverse incomplete beta functions
-      
-ibeta_inva, and ibeta_invb respectively.]]
-[[`estimate_alpha`][`ibeta_inva(beta, x, probability)`]]
-[[`estimate_beta`][`ibeta_invb(alpha, x, probability)`]]
-]
-
-[endsect]
-
-[endsect]
-
-[section Images]
-
-These are tricky enough that they warrent their own section.
-
-Let's start with a PNG file that's set to 120dpi, it should render at 
-a sensible size in both html and PDF forms.  It should print OK too!
-
-[$images/digamma3.png]
-
-Now try again with a sample SVG image:
-
-[$images/open_clipart_library_logo.svg]
-
-
-[endsect]
-
-[include test_HTML4_symbols.qbk]
-
+[article Document To Test Formatting
+    [quickbook 1.4]
+    [copyright 2007 John Maddock, Joel de Guzman, Eric Niebler and Matias Capeletto]
+    [purpose Test Formatting Document]
+    [license
+        Distributed under the Boost Software License, Version 1.0.
+        (See accompanying file LICENSE_1_0.txt or copy at
+        [@http://www.boost.org/LICENSE_1_0.txt])
+    ]
+    [authors [Maddock, John], [de Guzman, Joel], [Niebler, Eric], [Capeletto, Matias] ]
+    [category math]
+    [/last-revision $Date: 2007-05-07 10:21:52 +0100 (Mon, 07 May 2007) $]
+]
+
+[include HTML4_symbols.qbk]
+
+[/ Some composite templates]
+[template super[x]'''<superscript>'''[x]'''</superscript>''']
+[template sub[x]'''<subscript>'''[x]'''</subscript>''']
+[template floor[x]'''&#x230A;'''[x]'''&#x230B;''']
+[template floorlr[x][lfloor][x][rfloor]]
+[template ceil[x] '''&#x2308;'''[x]'''&#x2309;''']
+
+[section Introduction]
+
+This document is purely a test case to test out HTML and PDF generation and style.
+
+This is some body text.
+
+    int main()
+    {
+        double d = 2.345;
+        return d;
+    }
+
+We can count in Greek too: [alpha], [beta], [gamma].
+
+Try some superscrips and subscripts: x[super 2], x[sub i][super 3], [alpha][super 2], 
+[beta][super [alpha]], [floor x], [floor [alpha]], [ceil a].
+
+[endsect]
+
+[section Code Blocks]
+
+[section Embedded code]
+
+These should be syntax highlighted:
+
+   #include <iostream>
+
+   int main()
+   {
+       // Sample code
+       std::cout << "Hello, World\n";
+       return 0;
+   }
+
+[endsect]
+
+[section Imported code and callouts]
+
+[import stub.cpp]
+
+Here's some code with left-placed callouts:
+
+[class_]
+
+And again with callouts placed exactly where we put them:
+
+[foo_bar]
+
+[endsect]
+
+[section Larger example]
+
+Now let's include a larger example, this may span several pages
+and should not be chopped off half way through... some FO processors
+get this wrong!
+
+   namespace boost{
+
+   template <class BidirectionalIterator>
+   class sub_match;
+
+   typedef sub_match<const char*>                    csub_match;
+   typedef sub_match<const wchar_t*>                 wcsub_match;
+   typedef sub_match<std::string::const_iterator>    ssub_match;
+   typedef sub_match<std::wstring::const_iterator>   wssub_match;
+
+   template <class BidirectionalIterator>
+   class sub_match : public std::pair<BidirectionalIterator, BidirectionalIterator>
+   {
+   public:
+      typedef typename iterator_traits<BidirectionalIterator>::value_type value_type;
+      typedef typename iterator_traits<BidirectionalIterator>::difference_type   difference_type;
+      typedef          BidirectionalIterator                                    iterator;
+
+      bool  matched;
+
+      difference_type length()const;
+      operator basic_string<value_type>()const;
+      basic_string<value_type> str()const;
+
+      int compare(const sub_match& s)const;
+      int compare(const basic_string<value_type>& s)const;
+      int compare(const value_type* s)const;
+   #ifdef BOOST_REGEX_MATCH_EXTRA
+      typedef implementation-private capture_sequence_type;
+      const capture_sequence_type& captures()const;
+   #endif
+   };
+   //
+   // comparisons to another sub_match:
+   //
+   template <class BidirectionalIterator>
+   bool operator == (const sub_match<BidirectionalIterator>& lhs,
+                     const sub_match<BidirectionalIterator>& rhs);
+   template <class BidirectionalIterator>
+   bool operator != (const sub_match<BidirectionalIterator>& lhs,
+                     const sub_match<BidirectionalIterator>& rhs);
+   template <class BidirectionalIterator>
+   bool operator < (const sub_match<BidirectionalIterator>& lhs,
+                  const sub_match<BidirectionalIterator>& rhs);
+   template <class BidirectionalIterator>
+   bool operator <= (const sub_match<BidirectionalIterator>& lhs,
+                     const sub_match<BidirectionalIterator>& rhs);
+   template <class BidirectionalIterator>
+   bool operator >= (const sub_match<BidirectionalIterator>& lhs,
+                     const sub_match<BidirectionalIterator>& rhs);
+   template <class BidirectionalIterator>
+   bool operator > (const sub_match<BidirectionalIterator>& lhs,
+                  const sub_match<BidirectionalIterator>& rhs);
+
+
+   //
+   // comparisons to a basic_string:
+   //
+   template <class BidirectionalIterator, class traits, class Allocator> 
+   bool operator == (const std::basic_string<iterator_traits<BidirectionalIterator>::value_type,
+                                             traits, 
+                                             Allocator>& lhs,
+                     const sub_match<BidirectionalIterator>& rhs);
+   template <class BidirectionalIterator, class traits, class Allocator> 
+   bool operator != (const std::basic_string<iterator_traits<BidirectionalIterator>::value_type,
+                                             traits, 
+                                             Allocator>& lhs,
+                     const sub_match<BidirectionalIterator>& rhs);
+   template <class BidirectionalIterator, class traits, class Allocator> 
+   bool operator < (const std::basic_string<iterator_traits<BidirectionalIterator>::value_type,
+                                             traits, 
+                                             Allocator>& lhs,
+                     const sub_match<BidirectionalIterator>& rhs);
+   template <class BidirectionalIterator, class traits, class Allocator> 
+   bool operator > (const std::basic_string<iterator_traits<BidirectionalIterator>::value_type,
+                                             traits, 
+                                             Allocator>& lhs,
+                     const sub_match<BidirectionalIterator>& rhs);
+   template <class BidirectionalIterator, class traits, class Allocator> 
+   bool operator >= (const std::basic_string<iterator_traits<BidirectionalIterator>::value_type,
+                                             traits, 
+                                             Allocator>& lhs,
+                     const sub_match<BidirectionalIterator>& rhs);
+   template <class BidirectionalIterator, class traits, class Allocator> 
+   bool operator <= (const std::basic_string<iterator_traits<BidirectionalIterator>::value_type,
+                                             traits, 
+                                             Allocator>& lhs,
+                     const sub_match<BidirectionalIterator>& rhs);
+
+   template <class BidirectionalIterator, class traits, class Allocator> 
+   bool operator == (const sub_match<BidirectionalIterator>& lhs,
+                     const std::basic_string<iterator_traits<BidirectionalIterator>::value_type, 
+                                             traits, 
+                                             Allocator>& rhs);
+   template <class BidirectionalIterator, class traits, class Allocator> 
+   bool operator != (const sub_match<BidirectionalIterator>& lhs,
+                     const std::basic_string<iterator_traits<BidirectionalIterator>::value_type, 
+                                             traits, 
+                                             Allocator>& rhs);
+   template <class BidirectionalIterator, class traits, class Allocator> 
+   bool operator < (const sub_match<BidirectionalIterator>& lhs,
+                  const std::basic_string<iterator_traits<BidirectionalIterator>::value_type, 
+                                          traits, 
+                                          Allocator>& rhs);
+   template <class BidirectionalIterator, class traits, class Allocator> 
+   bool operator > (const sub_match<BidirectionalIterator>& lhs,
+                  const std::basic_string<iterator_traits<BidirectionalIterator>::value_type, 
+                                          traits, 
+                                          Allocator>& rhs);
+   template <class BidirectionalIterator, class traits, class Allocator> 
+   bool operator >= (const sub_match<BidirectionalIterator>& lhs,
+                     const std::basic_string<iterator_traits<BidirectionalIterator>::value_type, 
+                                          traits, 
+                                          Allocator>& rhs);
+   template <class BidirectionalIterator, class traits, class Allocator> 
+   bool operator <= (const sub_match<BidirectionalIterator>& lhs,
+                     const std::basic_string<iterator_traits<BidirectionalIterator>::value_type, 
+                                             traits, 
+                                             Allocator>& rhs);
+
+   //
+   // comparisons to a pointer to a character array:
+   //
+   template <class BidirectionalIterator> 
+   bool operator == (typename iterator_traits<BidirectionalIterator>::value_type const* lhs,
+                     const sub_match<BidirectionalIterator>& rhs); 
+   template <class BidirectionalIterator> 
+   bool operator != (typename iterator_traits<BidirectionalIterator>::value_type const* lhs,
+                     const sub_match<BidirectionalIterator>& rhs); 
+   template <class BidirectionalIterator> 
+   bool operator < (typename iterator_traits<BidirectionalIterator>::value_type const* lhs,
+                  const sub_match<BidirectionalIterator>& rhs); 
+   template <class BidirectionalIterator> 
+   bool operator > (typename iterator_traits<BidirectionalIterator>::value_type const* lhs,
+                  const sub_match<BidirectionalIterator>& rhs); 
+   template <class BidirectionalIterator> 
+   bool operator >= (typename iterator_traits<BidirectionalIterator>::value_type const* lhs,
+                     const sub_match<BidirectionalIterator>& rhs); 
+   template <class BidirectionalIterator> 
+   bool operator <= (typename iterator_traits<BidirectionalIterator>::value_type const* lhs,
+                     const sub_match<BidirectionalIterator>& rhs); 
+
+   template <class BidirectionalIterator> 
+   bool operator == (const sub_match<BidirectionalIterator>& lhs,
+                     typename iterator_traits<BidirectionalIterator>::value_type const* rhs); 
+   template <class BidirectionalIterator> 
+   bool operator != (const sub_match<BidirectionalIterator>& lhs,
+                     typename iterator_traits<BidirectionalIterator>::value_type const* rhs); 
+   template <class BidirectionalIterator> 
+   bool operator < ]``(const sub_match<BidirectionalIterator>& lhs,
+                  typename iterator_traits<BidirectionalIterator>::value_type const* rhs); 
+   template <class BidirectionalIterator> 
+   bool operator > (const sub_match<BidirectionalIterator>& lhs,
+                  typename iterator_traits<BidirectionalIterator>::value_type const* rhs); 
+   template <class BidirectionalIterator> 
+   bool operator >= (const sub_match<BidirectionalIterator>& lhs,
+                     typename iterator_traits<BidirectionalIterator>::value_type const* rhs); 
+   template <class BidirectionalIterator> 
+   bool operator <= (const sub_match<BidirectionalIterator>& lhs,
+                     typename iterator_traits<BidirectionalIterator>::value_type const* rhs); 
+
+   //
+   // comparisons to a single character:
+   //
+   template <class BidirectionalIterator> 
+   bool operator == (typename iterator_traits<BidirectionalIterator>::value_type const& lhs,
+                     const sub_match<BidirectionalIterator>& rhs); 
+   template <class BidirectionalIterator> 
+   bool operator != (typename iterator_traits<BidirectionalIterator>::value_type const& lhs,
+                     const sub_match<BidirectionalIterator>& rhs); 
+   template <class BidirectionalIterator> 
+   bool operator < (typename iterator_traits<BidirectionalIterator>::value_type const& lhs,
+                  const sub_match<BidirectionalIterator>& rhs); 
+   template <class BidirectionalIterator> 
+   bool operator > (typename iterator_traits<BidirectionalIterator>::value_type const& lhs,
+                  const sub_match<BidirectionalIterator>& rhs); 
+   template <class BidirectionalIterator> 
+   bool operator >= (typename iterator_traits<BidirectionalIterator>::value_type const& lhs,
+                     const sub_match<BidirectionalIterator>& rhs); 
+   template <class BidirectionalIterator> 
+   bool operator <= (typename iterator_traits<BidirectionalIterator>::value_type const& lhs,
+                     const sub_match<BidirectionalIterator>& rhs); 
+
+   template <class BidirectionalIterator> 
+   bool operator == (const sub_match<BidirectionalIterator>& lhs,
+                     typename iterator_traits<BidirectionalIterator>::value_type const& rhs); 
+   template <class BidirectionalIterator> 
+   bool operator != (const sub_match<BidirectionalIterator>& lhs,
+                     typename iterator_traits<BidirectionalIterator>::value_type const& rhs); 
+   template <class BidirectionalIterator> 
+   bool operator < (const sub_match<BidirectionalIterator>& lhs,
+                  typename iterator_traits<BidirectionalIterator>::value_type const& rhs); 
+   template <class BidirectionalIterator> 
+   bool operator > (const sub_match<BidirectionalIterator>& lhs,
+                  typename iterator_traits<BidirectionalIterator>::value_type const& rhs); 
+   template <class BidirectionalIterator> 
+   bool operator >= (const sub_match<BidirectionalIterator>& lhs,
+                     typename iterator_traits<BidirectionalIterator>::value_type const& rhs); 
+   template <class BidirectionalIterator> 
+   bool operator <= (const sub_match<BidirectionalIterator>& lhs,
+                     typename iterator_traits<BidirectionalIterator>::value_type const& rhs); 
+   // 
+   // addition operators: 
+   //
+   template <class BidirectionalIterator, class traits, class Allocator> 
+   std::basic_string<typename iterator_traits<BidirectionalIterator>::value_type, traits, Allocator> 
+      operator + (const std::basic_string<typename iterator_traits<BidirectionalIterator>::value_type,
+                                          traits, 
+                                          Allocator>& s, 
+                  const sub_match<BidirectionalIterator>& m); 
+   template <class BidirectionalIterator, class traits, class Allocator> 
+   std::basic_string<typename iterator_traits<BidirectionalIterator>::value_type, traits, Allocator>
+      operator + (const sub_match<BidirectionalIterator>& m,
+                  const std::basic_string<typename iterator_traits<BidirectionalIterator>::value_type, 
+                                          traits, 
+                                          Allocator>& s); 
+   template <class BidirectionalIterator> 
+   std::basic_string<typename iterator_traits<BidirectionalIterator>::value_type> 
+      operator + (typename iterator_traits<BidirectionalIterator>::value_type const* s,
+                  const sub_match<BidirectionalIterator>& m); 
+   template <class BidirectionalIterator> 
+   std::basic_string<typename iterator_traits<BidirectionalIterator>::value_type> 
+      operator + (const sub_match<BidirectionalIterator>& m,
+                  typename iterator_traits<BidirectionalIterator>::value_type const * s);
+   template <class BidirectionalIterator> 
+   std::basic_string<typename iterator_traits<BidirectionalIterator>::value_type> 
+      operator + (typename iterator_traits<BidirectionalIterator>::value_type const& s,
+                  const sub_match<BidirectionalIterator>& m); 
+   template <class BidirectionalIterator> 
+   std::basic_string<typename iterator_traits<BidirectionalIterator>::value_type> 
+      operator + (const sub_match<BidirectionalIterator>& m,
+                  typename iterator_traits<BidirectionalIterator>::value_type const& s); 
+   template <class BidirectionalIterator> 
+   std::basic_string<typename iterator_traits<BidirectionalIterator>::value_type> 
+      operator + (const sub_match<BidirectionalIterator>& m1,
+                  const sub_match<BidirectionalIterator>& m2);
+
+   //
+   // stream inserter:
+   //
+   template <class charT, class traits, class BidirectionalIterator>
+   basic_ostream<charT, traits>&
+      operator << (basic_ostream<charT, traits>& os,
+                  const sub_match<BidirectionalIterator>& m);
+
+   } // namespace boost
+
+[endsect]
+
+[endsect]
+
+[section Basic Formatting]
+
+[section Font Styles]
+
+Here we go with some inline formatting: 
+['italic], [*bold], [_underline], [^teletype], [-strikethrough],
+we can combine styles as well: ['[*bold italic]], [_[^teletype with underline]].
+
+[endsect]
+
+[section Replaceable Text]
+
+Text that is intended to be user-replaceable is [~rendered like this].
+
+[endsect]
+
+[section Quotations]
+
+Here we go: ["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein
+
+Note the proper left and right quote marks. Also, while you can simply use ordinary quote marks like "quoted", our quotation, above, will generate correct DocBook quotations (e.g. <quote>quoted</quote>).
+
+Like all phrase elements, quotations may be nested. Example:
+
+["Here's the rule for bargains: ["Do other men, for they would do you.] That's
+the true business precept.]
+
+[endsect]
+
+[section Inline Code]
+
+This text has inlined code `int main() { return 0; }`  in it. 
+The code should be syntax highlighted.
+
+[endsect]
+
+[section Links]
+
+Try this: [@http://www.boost.org this is [*boost's] website....] it should
+be visible as a link.
+
+[endsect]
+
+[section Footnotes]
+
+Here's one [footnote A sample footnote].
+
+And here's another [footnote Another sample footnote].
+
+[endsect]
+
+[section Blockquote]
+
+Lets indent the next paragraph:
+
+[:Here we go!!!]
+
+[endsect]
+
+[section Headings]
+
+Now try rendering some heading styles:
+
+[h1 Heading 1]
+
+[h2 Heading 2]
+
+[h3 Heading 3]
+
+[h4 Heading 4]
+
+[h5 Heading 5]
+
+[h6 Heading 6]
+
+[endsect]
+
+[endsect]
+
+[section Blurbs]
+
+[section Preformatted text]
+
+Here's some sample program output:
+
+[pre
+'''F test for equal standard deviations
+____________________________________
+
+Sample 1:
+Number of Observations                                 =  240
+Sample Standard Deviation                              =  65.549
+
+Sample 2:
+Number of Observations                                 =  240
+Sample Standard Deviation                              =  61.854
+
+Test Statistic                                         =  1.123
+
+CDF of test statistic:                                 =  8.148e-001
+Upper Critical Value at alpha:                         =  1.238e+000
+Upper Critical Value at alpha/2:                       =  1.289e+000
+Lower Critical Value at alpha:                         =  8.080e-001
+Lower Critical Value at alpha/2:                       =  7.756e-001
+
+Results for Alternative Hypothesis and alpha           =  0.0500
+
+Alternative Hypothesis                                    Conclusion
+Standard deviations are unequal (two sided test)          REJECTED
+Standard deviation 1 is less than standard deviation 2    REJECTED
+Standard deviation 1 is greater than standard deviation 2 REJECTED'''
+]
+
+[endsect]
+
+[section Admonishments]
+
+There are four admonishments supported by Docbook XML:
+
+[note This is a note]
+
+[tip This is a tip]
+
+[important This is important]
+
+[caution This is a caution]
+
+[warning This is a warning
+
+They can contain more than one paragraph.
+]
+
+[endsect]
+
+[section Blurbs]
+
+[blurb [*An eye catching advertisement or note...]
+
+These should be rendered in a manner similar to admonishments.
+
+They can contain more than one paragraph.
+]
+
+[endsect]
+
+[endsect]
+
+[section Lists and Tables]
+
+[section Lists]
+
+A numbered list:
+
+# One
+# Two
+# Three
+    # Three.a
+    # Three.b
+    # Three.c
+# Four
+    # Four.a
+        # Four.a.i
+        # Four.a.ii
+# Five
+
+An unordered list:
+
+* First
+* Second
+* Third
+
+A mixture of the two:
+
+# 1
+    * 1.a
+        # 1.a.1
+        # 1.a.2
+    * 1.b
+# 2
+    * 2.a
+    * 2.b
+        # 2.b.1
+        # 2.b.2
+            * 2.b.2.a
+            * 2.b.2.b
+
+
+[endsect]
+
+[section Variable Lists]
+
+[variablelist A Variable List
+    [[term 1] [The definition of term 1]]
+    [[term 2] [The definition of term 2]]
+    [[term 3] [The definition of term 3]]
+]
+
+[endsect]
+
+[section Tables]
+
+Here's a big table with code and other tricky things:
+
+[table Notes on the Implementation of the Beta Distribution
+[[Function][Implementation Notes]]
+[[pdf]
+   [f(x;[alpha],[beta]) = x[super[alpha] - 1] (1 - x)[super[beta] -1] / B([alpha], [beta])
+
+    Implemented using ibeta_derivative(a, b, x).]]
+
+[[cdf][Using the incomplete beta function ibeta(a, b, x)]]
+[[cdf complement][ibetac(a, b, x)]]
+[[quantile][Using the inverse incomplete beta function ibeta_inv(a, b, p)]]
+[[quantile from the complement][ibetac_inv(a, b, q)]]
+[[mean][`a/(a+b)`]]
+[[variance][`a * b / (a+b)^2 * (a + b + 1)`]]
+[[mode][`(a-1) / (a + b + 2)`]]
+[[skewness][`2 (b-a) sqrt(a+b+1)/(a+b+2) * sqrt(a * b)`]]
+[[kurtosis excess][ [$../beta_dist_kurtosis.png]  ]]
+[[kurtosis][`kurtosis + 3`]]
+[[parameter estimation][ ]]
+[[alpha
+
+   from mean and variance][`mean * (( (mean * (1 - mean)) / variance)- 1)`]]
+[[beta
+
+  from mean and variance][`(1 - mean) * (((mean * (1 - mean)) /variance)-1)`]]
+[[The member functions `estimate_alpha` and `estimate_beta`
+
+  from cdf and probability x
+  
+  and *either* `alpha` or `beta`]
+      [Implemented in terms of the inverse incomplete beta functions
+      
+ibeta_inva, and ibeta_invb respectively.]]
+[[`estimate_alpha`][`ibeta_inva(beta, x, probability)`]]
+[[`estimate_beta`][`ibeta_invb(alpha, x, probability)`]]
+]
+
+[endsect]
+
+[endsect]
+
+[section Images]
+
+These are tricky enough that they warrent their own section.
+
+Let's start with a PNG file that's set to 120dpi, it should render at 
+a sensible size in both html and PDF forms.  It should print OK too!
+
+[$images/digamma3.png]
+
+Now try again with a sample SVG image:
+
+[$images/open_clipart_library_logo.svg]
+
+
+[endsect]
+
+[include test_HTML4_symbols.qbk]
+
+[include remez.qbk]
+
+