[/
    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.6]
    [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]`.

There is also some mention of the next version `[quickbook 1.6]`. While
quickbook allows you to use it now, it isn't recommended as it is
currently a work in progress and subject to change.
]

[#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.5]
    [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.5]
    [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.5]
```

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.5]` which is the version described here.

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

[endsect] [/attributes]

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

Sections can nest, and that results in a hierarchy in the table of contents.

[endsect] [/Section]