quickbook.qbk

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

[article Quickbook
    [quickbook 1.4]
    [version 1.4]
    [authors [de Guzman, Joel], [Niebler, Eric]]
    [copyright 2002 2004 2006 Joel de Guzman, Eric Niebler]
    [purpose /WikiWiki/ style documentation tool]
    [license
        Distributed under the Boost Software License, Version 1.0.
        (See accompanying file LICENSE_1_0.txt or copy at
        [@http://www.boost.org/LICENSE_1_0.txt])
    ]
]

[/ QuickBook Document version 1.4 ]
[/ Sept 24, 2002 ]
[/ Sept 2, 2004 ]
[/ Feb 14, 2005 ]
[/ Sept 13, 2005 ]

[/ Some links]

[def __note__       [$images/note.png]]
[def __alert__      [$images/alert.png]]
[def __tip__        [$images/tip.png]]
[def :-)            [$images/smiley.png]]
[def __spirit__     [@http://spirit.sourceforge.net Spirit]]
[def __boostbook__  [@http://www.boost.org/doc/html/boostbook.html BoostBook]]
[def __docbook__    [@http://www.docbook.org/ DocBook]]

[def __comments__           [link quickbook.syntax.comments Comments]]

[def __font_styles__        [link quickbook.syntax.phrase.font_styles Font Styles]]
[def __quotations__         [link quickbook.syntax.phrase.quotations Quotations]]
[def __replaceable__        [link quickbook.syntax.phrase.replaceable Replaceble]]
[def __simple_formatting__  [link quickbook.syntax.phrase.simple_formatting Simple formatting]]
[def __inline_code__        [link quickbook.syntax.phrase.inline_code Inline code]]
[def __code_blocks__        [link quickbook.syntax.phrase.code_blocks Code blocks]]
[def __source_mode__        [link quickbook.syntax.phrase.source_mode Source Mode]]
[def __line_break__         [link quickbook.syntax.phrase.line_break line-break]]
[def __anchors__            [link quickbook.syntax.phrase.anchors Anchors]]
[def __links__              [link quickbook.syntax.phrase.links Links]]
[def __anchor_links__       [link quickbook.syntax.phrase.anchor_links Anchor links]]
[def __refentry_links__     [link quickbook.syntax.phrase.refentry_links refentry links]]
[def __code_links__         [link quickbook.syntax.phrase.code_links function, class, member, enum, macro, concept or header links]]
[def __escape__             [link quickbook.syntax.phrase.escape Escape]]
[def __single_char_escape__ [link quickbook.syntax.phrase.single_char_escape Single char escape]]
[def __images__             [link quickbook.syntax.phrase.images Images]]
[def __cond__               [link quickbook.syntax.phrase.cond Conditional Generation]]

[def __document__           [link quickbook.syntax.block.document Document]]
[def __section__            [link quickbook.syntax.block.section Section]]
[def __xinclude__           [link quickbook.syntax.block.xinclude  xinclude]]
[def __paragraphs__         [link quickbook.syntax.block.paragraphs Paragraphs]]
[def __ordered_lists__      [link quickbook.syntax.block.lists.ordered_lists Ordered lists]]
[def __list_hierarchies__   [link quickbook.syntax.block.lists.list_hierarchies List Hierarchies]]
[def __long_list_lines__    [link quickbook.syntax.block.lists.long_list_lines Long List Lines]]
[def __unordered_lists__    [link quickbook.syntax.block.lists.unordered_lists Unordered lists]]
[def __mixed_lists__        [link quickbook.syntax.block.lists.mixed_lists Mixed lists]]
[def __code__               [link quickbook.syntax.block.code Code]]
[def __escape_back__        [link quickbook.syntax.block.escape_back Escaping Back To QuickBook]]
[def __preformatted__       [link quickbook.syntax.block.preformatted Preformatted]]
[def __blockquote__         [link quickbook.syntax.block.blockquote Blockquote]]
[def __heading__            [link quickbook.syntax.block.headings Heading]]
[def __macros__             [link quickbook.syntax.block.macros Macros]]
[def __templates__          [link quickbook.syntax.block.templates Templates]]
[def __predefined_macros__  [link quickbook.syntax.block.predefined_macros Predefined Macros]]
[def __blurbs__             [link quickbook.syntax.block.blurbs Blurbs]]
[def __admonitions__        [link quickbook.syntax.block.admonitions Admonitions]]
[def __tables__             [link quickbook.syntax.block.tables Tables]]
[def __variable_lists__     [link quickbook.syntax.block.variable_lists Variable Lists]]
[def __include__            [link quickbook.syntax.block.include Include]]
[def __import__             [link quickbook.syntax.block.import Import]]

[section:intro Introduction]

[:[*['["Why program by hand in five days what you can spend five years of your
life automating?]]]

-- Terrence Parr, author ANTLR/PCCTS
]

Well, QuickBook started as a weekend hack. It was originally intended to be a
sample application using __spirit__. What is it? What you are viewing now, this
documentation, is autogenerated by QuickBook. These files were generated from
one master:

[:[@../../tools/quickbook/doc/quickbook.qbk quickbook.qbk]]

Originally named QuickDoc, this funky tool that never dies, evolved into a
funkier tool thanks to Eric Niebler who resurrected the project making it
generate __boostbook__ instead of HTML. The __boostbook__ documentation format
is an extension of __docbook__, an SGML or XML based format for describing
documentation.

QuickBook is a WikiWiki style documentation tool geared towards C++
documentation using simple rules and markup for simple formatting tasks.
QuickBook extends the WikiWiki concept. Like the WikiWiki, QuickBook documents are
simple text files. A single QuickBook document can generate a fully linked set
of nice HTML and PostScript/PDF documents complete with images and syntax-
colorized source code.

Features include:

* generate __boostbook__ xml, to generate HTML, PostScript and PDF
* simple markup to link to Doxygen-generated entities
* macro system for simple text substitution
* simple markup for italics, bold, preformatted, blurbs, code samples,
  tables, URLs, anchors, images, etc.
* automatic syntax coloring of code samples
* CSS support

[endsect]

[section:change_log Change Log]

[h3 Version 1.3]

* Quickbook file inclusion \[include\].
* Better xml output (pretty layout). Check out the generated XML.
* Regression testing facility: to make sure your document will always be
  compatible (full backward compatibility) regardless of changes to
  QuickBook.
* Code cleanup and refactoring.
* Allow phrase markup in the doc-info.
* Preformatted code blocks via \`\`code\`\` (double ticks) allows code in tables
  and lists, for example.
* Quickbook versioning; allows full backward compatibility. You have to add
  \[quickbook 1.3\] to the doc-info header to enable the new features. Without
  this, QuickBook will assume that the document is a pre-1.3 document.
* Better (intuitive) paragraph termination. Some markups may terminate a paragraph.
  Example:``
  [section x]
  blah...
  [endsect]``
* Fully qualified section and headers. Subsection names are concatenated to the
  ID to avoid clashing. Example: `doc_name.sect_name.sub_sect_name.sub_sub_sect_name`
* Better   and whitespace handling in code snippets.
* \[xinclude\] fixes up the relative path to the target XML file when
  input_directory is not the same as the output_directory.
* Allow untitled tables.
* Allow phrase markups in section titles.
* Allow escaping back to QuickBook from code, code blocks and inline code.
* Footnotes, with the \[footnote This is the footnote\] syntax.
* Post-processor bug fix for escaped XML code that it does not recognize.
* Replaceable, with the \[~replacement\] syntax.

[h3 Version 1.4]

* Generic Headers
* Code changes to allow full recursion (i.e. Collectors and push/pop functions)
* Various code cleanup/maintenance
* Templates!
* \[conceptref\] for referencing BoostBook <concept> entities.
* Allow escape of spaces. The escaped space is removed from the output. Syntax:
  `\ `.
* Nested comments are now allowed.
* Quickbook blocks can nest inside comments.
* __import__ facility.
* Callouts on imported code
* Simple markups can now span a whole block.
* __blurbs__, __admonitions__ and table cells (see __tables__) may now
  contain paragraphs.
* `\n` and `[br]` are now deprecated.
* __cond__. Ala C++ #ifdef.
* Searching of included and imported files in an extensible search path with
  `--include-path` (`-I`) option.

[endsect]

[section:syntax Syntax Summary]

A QuickBook document is composed of one or more blocks. An example of
a block is the paragraph or a C++ code snippet. Some blocks have
special mark-ups. Blocks, except code snippets which have their own
grammar (C++ or Python), are composed of one or more phrases. A phrase
can be a simple contiguous run of characters. Phrases can have special
mark-ups. Marked up phrases can recursively contain other phrases, but
cannot contain blocks. A terminal is a self contained block-level or
phrase-level element that does not nest anything.

Blocks, in general, are delimited by two end-of-lines (the block terminator).
Phrases in each block cannot contain a block terminator. This way, syntax errors
such as un-matched closing brackets do not go haywire and corrupt anything past
a single block.

[section Comments]

Can be placed anywhere.

[pre
'''[/ comment (no output generated) ]'''
]

[/ for testing only... ]

[pre
'''[/ comments can be nested [/ some more here] ]'''
]

[/ for testing [/ only ] ]

[pre
'''[/ Quickbook blocks can nest inside comments. [*Comment this out too!] ]'''
]

[/ for testing [*only ] ]

[endsect]

[section:phrase Phrase Level Elements]

[section Font Styles]

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

[pre'''
[*['bold-italic]]
''']

will generate:

[*['bold-italic]]

[endsect]

[section Replaceable]

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

[pre'''
[~replacement]
''']

This will generate:

[~replacement]

[endsect]

[section Quotations]

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

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

[endsect]
[section Simple formatting]

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

[pre'''
/italic/, *bold*, _underline_, =teletype=
''']

will generate:

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

Unlike QuickBook's standard formatting scheme, the rules for simpler
alternatives are much stricter[footnote Thanks to David Barrett, author of
[@http://quinthar.com/qwikiwiki/index.php?page=Home Qwiki], for sharing
these samples and teaching me these obscure formatting rules. I wasn't sure
at all if __spirit__, being more or less a formal EBNF parser, can handle
the context sensitivity and ambiguity.].

* Simple markups cannot nest. You can combine a simple markup with a nestable markup.
* Simple markups cannot contain any other form of quickbook markup.
* A non-space character must follow the leading markup
* A non-space character must precede the trailing markup
* A space or a punctuation must follow the trailing markup
* If the matching markup cannot be found within a block, the formatting
  will not be applied. This is to ensure that un-matched formatting markups,
  which can be a common mistake, does not corrupt anything past a single block.
  We do not want the rest of the document to be rendered bold just because we
  forgot a trailing '*'. A single block is terminated by two end of lines or
  the close bracket: ']'.
* A line starting with the star will be interpreted as an unordered list.
  See __unordered_lists__.

[table More Formatting Samples
    [[Markup]                                           [Result]]
    [[[^'''*Bold*''']]                                  [*Bold*]]
    [[[^'''*Is bold*''']]                               [*Is bold*]]
    [[[^'''* Not bold* *Not bold * * Not bold *''']]    [* Not bold* *Not bold * * Not bold *]]
    [[[^'''This*Isn't*Bold (no bold)''']]               [This*Isn't*Bold (no bold)]]
    [[[^'''(*Bold Inside*) (parenthesis not bold)''']]  [(*Bold Inside*) (parenthesis not bold)]]
    [[[^'''*(Bold Outside)* (parenthesis bold)''']]     [*(Bold Outside)* (parenthesis bold)]]
    [[[^'''3*4*5 = 60 (no bold)''']]                    [3*4*5 = 60 (no bold)]]
    [[[^'''3 * 4 * 5 = 60 (no bold)''']]                [3 * 4 * 5 = 60 (no bold)]]
    [[[^'''3 *4* 5 = 60 (4 is bold)''']]                [3 *4* 5 = 60 (4 is bold)]]
    [[[^'''*This is bold* this is not *but this is*''']][*This is bold* this is not *but this is*]]
    [[[^'''*This is bold*.''']]                         [*This is bold*.]]
    [[[^'''*B*. (bold B)''']]                           [*B*. (bold B)]]
    [[[^'''['*Bold-Italic*]''']]                        [['*Bold-Italic*]]]
    [[[^'''*side-by*/-side/''']]                        [*side-by*/-side/]]
]

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:

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

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

[endsect]
[section Inline code]

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

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

[endsect]
[section Code blocks]

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:

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

[endsect]
[section Source Mode]

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:

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

[table Supported Source Modes