ceph/src/boost/tools/quickbook/doc/structure.qbk

   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
  17 much information, will incorporate into this file.]
  18 [/
  19 To avoid breaking old documentation we support using different versions
  20 of the language, compatibility is not 100% but we try to avoid
  21 problematic changes. This documentation applies to the current version,
  22 `[quickbook 1.5]`.
  23
  24 There is also some mention of the next version `[quickbook 1.6]`. While
  25 quickbook allows you to use it now, it isn't recommended as it is
  26 currently a work in progress and subject to change.
  27 ]
  28
  29 [#quickbook.ref.docinfo]
  30 [section:docinfo Document Info]
  31
  32 Every document must begin with a Document Info section, which looks something
  33 like 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,
  48 most of these are based on docbook document elements. These are fully
  49 described 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
  63 Boostbook also adds another document type [^[link boostbook.defining library]]
  64 for documenting software libraries.
  65
  66 So 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
  79 The document info block has a few different types of attributes.
  80 They are all optional.
  81
  82 [heading Quickbook specific meta data]
  83
  84 ```
  85     [quickbook 1.6]
  86 ```
  87
  88 The `quickbook` attribute declares the version of quickbook
  89 the document is written for.
  90 In its absence, version 1.1 is assumed. It's recommended that
  91 you use `[quickbook 1.6]` which is the version described here.
  92
  93 [note
  94
  95 The quickbook version also makes some changes to the markup
  96 that's generated. Most notably, the ids that are automatically
  97 for headers and sections are different in later versions. To
  98 minimise disruption, you can use the =compatibility-mode=
  99 attribute 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
 109 This feature shouldn't be used for new documents, just for
 110 porting old documents to the new version.
 111 ]
 112
 113 Both the =quickbook= and =compatibility-mode= tags can be used
 114 at the start of the file, before the document info block, and
 115 also in files that don't have a document info block.
 116
 117 ```
 118     [source-mode teletype]
 119 ```
 120
 121 The `source-mode` attribute sets the initial __source_mode__. If
 122 it 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
 131 the id is automatically generated from the title. This id is also
 132 used to generate the nested ids.
 133
 134 ```
 135 [lang en]
 136 ```
 137
 138 `lang` specifies the document language. This is used by docbook to
 139 localize the documentation. Note that Boostbook doesn't have any
 140 localization support so if you use it to generate the reference
 141 documentation it will be in English regardless.
 142
 143 It should be a language code
 144 drawn from ISO 639 (perhaps extended with a country code drawn from
 145 ISO 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
 152 repository. This is a boostbook extension so it's only valid for
 153 `library` documentation blocks.  It's used for some boostbook
 154 functionality, but for pure quickbook documentation has no practical
 155 effect.
 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
 165 valid for =library= documents. If you use them for other document types,
 166 quickbook will warn about them, but still use them, generating invalid markup,
 167 that's just ignored by the style sheets.
 168
 169 [endsect] [/attributes]
 170
 171 [section:nesting Nesting quickbook documents]
 172
 173 Docinfo blocks can only appear at the beginning of a quickbook file, so to
 174 create a more complicated document you need to use several quickbook files and
 175 use the [link quickbook.ref.include include tag] to nest them. For example, say
 176 you wish to create a book with an introduction and a chapter, you first create
 177 a 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
 189 The appropriate document type for an introduction is `preface`, so
 190 the 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
 198 And `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
 213 Quickbook documents are structured using 'sections'. These are used
 214 to generate the table of contents, and, when generating html, to
 215 split the document into pages. This is optional but a good idea for
 216 all but the simplest of documents.
 217
 218 A 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
 238 Sections start with the `section` tag, and end with the `[endsect]` tag.
 239 (`[/...]` is a comment, [link quickbook.ref.comments described later]).
 240
 241 Sections 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.
 249 If it is not present, "The Section Title" will be normalized and become the id.
 250 Valid characters are =a-Z=, =A-Z=, =0-9= and =_=. All non-valid characters are
 251 converted to underscore and all upper-case are converted to lower case.
 252 Thus: "The Section Title" will be normalized to "the_section_title".
 253
 254 Sections can nest, and that results in a hierarchy in the table of contents.
 255
 256 [endsect] [/Section]