1[/
2    Copyright 2002,2004,2006 Joel de Guzman, Eric Niebler
3    Copyright 2010-2011 Daniel James
4
5    Distributed under the Boost Software License, Version 1.0.
6    (See accompanying file LICENSE_1_0.txt or copy at
7    [@http://www.boost.org/LICENSE_1_0.txt])
8]
9
10[chapter Document Structure
11    [quickbook 1.6]
12    [id quickbook.syntax.structure]
13    [source-mode teletype]
14]
15
16[/TODO: I started to write this in the syntax chapter, but it was too
17much information, will incorporate into this file.]
18[/
19To avoid breaking old documentation we support using different versions
20of the language, compatibility is not 100% but we try to avoid
21problematic changes. This documentation applies to the current version,
22`[quickbook 1.5]`.
23
24There is also some mention of the next version `[quickbook 1.6]`. While
25quickbook allows you to use it now, it isn't recommended as it is
26currently a work in progress and subject to change.
27]
28
29[#quickbook.ref.docinfo]
30[section:docinfo Document Info]
31
32Every document must begin with a Document Info section, which looks something
33like this:
34
35```
36[article The Document Title
37    [quickbook 1.5]
38    [version 1.0]
39    [id the_document_name]
40    [copyright 2000 2002 2003 Joe Blow, Jane Doe]
41    [authors [Blow, Joe] [Doe, Jane]]
42    [license The document's license]
43    [source-mode c++]
44]
45```
46
47`article` is the document type. There are several possible document types,
48most of these are based on docbook document elements. These are fully
49described in
50[@http://www.docbook.org/tdg/ DocBook: The Definitive Guide]:
51
52* [@http://www.docbook.org/tdg/en/html/book.html book]
53* [@http://www.docbook.org/tdg/en/html/article.html article]
54* [@http://www.docbook.org/tdg/en/html/chapter.html chapter]
55* [@http://www.docbook.org/tdg/en/html/part.html part]
56* [@http://www.docbook.org/tdg/en/html/appendix.html appendix]
57* [@http://www.docbook.org/tdg/en/html/preface.html preface]
58* [@http://www.docbook.org/tdg/en/html/qandadiv.html qandadiv]
59* [@http://www.docbook.org/tdg/en/html/qandaset.html qandaset]
60* [@http://www.docbook.org/tdg/en/html/reference.html reference]
61* [@http://www.docbook.org/tdg/en/html/set.html set]
62
63Boostbook also adds another document type [^[link boostbook.defining library]]
64for documenting software libraries.
65
66So the documentation for the 'foo' library might start:
67
68```
69[library Foo
70    [quickbook 1.5]
71    [id foo]
72    [version 1.0]
73]
74```
75
76[#quickbook.ref.attributes]
77[section:attributes Document Info Attributes]
78
79The document info block has a few different types of attributes.
80They are all optional.
81
82[heading Quickbook specific meta data]
83
84```
85    [quickbook 1.6]
86```
87
88The `quickbook` attribute declares the version of quickbook
89the document is written for.
90In its absence, version 1.1 is assumed. It's recommended that
91you use `[quickbook 1.6]` which is the version described here.
92
93[note
94
95The quickbook version also makes some changes to the markup
96that's generated. Most notably, the ids that are automatically
97for headers and sections are different in later versions. To
98minimise disruption, you can use the =compatibility-mode=
99attribute to generate similar markup to the old version:
100
101```
102[article Article that was original
103         written in quickbook 1.3
104[quickbook 1.6]
105[compatibility-mode 1.3]
106]
107```
108
109This feature shouldn't be used for new documents, just for
110porting old documents to the new version.
111]
112
113Both the =quickbook= and =compatibility-mode= tags can be used
114at the start of the file, before the document info block, and
115also in files that don't have a document info block.
116
117```
118    [source-mode teletype]
119```
120
121The `source-mode` attribute sets the initial __source_mode__. If
122it is omitted, the default value of =c++= will be used.
123
124[heading Boostbook/Docbook root element attributes]
125
126```
127[id foo]
128```
129
130`id` specifies the id of the document element. If it isn't specified
131the id is automatically generated from the title. This id is also
132used to generate the nested ids.
133
134```
135[lang en]
136```
137
138`lang` specifies the document language. This is used by docbook to
139localize the documentation. Note that Boostbook doesn't have any
140localization support so if you use it to generate the reference
141documentation it will be in English regardless.
142
143It should be a language code
144drawn from ISO 639 (perhaps extended with a country code drawn from
145ISO 3166, as en-US).
146
147```
148[dirname foo]
149```
150
151`dirname` is used to specify the directory name of the library in the
152repository. This is a boostbook extension so it's only valid for
153`library` documentation blocks.  It's used for some boostbook
154functionality, but for pure quickbook documentation has no practical
155effect.
156
157[heading Docbook Metadata]
158
159=version=, =copyright=, =authors=,
160=license=, =last-revision= and =bibliod= are optional information.
161
162[heading Boostbook Metadata]
163
164=purpose= and =category= are boostbook attributes which are only
165valid for =library= documents. If you use them for other document types,
166quickbook will warn about them, but still use them, generating invalid markup,
167that's just ignored by the style sheets.
168
169[endsect] [/attributes]
170
171[section:nesting Nesting quickbook documents]
172
173Docinfo blocks can only appear at the beginning of a quickbook file, so to
174create a more complicated document you need to use several quickbook files and
175use the [link quickbook.ref.include include tag] to nest them. For example, say
176you wish to create a book with an introduction and a chapter, you first create
177a file for the book:
178
179    [book Simple example
180    [quickbook 1.6]
181    ]
182
183    [include introduction.qbk]
184    [include chapter.qbk]
185
186[note Structuring a document like this was introduced in quickbook 1.6, so the
187`[quickbook 1.6]` docinfo field is required.]
188
189The appropriate document type for an introduction is `preface`, so
190the contents of `introduction.qbk` should be something like:
191
192    [preface Introduction
193    [quickbook 1.6]
194    ]
195
196    Write the introduction to the book here....
197
198And `chapter.qbk`:
199
200    [chapter A chapter
201    [quickbook 1.6]
202    ]
203
204    Chapter contents....
205
206[endsect] [/nesting]
207
208[endsect] [/docinfo]
209
210[#quickbook.ref.section]
211[section:section Sections]
212
213Quickbook documents are structured using 'sections'. These are used
214to generate the table of contents, and, when generating html, to
215split the document into pages. This is optional but a good idea for
216all but the simplest of documents.
217
218A sectioned document might look like:
219
220```
221    [book Title
222        [quickbook 1.5]
223    ]
224
225    [section First Section]
226
227    [/...]
228
229    [endsect]
230
231    [section Second Section]
232
233    [/...]
234
235    [endsect]
236```
237
238Sections start with the `section` tag, and end with the `[endsect]` tag.
239(`[/...]` is a comment, [link quickbook.ref.comments described later]).
240
241Sections can be given an optional id:
242
243```
244[#quickbook.ref.id]
245[section:id The Section Title]
246```
247
248`id` will be the filename of the generated section.
249If it is not present, "The Section Title" will be normalized and become the id.
250Valid characters are =a-Z=, =A-Z=, =0-9= and =_=. All non-valid characters are
251converted to underscore and all upper-case are converted to lower case.
252Thus: "The Section Title" will be normalized to "the_section_title".
253
254Sections can nest, and that results in a hierarchy in the table of contents.
255
256[endsect] [/Section]
257