[article Quickbook
    [quickbook 1.5]
    [version 1.5]
    [authors [de Guzman, Joel], [Niebler, Eric]]
    [copyright 2002 2004 2006 Joel de Guzman, Eric Niebler]
    [purpose /WikiWiki/ style documentation tool]
    [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])
    ]
]

[/ QuickBook Document version 1.5 ]
[/ Sept 24, 2002 ]
[/ Sept 2, 2004 ]
[/ Feb 14, 2005 ]
[/ Sept 13, 2005 ]

[/ Some links]

[def :-)            [$../src/images/smiley.png]]
[def __spirit__     [@http://spirit.sourceforge.net Spirit]]
[def __boostbook__  [@http://www.boost.org/doc/html/boostbook.html BoostBook]]
[def __docbook__    [@http://www.docbook.org/ DocBook]]

[def __comments__           [link quickbook.syntax.comments Comments]]

[def __font_styles__        [link quickbook.syntax.phrase.font_styles Font Styles]]
[def __quotations__         [link quickbook.syntax.phrase.quotations Quotations]]
[def __replaceable__        [link quickbook.syntax.phrase.replaceable Replaceble]]
[def __simple_formatting__  [link quickbook.syntax.phrase.simple_formatting Simple formatting]]
[def __inline_code__        [link quickbook.syntax.phrase.inline_code Inline code]]
[def __code_blocks__        [link quickbook.syntax.phrase.code_blocks Code blocks]]
[def __source_mode__        [link quickbook.syntax.phrase.source_mode Source Mode]]
[def __line_break__         [link quickbook.syntax.phrase.line_break line-break]]
[def __anchors__            [link quickbook.syntax.phrase.anchors Anchors]]
[def __links__              [link quickbook.syntax.phrase.links Links]]
[def __anchor_links__       [link quickbook.syntax.phrase.anchor_links Anchor links]]
[def __refentry_links__     [link quickbook.syntax.phrase.refentry_links refentry links]]
[def __code_links__         [link quickbook.syntax.phrase.code_links function, class, member, enum, macro, concept or header links]]
[def __escape__             [link quickbook.syntax.phrase.escape Escape]]
[def __single_char_escape__ [link quickbook.syntax.phrase.single_char_escape Single char escape]]
[def __images__             [link quickbook.syntax.phrase.images Images]]
[def __cond__               [link quickbook.syntax.phrase.cond Conditional Generation]]

[def __document__           [link quickbook.syntax.block.document Document]]
[def __section__            [link quickbook.syntax.block.section Section]]
[def __xinclude__           [link quickbook.syntax.block.xinclude  xinclude]]
[def __paragraphs__         [link quickbook.syntax.block.paragraphs Paragraphs]]
[def __ordered_lists__      [link quickbook.syntax.block.lists.ordered_lists Ordered lists]]
[def __list_hierarchies__   [link quickbook.syntax.block.lists.list_hierarchies List Hierarchies]]
[def __long_list_lines__    [link quickbook.syntax.block.lists.long_list_lines Long List Lines]]
[def __unordered_lists__    [link quickbook.syntax.block.lists.unordered_lists Unordered lists]]
[def __mixed_lists__        [link quickbook.syntax.block.lists.mixed_lists Mixed lists]]
[def __code__               [link quickbook.syntax.block.code Code]]
[def __escape_back__        [link quickbook.syntax.block.escape_back Escaping Back To QuickBook]]
[def __preformatted__       [link quickbook.syntax.block.preformatted Preformatted]]
[def __blockquote__         [link quickbook.syntax.block.blockquote Blockquote]]
[def __heading__            [link quickbook.syntax.block.headings Heading]]
[def __macros__             [link quickbook.syntax.block.macros Macros]]
[def __templates__          [link quickbook.syntax.block.templates Templates]]
[def __predefined_macros__  [link quickbook.syntax.block.predefined_macros Predefined Macros]]
[def __blurbs__             [link quickbook.syntax.block.blurbs Blurbs]]
[def __admonitions__        [link quickbook.syntax.block.admonitions Admonitions]]
[def __tables__             [link quickbook.syntax.block.tables Tables]]
[def __variable_lists__     [link quickbook.syntax.block.variable_lists Variable Lists]]
[def __include__            [link quickbook.syntax.block.include Include]]
[def __import__             [link quickbook.syntax.block.import Import]]

[section:intro Introduction]

[:[*['["Why program by hand in five days what you can spend five years of your
life automating?]]]

-- Terrence Parr, author ANTLR/PCCTS
]

Well, QuickBook started as a weekend hack. It was originally intended to be a
sample application using __spirit__. What is it? What you are viewing now, this
documentation, is autogenerated by QuickBook. These files were generated from
one master:

[:[@boost:/tools/quickbook/doc/quickbook.qbk quickbook.qbk]]

Originally named QuickDoc, this funky tool that never dies, evolved into a
funkier tool thanks to Eric Niebler who resurrected the project making it
generate __boostbook__ instead of HTML. The __boostbook__ documentation format
is an extension of __docbook__, an SGML or XML based format for describing
documentation.

QuickBook is a WikiWiki style documentation tool geared towards C++
documentation using simple rules and markup for simple formatting tasks.
QuickBook extends the WikiWiki concept. Like the WikiWiki, QuickBook documents are
simple text files. A single QuickBook document can generate a fully linked set
of nice HTML and PostScript/PDF documents complete with images and syntax-
colorized source code.

Features include:

* generate __boostbook__ xml, to generate HTML, PostScript and PDF
* simple markup to link to Doxygen-generated entities
* macro system for simple text substitution
* simple markup for italics, bold, preformatted, blurbs, code samples,
  tables, URLs, anchors, images, etc.
* automatic syntax coloring of code samples
* CSS support

[endsect]

[section:change_log Change Log]

[h3 Version 1.3]

* Quickbook file inclusion \[include\].
* Better xml output (pretty layout). Check out the generated XML.
* Regression testing facility: to make sure your document will always be
  compatible (full backward compatibility) regardless of changes to
  QuickBook.
* Code cleanup and refactoring.
* Allow phrase markup in the doc-info.
* Preformatted code blocks via \`\`code\`\` (double ticks) allows code in tables
  and lists, for example.
* Quickbook versioning; allows full backward compatibility. You have to add
  \[quickbook 1.3\] to the doc-info header to enable the new features. Without
  this, QuickBook will assume that the document is a pre-1.3 document.
* Better (intuitive) paragraph termination. Some markups may terminate a paragraph.
  Example:``
  [section x]
  blah...
  [endsect]``
* Fully qualified section and headers. Subsection names are concatenated to the
  ID to avoid clashing. Example: `doc_name.sect_name.sub_sect_name.sub_sub_sect_name`
* Better &nbsp; and whitespace handling in code snippets.
* \[xinclude\] fixes up the relative path to the target XML file when
  input_directory is not the same as the output_directory.
* Allow untitled tables.
* Allow phrase markups in section titles.
* Allow escaping back to QuickBook from code, code blocks and inline code.
* Footnotes, with the \[footnote This is the footnote\] syntax.
* Post-processor bug fix for escaped XML code that it does not recognize.
* Replaceable, with the \[~replacement\] syntax.

[h3 Version 1.4]

* Generic Headers
* Code changes to allow full recursion (i.e. Collectors and push/pop functions)
* Various code cleanup/maintenance
* Templates!
* \[conceptref\] for referencing BoostBook <concept> entities.
* Allow escape of spaces. The escaped space is removed from the output. Syntax:
  `\ `.
* Nested comments are now allowed.
* Quickbook blocks can nest inside comments.
* __import__ facility.
* Callouts on imported code
* Simple markups can now span a whole block.
* __blurbs__, __admonitions__ and table cells (see __tables__) may now
  contain paragraphs.
* `\n` and `[br]` are now deprecated.
* __cond__. Ala C++ #ifdef.
* Searching of included and imported files in an extensible search path with
  `--include-path` (`-I`) option.
  
[h3 Version 1.5]

* Support multiple copyright entrys in document info.
* Improved SVG support.
* \[globalref\] for referencing BoostBook <global> entities.
* Fail on error.
* Fix crash for templates with too many arguments or trailing space.
* Improved handling of unexpected characters in code blocks.
* Improved handling of unmatched escape in code blocks.
* Support for python snippets.
* `teletype` source mode.
* Use static scoping in templates, should be a lot more intuitive.
* Accept a space between `section:` and the section id.
* Support table ids.

[h3 Version 1.5.1 - Boost 1.43.0]

* Improve the post processor's list of block elements. `table`, `entry` and
  `varlistentry` are treated as blocks. `replaceable` is treated as an inline
  element.
* Check that `[section]` and `[endsect]` tags are balanced in templates.
* Add unicode escape characters, eg. `\u03B1` for \u03B1.
* Support UTF-8 files with a unicode byte order mark.
* Disallow `[` in simple markup. Fixes some errors with mismatched punctuation.
* Add command line flag to define macros at the command line,
  e.g. `quickbook "-D__italic_foo__=/foo/"`.

[h3 Version 1.5.2 - Boost 1.44.0]

* Use the cygwin 1.7 API for better path handling.
* Improved boostbook generation:
  * XML encode the documentation info correctly.
  * Avoid generating empty paragraphs.
  * No longer wraps block templates in paragraphs.
  * Warns if you use invalid doc_info members for docbook document types.
  * Fixes some other causes of invalid boostbook, although it still
    generates invalid boostbook in places.
* Improved grammar:
  * Supports multiple categories in library doc_info.
  * No longer requires commas between authors in docinfo.
  * Allows empty document bodies.
  * A line containing only a comment is no longer interpreted as a
    paragraph break.
  * If a line starts with a comment, interpret it as a paragraph even if it's
    followed by whitespace or a list character.
  * Doesn't treat several consecutive blank lines as multiple paragraph breaks.
* Fixes duplicate image attribute detection.
* Fixes using code snippets more than once.
* Early work on quickbook 1.6, available using the `[quickbook 1.6]` version switch,
  but liable to change in future versions.
  * When automatically generating ids for headers, use the quickbook
    source, rather than the generated docbook.
  * Fix id generation in included files. It wasn't correctly using the
    main document's documentation id.
  * Correctly restore the quickbook version switch after including a file
    with a different version.

[h3 Version 1.5.3 - Boost 1.45.0]

* Fix command line flag for defining macros.
* Fix a couple of issues with the code block parser:
  * A comment with no indentation will now end a code block.
  * Code blocks no longer have to be followed by a blank line.
* Improved tracking of file position in templates and imported code blocks.
* Better generated markup for callout lists.
* In docbook, variable list entries can only have one `listitem`, so if an
  entry has multiple values, merge them into one `listitem`.
* Support nested code snippets.
* Support nested blocks in document info comments.
* Revert xml escaping document info, it broke some documentation files
  (now a 1.6 feature).
* Further work on quickbook 1.6, still not stable.
  * Allow heading to have ids, using the syntax: `[heading:id title]`.
  * XML escape documentation fields, with escapes to allow encoding unicode
    in ASCII.

[endsect]

[section:syntax Syntax Summary]

A QuickBook document is composed of one or more blocks. An example of
a block is the paragraph or a C++ code snippet. Some blocks have
special mark-ups. Blocks, except code snippets which have their own
grammar (C++ or Python), are composed of one or more phrases. A phrase
can be a simple contiguous run of characters. Phrases can have special
mark-ups. Marked up phrases can recursively contain other phrases, but
cannot contain blocks. A terminal is a self contained block-level or
phrase-level element that does not nest anything.

Blocks, in general, are delimited by two end-of-lines (the block terminator).
Phrases in each block cannot contain a block terminator. This way, syntax errors
such as un-matched closing brackets do not go haywire and corrupt anything past
a single block.

[section Comments]

Can be placed anywhere.

[pre
'''[/ comment (no output generated) ]'''
]

[/ for testing only... ]

[pre
'''[/ comments can be nested [/ some more here] ]'''
]

[/ for testing [/ only ] ]

[pre
'''[/ Quickbook blocks can nest inside comments. [*Comment this out too!] ]'''
]

[/ for testing [*only ] ]

[endsect]

[section:phrase Phrase Level Elements]

[section Font Styles]

[pre'''
['italic], [*bold], [_underline], [^teletype], [-strikethrough]
''']

will generate:

['italic], [*bold], [_underline], [^teletype], [-strikethrough]

Like all non-terminal phrase level elements, this can of course be nested:

[pre'''
[*['bold-italic]]
''']

will generate:

[*['bold-italic]]

[endsect]

[section Replaceable]

When you want content that may or must be replaced by the user, use the syntax:

[pre'''
[~replacement]
''']

This will generate:

[~replacement]

[endsect]

[section Quotations]

[pre'''
["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein
''']

will generate:

["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:

[pre'''
["Here's the rule for bargains: ["Do other men, for they would do you.] That's
the true business precept.]
''']

will generate:

["Here's the rule for bargains: ["Do other men, for they would do you.]
That's the true business precept.]

[endsect]
[section Simple formatting]

Simple markup for formatting text, common in many applications, is now supported:

[pre'''
/italic/, *bold*, _underline_, =teletype=
''']

will generate:

/italic/, *bold*, _underline_, =teletype=

Unlike QuickBook's standard formatting scheme, the rules for simpler
alternatives are much stricter[footnote Thanks to David Barrett, author of
[@http://quinthar.com/qwikiwiki/index.php?page=Home Qwiki], for sharing
these samples and teaching me these obscure formatting rules. I wasn't sure
at all if __spirit__, being more or less a formal EBNF parser, can handle
the context sensitivity and ambiguity.].

* Simple markups cannot nest. You can combine a simple markup with a nestable markup.
* Simple markups cannot contain any other form of quickbook markup.
* A non-space character must follow the leading markup
* A non-space character must precede the trailing markup
* A space or a punctuation must follow the trailing markup
* If the matching markup cannot be found within a block, the formatting
  will not be applied. This is to ensure that un-matched formatting markups,
  which can be a common mistake, does not corrupt anything past a single block.
  We do not want the rest of the document to be rendered bold just because we
  forgot a trailing '*'. A single block is terminated by two end of lines or
  the close bracket: ']'.
* A line starting with the star will be interpreted as an unordered list.
  See __unordered_lists__.

[table More Formatting Samples
    [[Markup]                                           [Result]]
    [[[^'''*Bold*''']]                                  [*Bold*]]
    [[[^'''*Is bold*''']]                               [*Is bold*]]
    [[[^'''* Not bold* *Not bold * * Not bold *''']]    [* Not bold* *Not bold * * Not bold *]]
    [[[^'''This*Isn't*Bold (no bold)''']]               [This*Isn't*Bold (no bold)]]
    [[[^'''(*Bold Inside*) (parenthesis not bold)''']]  [(*Bold Inside*) (parenthesis not bold)]]
    [[[^'''*(Bold Outside)* (parenthesis bold)''']]     [*(Bold Outside)* (parenthesis bold)]]
    [[[^'''3*4*5 = 60 (no bold)''']]                    [3*4*5 = 60 (no bold)]]
    [[[^'''3 * 4 * 5 = 60 (no bold)''']]                [3 * 4 * 5 = 60 (no bold)]]
    [[[^'''3 *4* 5 = 60 (4 is bold)''']]                [3 *4* 5 = 60 (4 is bold)]]
    [[[^'''*This is bold* this is not *but this is*''']][*This is bold* this is not *but this is*]]
    [[[^'''*This is bold*.''']]                         [*This is bold*.]]
    [[[^'''*B*. (bold B)''']]                           [*B*. (bold B)]]
    [[[^'''['*Bold-Italic*]''']]                        [['*Bold-Italic*]]]
    [[[^'''*side-by*/-side/''']]                        [*side-by*/-side/]]
]

As mentioned, simple markups cannot go past a single block. The text
from "have" to "full" in the following paragraph will be rendered as
bold:

[pre'''
Baa baa black sheep, *have you any wool?
Yes sir, yes sir, three bags full!*
One for the master, one for the dame,
And one for the little boy who lives down the lane.
''']

Baa baa black sheep, *have you any wool?
Yes sir, yes sir, three bags full!*
One for the master, one for the dame,
And one for the little boy who lives down the lane.

But in the following paragraph, bold is not applied:

[pre'''
Baa baa black sheep, *have you any wool?
Yes sir, yes sir, three bags full!
One for the master, one for the dame,
And one for the little boy who lives down the lane.
''']

Baa baa black sheep, *have you any wool?
Yes sir, yes sir, three bags full!
One for the master, one for the dame,
And one for the little boy who lives down the lane.

[endsect]
[section Inline code]

Inlining code in paragraphs is quite common when writing C++ documentation. We
provide a very simple markup for this. For example, this:

[pre'''
This text has inlined code `int main() { return 0; }` in it.
''']

will generate:

This text has inlined code `int main() { return 0; }` in it. The code will be
syntax highlighted.

[note We simply enclose the code with the tick: [^'''"`"'''], not the
single quote: `"'"`. Note too that [^'''`some code`'''] is preferred over
[^'''[^some code]''']. ]

[endsect]
[section Code blocks]

Preformatted code simply starts with a space or a tab (See __code__).
However, such a simple syntax cannot be used as phrase elements in lists
(See __ordered_lists__ and __unordered_lists__), tables (See __tables__),
etc. Inline code (see above) can. The problem is, inline code does not
allow formatting with newlines, spaces, and tabs. These are lost.

We provide a phrase level markup that is a mix between the two. By using the
double-tick, instead of the single-tick, we are telling QuickBook to use
preformatted blocks of code. Example:

[pre
\`\`
    #include <iostream>

    int main()
    {
        std::cout << "Hello, World!" << std::endl;
        return 0;
    }
\`\`
]

will generate:

``
    #include <iostream>

    int main()
    {
        std::cout << "Hello, World!" << std::endl;
        return 0;
    }
``

[endsect]
[section Source Mode]

If a document contains more than one type of source code then the source
mode may be changed dynamically as the document is processed. All QuickBook
documents are initially in C++ mode by default, though an alternative
initial value may be set in the __document__ section.

To change the source mode, use the [^\[source-mode\]] markup, where
=source-mode= is one of the supported modes. For example, this:

[pre'''
Python's [python] `import` is rather like C++'s [c++] `#include`. A
C++ comment `// looks like this` whereas a Python comment [python]
`# looks like this`.
''']

will generate:

Python's [python] `import` is rather like C++'s [c++] `#include`. A
C++ comment `// looks like this` whereas a Python comment [python]
`#looks like this`.

[table Supported Source Modes
    [[Mode]                 [Source Mode Markup]]
    [[C++]                  [[^\[c++\]]]]
    [[Python]               [[^\[python\]]]]
    [[Plain Text]           [[^\[teletype\]]]]
]

[note The source mode strings are lowercase.]

[endsect]
[section line-break]

[pre'''
[br]
''']

[warning `[br]` is now deprecated. __blurbs__, __admonitions__ and
table cells (see __tables__) may now contain paragraphs.]

[endsect]
[section Anchors]

[pre'''
[#named_anchor]
''']

A named anchor is a hook that can be referenced by a link elsewhere in the
document. You can then reference an anchor with [^'''[link named_anchor
Some link text]''']. See __anchor_links__, __section__ and __heading__.

These anchors are global and can be accessed from anywhere in the
quickbook documentation. Be careful to avoid clashes with anchors in
other sections.

[endsect]
[section Links]

[pre'''
[@http://www.boost.org this is [*boost's] website....]
''']

will generate:

[@http://www.boost.org this is [*boost's] website....]

URL links where the link text is the link itself is common. Example:

[pre'''
see http://spirit.sourceforge.net/
''']

so, when the text is absent in a link markup, the URL is assumed. Example:

[pre
see '''[@http://spirit.sourceforge.net/]'''
]

will generate:

see [@http://spirit.sourceforge.net/]

Boostbook also support a custom url schema for linking to files within
the boost distribution:

[pre
'''[@boost:/libs/spirit/index.html the Boost.Spirit documentation]'''
]

will generate: [@boost:/libs/spirit/index.html the Boost.Spirit documentation]

Note that this is only available when using BoostBook, and only for links
- it can't be used for images.

[endsect]
[section Anchor links]

You can link within a document using:

[pre'''
[link document_id.section_id.normalized_header_text The link text]
''']

See sections __section__ and __heading__ for more info.

[endsect]
[section refentry links]

In addition, you can link internally to an XML refentry like:

[pre'''
[link xml.refentry The link text]
''']

This gets converted into [^<link linkend="xml.refentry">The link text</link>].

Like URLs, the link text is optional. If this is not present, the link text will
automatically be the refentry. Example:

[pre'''
[link xml.refentry]
''']

This gets converted into [^<link linkend="xml.refentry">xml.refentry</link>].

[endsect]
[section:code_links Code Links]

If you want to link to a function, class, member, enum, concept, global, or header in
the reference section, you can use:

[pre'''
[funcref fully::qualified::function_name The link text]
[classref fully::qualified::class_name The link text]
[memberref fully::qualified::member_name The link text]
[enumref fully::qualified::enum_name The link text]
[macroref MACRO_NAME The link text]
[conceptref ConceptName The link text]
[headerref path/to/header.hpp The link text]
[globalref fully::qualified::global The link text]
''']

Again, the link text is optional. If this is not present, the link text will
automatically be the function, class, member, enum, macro, concept, global, or header name.
Example:

[pre'''
[classref boost::bar::baz]
''']

would have "boost::bar::baz" as the link text.

[endsect]
[section Escape]

The escape mark-up is used when we don't want to do any processing.

[pre
\'\'\'
escape (no processing/formatting)
\'\'\'
]

Escaping allows us to pass XML markup to __boostbook__ or __docbook__. For example:

[pre
\'\'\'
<emphasis role="bold">This is direct XML markup</emphasis>
\'\'\'
]

'''
<emphasis role="bold">This is direct XML markup</emphasis>
'''

[important Be careful when using the escape. The text must conform to
__boostbook__/__docbook__ syntax.]

[endsect]
[section Single char escape]

The backslash may be used to escape a single punctuation character. The
punctuation immediately after the backslash is passed without any processing.
This is useful when we need to escape QuickBook punctuations such as `[` and `]`.
For example, how do you escape the triple quote? Simple: [^\\'\\'\\']


`\n` has a special meaning. It is used to generate line breaks.

[warning `\n` and `[br]` are now deprecated. __blurbs__, __admonitions__
and table cells (see __tables__) may now contain paragraphs.]

The escaped space: `\ ` also has a special meaning. The escaped space is removed
from the output.

[endsect]
[section Unicode escape]

You can enter any 16-bit unicode character by using `\u` followed by its 4 digit
hexadecimal code, or a 32-bit character by using `\U` followed by an 8 digit
hexadecimal code. eg.

[pre'''
\u03B1 + \u03B2
''']

will generate:

[:
\u03B1 + \u03B2
]

[endsect]
[section Images]

[pre'''
[$image.jpg]
''']

From version 1.5, you can also use
[@http://www.docbook.org/tdg/en/html/imagedata.html
DocBook imagedata attributes]:

[pre'''
[$image.jpg [width 200in] [height 200in]]
''']

[endsect]
[section Footnotes]

As of version 1.3, QuickBook supports footnotes. Just put the text of the
footnote in a `[footnote]` block, and the text will be put at the bottom
of the current page. For example, this:

[pre'''
[footnote A sample footnote]
''']

will generate this[footnote A sample footnote].

[section Macro Expansion]

[pre'''
__a_macro_identifier__
''']

See __macros__ for details.

[endsect]

[section Template Expansion]

[pre'''
[a_template_identifier]
''']

See __templates__ for details.

[endsect]

[endsect]

[section:cond Conditional Generation]

Like C++ `#ifdef`, you can generate phrases depending on the presence of
a macro. Example:

[pre'''
[? __to_be__ To be or not to be]
''']

[? __to_be__ To be or not to be]

Here, the phrase "To be or not to be" will only be generated if the
macro symbol '''__to_be__''' has been previously defined. The phrase
above will not do anything since we haven't defined '''__to_be__'''.
Now, let's define the symbol:

[pre'''
[def __to_be__]
''']

[def __to_be__]

And try again:

[? __to_be__ To be or not to be]

Yes![footnote Conditional Generation makes quickbook turing complete.]

[endsect]

[endsect]
[section:block Block Level Elements]

[section Document]

Every document must begin with a Document Info section, which should look
like this:

[pre'''
[document-type The Document Title
    [quickbook 1.5]
    [version 1.0]
    [id the_document_name]
    [dirname the_document_dir]
    [copyright 2000 2002 2003 Joe Blow, Jane Doe]
    [purpose The document's reason for being]
    [category The document's category]
    [authors [Blow, Joe] [Doe, Jane]]
    [license The document's license]
    [source-mode source-type]
]
''']

Where document-type is one of:

* book
* article
* library
* chapter
* part
* appendix
* preface
* qandadiv
* qandaset
* reference
* set

quickbook 1.5 declares the version of quickbook the document is written for.
In its absence, version 1.1 is assumed.

=version=, =id=, =dirname=, =copyright=, =purpose=, =category=, =authors=,
=license=, =last-revision= and =source-mode= are optional information.

=dirname=, =purpose= and =category= are boostbook attributes which are only
valid for =library= documents. If you use them for other document types,
quickbook will warn about them, but still use them, generating invalid markup,
that's just ignored by the style sheets.

=source-type= is a lowercase string setting the initial __source_mode__. If
the =source-mode= field is omitted, a default value of =c++= will be used.

[endsect]
[section Section]

Starting a new section is accomplished with:

[pre'''
[section:id The Section Title]
''']

where /id/ is optional. id will be the filename of the generated section.
If it is not present, "The Section Title" will be normalized and become the id.
Valid characters are =a-Z=, =A-Z=, =0-9= and =_=. All non-valid characters are
converted to underscore and all upper-case are converted to lower case.
Thus: "The Section Title" will be normalized to "the_section_title".

End a section with:

[pre'''
[endsect]
''']

Sections can nest, and that results in a hierarchy in the table of contents.

[endsect]
[section xinclude]

You can include another XML file with:

[pre'''
[xinclude file.xml]
''']

This is useful when file.xml has been generated by Doxygen and contains your
reference section.

[endsect]
[section Paragraphs]

Paragraphs start left-flushed and are terminated by two or more newlines. No
markup is needed for paragraphs. QuickBook automatically detects paragraphs from
the context. Block markups \[section, endsect, h1, h2, h3, h4, h5, h6, blurb,
(block-quote) ':', pre, def, table and include \] may also terminate a paragraph.
 [/ <-- There's a space here. Don't remove. this is intentianal, for testing]
This is a new paragraph...

[endsect]

[section Lists]
[section Ordered lists]

[pre
# One
# Two
# Three
]

will generate:

# One
# Two
# Three

[endsect]
[section List Hierarchies]

List hierarchies are supported. Example:

[pre
# One
# Two
# Three
    # Three.a
    # Three.b
    # Three.c
# Four
    # Four.a
        # Four.a.i
        # Four.a.ii
# Five
]

will generate:

# One
# Two
# Three
    # Three.a
    # Three.b
    # Three.c
# Fourth
    # Four.a
        # Four.a.i
        # Four.a.ii
# Five

[endsect]
[section Long List Lines]

Long lines will be wrapped appropriately. Example:

[pre
# A short item.
# A very long item. A very long item. A very long item.
  A very long item. A very long item. A very long item.
  A very long item. A very long item. A very long item.
  A very long item. A very long item. A very long item.
  A very long item. A very long item. A very long item.
# A short item.
]

# A short item.
# A very long item. A very long item. A very long item.
  A very long item. A very long item. A very long item.
  A very long item. A very long item. A very long item.
  A very long item. A very long item. A very long item.
  A very long item. A very long item. A very long item.
# A short item.

[endsect]
[section Unordered lists]

[pre'''
* First
* Second
* Third
''']

will generate:

* First
* Second
* Third

[endsect]
[section Mixed lists]

Mixed lists (ordered and unordered) are supported. Example:

[pre'''
# One
# Two
# Three
    * Three.a
    * Three.b
    * Three.c
# Four
''']

will generate:

# One
# Two
# Three
    * Three.a
    * Three.b
    * Three.c
# Four

And...

[pre'''
# 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
''']

will generate:

# 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]
[endsect]

[section Code]

Preformatted code starts with a space or a tab. The code will be
syntax highlighted according to the current __source_mode__:

[c++]

    #include <iostream>

    int main()
    {
        // Sample code
        std::cout << "Hello, World\n";
        return 0;
    }

[python]

    import cgi

    def cookForHtml(text):
        '''"Cooks" the input text for HTML.'''

        return cgi.escape(text)

[c++]

Macros that are already defined are expanded in source code. Example:

[pre'''
[def __array__ [@http://www.boost.org/doc/html/array/reference.html array]]
[def __boost__ [@http://www.boost.org/libs/libraries.htm boost]]

    using __boost__::__array__;
''']

Generates:

[def __array__ [@http://www.boost.org/doc/html/array/reference.html array]]
[def __boost__ [@http://www.boost.org/libs/libraries.htm boost]]

    using __boost__::__array__;

[endsect]
[section:escape_back Escaping Back To QuickBook]

Inside code, code blocks and inline code, QuickBook does not allow any
markup to avoid conflicts with the target syntax (e.g. c++). In case you
need to switch back to QuickBook markup inside code, you can do so using a
language specific /escape-back/ delimiter. In C++ and Python, the delimiter
is the double tick (back-quote): "\`\`" and "\`\`". Example:

[pre'''
void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``()
{
}
''']

Will generate:

    void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``()
    {
    }

When escaping from code to QuickBook, only phrase level markups are
allowed. Block level markups like lists, tables etc. are not allowed.

[endsect]
[section Preformatted]

Sometimes, you don't want some preformatted text to be parsed as C++. In such
cases, use the [^[pre ... \]] markup block.

[pre'''
[pre

    Some *preformatted* text                    Some *preformatted* text

        Some *preformatted* text            Some *preformatted* text

            Some *preformatted* text    Some *preformatted* text

]
''']

Spaces, tabs and newlines are rendered as-is. Unlike all quickbook block level
markup, pre (and Code) are the only ones that allow multiple newlines. The
markup above will generate:

[pre

Some *preformatted* text                    Some *preformatted* text

    Some *preformatted* text            Some *preformatted* text

        Some *preformatted* text    Some *preformatted* text

]

Notice that unlike Code, phrase markup such as font style is still permitted
inside =pre= blocks.

[endsect]
[section Blockquote]

[pre
'''[:sometext...]'''
]

[:Indents the paragraph. This applies to one paragraph only.]

[endsect]
[section Admonitions]

[pre'''
[note This is a note]
[tip This is a tip]
[important This is important]
[caution This is a caution]
[warning This is a warning]
''']

generates __docbook__ admonitions:

[note This is a note]
[tip This is a tip]
[important This is important]
[caution This is a caution]
[warning This is a warning]

These are the only admonitions supported by __docbook__. So,
for example [^\[information This is some information\]] is unlikely
to produce the desired effect.

[endsect]
[section Headings]

[pre'''
[h1 Heading 1]
[h2 Heading 2]
[h3 Heading 3]
[h4 Heading 4]
[h5 Heading 5]
[h6 Heading 6]
''']

[h1 Heading 1]
[h2 Heading 2]
[h3 Heading 3]
[h4 Heading 4]
[h5 Heading 5]
[h6 Heading 6]

Headings 1-3 \[h1 h2 and h3\] will automatically have anchors with
normalized names with
[^name="document_id.section_id.normalized_header_text"] (i.e. valid
characters are =a-z=, =A-Z=, =0-9= and =_=. All non-valid characters are
converted to underscore and all upper-case are converted to lower-case.
For example: Heading 1 in section Section 2 will be normalized to
[^section_2.heading_1]). You can use:

[pre'''
[link document_id.section_id.normalized_header_text The link text]
''']

to link to them. See __anchor_links__ and __section__ for more info.

[endsect]
[section Generic Heading]

In cases when you don't want to care about the heading level (1 to 6), you
can use the /Generic Heading/:

[pre'''
[heading Heading]
''']

The /Generic Heading/ assumes the level, plus one, of the innermost section
where it is placed. For example, if it is placed in the outermost section,
then, it assumes /h2/.

Headings are often used as an alternative to sections. It is used
particularly if you do not want to start a new section. In many cases,
however, headings in a particular section is just flat. Example:

[pre'''
[section A]
[h2 X]
[h2 Y]
[h2 Z]
[endsect]
''']

Here we use h2 assuming that section A is the outermost level. If it is
placed in an inner level, you'll have to use h3, h4, etc. depending on
where the section is. In general, it is the section level plus one. It is
rather tedious, however, to scan the section level everytime. If you
rewrite the example above as shown below, this will be automatic:

[pre'''
[section A]
[heading X]
[heading Y]
[heading Z]
[endsect]
''']

They work well regardless where you place them. You can rearrange sections
at will without any extra work to ensure correct heading levels. In fact,
with /section/ and /heading/, you have all you need. /h1/../h6/ becomes
redundant. /h1/../h6/ might be deprecated in the future.

[endsect]
[section Macros]

[pre'''
[def macro_identifier some text]
''']

When a macro is defined, the identifier replaces the text anywhere in the
file, in paragraphs, in markups, etc. macro_identifier is a string of non-
white space characters except '\]'. A macro may not follow an alphabetic
character or the underscore. The replacement text can be any phrase (even
marked up). Example:

[pre'''
[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&amp;type=1]]
sf_logo
''']

Now everywhere the sf_logo is placed, the picture will be inlined.

[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&type=1]]
sf_logo

[tip It's a good idea to use macro identifiers that are distinguishable.
For instance, in this document, macro identifiers have two leading and
trailing underscores (e.g. [^'''__spirit__''']). The reason is to avoid
unwanted macro replacement.]

Links (URLS) and images are good candidates for macros. *1*) They tend to
change a lot. It is a good idea to place all links and images in one place near the top
to make it easy to make changes. *2*) The syntax is not pretty. It's easier to read and
write, e.g. [^'''__spirit__'''] than [^'''[@http://spirit.sourceforge.net Spirit]'''].

Some more examples:

[pre'''
[def :-)            [$theme/smiley.png]]
[def __spirit__     [@http://spirit.sourceforge.net Spirit]]
''']

(See __images__ and __links__)

Invoking these macros:

[pre'''
Hi __spirit__  :-)
''']

will generate this:

Hi __spirit__ :-)

[endsect]
[section Predefined Macros]

Quickbook has some predefined macros that you can already use.

[table Predefined Macros
    [[Macro]                [Meaning]                       [Example]]
    [['''__DATE__''']       [Today's date]                  [__DATE__]]
    [['''__TIME__''']       [The current time]              [__TIME__]]
    [['''__FILENAME__''']   [Quickbook source filename]     [__FILENAME__]]
]

[endsect]
[section Templates]

Templates provide a more versatile text substitution mechanism. Templates
come in handy when you need to create parameterizable, multi-line,
boilerplate text that you specify once and expand many times. Templates
accept one or more arguments. These arguments act like place-holders for
text replacement. Unlike simple macros, which are limited to phrase level
markup, templates can contain block level markup (e.g. paragraphs, code
blocks and tables).

Example template:

[pre'''
[template person[name age what]

Hi, my name is [name]. I am [age] years old. I am a [what].

]
''']

[template person[name age what]

Hi, my name is [name]. I am [age] years old. I am a [what].

]

[heading Template Identifier]

Template identifiers can either consist of:

* An initial alphabetic character or the underscore, followed by
  zero or more alphanumeric characters or the underscore. This is
  similar to your typical C/C++ identifier.
* A single character punctuation (a non-alphanumeric printable character)

[heading Formal Template Arguments]

Template formal arguments are identifiers consisting of an initial
alphabetic character or the underscore, followed by zero or more
alphanumeric characters or the underscore. This is similar to your typical
C/C++ identifier.

A template formal argument temporarily hides a template of the same name at
the point where the [link quickbook.syntax.block.templates.template_expansion
template is expanded]. Note that the body of the [^person] template above
refers to [^name] [^age] and [^what] as [^\[name\]] [^\[age\]] and
[^\[what\]]. [^name] [^age] and [^what] are actually templates that exist
in the duration of the template call.

[heading Template Body]

The template body can be just about any QuickBook block or phrase. There
are actually two forms. Templates may be phrase or block level. Phrase
templates are of the form:

[pre'''
[template sample[arg1 arg2...argN] replacement text... ]
''']

Block templates are of the form:

[pre'''
[template sample[arg1 arg2...argN]
replacement text...
]
''']

The basic rule is as follows: if a newline immediately follows the argument
list, then it is a block template, otherwise, it is a phrase template.
Phrase templates are typically expanded as part of phrases. Like macros,
block level elements are not allowed in phrase templates.

[heading Template Expansion]

You expand a template this way:

[pre'''
[template_identifier arg1..arg2..arg3]
''']

At template expansion, you supply the actual arguments. The template will
be expanded with your supplied arguments. Example:

[pre'''
[person James Bond..39..Spy]
[person Santa Clause..87..Big Red Fatso]
''']

Which will expand to:

[person James Bond..39..Spy]
[person Santa Clause..87..Big Red Fatso]

[caution A word of caution: Templates are recursive. A template can call
another template or even itself, directly or indirectly. There are no
control structures in QuickBook (yet) so this will always mean infinite
recursion. QuickBook can detect this situation and report an error if
recursion exceeds a certain limit.]

Each actual argument can be a word, a text fragment or just about any [link
quickbook.syntax.phrase QuickBook phrase]. Arguments are separated by the
double dot [^".."] and terminated by the close parenthesis.

[heading Nullary Templates]

Nullary templates look and act like simple macros. Example:

[pre'''
[template alpha[]&apos;&apos;&apos;&amp;#945;&apos;&apos;&apos;]
[template beta[]&apos;&apos;&apos;&amp;#946;&apos;&apos;&apos;]
''']

[template alpha[]'''&#945;''']
[template beta[]'''&#946;''']

Expanding:

[pre'''Some squigles...[*[alpha][beta]]''']

We have:

Some squiggles...[*[alpha][beta]]

The difference with macros are

* The explicit [link quickbook.syntax.block.templates.template_expansion
  template expansion syntax]. This is an advantage because, now, we don't
  have to use obscure naming conventions like double underscores (e.g.
  \_\_alpha\_\_) to avoid unwanted
  macro replacement.
* The template is expanded at the point where it is invoked. A macro is
  expanded immediately at its point of declaration. This is subtle and
  can cause a slight difference in behavior especially if you refer to
  other macros and templates in the body.

The empty brackets after the template identifier ([^alpha\[\]]) indicates no
arguments. If the template body does not look like a template argument list, we
can elide the empty brackets. Example:

[pre'''
[template aristotle_quote Aristotle: [*['Education is the best provision
for the journey to old age.]]]
''']

[template aristotle_quote\ Aristotle: [*['Education is the best provision
for the journey to old age.]]]

Expanding:

[pre'''
Here's a quote from [aristotle_quote].
''']

We have:

Here's a quote from [aristotle_quote].

The disadvantage is that you can't avoid the space between the template
identifier, `aristotle_quote`, and the template body "Aristotle...". This space
will be part of the template body. If that space is unwanted, use empty
brackets or use the space escape: "`\ `". Example:

[pre'''
[template tag\ _tag]
''']

[template tag\ _tag]

Then expanding:

[pre'''
`struct` x[tag];
''']

We have:

`struct` x[tag];

You have a couple of ways to do it. I personally prefer the explicit empty
brackets, though.

[heading Simple Arguments]

As mentioned, arguments are separated by the double dot [^".."]. Alternatively,
if the double dot isn't used and more than one argument is expected, QuickBook
uses whitespace to separate the arguments, following this logic:

* Break the last argument into two, at the first space found ([^'', '\\n',
  \\t' or '\\r']).
* Repeat until there are enough arguments or if there are no more spaces
  found (in which case, an error is reported).

For example:

[pre'''
[template simple[a b c d] [a][b][c][d]]
[simple w x y z]
''']

will produce:

[template simple[a b c d] [a][b][c][d]]
[simple w x y z]

"w x y z" is initially treated as a single argument because we didn't
supply any [^".."] separators. However, since [^simple] expects 4
arguments, "w x y z" is broken down iteratively (applying the logic above)
until we have "w", "x", "y" and "z".

QuickBook only tries to get the arguments it needs. For example:

[pre'''
[simple w x y z trail]
''']

will produce:

[simple w x y z trail]

The arguments being: "w", "x", "y" and "z trail".

[caution The behavior described here is for QuickBook 1.5. In older versions you
could use both the double dot and whitespace as separators in the same template
call. If your document is marked up as an older version, it will use the old
behavior, which is described in the
[@http://www.boost.org/doc/libs/1_40_0/doc/html/quickbook/syntax.html#quickbook.syntax.block.templates.simple_arguments
QuickBook 1.4 documentation].]

[heading Punctuation Templates]

With templates, one of our objectives is to allow us to rewrite QuickBook
in QuickBook (as a qbk library). For that to happen, we need to accommodate
single character punctuation templates which are fairly common in
QuickBook. You might have noticed that single character punctuations are
allowed as [link quickbook.syntax.block.templates.template_identifier
template identifiers]. Example:

[pre'''
[template ![bar] '''<hey>'''[bar]'''</hey>''']
''']

Now, expanding this:

[pre'''
[!baz]
''']

We will have:

[pre
<hey>baz</hey>
]

[endsect]
[section Blurbs]

[pre'''
[blurb :-) [*An eye catching advertisement or note...]

    __spirit__ is an object-oriented recursive-descent parser generator framework
    implemented using template meta-programming techniques. Expression templates
    allow us to approximate the syntax of Extended Backus-Normal Form (EBNF)
    completely in C++.
]
''']

will generate this:

[blurb :-) [*An eye catching advertisement or note...]

    __spirit__ is an object-oriented recursive-descent parser generator
    framework implemented using template meta-programming techniques. Expression
    templates allow us to approximate the syntax of Extended Backus-Normal Form
    (EBNF) completely in C++.
]

[note Prefer [link quickbook.syntax.block.admonitions admonitions] wherever
appropriate.]

[endsect]
[section Tables]

[pre'''
[table:id A Simple Table
    [[Heading 1] [Heading 2] [Heading 3]]
    [[R0-C0]     [R0-C1]     [R0-C2]]
    [[R1-C0]     [R1-C1]     [R1-C2]]
    [[R2-C0]     [R2-C1]     [R2-C2]]
]
''']

will generate:

[table:id A Simple Table
    [[Heading 1] [Heading 2] [Heading 3]]
    [[R0-C0]     [R0-C1]     [R0-C2]]
    [[R1-C0]     [R1-C1]     [R1-C2]]
    [[R2-C0]     [R2-C1]     [R2-C2]]
]

The table title is optional. The first row of the table is automatically
treated as the table header; that is, it is wrapped in [^<thead>...</thead>]
XML tags. Note that unlike the original QuickDoc, the columns are nested in
[cells... ].

Giving tables an id is a new feature for quickbook 1.5 onwards. As with
sections, the id is optional. If the table has a title but no id, an id will
be generated from the title. The table above can be linked to using:

[pre'''
[link quickbook.syntax.block.tables.id link to table]
''']

which will generate:

[link quickbook.syntax.block.tables.id link to table]

The syntax is free-format and allows big cells to be formatted
nicely. Example:

[pre'''
[table Table with fat cells
    [[Heading 1] [Heading 2]]
    [
        [Row 0, Col 0: a small cell]
        [
            Row 0, Col 1: a big fat cell with paragraphs

            Boost provides free peer-reviewed portable C++ source libraries.

            We emphasize libraries that work well with the C++ Standard Library.
            Boost libraries are intended to be widely useful, and usable across
            a broad spectrum of applications. The Boost license encourages both
            commercial and non-commercial use.
        ]
    ]
    [
        [Row 1, Col 0: a small cell]
        [Row 1, Col 1: a small cell]
    ]
]
''']

and thus:

[table Table with fat cells
    [[Heading 1] [Heading 2]]
    [
        [Row 0, Col 0: a small cell]
        [
            Row 0, Col 1: a big fat cell with paragraphs

            Boost provides free peer-reviewed portable C++ source libraries.
 [/ <-- There's a space here. Don't remove. This is intentional, for testing]
            We emphasize libraries that work well with the C++ Standard Library.
            Boost libraries are intended to be widely useful, and usable across
            a broad spectrum of applications. The Boost license encourages both
            commercial and non-commercial use.
        ]
    ]
    [
        [Row 1, Col 0: a small cell]
        [Row 1, Col 1: a small cell]
    ]
]

Here's how to have preformatted blocks of code in a table cell:

[pre'''
[table Table with code
    [[Comment] [Code]]
    [
        [My first program]
        ['''\`\`
            #include <iostream>

            int main()
            {
                std::cout << "Hello, World!" << std::endl;
                return 0;
            }
        \`\`''']
    ]
]
''']

[table Table with code
    [[Comment] [Code]]
    [
        [My first program]
        [``
            #include <iostream>

            int main()
            {
                std::cout << "Hello, World!" << std::endl;
                return 0;
            }
        ``]
    ]
]

[endsect]
[section Variable Lists]

[pre'''
[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.

    Definitions may contain paragraphs.
    ]]
]
''']

will generate:

[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.

    Definitions may contain paragraphs.
    ]]
]

The rules for variable lists are the same as for tables, except that
only 2 "columns" are allowed. The first column contains the terms, and
the second column contains the definitions. Those familiar with HTML
will recognize this as a "definition list".

[endsect]
[section Include]

You can include one QuickBook file from another. The syntax is simply:

[pre'''
[include someother.qbk]
''']

The included file will be processed as if it had been cut and pasted
into the current document, with the following exceptions:

* The '''__FILENAME__''' predefined macro will reflect the name of the
  file currently being processed.
* Any macros defined in the included file are scoped to that file.

The [^\[include\]] directive lets you specify a document id to use for the
included file. When this id is not explicitly specified, the id defaults to
the filename ("someother", in the example above). You can specify the id
like this:

[pre'''
[include:someid someother.qbk]
''']

All auto-generated anchors will use the document id as a unique prefix. So
for instance, if there is a top section in someother.qbk named "Intro", the
named anchor for that section will be "someid.intro", and you can link to
it with [^\[link someid.intro The Intro\]].

[endsect]

[section Import]

When documenting code, you'd surely need to present code from actual source
files. While it is possible to copy some code and paste them in your QuickBook
file, doing so is error prone and the extracted code in the documentation tends
to get out of sync with the actual code as the code evolves. The problem, as
always, is that once documentation is written, the tendency is for the docs to
languish in the archives without maintenance.

QuickBook's import facility provides a nice solution.

[heading Example]

You can effortlessly import code snippets from source code into your QuickBook.
The following illustrates how this is done:

[pre'''
[import ../test/stub.cpp]
[foo]
[bar]
''']

The first line:

[pre'''
[import ../test/stub.cpp]
''']

collects specially marked-up code snippets from
[@boost:/tools/quickbook/test/stub.cpp stub.cpp]
and places them in your QuickBook file as virtual templates. Each of the
specially marked-up code snippets has a name (e.g. `foo` and `bar` in the
example above). This shall be the template identifier for that particular code
snippet. The second and third line above does the actual template expansion:

[pre'''
[foo]
[bar]
''']

And the result is:

[import ../test/stub.cpp]
[foo]
[bar]

[heading Code Snippet Markup]

Note how the code snippets in [@boost:/tools/quickbook/test/stub.cpp stub.cpp]
get marked up. We use distinguishable comments following the form:

    //[id
    some code here
    //]

The first comment line above initiates a named code-snippet. This prefix will
not be visible in quickbook. The entire code-snippet in between `//[id` and
`//]` will be inserted as a template in quickbook with name ['/id/]. The comment
`//]` ends a code-snippet This too will not be visible in quickbook.

[heading Special Comments]

Special comments of the form:

    //` some [*quickbook] markup here

and:

    /*` some [*quickbook] markup here */

will be parsed by QuickBook. This can contain quickbook /blocks/ (e.g. sections,
paragraphs, tables, etc). In the first case, the initial slash-slash, tick and
white-space shall be ignored. In the second, the initial slash-star-tick and the
final star-slash shall be ignored.

Special comments of the form:

    /*<- this C++ comment will be ignored ->*/

or

    /*<-*/ "this c++ code  will be ignored" /*->*/

or

    //<-
    private:
        int some_member;
    //->

can be used to inhibit code from passing through to quickbook. All text between
the delimeters will simply be ignored.

[heading Callouts]

Special comments of the form:

    /*< some [*quickbook] markup here >*/

will be regarded as callouts. These will be collected, numbered and
rendered as a "callout bug" (a small icon with a number). After the
whole snippet is parsed, the callout list is generated. See
[@http://www.docbook.org/tdg/en/html/callout.html Callouts] for details.
Example:

[foo_bar]

This is the actual code:

    //[ foo_bar
    std::string foo_bar() /*< The /Mythical/ FooBar.
                          See [@http://en.wikipedia.org/wiki/Foobar Foobar for details] >*/
    {
        return "foo-bar"; /*< return 'em, foo-bar man! >*/
    }
    //]

The callouts bugs are placed exactly where the special callout comment
is situated. It can be anywhere in the code. The bugs can be rather
obtrusive, however. They get in the way of the clarity of the code.
Another special callout comment style is available:

    /*<< some [*quickbook] markup here >>*/

This is the line-oriented version of the callout. With this, the "bug"
is placed at the very left of the code block, away from the actual code.
By placing it at the far left, the code is rendered un-obscured.
Example:

[class_]

See the actual code here: [@boost:/tools/quickbook/test/stub.cpp]

[endsect]

[endsect]
[endsect]

[section:install Installation and configuration]

This section provides some guidelines on how to install and configure
BoostBook and Quickbook under several operating systems.

Before continuing, it is very important that you keep this in mind: if you
try to build some documents and the process breaks due to misconfiguration,
be absolutely sure to delete any `bin` and `bin.v2` directories generated
by the build before trying again.  Otherwise your configuration fixes will
not take any effect.

[section:macosx Mac OS X]

[:['Section contributed by Julio M. Merino Vidal]]

The following instructions explain how to install Docbook XML, Docbook XSL
and Doxygen in a Mac OS X system, how to configure Boost.Build v2 to
recognize them and how to build and install Quickbook.  They were taken
from a 10.4 (Tiger) machine so it is likely that they also apply to future
versions; they may not work with older ones, though.

The text below assumes you want to install all the necessary utilities in a
system-wide location, allowing any user in the machine to have access to
them. Therefore, all files will be put in the `/usr/local` hierarchy.  If
you do not want this, you can choose any other prefix such as
`~/Applications` for a single-user installation.

Mac OS X comes with `xsltproc` and all related libraries preinstalled, so
you do not need to take any extra steps to set them up.  It is probable
that future versions will include them too, but these instructions may not
apply to older versions.

To get started:

# Download [@http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip Docbook XML
  4.2] and unpack it inside `/usr/local/share/xml/docbook/4.2`.

# Download the latest
  [@http://sourceforge.net/project/showfiles.php?group_id=21935&package_id=16608
  Docbook XSL] version and unpack it.  Put the results in
  `/usr/local/share/xsl/docbook`, thus effectively removing the version
  number from the directory name (for simplicity).

# Add the following to your `user-config.jam` file, which should live in
  your home directory (`/Users/<your_username>`).  You must already have it
  somewhere or otherwise you could not be building Boost (i.e. missing
  tools configuration).

 using xsltproc ;

 using boostbook
     : "/usr/local/share/xsl/docbook"
     : "/usr/local/share/xml/docbook/4.2"
     ;

The above steps are enough to get a functional BoostBook setup.  Quickbook
will be automatically built when needed.  If you want to avoid these
rebuilds and install a system-wide Quickbook instead:

# Go to Quickbook's source directory (`BOOST_ROOT/tools/quickbook`).

# Build the utility by issuing `bjam`.

# Copy the resulting `quickbook` binary (located under the
  `BOOST_ROOT/bin.v2` hierarchy) to a safe place.  Following our previous
  example, you can install it into: `/usr/local/bin`.

# Add the following to your `user-config.jam` file:

 using quickbook
     : "/usr/local/bin/quickbook" ;
     ;

Additionally, if you need to build documentation that uses
[@http://www.doxygen.org Doxygen], you will need to install it too:

# Go to the [@http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc
  downloads section] and get the disk image (`dmg` file) for Mac OS X.

# Open the disk image and drag the Doxygen application to your
  `Applications` folder to install it.

# Add the following to your `user-config.jam` file:

 using doxygen
     : /Applications/Doxygen.app/Contents/Resources/doxygen
     ;

Alternatively, you may want to install all the prerequistes through a
package system to avoid manual management of the installations.  In that
case, check out [@http://www.pkgsrc.org pkgsrc].

[endsect]

[section:windows Windows 2000, XP, 2003, Vista]

[python]

[:['Section contributed by Julio M. Merino Vidal]]

The following instructions apply to any Windows system based on Windows
2000, including Windows XP, Windows 2003 Server and Windows Vista. The
paths shown below are taken from a Windows Vista machine; you will need to
adjust them to match your system in case you are running an older version.

# First of all you need to have a copy of `xsltproc` for Windows.  There
  are many ways to get this tool, but to keep things simple, use the
  [@http://www.zlatkovic.com/pub/libxml/ binary packages] made by Igor
  Zlatkovic.  At the very least, you need to download the following
  packages: `iconv`, `zlib`, `libxml2` and `libxslt`.

# Unpack all these packages in the same directory so that you get unique
  `bin`, `include` and `lib` directories within the hierarchy.  These
  instructions use `C:\Users\example\Documents\boost\xml` as the root for
  all files.

# From the command line, go to the `bin` directory and launch
  `xsltproc.exe` to ensure it works.  You should get usage information on
  screen.

# Download [@http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip Docbook XML
  4.2] and unpack it in the same directory used above.  That is:
  `C:\Users\example\Documents\boost\xml\docbook-xml`.

# Download the latest
  [@http://sourceforge.net/project/showfiles.php?group_id=21935&package_id=16608
  Docbook XSL] version and unpack it, again in the same directory
  used before.  To make things easier, rename the directory created
  during the extraction to `docbook-xsl` (bypassing the version name):
  `C:\Users\example\Documents\boost\xml\docbook-xsl`.

# Add the following to your `user-config.jam` file, which should live in
  your home directory (`%HOMEDRIVE%%HOMEPATH%`).  You must already have it
  somewhere or otherwise you could not be building Boost (i.e. missing
  tools configuration).

 using xsltproc
     : "C:/Users/example/Documents/boost/xml/bin/xsltproc.exe"
     ;

 using boostbook
     : "C:/Users/example/Documents/boost/xml/docbook-xsl"
     : "C:/Users/example/Documents/boost/xml/docbook-xml"
     ;

The above steps are enough to get a functional BoostBook setup.  Quickbook
will be automatically built when needed.  If you want to avoid these
rebuilds:

# Go to Quickbook's source directory (`BOOST_ROOT\tools\quickbook`).

# Build the utility by issuing `bjam`.

# Copy the resulting `quickbook.exe` binary (located under the
  `BOOST_ROOT\bin.v2` hierarchy) to a safe place.  Following our previous
  example, you can install it into:
  `C:\Users\example\Documents\boost\xml\bin`.

# Add the following to your `user-config.jam` file:

 using quickbook
     : "C:/Users/example/Documents/boost/xml/bin/quickbook.exe"
     ;

[endsect]

[section:linux Debian, Ubuntu]

The following instructions apply to Debian and its derivatives. They are based
on a Ubuntu Edgy install but should work on other Debian based systems.

First install the `bjam`, `xsltproc`, `docbook-xsl` and `docbook-xml` packages.
For example, using `apt-get`:

    sudo apt-get install xsltproc docbook-xsl docbook-xml

If you're planning on building boost's documentation, you'll also need to
install the `doxygen` package as well.

Next, we need to configure Boost Build to compile BoostBook files. Add the
following to your `user-config.jam` file, which should be in your home
directory. If you don't have one, create a file containing this text. For more
information on setting up `user-config.jam`, see the
[@http://boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html Boost
Build documentation].

    using xsltproc ;

    using boostbook
        : /usr/share/xml/docbook/stylesheet/nwalsh
        : /usr/share/xml/docbook/schema/dtd/4.2
        ;

    # Remove this line if you're not using doxygen
    using doxygen ;

The above steps are enough to get a functional BoostBook setup.  Quickbook
will be automatically built when needed.  If you want to avoid these
rebuilds:

# Go to Quickbook's source directory (`BOOST_ROOT/tools/quickbook`).

# Build the utility by issuing `bjam`.

# Copy the resulting `quickbook` binary (located under the
  `BOOST_ROOT/bin.v2` hierarchy) to a safe place.  The traditional location is
  `/usr/local/bin`.

# Add the following to your `user-config.jam` file, using the full path of the
  quickbook executable:

 using quickbook
     : /usr/local/bin/quickbook
     ;

[endsect]
[endsect] [/Installation and configuration]

[section:editors Editor Support]

Editing quickbook files is usually done with text editors both simple and
powerful. The following sections list the settings for some editors which can
help make editing quickbook files a bit easier.

[note You may submit your settings, tips, and suggestions to the
authors, or through the [@https://lists.sourceforge.net/lists/listinfo/boost-
docs Boost Docs mailing list].]

[section:scite Scintilla Text Editor]

[:['Section contributed by Dean Michael Berris]]

The Scintilla Text Editor (SciTE) is a free source code editor for Win32 and X.
It uses the SCIntilla source code editing component.

[tip SciTE can be downloaded from [@http://www.scintilla.org/SciTE.html]]

You can use the following settings to highlight quickbook tags when
editing quickbook files.

[pre'''
qbk=*.qbk
lexer.*.qbk=props
use.tabs.$(qbk)=0
tab.size.$(qbk)=4
indent.size.$(qbk)=4
style.props.32=$(font.base)
comment.stream.start.props=[/
comment.stream.end.props=]
comment.box.start.props=[/
comment.box.middle.props=
comment.box.end.props=]
''']

[note Thanks to Rene Rivera for the above SciTE settings.]

[endsect] [/scite]

[/ KDE support (Kate, KWrite, Konqueror, KDevelop) ]
[include ../extra/katepart/katepart.qbk]

[endsect] [/editors]

[section:faq Frequently Asked Questions]

[heading Can I use QuickBook for non-Boost documentation?]

QuickBook can be used for non-Boost documentation with a little extra work.

[:['Faq contributed by Michael Marcin]]

When building HTML documentation with BoostBook a Boost C++ Libraries header
is added to the files. When using QuickBook to document projects outside of
Boost this is not desirable. This behavior can be overridden at the BoostBook
level by specifying some XSLT options. When using Boost Build version 2 (BBv2)
this can be achieved by adding parameters to the BoostBook target declaration.

For example:
[pre
using quickbook ;

xml my_doc : my_doc.qbk ;

boostbook standalone
    :
        my_doc
    :
        <xsl:param>boost.image.src\=images/my_project_logo.png
        <xsl:param>boost.image.alt\="\\"My Project\\""
        <xsl:param>boost.image.w=100
        <xsl:param>boost.image.h=50
        <xsl:param>nav.layout=none
    ;
]

[heading Is there an easy way to convert BoostBook docs to QuickBook?]

There's a stylesheet that allows Boostbook generated HTML to be viewed
as quickbook source, see
[@http://svn.boost.org/trac/boost/wiki/QuickbookSourceStylesheetProject],
so it's then just a cut and paste job to convert the BoostBook to
QuickBook (which IMO is a whole lot easier to edit and maintain).

--John Maddock

[endsect] [/faq]

[section:ref Quick Reference]

[c++]

[template ordered_list_sample[]
[pre'''
# one
# two
# three
''']
]

[template unordered_list_sample[]
[pre'''
* one
* two
* three
''']
]

[template table_sample[]
[pre'''
[table Title
[[a][b][c]]
[[a][b][c]]
]
''']
]

[template var_list_sample[]
[pre'''
[variablelist Title
[[a][b]]
[[a][b]]
]
''']
]


[table Syntax Compendium
    [[To do this...]        [Use this...]                                   [See this...]]
    [[comment]              [[^'''[/ some comment]''']]                     [__comments__]]
    [[['italics]]           [[^'''['italics] or /italics/''']]              [__font_styles__ and __simple_formatting__]]
    [[[*bold]]              [[^'''[*bold] or *bold*''']]                    [__font_styles__ and __simple_formatting__]]
    [[[_underline]]         [[^'''[_underline] or _underline_''']]          [__font_styles__ and __simple_formatting__]]
    [[[^teletype]]          [[^'''[^teletype] or =teletype=''']]            [__font_styles__ and __simple_formatting__]]
    [[[-strikethrough]]     [[^'''[-strikethrough]''']]                     [__font_styles__ and __simple_formatting__]]
    [[[~replaceable]]       [[^'''[~replaceable]''']]                       [__replaceable__]]
    [[source mode]          [[^\[c++\]] or [^\[python\]]]                   [__source_mode__]]
    [[inline code]          [[^'''`int main();`''']]                        [__inline_code__]]
    [[code block]           [[^'''``int main();``''']]                      [__code__]]
    [[code escape]          [[^'''``from c++ to QuickBook``''']]            [__escape_back__]]
    [[line break]           [[^'''[br] or \n''']]                           [__line_break__ *DEPRECATED*]]
    [[anchor]               [[^'''[#anchor]''']]                            [__anchors__]]
    [[link]                 [[^'''[@http://www.boost.org Boost]''']]        [__links__]]
    [[anchor link]          [[^'''[link section.anchor Link text]''']]      [__anchor_links__]]
    [[refentry link]        [[^'''[link xml.refentry Link text]''']]        [__refentry_links__]]
    [[function link]        [[^'''[funcref fully::qualified::function_name Link text]''']]      [__code_links__]]
    [[class link]           [[^'''[classref fully::qualified::class_name Link text]''']]        [__code_links__]]
    [[member link]          [[^'''[memberref fully::qualified::member_name Link text]''']]      [__code_links__]]
    [[enum link]            [[^'''[enumref fully::qualified::enum_name Link text]''']]          [__code_links__]]
    [[macro link]           [[^'''[macroref MACRO_NAME Link text]''']]                          [__code_links__]]
    [[concept link]         [[^'''[conceptref ConceptName Link text]''']]                       [__code_links__]]
    [[header link]          [[^'''[headerref path/to/header.hpp Link text]''']]                 [__code_links__]]
    [[global link]          [[^'''[globalref fully::qualified::global Link text]''']]           [__code_links__]]
    [[escape]               [[^\'\'\'escaped text (no processing/formatting)\'\'\']]            [__escape__]]
    [[single char escape]   [[^\\c]]                                        [__single_char_escape__]]
    [[images]               [[^'''[$image.jpg]''']]                         [__images__]]
    [[begin section]        [[^'''[section The Section Title]''']]          [__section__]]
    [[end section]          [[^'''[endsect]''']]                            [__section__]]
    [[paragraph]            [No markup. Paragraphs start left-flushed and are terminated by two or more newlines.]  [__paragraphs__]]
    [[ordered list]         [[ordered_list_sample]]                         [__ordered_lists__]]
    [[unordered list]       [[unordered_list_sample]]                       [__unordered_lists__]]
    [[code]                 [No markup. Preformatted code starts with a space or a tab.]        [__code__]]
    [[preformatted]         [[^'''[pre preformatted]''']]                   [__preformatted__]]
    [[block quote]          [[^'''[:sometext...]''']]                       [__blockquote__]]
    [[heading 1]            [[^'''[h1 Heading 1]''']]                       [__heading__]]
    [[heading 2]            [[^'''[h2 Heading 2]''']]                       [__heading__]]
    [[heading 3]            [[^'''[h3 Heading 3]''']]                       [__heading__]]
    [[heading 4]            [[^'''[h4 Heading 4]''']]                       [__heading__]]
    [[heading 5]            [[^'''[h5 Heading 5]''']]                       [__heading__]]
    [[heading 6]            [[^'''[h6 Heading 6]''']]                       [__heading__]]
    [[macro]                [[^'''[def macro_identifier some text]''']]     [__macros__]]
    [[template]             [[^'''[template[a b] [a] body [b]]''']]         [__templates__]]
    [[blurb]                [[^'''[blurb advertisement or note...]''']]     [__blurbs__]]
    [[admonition]           [[^'''[warning Warning text...]''']]            [__admonitions__]]
    [[table]                [[table_sample]]                                [__tables__]]
    [[variablelist]         [[var_list_sample]]                             [__variable_lists__]]
    [[include]              [[^'''[include someother.qbk]''']]              [__include__]]
    [[conditional generation]
                            [[^'''[? symbol phrase]''']]                    [__cond__]]
]

[endsect]