boost/doc/test/test.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 superscripts 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 Code With a Very Long Line]

	template <class RealType> RealType inline foo(const RealType& a, const RealType& b, const RealType& c, const RealType& d, const RealType& e, const RealType& f, const RealType& g, const RealType& h){ 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.

This is [@../../../boost/math/distributions.hpp a link to a header file (boost/math/distributions.hpp)],
it should be rewritable and point to the website when built as a PDF.

This is [@boost:libs/regex/index.html a link to another library's documentation (Boost.Regex)], using the boost: protocol,
it should be rewritten to point to the website when building a PDF.

This is [@boost:/libs/regex/index.html a link to another library's documentation (Boost.Regex)], using the boost:/ protocol,
it should be rewritten to point to the website when building a PDF.

This is [@../weighted_tail_quantile.hpp a relative link to a header file within the test source],
it should be rewritten to point to the website when building a PDF.
Although it might be on the website yet.

[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][ [$images/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 warrant 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]

[section Equations]

This page is largely to test equation handling in various browsers, unfortunately none of this works as well as it should (or at all?)
in Internet Explorer....

This equation is formatted from Latex text:

'''<inlinemediaobject><textobject role="tex">ax^2 + bx + c = 0</textobject></inlinemediaobject>'''

This equation is formed from MathML:

'''<inlinemediaobject><textobject role="MathML"><?dbhtml-include href="test.mml"?></textobject></inlinemediaobject>'''

This equation is SVG:

'''<inlinemediaobject><imageobject><imagedata format="SVG" fileref="../test.svg"></imagedata></imageobject></inlinemediaobject>'''


[endsect]

[include test_HTML4_symbols.qbk]

[include remez.qbk]

[section:array Array Example Boostbook XML Documentation]
[xinclude array.xml]
[xinclude array1.xml]
[xinclude array2.xml]
[xinclude array3.xml]
[xinclude array4.xml]
[endsect]

[section:accumulators Accumulators Example Doxygen Documentation]
[xinclude statsdoc.xml]
[endsect]