299 lines
7.9 KiB
Plaintext
299 lines
7.9 KiB
Plaintext
[/
|
|
Copyright 2002,2004,2006 Joel de Guzman, Eric Niebler
|
|
Copyright 2010-2011 Daniel James
|
|
|
|
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])
|
|
]
|
|
|
|
[chapter Document Structure
|
|
[quickbook 1.7]
|
|
[id quickbook.syntax.structure]
|
|
[source-mode teletype]
|
|
]
|
|
|
|
[/TODO: I started to write this in the syntax chapter, but it was too
|
|
much information, will incorporate into this file.]
|
|
[/
|
|
To avoid breaking old documentation we support using different versions
|
|
of the language, compatibility is not 100% but we try to avoid
|
|
problematic changes. This documentation applies to the current version,
|
|
`[quickbook 1.5]`.
|
|
]
|
|
|
|
[#quickbook.ref.docinfo]
|
|
[section:docinfo Document Info]
|
|
|
|
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
|
|
[@http://www.docbook.org/tdg/ DocBook: The Definitive Guide]:
|
|
|
|
* [@http://www.docbook.org/tdg/en/html/book.html book]
|
|
* [@http://www.docbook.org/tdg/en/html/article.html article]
|
|
* [@http://www.docbook.org/tdg/en/html/chapter.html chapter]
|
|
* [@http://www.docbook.org/tdg/en/html/part.html part]
|
|
* [@http://www.docbook.org/tdg/en/html/appendix.html appendix]
|
|
* [@http://www.docbook.org/tdg/en/html/preface.html preface]
|
|
* [@http://www.docbook.org/tdg/en/html/qandadiv.html qandadiv]
|
|
* [@http://www.docbook.org/tdg/en/html/qandaset.html qandaset]
|
|
* [@http://www.docbook.org/tdg/en/html/reference.html reference]
|
|
* [@http://www.docbook.org/tdg/en/html/set.html set]
|
|
|
|
Boostbook also adds another document type [^[link boostbook.defining library]]
|
|
for documenting software libraries.
|
|
|
|
So the documentation for the 'foo' library might start:
|
|
|
|
```
|
|
[library Foo
|
|
[quickbook 1.7]
|
|
[id foo]
|
|
[version 1.0]
|
|
]
|
|
```
|
|
|
|
[#quickbook.ref.attributes]
|
|
[section:attributes Document Info Attributes]
|
|
|
|
The document info block has a few different types of attributes.
|
|
They are all optional.
|
|
|
|
[heading 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.
|
|
|
|
[heading 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.
|
|
|
|
[heading Docbook Metadata]
|
|
|
|
=version=, =copyright=, =authors=,
|
|
=license=, =last-revision= and =bibliod= are optional information.
|
|
|
|
[heading 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.
|
|
|
|
[heading:escaped-docbook Escaped Docbook]
|
|
|
|
From quickbook 1.7 onwards,
|
|
[link quickbook.ref.escape 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.
|
|
|
|
[endsect:attributes]
|
|
|
|
[section:nesting 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 [link quickbook.ref.include 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....
|
|
|
|
[endsect:nesting]
|
|
|
|
[endsect:docinfo]
|
|
|
|
[#quickbook.ref.section]
|
|
[section:section Sections]
|
|
|
|
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 `[endsect]` tag.
|
|
(`[/...]` is a comment, [link quickbook.ref.comments described later]).
|
|
|
|
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 =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".
|
|
|
|
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 `generated`
|
|
for the section:
|
|
|
|
```
|
|
[section Generated]
|
|
|
|
[/...]
|
|
|
|
[endsect:generated]
|
|
```
|
|
|
|
Sections can nest, and that results in a hierarchy in the table of contents.
|
|
|
|
[endsect:section]
|