Chapter 10. Document Structure

Table of Contents

Document Info Attributes
Nesting quickbook documents

Document Info

Document Info Attributes
Nesting quickbook documents

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 Guide:

Boostbook also adds another document type library for documenting software libraries.

So the documentation for the 'foo' library might start:

[library Foo
    [quickbook 1.7]
    [id foo]
    [version 1.0]
]

Document Info Attributes

The document info block has a few different types of attributes. They are all optional.

Quickbook specific meta data

[quickbook 1.7]

The 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 described here.

Note

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 the compatibility-mode attribute to generate similar markup to the old version:

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

Both the quickbook and compatibility-mode 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 teletype]

The source-mode attribute sets the initial Source Mode. If it is omitted, the default value of c++ will be used.

Boostbook/Docbook root element attributes

[id foo]

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 en]

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 foo]

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.

Docbook Metadata

version, copyright, authors, license, last-revision and bibliod are optional information.

Boostbook Metadata

purpose and category are boostbook attributes which are only valid for library documents. 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 style sheets.

Escaped Docbook

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>john.doe@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.

Nesting quickbook documents

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]

	Note
	Structuring a document like this was introduced in quickbook 1.6, so a `[quickbook 1.6]` or later docinfo field is required.

The appropriate document type for an introduction is preface, so the contents of introduction.qbk should be something like:

[preface Introduction
[quickbook 1.7]
]

Write the introduction to the book here....

And chapter.qbk:

[chapter A chapter
[quickbook 1.7]
]

Chapter contents....