quickbook/doc/structure.qbk

[/
    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]