...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
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.
xinclude
paths are normally used unchanged in the generated
documentation, which will not work if you wish them to be relative to the
current quickbook file. Quickbook can add a xml:base
attribute
to the boostbook documentation to specify where xinclude
files should be found. For example, if you wish them to be relative to the
current quickbook file:
[article Article with xincludes [quickbook 1.7] [xmlbase .] ] [xinclude file.xml]
Now the xinclude should work if file.xml
is in the same
directory as the quickbook file. Although it might not work if you distribute
the generated files (as their relative directories can change).
Say the article is generated in a sub-directory, by running something like:
quickbook article.qbk --output-file=output/article.xml
This will generate a boostbook root tag:
<article id="article_with_xincludes" last-revision="$Date: 2013/08/20 08:26:48 $" xml:base=".." xmlns:xi="http://www.w3.org/2001/XInclude">
Because xml:base
is set to ..
, the
xml processor will know to look in the parent directory to find file.xml
,
which it comes across the xi:include
tag.
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...
List hierarchies are supported. Example:
# One # Two # Three # Three.a # Three.b # Three.c # Four # Four.a # Four.a.i # Four.a.ii # Five
will generate:
Long lines will be wrapped appropriately. Example:
# 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.
Mixed lists (ordered and unordered) are supported. Example:
# One # Two # Three * Three.a * Three.b * Three.c # Four
will generate:
And...
# 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:
In quickbook 1.7 onwards, you can nest paragraphs in lists by separating them with blank lines:
* List item 1, paragraph 1 List item 1, paragraph 2 * List item 2, paragraph 1 List item 2, paragraph 2
will generate:
List item 1, paragraph 1
List item 1, paragraph 2
List item 2, paragraph 1
List item 2, paragraph 2
Sometimes the wiki-style list markup can be tricky to use, especially if you wish to include more complicated markup with the list. So in quickbook 1.6, an alternative way to mark up lists introduced:
[ordered_list [item1][item2]]
is equivalent to:
# item1 # item2
And:
[itemized_list [item1][item2]]
is equivalent to:
* item1 * item2
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;
In quickbook 1.7 and later, you can include callouts in code blocks, like so:
[!c++] 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! >*/ }
Which will generate:
std::string foo_bar() { return "foo-bar"; }
The Mythical FooBar. See Foobar for details |
|
return 'em, foo-bar man! |
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 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 source code.
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.
[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]
You can specify an id for a heading:
[h1:heading_id A heading to link to]
To link to it, you'll need to include the enclosing section's id:
[link document_id.section_id.heading_id The link text]
Although you can preceed a heading by an anchor if you wish to use a location independent link.
If a heading doesn't have an id, one will be automatically generated with
a normalized name 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.
Note | |
---|---|
Specifying heading ids is a quickbook 1.6 feature, earlier versions don't support them. |
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:link_id 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. |
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]]
Invoking these macros:
Hi __spirit__ :-)
will generate this:
Hi Spirit
Quickbook has some predefined macros that you can already use.
Table 48.3. Predefined Macros
Macro |
Meaning |
Example |
---|---|---|
|
Today's date |
2023-Dec-06 |
|
The current time |
09:14:45 PM |
|
Quickbook source filename |
block.qbk |
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 identifiers can either consist of:
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.
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.
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.
Note that templates and template parameters can't be expanded everywhere, only where text is interpreted as a phrase. So they can't be expanded in places such as table titles and link's urls. If you want to use a template to generate a link based of the template parameter, you can't use a normal link and will need to use escaped docbook instead. Example:
[template boost_ticket[key] '''<ulink url="https://svn.boost.org/trac/boost/ticket/'''[key]'''">#'''[key]'''</ulink>'''] [boost_ticket 2035]
will expand to:
Caution | |
---|---|
Since quickbook doesn't understand the context where the parameter is being used, it will interpret it as quickbook markup, so when writing a template like this, you'll need to escape any meaningful punctuation. |
Nullary templates look and act like simple macros. Example:
[template alpha[]'''&#945;'''] [template beta[]'''&#946;''']
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.
As mentioned, arguments are separated by the double dot ".."
.
Alternatively, if the double dot isn't used and more than one argument is
expected, QuickBook uses whitespace to separate the arguments, following
this logic:
'',
'\n', \t' or '\r'
).
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".
Caution | |
---|---|
The behavior described here is for QuickBook 1.5. In older versions you could use both the double dot and whitespace as separators in the same template call. If your document is marked up as an older version, it will use the old behavior, which is described in the QuickBook 1.4 documentation. |
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:
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 admonitions wherever appropriate. |
[table:id 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 48.4. 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 |
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... ].
Giving tables an id is a new feature for quickbook 1.5 onwards. As with sections, the id is optional. If the table has a title but no id, an id will be generated from the title. The table above can be linked to using:
[link quickbook.syntax.block.tables.id link to table]
which will generate:
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:
Table 48.5. 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 |
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; } ``] ] ]
Table 48.6. Table with code
Comment |
Code |
---|---|
My first program |
#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:
A Variable List
The definition of term 1
The definition of term 2
The definition of term 3.
Definitions may contain paragraphs.
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]
In quickbook 1.6 and later, if the included file has a docinfo block then it will create a nested document. This will be processed as a standalone document, although any macros or templates from the enclosing file will still be defined.
Otherwise the included file will be processed as if it had been cut and pasted into the current document, with the following exceptions:
Note | |
---|---|
In quickbook 1.5 and earlier templates weren't scoped in included files. If you want to use templates or macros from a file in quickbook 1.6, use import instead. |
The [include]
directive lets you specify a document id
to use for the included file. 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]
.
If the included file has a docinfo block, an id specified in an [include]
directive will overwrite it.
You can also include C, C++ and python source files. This will include any quickbook blocks in the file that aren't inside of named code snippets. See the Import section for syntax details. For example, say you included this file:
/** * Hello world example */ // In this comment, the backtick indicates that this is a // quickbook source block that will be included. /*` First include the appropriate header: [hello_includes] Then write your main function: [hello_main] */ // This defines a code snippet, the syntax is // described in the import section. It's available // in the whole of this source file, not just after // its definition. //[hello_includes #include <iostream> //] //[hello_main int main() { std::cout << "Hello, trivial example" << std::endl; } //]
It will generate:
First include the appropriate header: #include <iostream> Then write your main function: int main() { std::cout << "Hello, trivial example" << std::endl; }
In quickbook 1.6 and later if you wish to use a template, macro or code snippet from a file, you need to import it. This will not include any of the content from that file, but will pull templates, macros and code snippets into the current file's scope.
With quickbook files, this allows you to create template and macro libraries.
For python (indicated by the .py
extension), C or C++ files
this allows you to include code snippets from source files, so that your
code examples can be kept up to date and fully tested.
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
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 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.
Comments of this form:
//=int main() {}
or
/*=foo()*/
will be displayed as code that isn't in comments. This allows you to include some code in the snippet but not actually use it when compiling your example.
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"; }
The Mythical FooBar. See Foobar for details |
|
return 'em, foo-bar man! |
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: tools/quickbook/test/stub.cpp
block
is a plain block element, that doesn't wrap its contents
in any docbook or boostbook tags. This can be useful when using escaped docbook
block tags, such as:
[template chapter[title] [block'''<chapter><title>'''[title]'''</title>'''] ] [template chapterend [block'''</chapter>'''] ] [chapter An example chapter] Content [chapterend]
Without the block
element, the chapter
and chapterend
templates would be wrapped in paragraph tags.
Note | |
---|---|
In this example, the template body has to start with a newline so that the template will be interpreted in block mode. |