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