Boost C++ Libraries

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

[*['bold-italic]]

will generate:

bold-italic

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

[~replacement]

This will generate:

replacement

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

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

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

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

will generate:

italic, bold, underline, teletype

Unlike QuickBook's standard formatting scheme, the rules for simpler alternatives are much stricter ^[6] .

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:

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:

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.

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

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

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:

``
    #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;
}

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:

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 import is rather like C++'s #include. A C++ comment // looks like this whereas a Python comment #looks like this.

	Note
	The source mode strings are lowercase.

[br]

	Warning
	[br] is now deprecated. Blurbs, Admonitions and table cells (see Tables) may now contain paragraphs.

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

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

will generate:

this is boost's website....

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

see http://spirit.sourceforge.net/

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

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:

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

will generate: the Boost.Spirit documentation

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

You can link within a document using:

[link document_id.section_id.normalized_header_text The link text]

See sections Section and Heading for more info.

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

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

[link xml.refentry]

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

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

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

[classref boost::bar::baz]

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

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

'''
escape (no processing/formatting)
'''

Escaping allows us to pass XML markup to BoostBook or DocBook. For example:

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

This is direct XML markup

	Important
	Be careful when using the escape. The text must conform to BoostBook/DocBook syntax.

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.

[$image.jpg]

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:

[footnote A sample footnote]

will generate this ^[7] .

__a_macro_identifier__

[a_template_identifier]

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

[? __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:

[def __to_be__]

And try again:

To be or not to be

Yes! ^[8]

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

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

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.

Starting a new section is accomplished with:

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

[endsect]

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

You can include another XML file with:

[xinclude file.xml]

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

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.

This is a new paragraph...

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

#include <iostream>

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

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:

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

using boost::array;

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:

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

Will generate:

void foo()
{
}

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

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

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

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.

[:sometext...]

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

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

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5

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:

[link document_id.section_id.normalized_header_text The link text]

to link to them. See Anchor links and Section for more info.

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

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

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

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

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

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

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

	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:

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

(See Images and Links)

Invoking these macros:

Hi __spirit__  :-)

will generate this:

Hi Spirit

Quickbook has some predefined macros that you can already use.

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:

[template person[name age what]

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

]

Template Identifier

Template identifiers can either consist of:

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

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:

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

Block templates are of the form:

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

Template Expansion

You expand a template this way:

[template_identifier arg1..arg2..arg3]

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

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

Which will expand to:

Hi, my name is James Bond. I am 39 years old. I am a Spy.

Hi, my name is Santa Clause. I am 87 years old. I am a 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 QuickBook phrase. Arguments are separated by the double dot ".." and terminated by the close parenthesis.

Nullary Templates

Nullary templates look and act like simple macros. Example:

[template alpha[]'''α''']
[template beta[]'''β''']

Expanding:

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

We have:

Some squiggles...αβ

The difference with macros are

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:

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

Expanding:

Here's a quote from [aristotle_quote].

We have:

Here's a quote from Aristotle: Education is the best provision for the journey to old age..

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:

[template tag\ _tag]

Then expanding:

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

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:

For example:

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

will produce:

wxyz

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

[simple w x y z trail]

will produce:

wxyz 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:

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

will produce:

what do you think man?

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 template identifiers. Example:

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

Now, expanding this:

[!baz]

We will have:

<hey>baz</hey>

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

	Note
	Prefer admonitions wherever appropriate.

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

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:

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

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

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

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

#include <iostream>

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

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

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

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

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

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

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.

Example

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

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

The first line:

[import ../test/stub.cpp]

collects specially marked-up code snippets from 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:

[foo]
[bar]

And the result is:

This is the foo function.

This description can have paragraphs...

And any quickbook block markup.

std::string foo()
{
    // return 'em, foo man!
    return "foo";
}

This is the bar function

std::string bar()
{
    // return 'em, bar man!
    return "bar";
}

Some trailing text here

Code Snippet Markup

Note how the code snippets in 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.

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.

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 Callouts for details. Example:

std::string foo_bar() 
{
    return "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 x
{
public:

    x() : n(0)
    {
    }

    ~x()
    {
    }

    int get() const
    {
        return n; 
    }

    void set(int n_)
    {
        n = n_;
    }
};

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