quickbook-manual.quickbook

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

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&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[]'''α''']
[template beta[]'''β''']
''']

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

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

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