source: downloads/boost_1_34_1/tools/quickbook/doc/quickbook.qbk @ 35

[article Quickbook
    [quickbook 1.3]
    [version 1.3]
    [authors [de Guzman, Joel], [Niebler, Eric]]
    [copyright 2002 2004 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.3 ]
[/ Sept 24, 2002 ]
[/ Sept 2, 2004 ]
[/ Feb 14, 2005 ]
[/ Sept 13, 2005 ]

[/ Some links]

[def __note__       [$images/note.png]]
[def __alert__      [$images/alert.png]]
[def __tip__        [$images/tip.png]]
[def :-)            [$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 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 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 __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 __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]]

[section:intro Introduction]

[:[*['["Why program by hand in five days what you can spend five years of your
life automating?]]]\n\n-- 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:

[:[@../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   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.

[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) ]'''
]

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

* Simple markups cannot nest. You can combine a simple markup with a nestable 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 line, 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 line.
  We do not want the rest of the document to be rendered bold just because we
  forgot a trailing '*'.
* 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*]]]
]

[blurb __note__ 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.]

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

[blurb __note__
Note that 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\]]]]
]

[blurb __note__ The source mode strings are lowercase.]

[endsect]
[section line-break]

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

[blurb __note__ Note that `\n` is now preferred over `[br]`.]

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

[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/]

[endsect]
[section Anchor links]

You can link within a document using:

[pre'''
[link 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 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]
[headerref path/to/header.hpp The link text]
''']

Again, the link text is optional. If this is not present, the link text will
automatically be the function, class, member or enum. 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>
'''

[blurb __alert__ 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. Note that `\n`
is now preferred over `[br]`.

[endsect]
[section Images]

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

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

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

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

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

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="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 section_id.normalized_header_text The link text]
''']

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

[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 '\]' while 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

[blurb __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 Blurbs]

[pre'''
[blurb :-) [*An eye catching advertisement or note...]\n\n
    __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...]\n\n
    __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++.
]

[endsect]
[section Tables]

[pre'''
[table 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 A Simple Table
    [[Heading 1] [Heading 2] [Heading 3]]
    [[R0-C0]     [R0-C1]     [R0-C2]]
    [[R2-C0]     [R2-C1]     [R2-C2]]
    [[R3-C0]     [R3-C1]     [R3-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... ]. 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 very big cell...A very big cell...A very big cell...
            A very big cell...A very big cell...A very big cell...
            A very big cell...A very big cell...A very big cell...
        ]
    ]
    [
        [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 very big cell...A very big cell...A very big cell...
            A very big cell...A very big cell...A very big cell...
            A very big cell...A very big cell...A very big cell...
        ]
    ]
    [
        [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]]
]
''']

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]]
]

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

As the number of included QuickBook files grows, so too does the
likelihood of two sections having the same name. Since QuickBook generates
an anchor for each section based on the section name, it is possible to
end up with two identically named anchors, leading to link ambiguities.
To resolve these ambiguities, the [^\[include\]] directive lets you
specify a document id to use for the included file. You can use it like
this:

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

When using this form, all auto-generated anchors will use "someid" as
a unique prefix. So for instance, if there is a 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]
[endsect]
[endsect]
[section:ref Quick Reference]

[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__]]
    [[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__]]
    [[header link]          [[^'''[headerref path/to/header.hpp 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]         [[^# one\n# two\n# three\n]]                    [__ordered_lists__]]
    [[unordered list]       [[^\* one\n\* two\n\* three\n]]                 [__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__]]
    [[blurb]                [[^'''[blurb advertisement or note...]''']]     [__blurbs__]]
    [[admonition]           [[^'''[warning Warning text...]''']]            [__admonitions__]]
    [[table]                [[^[table Title\n \[\[a\]\[b\]\[c\]\]\n    \[\[a\]\[b\]\[c\]\]\n\]]]    [__tables__]]
    [[variablelist]         [[^[variablelist Title\n \[\[a\]\[b\]\]\n    \[\[a\]\[b\]\]\n\]]]       [__variable_lists__]]
    [[include]              [[^'''[include someother.qbk]''']]              [__include__]]
]

[endsect]