quickbook.qbk

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

    [[Mode]                 [Source Mode Markup]]
    [[C++]                  [[^\[c++\]]]]
    [[Python]               [[^\[python\]]]]
]

[note The source mode strings are lowercase.]

[endsect]
[section line-break]

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

[warning `[br]` is now deprecated. __blurbs__, __admonitions__ and
table cells (see __tables__) may now contain paragraphs.]

[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, concept, global, 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]
[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:

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

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

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

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

[section Macro Expansion]

[pre'''
__a_macro_identifier__
''']

See __macros__ for details.

[endsect]

[section Template Expansion]

[pre'''
[a_template_identifier]
''']

See __templates__ for details.

[endsect]

[endsect]

[section:cond Conditional Generation]

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

[pre'''
[? __to_be__ To be or not to be]
''']

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

[pre'''
[def __to_be__]
''']

[def __to_be__]

And try again:

[? __to_be__ To be or not to be]

Yes![footnote Conditional Generation makes quickbook turing complete.]

[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.
 [/ <-- There's a space here. Don't remove. this is intentianal, for testing]
This is a new 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'''