ceph/src/boost/tools/quickbook/doc/1_6.qbk

   1 [/
   2     Copyright 2002,2004,2006 Joel de Guzman, Eric Niebler
   3     Copyright 2010-2013 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 [section:1_6 Quickbook 1.6]
  11
  12 Upgrading a document from an earlier version of quickbook shouldn't be too
  13 hard. The first thing to do is update the version in the docinfo block.
  14 For example, if you were updating the Xpressive documentation, the existing
  15 docinfo block looks like:
  16
  17     [library Boost.Xpressive
  18         [quickbook 1.3]
  19         ...
  20     ]
  21
  22 Change this to:
  23
  24     [library Boost.Xpressive
  25         [quickbook 1.6]
  26         [compatibility-mode 1.3]
  27         ...
  28     ]
  29
  30 The =compatibility-mode= tag ensures that automatically generated links
  31 won't change. It might turn out that it isn't required, but in Xpressive's
  32 case if it isn't included it will break a lot of links.
  33
  34 Then try building it. You might need to fix some stray square brackets. The
  35 new version has a stricter parser which will have an error for brackets
  36 which don't pair up. They might be there by mistake, in which case they
  37 should probably be deleted, or if they're intentional escaped. For example,
  38 to write out the half-open range \[a,b), use: `\[a,b)`.
  39
  40 Next, you might need to reconsider how templates and macros are defined.
  41 If you `include` a file to use its templates, you'll now need to `import` it
  42 instead as templates are now scoped by included files. Also, if you define
  43 templates and macros in your main quickbook file, you might want to put them
  44 into a separate file and `import` that, which allows the main documentation
  45 files to concentrate on the structure and contents of the document, making them
  46 easier to read.
  47
  48 Now that headings can have ids, it can be a good idea to add ids to existing
  49 headings. This means that the headings will have more predictable ids which
  50 don't change when the text of the heading changes. In order to preserve
  51 links you can use the existing generated id as the heading.
  52
  53 [section:docinfo Includes with docinfo]
  54
  55 In quickbook 1.5 if you include a file which starts with a docinfo block, it's
  56 ignored and the file is expanded in place. In quickbook 1.6 it's treated as a
  57 document nested in the current position. So if it has an 'article' docinfo block,
  58 boostbook 'article' tags are used.
  59
  60 It also mostly generates the same markup as if the file was converted separately -
  61 so for example, the same ids are generated, the document is processed using the
  62 language version specified in the docinfo block. If no language is specified it
  63 uses the default (1.1) not the version of the document that included it. This
  64 might seem surprising, but is requried so that quickbook will convert it the same
  65 way as if it was converted separately.
  66
  67 So for the most part, includes with a docinfo are like an `xinclude`, apart from
  68 a couple of differences. Templates and macros defined in the parent document are
  69 used in the included document, and the id generator rewrites ids that clash
  70 between multiple documents.
  71
  72 If an included document doesn't have a docinfo block, it's just included as
  73 before.
  74
  75 [endsect] [/docinfo]
  76
  77 [section:doc_info_macros Macros in docinfo block]
  78
  79 You can now expand macros in text fields in the docinfo block. In the top
  80 docinfo block only the predefined macros are available, but in nested documents
  81 macros defined in the parent document are also available.
  82
  83 There's a small bug here - this leaks into older versions for the `license`
  84 and `purpose` fields, but since only the predefined macros are available, it's
  85 unlikely to break any existing documents. So I'd rather not complicate the code
  86 further by fixing that.
  87
  88 [endsect]
  89
  90 [section:scope Scoping templates and macros]
  91
  92 A long standing quickbook bug is that macros are scoped by file, but templates
  93 aren't. So you can define templates in a separate file and include them, but not
  94 macros. This has been fixed so that templates defined in one file won't 'leak'
  95 into another.
  96
  97 But this means there's no way to define templates in a separate file - a useful
  98 feature. To do this the `import` element has been adapted to also support
  99 quickbook files. If a quickbook file is imported, the templates and macros
 100 defined in it are added to the current scope, but nothing else contained in that
 101 file is used. This could be used to create template and macro library files.
 102 This matches the existing semantics of importing code snippets.
 103
 104 When importing templates, they're bound to the language version of the file
 105 they were defined in. This means that if you import them into a file with
 106 a different version it won't change the way they're interpreted. Although,
 107 as we'll see [link compatibility later], the generated boostbook is slightly
 108 different.
 109
 110 [endsect] [/scope]
 111
 112 [section:include Including C++ and python files]
 113
 114 As `import` now supports quickbook files, `include` also supports source files.
 115 It includes any quickbook contained in comments outside of code snippets.
 116 Code snippets in the file are available to be expanded within the file but
 117 are scoped to the file. In exactly the same manner as when templates and macros
 118 are scoped in an included quickbook file.
 119
 120 [endsect] [/include]
 121
 122 [section:ids Id Generation]
 123
 124 Id generation in quickbook 1.5 is a bit buggy, but that can't be fixed without a
 125 version switch as it will break existing documents. For example in quickbook 1.5
 126 when you include a quickbook file, it stops using the explicit id from the
 127 documentation info and generates a new id from the document title to use instead.
 128
 129 The id generator in quickbook 1.6 has been improved in some other ways to. When
 130 generating ids from section titles, table titles etc. it always uses the
 131 quickbook source rather than the generated boostbook to generate the id. It then
 132 cleans up the id slightly, trimming leading and trailing underscores and replacing
 133 multiple underscores with a single underscore. Then if the newly generated part
 134 of the id is longer than 32 characters it truncates it.
 135
 136 While the new id generator generally creates better ids, it's more likely to
 137 generate duplicates so quickbook needs to handle duplicates better. When there
 138 are multiple identical ids, quickbook chooses one to use based on a priority
 139 list - anchors are preferred, then explicit document and section ids, then other
 140 explicit ids, followed by the generated ids. Then any other explicit ids in the
 141 document have numbers added to avoid duplicates - first the explicit ids in the
 142 order they appear and then the generated ids. A generated id which accidentally
 143 clashes with an explicit id should never change the explicit id.
 144
 145 Older language versions still generate the same ids they always have, with the
 146 exception of duplicate ids which are handled using the new mechanism - this
 147 is not a breaking change since duplicate ids can't be linked to.
 148
 149 [endsect] [/ids]
 150
 151 [#compatibility]
 152 [section:compatibility Compatibility Mode]
 153
 154 As mentioned before, changing the id generator will break links in documents
 155 written using an old language version. So to ease the transition a
 156 'compatibility mode' is used, this just requires an extra attribute in the
 157 docinfo, for example if you're converting a 1.5 document to 1.6:
 158
 159     [article Document
 160     [quickbook 1.6]
 161     [compatibility-mode 1.5]
 162     ]
 163
 164 This means the document will be parsed as 1.6, using all the new features, but
 165 ids (and possibly other markup) will generated as they were for a 1.5 document.
 166
 167 Compatibility mode is also implicitly used when generating templates written
 168 in a different language version to the current document. So the template is
 169 parsed in the version it was written for, but generates boostbook that's
 170 compatible with the current document.
 171
 172 [endsect] [/compatibility]
 173
 174 [section:version Version info outside of document info block]
 175
 176 Can now use `quickbook` and `compatibility-mode` tags at the beginning of the
 177 file. Either before or without a document info block. This is useful for
 178 files just containing templates, which don't really need a document info
 179 block.
 180
 181 If you don't specify `compatibility-mode`, the behaviour depends on whether or
 182 not you have a docinfo block. If you do it uses the file's quickbook version,
 183 if you don't it inherits the parent's compatibility mode even if you specify
 184 a quickbook version. This is the right thing to do - mixing compatibility modes
 185 within documents is problematic. It might actually be a mistake to allow them
 186 to specified outside docinfo blocks.
 187
 188 This change is also backdated to older versions. So when including from an
 189 older version, the included file's version can be set (older versions
 190 ignore document info in included files).
 191
 192 [endsect]
 193
 194 [section:heading_ids Explicit Heading Ids]
 195
 196 Headings can now be given explicit ids:
 197
 198     [heading:id A heading with an explicit id]
 199
 200 [endsect] [/heading_ids]
 201
 202 [section:escapes Punctuation changes]
 203
 204 In 1.6, quickbook is more consistent about how it parses punctuation.
 205 Escapes are now supported in links, anchors, table titles, image
 206 attributes etc. The flip side of this is that quickbook is now stricter
 207 about unescaped brackets. They can still be used, but need to match up,
 208 otherwise there's an error.
 209
 210 Since quickbook now matches up square brackets it will fix some
 211 mis-parses. For example `[*[bold]]` used to parse as [*\[bold]\] - note
 212 that the closing square bracket isn't bold, now it parses as
 213 [*\[bold\]]. In this case it's just a subtle visual difference, but it
 214 could cause odd problems, for example when nested in a table cell.
 215
 216 [endsect] [/escapes]
 217
 218 [section:table Table Titles]
 219
 220 Table titles are now parsed as phrases, so some markup is allowd:
 221
 222     [table [*bold title]]
 223
 224 Which is an empty table with a bold title. The title is no longer ended
 225 by a newline, but by either a closing square bracket, or two opening
 226 square brackets - which you get at the start of the table cells, so
 227 this now works:
 228
 229     [table Simple[[heading 1][heading 2]][[cell 1][cell 2]]]
 230
 231 [endsect] [/table]
 232
 233 [section:xmlbase XML base]
 234
 235 A problem when using `xi:include` tags in escaped boostbook is that you
 236 typically don't know which directory the boostbook file will be in, so
 237 it's impossible to use relative links. This can be fixed by adding an
 238 `xml:base` attribute to the document tag. To do this use the new
 239 `xmlbase` attribute in your document's docinfo block. For example to
 240 make escaped `xi:include`s be relative to the directory of the file:
 241
 242     [library Library documentation
 243     [quickbook 1.6]
 244     [xmlbase .]
 245     ]
 246
 247 Any paths in `xinclude` elements will be rewritten accordingly. Note that
 248 most documents won't need this, and probably shouldn't use it. Only use it
 249 if you're totally sure that you will need it.
 250
 251 [endsect] [/xmlbase]
 252
 253 [section:template_parser Improved template parser]
 254
 255 There's a new parser for template declarations and parameters which does
 256 a better job of understanding escaped and bracketed text. Unfortunately
 257 it does not understand element names so there are some cases where it
 258 could go wrong. For example:
 259
 260     [template doesnt_work[]
 261     [ordered_list
 262         [`code phrase`]
 263     ]
 264     ]
 265
 266 In this case it will think the `[\`` is a template call and give a parse
 267 error. To work around this put an escaped space before the code phrase:
 268
 269     [template works[]
 270     [ordered_list
 271         [\ `code phrase`]
 272     ]
 273     ]
 274
 275 [endsect]
 276
 277 [section:elements New Elements]
 278
 279 New elements added in quickbook 1.6:
 280
 281 * [link quickbook.ref.block `block`]
 282 * [link quickbook.ref.list_tags `ordered_list` and `itemized_list`]
 283 * [link quickbook.ref.role `role`]
 284
 285 [endsect] [/ elements]
 286
 287 [endsect] [/ Quickbok 1.6]