quickbook.qbk

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

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