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