quickbook.qbk

Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work

  \_\_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 [^".."]. If there
are less arguments passed than expected, QuickBook attempts to break the
last argument into two or more 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".

It should be obvious now that for simple arguments with no spaces, we can
get by without separating the arguments with [^".."] separators. It is
possible to combine [^".."] separators with the argument passing
simplification presented above. Example:

[pre'''
[simple what do you think ..m a n?]
''']

will produce:

[simple what do you think ..m a n?]

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