1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<head> 4<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 5<title>Language Versions</title> 6<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css"> 7<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 8<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> 9<link rel="up" href="../quickbook.html" title="Chapter 50. Quickbook 1.7"> 10<link rel="prev" href="syntax/block.html" title="Block Level Elements"> 11<link rel="next" href="install.html" title="Installation and configuration"> 12</head> 13<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 14<table cellpadding="2" width="100%"><tr> 15<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td> 16<td align="center"><a href="../../../index.html">Home</a></td> 17<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td> 18<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 19<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 20<td align="center"><a href="../../../more/index.htm">More</a></td> 21</tr></table> 22<hr> 23<div class="spirit-nav"> 24<a accesskey="p" href="syntax/block.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../quickbook.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="install.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> 25</div> 26<div class="section"> 27<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 28<a name="quickbook.versions"></a>Language Versions</h2></div></div></div> 29<div class="toc"><dl class="toc"> 30<dt><span class="section"><a href="versions.html#quickbook.versions.upgrading">Upgrading to a new version</a></span></dt> 31<dt><span class="section"><a href="versions.html#quickbook.versions.stable">Stable Versions</a></span></dt> 32<dt><span class="section"><a href="versions.html#language_versions.1_6">Quickbook 1.6</a></span></dt> 33<dt><span class="section"><a href="versions.html#language_versions.1_7">Quickbook 1.7</a></span></dt> 34</dl></div> 35<div class="section"> 36<div class="titlepage"><div><div><h3 class="title"> 37<a name="quickbook.versions.upgrading"></a><a class="link" href="versions.html#quickbook.versions.upgrading" title="Upgrading to a new version">Upgrading to a new version</a> 38</h3></div></div></div> 39<p> 40 To upgrade an existing document to a new version of quickbook, you will need 41 to update the version in the docinfo block. For example, the existing docinfo 42 block might look like: 43 </p> 44<pre class="programlisting">[library Boost.Example 45 [quickbook 1.3] 46 ... 47] 48</pre> 49<p> 50 Change this to: 51 </p> 52<pre class="programlisting">[library Boost.Example 53 [quickbook 1.7] 54 [compatibility-mode 1.3] 55 ... 56] 57</pre> 58<p> 59 The <code class="literal">compatibility-mode</code> tag ensures that it will generate 60 similar output to the older version - most importantly is will generate the 61 same ids, ensuring that links to the generated html won't break. 62 </p> 63<p> 64 Then try building it. Later versions have a stricter parser, so there might 65 be errors. It's quite likely that you might need to fix some stray square 66 brackets. They might need to be escaped. For example, to write out the half-open 67 range [a,b), use: <code class="computeroutput">\[a,b)</code>. 68 </p> 69<p> 70 When upgrading to 1.6 or later, you might need to reconsider how templates 71 and macros are defined. If you <code class="computeroutput">include</code> a file to use its templates, 72 you'll now need to <code class="computeroutput">import</code> it instead as templates are now scoped 73 by included files. Also, if you define templates and macros in your main 74 quickbook file, you might want to put them into a separate file and <code class="computeroutput">import</code> 75 that, which allows the main documentation files to concentrate on the structure 76 and contents of the document, making them easier to read. 77 </p> 78<p> 79 Now that headings can have ids, it can be a good idea to add ids to existing 80 headings. This means that the headings will have more predictable ids which 81 don't change when the text of the heading changes. In order to preserve links 82 you can use the existing generated id as the heading. 83 </p> 84</div> 85<div class="section"> 86<div class="titlepage"><div><div><h3 class="title"> 87<a name="quickbook.versions.stable"></a><a class="link" href="versions.html#quickbook.versions.stable" title="Stable Versions">Stable Versions</a> 88</h3></div></div></div> 89<p> 90 Since quickbook 1.3 the <code class="computeroutput">quickbook</code> attribute in the document 91 block selects which version of the language to use. Not all changes to quickbook 92 are implemented using a version switch, it's mainly just the changes that 93 change the way a document is interpreted or would break existing documentation. 94 </p> 95<h4> 96<a name="quickbook.versions.stable.h0"></a> 97 <span class="phrase"><a name="quickbook.versions.stable.quickbook_1_3_and_later"></a></span><a class="link" href="versions.html#quickbook.versions.stable.quickbook_1_3_and_later">Quickbook 98 1.3 and later</a> 99 </h4> 100<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 101<li class="listitem"> 102 Introduced quickbook language versioning. 103 </li> 104<li class="listitem"> 105 In the documentation info, allow phrase markup in license and purpose 106 attributes. 107 </li> 108<li class="listitem"> 109 Fully qualified section and headers. Subsection names are concatenated 110 to the ID to avoid clashing. Example: <code class="computeroutput">doc_name.sect_name.sub_sect_name.sub_sub_sect_name</code>. 111 </li> 112</ul></div> 113<h4> 114<a name="quickbook.versions.stable.h1"></a> 115 <span class="phrase"><a name="quickbook.versions.stable.quickbook_1_5_and_later"></a></span><a class="link" href="versions.html#quickbook.versions.stable.quickbook_1_5_and_later">Quickbook 116 1.5 and later</a> 117 </h4> 118<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 119<li class="listitem"> 120 Ignore template argument separators inside square brackets. 121 </li> 122<li class="listitem"> 123 Don't separate the final template argument if the <code class="computeroutput">..</code> separator 124 was used. i.e. never mix <code class="computeroutput">..</code> and whitespace separators. 125 </li> 126<li class="listitem"> 127 Statically scope templates and their arguments rather than dynamically 128 scope them. 129 </li> 130<li class="listitem"> 131 Give table ids, and let you set them. 132 </li> 133<li class="listitem"> 134 Allow spaces between the <code class="computeroutput">:</code> character and ids in elements 135 which can have ids. 136 </li> 137</ul></div> 138</div> 139<div class="section"> 140<div class="titlepage"><div><div><h3 class="title"> 141<a name="language_versions.1_6"></a><a class="link" href="versions.html#language_versions.1_6" title="Quickbook 1.6">Quickbook 1.6</a> 142</h3></div></div></div> 143<div class="toc"><dl class="toc"> 144<dt><span class="section"><a href="versions.html#language_versions.1_6.docinfo">Includes with docinfo</a></span></dt> 145<dt><span class="section"><a href="versions.html#language_versions.1_6.doc_info_macros">Macros in docinfo 146 block</a></span></dt> 147<dt><span class="section"><a href="versions.html#language_versions.1_6.scope">Scoping templates and 148 macros</a></span></dt> 149<dt><span class="section"><a href="versions.html#language_versions.1_6.include">Including C++ and python 150 files</a></span></dt> 151<dt><span class="section"><a href="versions.html#language_versions.1_6.ids">Id Generation</a></span></dt> 152<dt><span class="section"><a href="versions.html#language_versions.1_6.compatibility">Compatibility 153 Mode</a></span></dt> 154<dt><span class="section"><a href="versions.html#language_versions.1_6.version">Version info outside 155 of document info block</a></span></dt> 156<dt><span class="section"><a href="versions.html#language_versions.1_6.heading_ids">Explicit Heading 157 Ids</a></span></dt> 158<dt><span class="section"><a href="versions.html#language_versions.1_6.escapes">Punctuation changes</a></span></dt> 159<dt><span class="section"><a href="versions.html#language_versions.1_6.table">Table Titles</a></span></dt> 160<dt><span class="section"><a href="versions.html#language_versions.1_6.xmlbase">XML base</a></span></dt> 161<dt><span class="section"><a href="versions.html#language_versions.1_6.template_parser">Improved template 162 parser</a></span></dt> 163<dt><span class="section"><a href="versions.html#language_versions.1_6.elements">New Elements</a></span></dt> 164</dl></div> 165<div class="section"> 166<div class="titlepage"><div><div><h4 class="title"> 167<a name="language_versions.1_6.docinfo"></a><a class="link" href="versions.html#language_versions.1_6.docinfo" title="Includes with docinfo">Includes with docinfo</a> 168</h4></div></div></div> 169<p> 170 In quickbook 1.5 if you include a file which starts with a docinfo block, 171 it's ignored and the file is expanded in place. In quickbook 1.6 it's treated 172 as a document nested in the current position. So if it has an 'article' 173 docinfo block, boostbook 'article' tags are used. 174 </p> 175<p> 176 It also mostly generates the same markup as if the file was converted separately 177 - so for example, the same ids are generated, the document is processed 178 using the language version specified in the docinfo block. If no language 179 is specified it uses the default (1.1) not the version of the document 180 that included it. This might seem surprising, but is requried so that quickbook 181 will convert it the same way as if it was converted separately. 182 </p> 183<p> 184 So for the most part, includes with a docinfo are like an <code class="computeroutput">xinclude</code>, 185 apart from a couple of differences. Templates and macros defined in the 186 parent document are used in the included document, and the id generator 187 rewrites ids that clash between multiple documents. 188 </p> 189<p> 190 If an included document doesn't have a docinfo block, it's just included 191 as before. 192 </p> 193</div> 194<div class="section"> 195<div class="titlepage"><div><div><h4 class="title"> 196<a name="language_versions.1_6.doc_info_macros"></a><a class="link" href="versions.html#language_versions.1_6.doc_info_macros" title="Macros in docinfo block">Macros in docinfo 197 block</a> 198</h4></div></div></div> 199<p> 200 You can now expand macros in text fields in the docinfo block. In the top 201 docinfo block only the predefined macros are available, but in nested documents 202 macros defined in the parent document are also available. 203 </p> 204<p> 205 There's a small bug here - this leaks into older versions for the <code class="computeroutput">license</code> 206 and <code class="computeroutput">purpose</code> fields, but since only the predefined macros are 207 available, it's unlikely to break any existing documents. So I'd rather 208 not complicate the code further by fixing that. 209 </p> 210</div> 211<div class="section"> 212<div class="titlepage"><div><div><h4 class="title"> 213<a name="language_versions.1_6.scope"></a><a class="link" href="versions.html#language_versions.1_6.scope" title="Scoping templates and macros">Scoping templates and 214 macros</a> 215</h4></div></div></div> 216<p> 217 A long standing quickbook bug is that macros are scoped by file, but templates 218 aren't. So you can define templates in a separate file and include them, 219 but not macros. This has been fixed so that templates defined in one file 220 won't 'leak' into another. 221 </p> 222<p> 223 But this means there's no way to define templates in a separate file - 224 a useful feature. To do this the <code class="computeroutput">import</code> element has been adapted 225 to also support quickbook files. If a quickbook file is imported, the templates 226 and macros defined in it are added to the current scope, but nothing else 227 contained in that file is used. This could be used to create template and 228 macro library files. This matches the existing semantics of importing code 229 snippets. 230 </p> 231<p> 232 When importing templates, they're bound to the language version of the 233 file they were defined in. This means that if you import them into a file 234 with a different version it won't change the way they're interpreted. Although, 235 as we'll see <a class="link" href="versions.html#compatibility">later</a>, the generated 236 boostbook is slightly different. 237 </p> 238</div> 239<div class="section"> 240<div class="titlepage"><div><div><h4 class="title"> 241<a name="language_versions.1_6.include"></a><a class="link" href="versions.html#language_versions.1_6.include" title="Including C++ and python files">Including C++ and python 242 files</a> 243</h4></div></div></div> 244<p> 245 As <code class="computeroutput">import</code> now supports quickbook files, <code class="computeroutput">include</code> 246 also supports source files. It includes any quickbook contained in comments 247 outside of code snippets. Code snippets in the file are available to be 248 expanded within the file but are scoped to the file. In exactly the same 249 manner as when templates and macros are scoped in an included quickbook 250 file. 251 </p> 252</div> 253<div class="section"> 254<div class="titlepage"><div><div><h4 class="title"> 255<a name="language_versions.1_6.ids"></a><a class="link" href="versions.html#language_versions.1_6.ids" title="Id Generation">Id Generation</a> 256</h4></div></div></div> 257<p> 258 Id generation in quickbook 1.5 is a bit buggy, but that can't be fixed 259 without a version switch as it will break existing documents. For example 260 in quickbook 1.5 when you include a quickbook file, it stops using the 261 explicit id from the documentation info and generates a new id from the 262 document title to use instead. 263 </p> 264<p> 265 The id generator in quickbook 1.6 has been improved in some other ways 266 to. When generating ids from section titles, table titles etc. it always 267 uses the quickbook source rather than the generated boostbook to generate 268 the id. It then cleans up the id slightly, trimming leading and trailing 269 underscores and replacing multiple underscores with a single underscore. 270 Then if the newly generated part of the id is longer than 32 characters 271 it truncates it. 272 </p> 273<p> 274 While the new id generator generally creates better ids, it's more likely 275 to generate duplicates so quickbook needs to handle duplicates better. 276 When there are multiple identical ids, quickbook chooses one to use based 277 on a priority list - anchors are preferred, then explicit document and 278 section ids, then other explicit ids, followed by the generated ids. Then 279 any other explicit ids in the document have numbers added to avoid duplicates 280 - first the explicit ids in the order they appear and then the generated 281 ids. A generated id which accidentally clashes with an explicit id should 282 never change the explicit id. 283 </p> 284<p> 285 Older language versions still generate the same ids they always have, with 286 the exception of duplicate ids which are handled using the new mechanism 287 - this is not a breaking change since duplicate ids can't be linked to. 288 </p> 289</div> 290<div class="section"> 291<div class="titlepage"><div><div><h4 class="title"> 292<a name="language_versions.1_6.compatibility"></a><a name="compatibility"></a><a class="link" href="versions.html#language_versions.1_6.compatibility" title="Compatibility Mode">Compatibility 293 Mode</a> 294</h4></div></div></div> 295<p> 296 As mentioned before, changing the id generator will break links in documents 297 written using an old language version. So to ease the transition a 'compatibility 298 mode' is used, this just requires an extra attribute in the docinfo, for 299 example if you're converting a 1.5 document to 1.6: 300 </p> 301<pre class="programlisting">[article Document 302[quickbook 1.6] 303[compatibility-mode 1.5] 304] 305</pre> 306<p> 307 This means the document will be parsed as 1.6, using all the new features, 308 but ids (and possibly other markup) will generated as they were for a 1.5 309 document. 310 </p> 311<p> 312 Compatibility mode is also implicitly used when generating templates written 313 in a different language version to the current document. So the template 314 is parsed in the version it was written for, but generates boostbook that's 315 compatible with the current document. 316 </p> 317</div> 318<div class="section"> 319<div class="titlepage"><div><div><h4 class="title"> 320<a name="language_versions.1_6.version"></a><a class="link" href="versions.html#language_versions.1_6.version" title="Version info outside of document info block">Version info outside 321 of document info block</a> 322</h4></div></div></div> 323<p> 324 Can now use <code class="computeroutput">quickbook</code> and <code class="computeroutput">compatibility-mode</code> 325 tags at the beginning of the file. Either before or without a document 326 info block. This is useful for files just containing templates, which don't 327 really need a document info block. 328 </p> 329<p> 330 If you don't specify <code class="computeroutput">compatibility-mode</code>, the behaviour depends 331 on whether or not you have a docinfo block. If you do it uses the file's 332 quickbook version, if you don't it inherits the parent's compatibility 333 mode even if you specify a quickbook version. This is the right thing to 334 do - mixing compatibility modes within documents is problematic. It might 335 actually be a mistake to allow them to specified outside docinfo blocks. 336 </p> 337<p> 338 This change is also backdated to older versions. So when including from 339 an older version, the included file's version can be set (older versions 340 ignore document info in included files). 341 </p> 342</div> 343<div class="section"> 344<div class="titlepage"><div><div><h4 class="title"> 345<a name="language_versions.1_6.heading_ids"></a><a class="link" href="versions.html#language_versions.1_6.heading_ids" title="Explicit Heading Ids">Explicit Heading 346 Ids</a> 347</h4></div></div></div> 348<p> 349 Headings can now be given explicit ids: 350 </p> 351<pre class="programlisting">[heading:id A heading with an explicit id] 352</pre> 353</div> 354<div class="section"> 355<div class="titlepage"><div><div><h4 class="title"> 356<a name="language_versions.1_6.escapes"></a><a class="link" href="versions.html#language_versions.1_6.escapes" title="Punctuation changes">Punctuation changes</a> 357</h4></div></div></div> 358<p> 359 In 1.6, quickbook is more consistent about how it parses punctuation. Escapes 360 are now supported in links, anchors, table titles, image attributes etc. 361 The flip side of this is that quickbook is now stricter about unescaped 362 brackets. They can still be used, but need to match up, otherwise there's 363 an error. 364 </p> 365<p> 366 Since quickbook now matches up square brackets it will fix some mis-parses. 367 For example <code class="computeroutput">[*[bold]]</code> used to parse as <span class="bold"><strong>[bold</strong></span>] 368 - note that the closing square bracket isn't bold, now it parses as <span class="bold"><strong>[bold]</strong></span>. In this case it's just a subtle visual difference, 369 but it could cause odd problems, for example when nested in a table cell. 370 </p> 371</div> 372<div class="section"> 373<div class="titlepage"><div><div><h4 class="title"> 374<a name="language_versions.1_6.table"></a><a class="link" href="versions.html#language_versions.1_6.table" title="Table Titles">Table Titles</a> 375</h4></div></div></div> 376<p> 377 Table titles are now parsed as phrases, so some markup is allowd: 378 </p> 379<pre class="programlisting">[table [*bold title]] 380</pre> 381<p> 382 Which is an empty table with a bold title. The title is no longer ended 383 by a newline, but by either a closing square bracket, or two opening square 384 brackets - which you get at the start of the table cells, so this now works: 385 </p> 386<pre class="programlisting">[table Simple[[heading 1][heading 2]][[cell 1][cell 2]]] 387</pre> 388</div> 389<div class="section"> 390<div class="titlepage"><div><div><h4 class="title"> 391<a name="language_versions.1_6.xmlbase"></a><a class="link" href="versions.html#language_versions.1_6.xmlbase" title="XML base">XML base</a> 392</h4></div></div></div> 393<p> 394 A problem when using <code class="computeroutput">xi:include</code> tags in escaped boostbook 395 is that you typically don't know which directory the boostbook file will 396 be in, so it's impossible to use relative links. This can be fixed by adding 397 an <code class="computeroutput">xml:base</code> attribute to the document tag. To do this use 398 the new <code class="computeroutput">xmlbase</code> attribute in your document's docinfo block. 399 For example to make escaped <code class="computeroutput">xi:include</code>s be relative to the 400 directory of the file: 401 </p> 402<pre class="programlisting">[library Library documentation 403[quickbook 1.6] 404[xmlbase .] 405] 406</pre> 407<p> 408 Any paths in <code class="computeroutput">xinclude</code> elements will be rewritten accordingly. 409 Note that most documents won't need this, and probably shouldn't use it. 410 Only use it if you're totally sure that you will need it. 411 </p> 412</div> 413<div class="section"> 414<div class="titlepage"><div><div><h4 class="title"> 415<a name="language_versions.1_6.template_parser"></a><a class="link" href="versions.html#language_versions.1_6.template_parser" title="Improved template parser">Improved template 416 parser</a> 417</h4></div></div></div> 418<p> 419 There's a new parser for template declarations and parameters which does 420 a better job of understanding escaped and bracketed text. Unfortunately 421 it does not understand element names so there are some cases where it could 422 go wrong. For example: 423 </p> 424<pre class="programlisting">[template doesnt_work[] 425[ordered_list 426 [`code phrase`] 427] 428] 429</pre> 430<p> 431 In this case it will think the <code class="computeroutput">[\</code>` is a template call and 432 give a parse error. To work around this put an escaped space before the 433 code phrase: 434 </p> 435<pre class="programlisting">[template works[] 436[ordered_list 437 [\ `code phrase`] 438] 439] 440</pre> 441</div> 442<div class="section"> 443<div class="titlepage"><div><div><h4 class="title"> 444<a name="language_versions.1_6.elements"></a><a class="link" href="versions.html#language_versions.1_6.elements" title="New Elements">New Elements</a> 445</h4></div></div></div> 446<p> 447 New elements added in quickbook 1.6: 448 </p> 449<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 450<li class="listitem"> 451 <a class="link" href="syntax/block.html#quickbook.ref.block"><code class="computeroutput">block</code></a> 452 </li> 453<li class="listitem"> 454 <a class="link" href="syntax/block.html#quickbook.ref.list_tags"><code class="computeroutput">ordered_list</code> and 455 <code class="computeroutput">itemized_list</code></a> 456 </li> 457<li class="listitem"> 458 <a class="link" href="syntax/phrase.html#quickbook.ref.role"><code class="computeroutput">role</code></a> 459 </li> 460</ul></div> 461</div> 462</div> 463<div class="section"> 464<div class="titlepage"><div><div><h3 class="title"> 465<a name="language_versions.1_7"></a><a class="link" href="versions.html#language_versions.1_7" title="Quickbook 1.7">Quickbook 1.7</a> 466</h3></div></div></div> 467<div class="toc"><dl class="toc"> 468<dt><span class="section"><a href="versions.html#language_versions.1_7.context_error">Error for elements 469 used in incorrect context</a></span></dt> 470<dt><span class="section"><a href="versions.html#language_versions.1_7.phrase_parse_error">Error for 471 invalid phrase elements</a></span></dt> 472<dt><span class="section"><a href="versions.html#language_versions.1_7.source_mode">Source mode for 473 single entities</a></span></dt> 474<dt><span class="section"><a href="versions.html#language_versions.1_7.callouts">Callouts in code blocks</a></span></dt> 475<dt><span class="section"><a href="versions.html#language_versions.1_7.escaped_docinfo_attributes">Escaped 476 docbook in docinfo blocks</a></span></dt> 477<dt><span class="section"><a href="versions.html#language_versions.1_7.listparagraphs">Pargraphs in 478 lists</a></span></dt> 479<dt><span class="section"><a href="versions.html#language_versions.1_7.templates_in_attributes">Templates 480 in some attributes</a></span></dt> 481<dt><span class="section"><a href="versions.html#language_versions.1_7.list_markup_in_tables">List Markup 482 in Nested Blocks</a></span></dt> 483<dt><span class="section"><a href="versions.html#language_versions.1_7.phrase_block_templates">Allow 484 block elements in phrase templates</a></span></dt> 485<dt><span class="section"><a href="versions.html#language_versions.1_7.glob">Including multiple files 486 with Globs</a></span></dt> 487</dl></div> 488<div class="section"> 489<div class="titlepage"><div><div><h4 class="title"> 490<a name="language_versions.1_7.context_error"></a><a class="link" href="versions.html#language_versions.1_7.context_error" title="Error for elements used in incorrect context">Error for elements 491 used in incorrect context</a> 492</h4></div></div></div> 493<p> 494 Previously if you used an element in the wrong context it would just be 495 unprocessed, which was surprising. People often didn't realise that their 496 element hadn't been processed. So now it's an error. 497 </p> 498</div> 499<div class="section"> 500<div class="titlepage"><div><div><h4 class="title"> 501<a name="language_versions.1_7.phrase_parse_error"></a><a class="link" href="versions.html#language_versions.1_7.phrase_parse_error" title="Error for invalid phrase elements">Error for 502 invalid phrase elements</a> 503</h4></div></div></div> 504<p> 505 If the body of a phrase element didn't parse, it would be just used unprocessed. 506 Now change it to be a hard error. 507 </p> 508</div> 509<div class="section"> 510<div class="titlepage"><div><div><h4 class="title"> 511<a name="language_versions.1_7.source_mode"></a><a class="link" href="versions.html#language_versions.1_7.source_mode" title="Source mode for single entities">Source mode for 512 single entities</a> 513</h4></div></div></div> 514<p> 515 1.7 introduces a new <code class="computeroutput">!</code> element type for setting the source 516 mode of a single entity without changing the source mode otherwise. This 517 can be used for code blocks and other elements. For example: 518 </p> 519<pre class="programlisting">[!c++] 520 void foo() {}; 521 522[!python]```def foo():``` 523</pre> 524<p> 525 It can also be used to set the source mode for elements: 526 </p> 527<pre class="programlisting">[!teletype][table 528 [[code][meaning]] 529 [[`+`][addition]] 530] 531</pre> 532<p> 533 When used before a section, it sets the source mode for the whole section. 534 </p> 535<p> 536 If it appears at the beginning of a paragraph, it will be used for the 537 whole paragraph only if there's a newline, eg. 538 </p> 539<pre class="programlisting">[!c++] 540A declaration `void foo();` and a definition `void foo() {}`. 541</pre> 542</div> 543<div class="section"> 544<div class="titlepage"><div><div><h4 class="title"> 545<a name="language_versions.1_7.callouts"></a><a class="link" href="versions.html#language_versions.1_7.callouts" title="Callouts in code blocks">Callouts in code blocks</a> 546</h4></div></div></div> 547<p> 548 Currently callouts can only be used in code snippets. 1.7 adds support 549 in normal code blocks. The same syntax is used as in code snippets, the 550 callout descriptions appear immediately after the code block. 551 </p> 552</div> 553<div class="section"> 554<div class="titlepage"><div><div><h4 class="title"> 555<a name="language_versions.1_7.escaped_docinfo_attributes"></a><a class="link" href="versions.html#language_versions.1_7.escaped_docinfo_attributes" title="Escaped docbook in docinfo blocks">Escaped 556 docbook in docinfo blocks</a> 557</h4></div></div></div> 558<p> 559 Quickbook docinfo attributes will probably never be as rich as docbook 560 attributes. To allow more flexible markup that is not supported by quickbook, 561 escaped docbook can be included in the docinfo block: 562 </p> 563<pre class="programlisting">[article Some article 564[quickbook 1.7] 565'''<author> 566 <firstname>John</firstname> 567 <surname>Doe</surname> 568 <email>john.doe@example.com</email> 569</author>''' 570] 571</pre> 572<p> 573 The escaped docbook is always placed at the end of the docinfo block, so 574 it shouldn't be assumed that it will interleave with markup generated from 575 quickbook. A mixture of quickbook and docbook attributes for the same information 576 will not work well. 577 </p> 578</div> 579<div class="section"> 580<div class="titlepage"><div><div><h4 class="title"> 581<a name="language_versions.1_7.listparagraphs"></a><a class="link" href="versions.html#language_versions.1_7.listparagraphs" title="Pargraphs in lists">Pargraphs in 582 lists</a> 583</h4></div></div></div> 584<p> 585 Paragraphs and block elements can now be used in lists: 586 </p> 587<pre class="programlisting">* Para 1 588 589 Para 2 590 * Nested Para 1 591 592 Nested Para 2 593 594 Code block 595 Para 3 596</pre> 597<p> 598 generates: 599 </p> 600<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 601<p class="simpara"> 602 Para 1 603 </p> 604<p class="simpara"> 605 Para 2 606 </p> 607<p class="simpara"> 608 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"> 609<p class="simpara"> 610 Nested Para 1 611 </p> 612<p class="simpara"> 613 Nested Para 2 614 </p> 615<pre class="programlisting">Code block 616</pre> 617</li></ul></div> 618 </p> 619<p class="simpara"> 620 Para 3 621 </p> 622</li></ul></div> 623</div> 624<div class="section"> 625<div class="titlepage"><div><div><h4 class="title"> 626<a name="language_versions.1_7.templates_in_attributes"></a><a class="link" href="versions.html#language_versions.1_7.templates_in_attributes" title="Templates in some attributes">Templates 627 in some attributes</a> 628</h4></div></div></div> 629<p> 630 There's support for calling templates in link values, anchors, roles and 631 includes. This is sometimes a bit of a change, especially in places where 632 spaces are currently allowed, so I might try using a slightly different 633 grammar where required. I think I also need to add some validation, since 634 the parser can allow more symbols than some of the old ones. 635 </p> 636</div> 637<div class="section"> 638<div class="titlepage"><div><div><h4 class="title"> 639<a name="language_versions.1_7.list_markup_in_tables"></a><a class="link" href="versions.html#language_versions.1_7.list_markup_in_tables" title="List Markup in Nested Blocks">List Markup 640 in Nested Blocks</a> 641</h4></div></div></div> 642<p> 643 Can now place list markup in nested blocks, e.g in tables, variables lists 644 etc. Unfortunately indented code blocks are more tricky, because the contents 645 of these blocks are often indented already. It seemed easier to just not 646 support indented code blocks in this context than to try to work out sensible 647 actions for the edges cases. If you want to use code blocks in this context, 648 you should still be able to use explicit markup. 649 </p> 650</div> 651<div class="section"> 652<div class="titlepage"><div><div><h4 class="title"> 653<a name="language_versions.1_7.phrase_block_templates"></a><a class="link" href="versions.html#language_versions.1_7.phrase_block_templates" title="Allow block elements in phrase templates">Allow 654 block elements in phrase templates</a> 655</h4></div></div></div> 656<p> 657 Block elements can now be used in phrase templates, but paragraphs breaks 658 aren't allowed, so this is an error: 659 </p> 660<pre class="programlisting">[template paras[] Something or other. 661 662Second paragraph.] 663</pre> 664<p> 665 If a phrase template only contains block elements, then it's practically 666 indistinguishable from a block template. So you'll get the same output 667 from: 668 </p> 669<pre class="programlisting">[template foo[] [blurb Blah, blah, blah]] 670</pre> 671<p> 672 as: 673 </p> 674<pre class="programlisting">[template foo[] 675[blurb Blah, blah, blah] 676] 677</pre> 678<p> 679 If a phrase template has phrase content mixed with block elements, it'll 680 generate output as if it was expanded inline. 681 </p> 682</div> 683<div class="section"> 684<div class="titlepage"><div><div><h4 class="title"> 685<a name="language_versions.1_7.glob"></a><a class="link" href="versions.html#language_versions.1_7.glob" title="Including multiple files with Globs">Including multiple files 686 with Globs</a> 687</h4></div></div></div> 688<p> 689 One can now include multiple files at once using a glob pattern for the 690 file reference: 691 </p> 692<pre class="programlisting">[include sub/*/*.qbk] 693[include include/*.h] 694</pre> 695<p> 696 All the matching files, and intermediate irectories, will match and be 697 included. The glob pattern can be "*" for matching zero or more 698 characters, "?" for matching a single character, "[<c>-<c>]" 699 to match a character class, "[^<char>-<char>]" to 700 exclusive match a character class, "\\" to escape a glob special 701 character which is then matched, and anything else is matched to the character. 702 </p> 703<div class="note"><table border="0" summary="Note"> 704<tr> 705<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td> 706<th align="left">Note</th> 707</tr> 708<tr><td align="left" valign="top"><p> 709 Because of the escaping in file references the "\\" glob escape 710 is a double "\"; i.e. and escaped back-slash. 711 </p></td></tr> 712</table></div> 713</div> 714</div> 715</div> 716<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 717<td align="left"></td> 718<td align="right"><div class="copyright-footer">Copyright © 2002, 2004, 2006 Joel de Guzman, 719 Eric Niebler<br>Copyright © 2010-2017 Daniel James<p> 720 Distributed under the Boost Software License, Version 1.0. (See accompanying 721 file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) 722 </p> 723</div></td> 724</tr></table> 725<hr> 726<div class="spirit-nav"> 727<a accesskey="p" href="syntax/block.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../quickbook.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="install.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> 728</div> 729</body> 730</html> 731
