...one of the most highly
regarded and expertly designed C++ library projects in the
world. — Herb Sutter and Andrei
Every document must begin with a Document Info section, which looks something like this:
[article The Document Title [quickbook 1.7] [version 1.0] [id the_document_name] [copyright 2000 2002 2003 Joe Blow, Jane Doe] [authors [Blow, Joe] [Doe, Jane]] [license The document's license] [source-mode c++] ]
article is the document type. There are several possible document
types, most of these are based on docbook document elements. These are fully
described in DocBook: The Definitive
Boostbook also adds another document type
for documenting software libraries.
So the documentation for the 'foo' library might start:
[library Foo [quickbook 1.7] [id foo] [version 1.0] ]
The document info block has a few different types of attributes. They are all optional.
quickbook attribute declares the version of quickbook
the document is written for. In its absence, version 1.1 is assumed. It's
recommended that you use
[quickbook 1.7] which is the version
The quickbook version also makes some changes to the markup that's generated.
Most notably, the ids that are automatically for headers and sections
are different in later versions. To minimise disruption, you can use
[article Article that was original written in quickbook 1.3 [quickbook 1.7] [compatibility-mode 1.3] ]
This feature shouldn't be used for new documents, just for porting old documents to the new version.
tags can be used at the start of the file, before the document info block,
and also in files that don't have a document info block.
source-mode attribute sets the initial Source
Mode. If it is omitted, the default value of
will be used.
id specifies the id of the document element. If it isn't specified
the id is automatically generated from the title. This id is also used
to generate the nested ids.
lang specifies the document language. This is used by docbook
to localize the documentation. Note that Boostbook doesn't have any localization
support so if you use it to generate the reference documentation it will
be in English regardless.
It should be a language code drawn from ISO 639 (perhaps extended with a country code drawn from ISO 3166, as en-US).
dirname is used to specify the directory name of the library
in the repository. This is a boostbook extension so it's only valid for
library documentation blocks. It's used for some boostbook
functionality, but for pure quickbook documentation has no practical effect.
are optional information.
category are boostbook
attributes which are only valid for
If you use them for other document types, quickbook will warn about them,
but still use them, generating invalid markup, that's just ignored by the
From quickbook 1.7 onwards, escaped boostbook or docbook can be included in a docinfo block:
[article Some article [quickbook 1.7] '''<author> <firstname>John</firstname> <surname>Doe</surname> <email>email@example.com</email> </author>''' ]
The escaped docbook is always placed at the end of the docinfo block, so it shouldn't be assumed that it will interleave with markup generated from quickbook. A mixture of quickbook and docbook attributes for the same information will not work well.
Docinfo blocks can only appear at the beginning of a quickbook file, so to create a more complicated document you need to use several quickbook files and use the include tag to nest them. For example, say you wish to create a book with an introduction and a chapter, you first create a file for the book:
[book Simple example [quickbook 1.7] ] [include introduction.qbk] [include chapter.qbk]
Structuring a document like this was introduced in quickbook 1.6, so
The appropriate document type for an introduction is
so the contents of
introduction.qbk should be something like:
[preface Introduction [quickbook 1.7] ] Write the introduction to the book here....
[chapter A chapter [quickbook 1.7] ] Chapter contents....
Quickbook documents are structured using 'sections'. These are used to generate the table of contents, and, when generating html, to split the document into pages. This is optional but a good idea for all but the simplest of documents.
A sectioned document might look like:
[book Title [quickbook 1.5] ] [section First Section] [/...] [endsect] [section Second Section] [/...] [endsect]
Sections start with the
section tag, and end with the
[/...] is a comment, described
Sections can be given an optional id:
[#quickbook.ref.id] [section:id The Section Title]
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
_. 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".
The end of the section can also have an optional id, this is just used to check that it matches the opening of the section.
[section:matching Section with an id] [/...] [endsect:matching]
It won't match a generated id, only one that's explicitly specified, so this
will be an error, even if quickbook generates the id
for the section:
[section Generated] [/...] [endsect:generated]
Sections can nest, and that results in a hierarchy in the table of contents.