summaryrefslogtreecommitdiffstats
path: root/src/boost/tools/quickbook/test/quickbook_manual-1_4.quickbook
blob: 00fc9caa157cd2b2d01bec15ceb5affb2e55c100 (plain)
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
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
[article Quickbook
    [quickbook 1.4]
    [version 1.4]
    [authors [de Guzman, Joel], [Niebler, Eric]]
    [copyright 2002 2004 2006 Joel de Guzman, Eric Niebler]
    [purpose /WikiWiki/ style documentation tool]
    [license
        Distributed under the Boost Software License, Version 1.0.
        (See accompanying file LICENSE_1_0.txt or copy at
        [@http://www.boost.org/LICENSE_1_0.txt])
    ]
]

[/ QuickBook Document version 1.3 ]
[/ Sept 24, 2002 ]
[/ Sept 2, 2004 ]
[/ Feb 14, 2005 ]
[/ Sept 13, 2005 ]

[/ Some links]

[def __note__       [$images/note.png]]
[def __alert__      [$images/alert.png]]
[def __tip__        [$images/tip.png]]
[def :-)            [$images/smiley.png]]
[def __spirit__     [@http://spirit.sourceforge.net Spirit]]
[def __boostbook__  [@http://www.boost.org/doc/html/boostbook.html BoostBook]]
[def __docbook__    [@http://www.docbook.org/ DocBook]]

[def __comments__           [link quickbook.syntax.comments Comments]]

[def __font_styles__        [link quickbook.syntax.phrase.font_styles Font Styles]]
[def __quotations__         [link quickbook.syntax.phrase.quotations Quotations]]
[def __replaceable__        [link quickbook.syntax.phrase.replaceable Replaceble]]
[def __simple_formatting__  [link quickbook.syntax.phrase.simple_formatting Simple formatting]]
[def __inline_code__        [link quickbook.syntax.phrase.inline_code Inline code]]
[def __code_blocks__        [link quickbook.syntax.phrase.code_blocks Code blocks]]
[def __source_mode__        [link quickbook.syntax.phrase.source_mode Source Mode]]
[def __line_break__         [link quickbook.syntax.phrase.line_break line-break]]
[def __anchors__            [link quickbook.syntax.phrase.anchors Anchors]]
[def __links__              [link quickbook.syntax.phrase.links Links]]
[def __anchor_links__       [link quickbook.syntax.phrase.anchor_links Anchor links]]
[def __refentry_links__     [link quickbook.syntax.phrase.refentry_links refentry links]]
[def __code_links__         [link quickbook.syntax.phrase.code_links function, class, member, enum, macro, concept or header links]]
[def __escape__             [link quickbook.syntax.phrase.escape Escape]]
[def __single_char_escape__ [link quickbook.syntax.phrase.single_char_escape Single char escape]]
[def __images__             [link quickbook.syntax.phrase.images Images]]

[def __document__           [link quickbook.syntax.block.document Document]]
[def __section__            [link quickbook.syntax.block.section Section]]
[def __xinclude__           [link quickbook.syntax.block.xinclude  xinclude]]
[def __paragraphs__         [link quickbook.syntax.block.paragraphs Paragraphs]]
[def __ordered_lists__      [link quickbook.syntax.block.lists.ordered_lists Ordered lists]]
[def __list_hierarchies__   [link quickbook.syntax.block.lists.list_hierarchies List Hierarchies]]
[def __long_list_lines__    [link quickbook.syntax.block.lists.long_list_lines Long List Lines]]
[def __unordered_lists__    [link quickbook.syntax.block.lists.unordered_lists Unordered lists]]
[def __mixed_lists__        [link quickbook.syntax.block.lists.mixed_lists Mixed lists]]
[def __code__               [link quickbook.syntax.block.code Code]]
[def __escape_back__        [link quickbook.syntax.block.escape_back Escaping Back To QuickBook]]
[def __preformatted__       [link quickbook.syntax.block.preformatted Preformatted]]
[def __blockquote__         [link quickbook.syntax.block.blockquote Blockquote]]
[def __heading__            [link quickbook.syntax.block.headings Heading]]
[def __macros__             [link quickbook.syntax.block.macros Macros]]
[def __templates__          [link quickbook.syntax.block.templates Templates]]
[def __predefined_macros__  [link quickbook.syntax.block.predefined_macros Predefined Macros]]
[def __blurbs__             [link quickbook.syntax.block.blurbs Blurbs]]
[def __admonitions__        [link quickbook.syntax.block.admonitions Admonitions]]
[def __tables__             [link quickbook.syntax.block.tables Tables]]
[def __variable_lists__     [link quickbook.syntax.block.variable_lists Variable Lists]]
[def __include__            [link quickbook.syntax.block.include Include]]
[def __import__             [link quickbook.syntax.block.import Import]]

[section:intro Introduction]

[:[*['["Why program by hand in five days what you can spend five years of your
life automating?]]]

-- Terrence Parr, author ANTLR/PCCTS
]

Well, QuickBook started as a weekend hack. It was originally intended to be a
sample application using __spirit__. What is it? What you are viewing now, this
documentation, is autogenerated by QuickBook. These files were generated from
one master:

[:[@../quickbook.qbk quickbook.qbk]]

Originally named QuickDoc, this funky tool that never dies evolved into a
funkier tool thanks to Eric Niebler who resurrected the project making it
generate __boostbook__ instead of HTML. The __boostbook__ documentation format
is an extension of __docbook__, an SGML or XML based format for describing
documentation.

QuickBook is a WikiWiki style documentation tool geared towards C++
documentation using simple rules and markup for simple formatting tasks.
QuickBook extends the WikiWiki concept. Like the WikiWiki, QuickBook documents are
simple text files. A single QuickBook document can generate a fully linked set
of nice HTML and PostScript/PDF documents complete with images and syntax-
colorized source code.

Features include:

* generate __boostbook__ xml, to generate HTML, PostScript and PDF
* simple markup to link to Doxygen-generated entities
* macro system for simple text substitution
* simple markup for italics, bold, preformatted, blurbs, code samples,
  tables, URLs, anchors, images, etc.
* automatic syntax coloring of code samples
* CSS support

[endsect]

[section:change_log Change Log]

[h3 Version 1.3]

* Quickbook file inclusion \[include\].
* Better xml output (pretty layout). Check out the generated XML.
* Regression testing facility: to make sure your document will always be
  compatible (full backward compatibility) regardless of changes to
  QuickBook.
* Code cleanup and refactoring.
* Allow phrase markup in the doc-info.
* Preformatted code blocks via \`\`code\`\` (double ticks) allows code in tables
  and lists, for example.
* Quickbook versioning; allows full backward compatibility. You have to add
  \[quickbook 1.3\] to the doc-info header to enable the new features. Without
  this, QuickBook will assume that the document is a pre-1.3 document.
* Better (intuitive) paragraph termination. Some markups may terminate a paragraph.
  Example:``
  [section x]
  blah...
  [endsect]``
* Fully qualified section and headers. Subsection names are concatenated to the
  ID to avoid clashing. Example: `doc_name.sect_name.sub_sect_name.sub_sub_sect_name`
* Better   and whitespace handling in code snippets.
* \[xinclude\] fixes up the relative path to the target XML file when
  input_directory is not the same as the output_directory.
* Allow untitled tables.
* Allow phrase markups in section titles.
* Allow escaping back to QuickBook from code, code blocks and inline code.
* Footnotes, with the \[footnote This is the footnote\] syntax.
* Post-processor bug fix for escaped XML code that it does not recognize.
* Replaceable, with the \[~replacement\] syntax.
* Generic Headers
* Code changes to allow full recursion (i.e. Collectors and push/pop functions)
* Various code cleanup/maintenance
* Templates!
* \[conceptref\] for referencing BoostBook <concept> entities.
* Allow escape of spaces. The escaped space is removed from the output. Syntax:
  `\ `.
* Nested comments are now allowed.
* Quickbook blocks can nest inside comments.
* __import__ facility.
* Callouts on imported code
* Simple markups can now span a whole block.
* __blurbs__, __admonitions__ and table cells (see __tables__) may now
  contain paragraphs.
* `\n` and `[br]` are now deprecated.

[endsect]

[section:syntax Syntax Summary]

A QuickBook document is composed of one or more blocks. An example of
a block is the paragraph or a C++ code snippet. Some blocks have
special mark-ups. Blocks, except code snippets which have their own
grammar (C++ or Python), are composed of one or more phrases. A phrase
can be a simple contiguous run of characters. Phrases can have special
mark-ups. Marked up phrases can recursively contain other phrases, but
cannot contain blocks. A terminal is a self contained block-level or
phrase-level element that does not nest anything.

Blocks, in general, are delimited by two end-of-lines (the block terminator).
Phrases in each block cannot contain a block terminator. This way, syntax errors
such as un-matched closing brackets do not go haywire and corrupt anything past
a single block.

[section Comments]

Can be placed anywhere.

[pre
'''[/ comment (no output generated) ]'''
]

[/ for testing only... ]

[pre
'''[/ comments can be nested [/ some more here] ]'''
]

[/ for testing [/ only ] ]

[pre
'''[/ Quickbook blocks can nest inside comments. [*Comment this out too!] ]'''
]

[/ for testing [*only ] ]

[endsect]

[section:phrase Phrase Level Elements]

[section Font Styles]

[pre'''
['italic], [*bold], [_underline], [^teletype], [-strikethrough]
''']

will generate:

['italic], [*bold], [_underline], [^teletype], [-strikethrough]

Like all non-terminal phrase level elements, this can of course be nested:

[pre'''
[*['bold-italic]]
''']

will generate:

[*['bold-italic]]

[endsect]

[section Replaceable]

When you want content that may or must be replaced by the user, use the syntax:

[pre'''
[~replacement]
''']

This will generate:

[~replacement]

[endsect]

[section Quotations]

[pre'''
["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein
''']

will generate:

["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein

Note the proper left and right quote marks. Also, while you can simply use
ordinary quote marks like "quoted", our quotation, above, will generate correct
DocBook quotations (e.g. <quote>quoted</quote>).

Like all phrase elements, quotations may be nested. Example:

[pre'''
["Here's the rule for bargains: ["Do other men, for they would do you.] That's
the true business precept.]
''']

will generate:

["Here's the rule for bargains: ["Do other men, for they would do you.]
That's the true business precept.]

[endsect]
[section Simple formatting]

Simple markup for formatting text, common in many applications, is now supported:

[pre'''
/italic/, *bold*, _underline_, =teletype=
''']

will generate:

/italic/, *bold*, _underline_, =teletype=

Unlike QuickBook's standard formatting scheme, the rules for simpler
alternatives are much stricter[footnote Thanks to David Barrett, author of
[@http://quinthar.com/qwikiwiki/index.php?page=Home Qwiki], for sharing
these samples and teaching me these obscure formatting rules. I wasn't sure
at all if __spirit__, being more or less a formal EBNF parser, can handle
the context sensitivity and ambiguity.].

* Simple markups cannot nest. You can combine a simple markup with a nestable markup.
* Simple markups cannot contain any other form of quickbook markup.
* A non-space character must follow the leading markup
* A non-space character must precede the trailing markup
* A space or a punctuation must follow the trailing markup
* If the matching markup cannot be found within a block, the formatting
  will not be applied. This is to ensure that un-matched formatting markups,
  which can be a common mistake, does not corrupt anything past a single block.
  We do not want the rest of the document to be rendered bold just because we
  forgot a trailing '*'. A single block is terminated by two end of lines or
  the close bracket: ']'.
* A line starting with the star will be interpreted as an unordered list.
  See __unordered_lists__.

[table More Formatting Samples
    [[Markup]                                           [Result]]
    [[[^'''*Bold*''']]                                  [*Bold*]]
    [[[^'''*Is bold*''']]                               [*Is bold*]]
    [[[^'''* Not bold* *Not bold * * Not bold *''']]    [* Not bold* *Not bold * * Not bold *]]
    [[[^'''This*Isn't*Bold (no bold)''']]               [This*Isn't*Bold (no bold)]]
    [[[^'''(*Bold Inside*) (parenthesis not bold)''']]  [(*Bold Inside*) (parenthesis not bold)]]
    [[[^'''*(Bold Outside)* (parenthesis bold)''']]     [*(Bold Outside)* (parenthesis bold)]]
    [[[^'''3*4*5 = 60 (no bold)''']]                    [3*4*5 = 60 (no bold)]]
    [[[^'''3 * 4 * 5 = 60 (no bold)''']]                [3 * 4 * 5 = 60 (no bold)]]
    [[[^'''3 *4* 5 = 60 (4 is bold)''']]                [3 *4* 5 = 60 (4 is bold)]]
    [[[^'''*This is bold* this is not *but this is*''']][*This is bold* this is not *but this is*]]
    [[[^'''*This is bold*.''']]                         [*This is bold*.]]
    [[[^'''*B*. (bold B)''']]                           [*B*. (bold B)]]
    [[[^'''['*Bold-Italic*]''']]                        [['*Bold-Italic*]]]
    [[[^'''*side-by*/-side/''']]                        [*side-by*/-side/]]
]

As mentioned, simple markups cannot go past a single block. The text
from "have" to "full" in the following paragraph will be rendered as
bold:

[pre'''
Baa baa black sheep, *have you any wool?
Yes sir, yes sir, three bags full!*
One for the master, one for the dame,
And one for the little boy who lives down the lane.
''']

Baa baa black sheep, *have you any wool?
Yes sir, yes sir, three bags full!*
One for the master, one for the dame,
And one for the little boy who lives down the lane.

But in the following paragraph, bold is not applied:

[pre'''
Baa baa black sheep, *have you any wool?
Yes sir, yes sir, three bags full!
One for the master, one for the dame,
And one for the little boy who lives down the lane.
''']

Baa baa black sheep, *have you any wool?
Yes sir, yes sir, three bags full!
One for the master, one for the dame,
And one for the little boy who lives down the lane.

[endsect]
[section Inline code]

Inlining code in paragraphs is quite common when writing C++ documentation. We
provide a very simple markup for this. For example, this:

[pre'''
This text has inlined code `int main() { return 0; }` in it.
''']

will generate:

This text has inlined code `int main() { return 0; }` in it. The code will be
syntax highlighted.

[note We simply enclose the code with the tick: [^'''"`"'''], not the
single quote: `"'"`. Note too that [^'''`some code`'''] is preferred over
[^'''[^some code]''']. ]

[endsect]
[section Code blocks]

Preformatted code simply starts with a space or a tab (See __code__).
However, such a simple syntax cannot be used as phrase elements in lists
(See __ordered_lists__ and __unordered_lists__), tables (See __tables__),
etc. Inline code (see above) can. The problem is, inline code does not
allow formatting with newlines, spaces, and tabs. These are lost.

We provide a phrase level markup that is a mix between the two. By using the
double-tick, instead of the single-tick, we are telling QuickBook to use
preformatted blocks of code. Example:

[pre
\`\`
    #include <iostream>

    int main()
    {
        std::cout << "Hello, World!" << std::endl;
        return 0;
    }
\`\`
]

will generate:

``
    #include <iostream>

    int main()
    {
        std::cout << "Hello, World!" << std::endl;
        return 0;
    }
``

[endsect]
[section Source Mode]

If a document contains more than one type of source code then the source
mode may be changed dynamically as the document is processed. All QuickBook
documents are initially in C++ mode by default, though an alternative
initial value may be set in the __document__ section.

To change the source mode, use the [^\[source-mode\]] markup, where
=source-mode= is one of the supported modes. For example, this:

[pre'''
Python's [python] `import` is rather like C++'s [c++] `#include`. A
C++ comment `// looks like this` whereas a Python comment [python]
`# looks like this`.
''']

will generate:

Python's [python] `import` is rather like C++'s [c++] `#include`. A
C++ comment `// looks like this` whereas a Python comment [python]
`#looks like this`.

[table Supported Source Modes
    [[Mode]                 [Source Mode Markup]]
    [[C++]                  [[^\[c++\]]]]
    [[Python]               [[^\[python\]]]]
]

[note The source mode strings are lowercase.]

[endsect]
[section line-break]

[pre'''
[br]
''']

[warning `[br]` is now deprecated. __blurbs__, __admonitions__ and
table cells (see __tables__) may now contain paragraphs.]

[endsect]
[section Anchors]

[pre'''
[#named_anchor]
''']

A named anchor is a hook that can be referenced by a link elsewhere in the
document. You can then reference an anchor with [^'''[link named_anchor
Some link text]''']. See __anchor_links__, __section__ and __heading__.

[endsect]
[section Links]

[pre'''
[@http://www.boost.org this is [*boost's] website....]
''']

will generate:

[@http://www.boost.org this is [*boost's] website....]

URL links where the link text is the link itself is common. Example:

[pre'''
see http://spirit.sourceforge.net/
''']

so, when the text is absent in a link markup, the URL is assumed. Example:

[pre
see '''[@http://spirit.sourceforge.net/]'''
]

will generate:

see [@http://spirit.sourceforge.net/]

[endsect]
[section Anchor links]

You can link within a document using:

[pre'''
[link section_id.normalized_header_text The link text]
''']

See sections __section__ and __heading__ for more info.

[endsect]
[section refentry links]

In addition, you can link internally to an XML refentry like:

[pre'''
[link xml.refentry The link text]
''']

This gets converted into [^<link linkend="xml.refentry">The link text</link>].

Like URLs, the link text is optional. If this is not present, the link text will
automatically be the refentry. Example:

[pre'''
[link xml.refentry]
''']

This gets converted into [^<link linkend="xml.refentry">xml.refentry</link>].

[endsect]
[section:code_links Code Links]

If you want to link to a function, class, member, enum, concept or header in the reference
section, you can use:

[pre'''
[funcref fully::qualified::function_name The link text]
[classref fully::qualified::class_name The link text]
[memberref fully::qualified::member_name The link text]
[enumref fully::qualified::enum_name The link text]
[macroref MACRO_NAME The link text]
[conceptref ConceptName The link text]
[headerref path/to/header.hpp The link text]
''']

Again, the link text is optional. If this is not present, the link text will
automatically be the function, class, member, enum, macro, concept or header. Example:

[pre'''
[classref boost::bar::baz]
''']

would have "boost::bar::baz" as the link text.

[endsect]
[section Escape]

The escape mark-up is used when we don't want to do any processing.

[pre
\'\'\'
escape (no processing/formatting)
\'\'\'
]

Escaping allows us to pass XML markup to __boostbook__ or __docbook__. For example:

[pre
\'\'\'
<emphasis role="bold">This is direct XML markup</emphasis>
\'\'\'
]

'''
<emphasis role="bold">This is direct XML markup</emphasis>
'''

[important Be careful when using the escape. The text must conform to
__boostbook__/__docbook__ syntax.]

[endsect]
[section Single char escape]

The backslash may be used to escape a single punctuation character. The
punctuation immediately after the backslash is passed without any processing.
This is useful when we need to escape QuickBook punctuations such as `[` and `]`.
For example, how do you escape the triple quote? Simple: [^\\'\\'\\']


`\n` has a special meaning. It is used to generate line breaks.

[warning `\n` and `[br]` are now deprecated. __blurbs__, __admonitions__
and table cells (see __tables__) may now contain paragraphs.]

The escaped space: `\ ` also has a special meaning. The escaped space is removed
from the output.

[endsect]
[section Images]

[pre'''
[$image.jpg]
''']

[endsect]
[section Footnotes]

As of version 1.3, QuickBook supports footnotes. Just put the text of the
footnote in a `[footnote]` block, and the text will be put at the bottom
of the current page. For example, this:

[pre'''
[footnote A sample footnote]
''']

will generate this[footnote A sample footnote].

[section Macro Expansion]

[pre'''
__a_macro_identifier__
''']

See __macros__ for details.

[endsect]

[section Template Expansion]

[pre'''
[a_template_identifier]
''']

See __templates__ for details.

[endsect]

[endsect]
[endsect]
[section:block Block Level Elements]

[section Document]

Every document must begin with a Document Info section, which should look
like this:

[pre'''
[document-type The Document Title
    [quickbook 1.3]
    [version 1.0]
    [id the_document_name]
    [dirname the_document_dir]
    [copyright 2000 2002 2003 Joe Blow, Jane Doe]
    [purpose The document's reason for being]
    [category The document's category]
    [authors [Blow, Joe], [Doe, Jane]]
    [license The document's license]
    [source-mode source-type]
]
''']

Where document-type is one of:

* book
* article
* library
* chapter
* part
* appendix
* preface
* qandadiv
* qandaset
* reference
* set

quickbook 1.3 declares the version of quickbook the document is written for.
In its absence, version 1.1 is assumed.

=version=, =id=, =dirname=, =copyright=, =purpose=, =category=, =authors=,
=license=, =last-revision= and =source-mode= are optional information.

=source-type= is a lowercase string setting the initial __source_mode__. If
the =source-mode= field is omitted, a default value of =c++= will be used.

[endsect]
[section Section]

Starting a new section is accomplished with:

[pre'''
[section:id The Section Title]
''']

where /id/ is optional. id will be the filename of the generated section.
If it is not present, "The Section Title" will be normalized and become the id.
Valid characters are =a-Z=, =A-Z=, =0-9= and =_=. All non-valid characters are
converted to underscore and all upper-case are converted to lower case.
Thus: "The Section Title" will be normalized to "the_section_title".

End a section with:

[pre'''
[endsect]
''']

Sections can nest, and that results in a hierarchy in the table of contents.

[endsect]
[section xinclude]

You can include another XML file with:

[pre'''
[xinclude file.xml]
''']

This is useful when file.xml has been generated by Doxygen and contains your
reference section.

[endsect]
[section Paragraphs]

Paragraphs start left-flushed and are terminated by two or more newlines. No
markup is needed for paragraphs. QuickBook automatically detects paragraphs from
the context. Block markups \[section, endsect, h1, h2, h3, h4, h5, h6, blurb,
(block-quote) ':', pre, def, table and include \] may also terminate a paragraph.

[endsect]

[section Lists]
[section Ordered lists]

[pre
# One
# Two
# Three
]

will generate:

# One
# Two
# Three

[endsect]
[section List Hierarchies]

List hierarchies are supported. Example:

[pre
# One
# Two
# Three
    # Three.a
    # Three.b
    # Three.c
# Four
    # Four.a
        # Four.a.i
        # Four.a.ii
# Five
]

will generate:

# One
# Two
# Three
    # Three.a
    # Three.b
    # Three.c
# Fourth
    # Four.a
        # Four.a.i
        # Four.a.ii
# Five

[endsect]
[section Long List Lines]

Long lines will be wrapped appropriately. Example:

[pre
# A short item.
# A very long item. A very long item. A very long item.
  A very long item. A very long item. A very long item.
  A very long item. A very long item. A very long item.
  A very long item. A very long item. A very long item.
  A very long item. A very long item. A very long item.
# A short item.
]

# A short item.
# A very long item. A very long item. A very long item.
  A very long item. A very long item. A very long item.
  A very long item. A very long item. A very long item.
  A very long item. A very long item. A very long item.
  A very long item. A very long item. A very long item.
# A short item.

[endsect]
[section Unordered lists]

[pre'''
* First
* Second
* Third
''']

will generate:

* First
* Second
* Third

[endsect]
[section Mixed lists]

Mixed lists (ordered and unordered) are supported. Example:

[pre'''
# One
# Two
# Three
    * Three.a
    * Three.b
    * Three.c
# Four
''']

will generate:

# One
# Two
# Three
    * Three.a
    * Three.b
    * Three.c
# Four

And...

[pre'''
# 1
    * 1.a
        # 1.a.1
        # 1.a.2
    * 1.b
# 2
    * 2.a
    * 2.b
        # 2.b.1
        # 2.b.2
            * 2.b.2.a
            * 2.b.2.b
''']

will generate:

# 1
    * 1.a
        # 1.a.1
        # 1.a.2
    * 1.b
# 2
    * 2.a
    * 2.b
        # 2.b.1
        # 2.b.2
            * 2.b.2.a
            * 2.b.2.b

[endsect]
[endsect]

[section Code]

Preformatted code starts with a space or a tab. The code will be
syntax highlighted according to the current __source_mode__:

[c++]

    #include <iostream>

    int main()
    {
        // Sample code
        std::cout << "Hello, World\n";
        return 0;
    }

[python]

    import cgi

    def cookForHtml(text):
        '''"Cooks" the input text for HTML.'''

        return cgi.escape(text)

[c++]

Macros that are already defined are expanded in source code. Example:

[pre'''
[def __array__ [@http://www.boost.org/doc/html/array/reference.html array]]
[def __boost__ [@http://www.boost.org/libs/libraries.htm boost]]

    using __boost__::__array__;
''']

Generates:

[def __array__ [@http://www.boost.org/doc/html/array/reference.html array]]
[def __boost__ [@http://www.boost.org/libs/libraries.htm boost]]

    using __boost__::__array__;

[endsect]
[section:escape_back Escaping Back To QuickBook]

Inside code, code blocks and inline code, QuickBook does not allow any
markup to avoid conflicts with the target syntax (e.g. c++). In case you
need to switch back to QuickBook markup inside code, you can do so using a
language specific /escape-back/ delimiter. In C++ and Python, the delimiter
is the double tick (back-quote): "\`\`" and "\`\`". Example:

[pre'''
void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``()
{
}
''']

Will generate:

    void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``()
    {
    }

When escaping from code to QuickBook, only phrase level markups are
allowed. Block level markups like lists, tables etc. are not allowed.

[endsect]
[section Preformatted]

Sometimes, you don't want some preformatted text to be parsed as C++. In such
cases, use the [^[pre ... \]] markup block.

[pre'''
[pre

    Some *preformatted* text                    Some *preformatted* text

        Some *preformatted* text            Some *preformatted* text

            Some *preformatted* text    Some *preformatted* text

]
''']

Spaces, tabs and newlines are rendered as-is. Unlike all quickbook block level
markup, pre (and Code) are the only ones that allow multiple newlines. The
markup above will generate:

[pre

Some *preformatted* text                    Some *preformatted* text

    Some *preformatted* text            Some *preformatted* text

        Some *preformatted* text    Some *preformatted* text

]

Notice that unlike Code, phrase markup such as font style is still permitted
inside =pre= blocks.

[endsect]
[section Blockquote]

[pre
'''[:sometext...]'''
]

[:Indents the paragraph. This applies to one paragraph only.]

[endsect]
[section Admonitions]

[pre'''
[note This is a note]
[tip This is a tip]
[important This is important]
[caution This is a caution]
[warning This is a warning]
''']

generates __docbook__ admonitions:

[note This is a note]
[tip This is a tip]
[important This is important]
[caution This is a caution]
[warning This is a warning]

These are the only admonitions supported by __docbook__. So,
for example [^\[information This is some information\]] is unlikely
to produce the desired effect.

[endsect]
[section Headings]

[pre'''
[h1 Heading 1]
[h2 Heading 2]
[h3 Heading 3]
[h4 Heading 4]
[h5 Heading 5]
[h6 Heading 6]
''']

[h1 Heading 1]
[h2 Heading 2]
[h3 Heading 3]
[h4 Heading 4]
[h5 Heading 5]
[h6 Heading 6]

Headings 1-3 \[h1 h2 and h3\] will automatically have anchors with normalized
names with [^name="section_id.normalized_header_text"] (i.e. valid characters are
=a-z=, =A-Z=, =0-9= and =_=. All non-valid characters are converted to underscore
and all upper-case are converted to lower-case. For example: Heading
1 in section Section 2 will be normalized to [^section_2.heading_1]). You can use:

[pre'''
[link section_id.normalized_header_text The link text]
''']

to link to them. See __anchor_links__ and __section__ for more info.

[endsect]
[section Generic Heading]

In cases when you don't want to care about the heading level (1 to 6), you
can use the /Generic Heading/:

[pre'''
[heading Heading]
''']

The /Generic Heading/ assumes the level, plus one, of the innermost section
where it is placed. For example, if it is placed in the outermost section,
then, it assumes /h2/.

Headings are often used as an alternative to sections. It is used
particularly if you do not want to start a new section. In many cases,
however, headings in a particular section is just flat. Example:

[pre'''
[section A]
[h2 X]
[h2 Y]
[h2 Z]
[endsect]
''']

Here we use h2 assuming that section A is the outermost level. If it is
placed in an inner level, you'll have to use h3, h4, etc. depending on
where the section is. In general, it is the section level plus one. It is
rather tedious, however, to scan the section level everytime. If you
rewrite the example above as shown below, this will be automatic:

[pre'''
[section A]
[heading X]
[heading Y]
[heading Z]
[endsect]
''']

They work well regardless where you place them. You can rearrange sections
at will without any extra work to ensure correct heading levels. In fact,
with /section/ and /heading/, you have all you need. /h1/../h6/ becomes
redundant. /h1/../h6/ might be deprecated in the future.

[endsect]
[section Macros]

[pre'''
[def macro_identifier some text]
''']

When a macro is defined, the identifier replaces the text anywhere in the
file, in paragraphs, in markups, etc. macro_identifier is a string of non-
white space characters except '\]'. A macro may not follow an alphabetic
character or the underscore. The replacement text can be any phrase (even
marked up). Example:

[pre'''
[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&amp;type=1]]
sf_logo
''']

Now everywhere the sf_logo is placed, the picture will be inlined.

[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&type=1]]
sf_logo

[tip It's a good idea to use macro identifiers that are distinguishable.
For instance, in this document, macro identifiers have two leading and
trailing underscores (e.g. [^'''__spirit__''']). The reason is to avoid
unwanted macro replacement.]

Links (URLS) and images are good candidates for macros. *1*) They tend to
change a lot. It is a good idea to place all links and images in one place near the top
to make it easy to make changes. *2*) The syntax is not pretty. It's easier to read and
write, e.g. [^'''__spirit__'''] than [^'''[@http://spirit.sourceforge.net Spirit]'''].

Some more examples:

[pre'''
[def :-)            [$theme/smiley.png]]
[def __spirit__     [@http://spirit.sourceforge.net Spirit]]
''']

(See __images__ and __links__)

Invoking these macros:

[pre'''
Hi __spirit__  :-)
''']

will generate this:

Hi __spirit__ :-)

[endsect]
[section Predefined Macros]

Quickbook has some predefined macros that you can already use.

[table Predefined Macros
    [[Macro]                [Meaning]                       [Example]]
    [['''__DATE__''']       [Today's date]                  [__DATE__]]
    [['''__TIME__''']       [The current time]              [__TIME__]]
    [['''__FILENAME__''']   [Quickbook source filename]     [__FILENAME__]]
]

[endsect]
[section Templates]

Templates provide a more versatile text substitution mechanism. Templates
come in handy when you need to create parameterizable, multi-line,
boilerplate text that you specify once and expand many times. Templates
accept one or more arguments. These arguments act like place-holders for
text replacement. Unlike simple macros, which are limited to phrase level
markup, templates can contain block level markup (e.g. paragraphs, code
blocks and tables).

Example template:

[pre'''
[template person[name age what]

Hi, my name is [name]. I am [age] years old. I am a [what].

]
''']

[template person[name age what]

Hi, my name is [name]. I am [age] years old. I am a [what].

]

[heading Template Identifier]

Template identifiers can either consist of:

* An initial alphabetic character or the underscore, followed by
  zero or more alphanumeric characters or the underscore. This is
  similar to your typical C/C++ identifier.
* A single character punctuation (a non-alphanumeric printable character)

[heading Formal Template Arguments]

Template formal arguments are identifiers consisting of an initial
alphabetic character or the underscore, followed by zero or more
alphanumeric characters or the underscore. This is similar to your typical
C/C++ identifier.

A template formal argument temporarily hides a template of the same name at
the point where the [link quickbook.syntax.block.templates.template_expansion
template is expanded]. Note that the body of the [^person] template above
refers to [^name] [^age] and [^what] as [^\[name\]] [^\[age\]] and
[^\[what\]]. [^name] [^age] and [^what] are actually templates that exist
in the duration of the template call.

[heading Template Body]

The template body can be just about any QuickBook block or phrase. There
are actually two forms. Templates may be phrase or block level. Phrase
templates are of the form:

[pre'''
[template sample[arg1 arg2...argN] replacement text... ]
''']

Block templates are of the form:

[pre'''
[template sample[arg1 arg2...argN]
replacement text...
]
''']

The basic rule is as follows: if a newline immediately follows the argument
list, then it is a block template, otherwise, it is a phrase template.
Phrase templates are typically expanded as part of phrases. Like macros,
block level elements are not allowed in phrase templates.

[heading Template Expansion]

You expand a template this way:

[pre'''
[template_identifier arg1..arg2..arg3]
''']

At template expansion, you supply the actual arguments. The template will
be expanded with your supplied arguments. Example:

[pre'''
[person James Bond..39..Spy]
[person Santa Clause..87..Big Red Fatso]
''']

Which will expand to:

[person James Bond..39..Spy]
[person Santa Clause..87..Big Red Fatso]

[caution A word of caution: Templates are recursive. A template can call
another template or even itself, directly or indirectly. There are no
control structures in QuickBook (yet) so this will always mean infinite
recursion. QuickBook can detect this situation and report an error if
recursion exceeds a certain limit.]

Each actual argument can be a word, a text fragment or just about any [link
quickbook.syntax.phrase QuickBook phrase]. Arguments are separated by the
double dot [^".."] and terminated by the close parenthesis.

[heading Nullary Templates]

Nullary templates look and act like simple macros. Example:

[pre'''
[template alpha[]&apos;&apos;&apos;&amp;#945;&apos;&apos;&apos;]
[template beta[]&apos;&apos;&apos;&amp;#946;&apos;&apos;&apos;]
''']

[template alpha[]'''&#945;''']
[template beta[]'''&#946;''']

Expanding:

[pre'''Some squigles...[*[alpha][beta]]''']

We have:

Some squiggles...[*[alpha][beta]]

The difference with macros are

* The explicit [link quickbook.syntax.block.templates.template_expansion
  template expansion syntax]. This is an advantage because, now, we don't
  have to use obscure naming conventions like double underscores (e.g.
  \_\_alpha\_\_) to avoid unwanted
  macro replacement.
* The template is expanded at the point where it is invoked. A macro is
  expanded immediately at its point of declaration. This is subtle and
  can cause a slight difference in behavior especially if you refer to
  other macros and templates in the body.

The empty brackets after the template identifier ([^alpha\[\]]) indicates no
arguments. If the template body does not look like a template argument list, we
can elide the empty brackets. Example:

[pre'''
[template aristotle_quote Aristotle: [*['Education is the best provision
for the journey to old age.]]]
''']

[template aristotle_quote\ Aristotle: [*['Education is the best provision
for the journey to old age.]]]

Expanding:

[pre'''
Here's a quote from [aristotle_quote].
''']

We have:

Here's a quote from [aristotle_quote].

The disadvantage is that you can't avoid the space between the template
identifier, `aristotle_quote`, and the template body "Aristotle...". This space
will be part of the template body. If that space is unwanted, use empty
brackets or use the space escape: "`\ `". Example:

[pre'''
[template tag\ _tag]
''']

[template tag\ _tag]

Then expanding:

[pre'''
`struct` x[tag];
''']

We have:

`struct` x[tag];

You have a couple of ways to do it. I personally prefer the explicit empty
brackets, though.

[heading Simple Arguments]

As mentioned, arguments are separated by the double dot [^".."]. If there
are less arguments passed than expected, QuickBook attempts to break the
last argument into two or more arguments following this logic:

* Break the last argument into two, at the first space found ([^'', '\\n',
  \\t' or '\\r']).
* Repeat until there are enough arguments or if there are no more spaces
  found (in which case, an error is reported).

For example:

[pre'''
[template simple[a b c d] [a][b][c][d]]
[simple w x y z]
''']

will produce:

[template simple[a b c d] [a][b][c][d]]
[simple w x y z]

"w x y z" is initially treated as a single argument because we didn't
supply any [^".."] separators. However, since [^simple] expects 4
arguments, "w x y z" is broken down iteratively (applying the logic above)
until we have "w", "x", "y" and "z".

QuickBook only tries to get the arguments it needs. For example:

[pre'''
[simple w x y z trail]
''']

will produce:

[simple w x y z trail]

The arguments being: "w", "x", "y" and "z trail".

It should be obvious now that for simple arguments with no spaces, we can
get by without separating the arguments with [^".."] separators. It is
possible to combine [^".."] separators with the argument passing
simplification presented above. Example:

[pre'''
[simple what do you think ..m a n?]
''']

will produce:

[simple what do you think ..m a n?]

[heading Punctuation Templates]

With templates, one of our objectives is to allow us to rewrite QuickBook
in QuickBook (as a qbk library). For that to happen, we need to accommodate
single character punctuation templates which are fairly common in
QuickBook. You might have noticed that single character punctuations are
allowed as [link quickbook.syntax.block.templates.template_identifier
template identifiers]. Example:

[pre'''
[template ![bar] '''<hey>'''[bar]'''</hey>''']
''']

Now, expanding this:

[pre'''
[!baz]
''']

We will have:

[pre
<hey>baz</hey>
]

[endsect]
[section Blurbs]

[pre'''
[blurb :-) [*An eye catching advertisement or note...]

    __spirit__ is an object-oriented recursive-descent parser generator framework
    implemented using template meta-programming techniques. Expression templates
    allow us to approximate the syntax of Extended Backus-Normal Form (EBNF)
    completely in C++.
]
''']

will generate this:

[blurb :-) [*An eye catching advertisement or note...]

    __spirit__ is an object-oriented recursive-descent parser generator
    framework implemented using template meta-programming techniques. Expression
    templates allow us to approximate the syntax of Extended Backus-Normal Form
    (EBNF) completely in C++.
]

[note Prefer [link quickbook.syntax.block.admonitions admonitions] wherever
appropriate.]

[endsect]
[section Tables]

[pre'''
[table A Simple Table
    [[Heading 1] [Heading 2] [Heading 3]]
    [[R0-C0]     [R0-C1]     [R0-C2]]
    [[R1-C0]     [R1-C1]     [R1-C2]]
    [[R2-C0]     [R2-C1]     [R2-C2]]
]
''']

will generate:

[table A Simple Table
    [[Heading 1] [Heading 2] [Heading 3]]
    [[R0-C0]     [R0-C1]     [R0-C2]]
    [[R2-C0]     [R2-C1]     [R2-C2]]
    [[R3-C0]     [R3-C1]     [R3-C2]]
]

The table title is optional. The first row of the table is automatically
treated as the table header; that is, it is wrapped in
[^<thead>...</thead>] XML tags. Note that unlike the original QuickDoc, the
columns are nested in [ cells... ]. The syntax is free-format and allows
big cells to be formatted nicely. Example:

[pre'''
[table Table with fat cells
    [[Heading 1] [Heading 2]]
    [
        [Row 0, Col 0: a small cell]
        [
            Row 0, Col 1: a big fat cell with paragraphs

            Boost provides free peer-reviewed portable C++ source libraries.

            We emphasize libraries that work well with the C++ Standard Library.
            Boost libraries are intended to be widely useful, and usable across
            a broad spectrum of applications. The Boost license encourages both
            commercial and non-commercial use.
        ]
    ]
    [
        [Row 1, Col 0: a small cell]
        [Row 1, Col 1: a small cell]
    ]
]
''']

and thus:

[table Table with fat cells
    [[Heading 1] [Heading 2]]
    [
        [Row 0, Col 0: a small cell]
        [
            Row 0, Col 1: a big fat cell with paragraphs

            Boost provides free peer-reviewed portable C++ source libraries.

            We emphasize libraries that work well with the C++ Standard Library.
            Boost libraries are intended to be widely useful, and usable across
            a broad spectrum of applications. The Boost license encourages both
            commercial and non-commercial use.
        ]
    ]
    [
        [Row 1, Col 0: a small cell]
        [Row 1, Col 1: a small cell]
    ]
]

Here's how to have preformatted blocks of code in a table cell:

[pre'''
[table Table with code
    [[Comment] [Code]]
    [
        [My first program]
        ['''\`\`
            #include <iostream>

            int main()
            {
                std::cout << "Hello, World!" << std::endl;
                return 0;
            }
        \`\`''']
    ]
]
''']

[table Table with code
    [[Comment] [Code]]
    [
        [My first program]
        [``
            #include <iostream>

            int main()
            {
                std::cout << "Hello, World!" << std::endl;
                return 0;
            }
        ``]
    ]
]

[endsect]
[section Variable Lists]

[pre'''
[variablelist A Variable List
    [[term 1] [The definition of term 1]]
    [[term 2] [The definition of term 2]]
    [[term 3] [The definition of term 3]]
]
''']

will generate:

[variablelist A Variable List
    [[term 1] [The definition of term 1]]
    [[term 2] [The definition of term 2]]
    [[term 3] [The definition of term 3]]
]

The rules for variable lists are the same as for tables, except that
only 2 "columns" are allowed. The first column contains the terms, and
the second column contains the definitions. Those familiar with HTML
will recognize this as a "definition list".

[endsect]
[section Include]

You can include one QuickBook file from another. The syntax is simply:

[pre'''
[include someother.qbk]
''']

The included file will be processed as if it had been cut and pasted
into the current document, with the following exceptions:

* The '''__FILENAME__''' predefined macro will reflect the name of the
  file currently being processed.
* Any macros defined in the included file are scoped to that file.

The [^\[include\]] directive lets you specify a document id to use for the
included file. When this id is not explicitly specified, the id defaults to
the filename ("someother", in the example above). You can specify the id
like this:

[pre'''
[include:someid someother.qbk]
''']

All auto-generated anchors will use the document id as a unique prefix. So
for instance, if there is a top section in someother.qbk named "Intro", the
named anchor for that section will be "someid.intro", and you can link to
it with [^\[link someid.intro The Intro\]].

[endsect]

[section Import]

When documenting code, you'd surely need to present code from actual source
files. While it is possible to copy some code and paste them in your QuickBook
file, doing so is error prone and the extracted code in the documentation tends
to get out of sync with the actual code as the code evolves. The problem, as
always, is that once documentation is written, the tendency is for the docs to
languish in the archives without maintenance.

QuickBook's import facility provides a nice solution.

[heading Example]

You can effortlessly import code snippets from source code into your QuickBook.
The following illustrates how this is done:

[pre'''
[import ../test/stub.cpp]
[foo]
[bar]
''']

The first line:

[pre'''
[import ../test/stub.cpp]
''']

collects specially marked-up code snippets from [@../../test/stub.cpp stub.cpp]
and places them in your QuickBook file as virtual templates. Each of the
specially marked-up code snippets has a name (e.g. `foo` and `bar` in the
example above). This shall be the template identifier for that particular code
snippet. The second and third line above does the actual template expansion:

[pre'''
[foo]
[bar]
''']

And the result is:

[import ../test/stub.cpp]
[foo]
[bar]

[heading Code Snippet Markup]

Note how the code snippets in [@../../test/stub.cpp stub.cpp] get marked up. We
use distinguishable comments following the form:

    //[id
    some code here
    //]

The first comment line above initiates a named code-snippet. This prefix will
not be visible in quickbook. The entire code-snippet in between `//[id` and
`//]` will be inserted as a template in quickbook with name ['/id/]. The comment
`//]` ends a code-snippet This too will not be visible in quickbook.

[heading Special Comments]

Special comments of the form:

    //` some [*quickbook] markup here

and:

    /*` some [*quickbook] markup here */

will be parsed by QuickBook. This can contain quickbook /blocks/ (e.g. sections,
paragraphs, tables, etc). In the first case, the initial slash-slash, tick and
white-space shall be ignored. In the second, the initial slash-star-tick and the
final star-slash shall be ignored.

[heading Callouts]

Special comments of the form:

    /*< some [*quickbook] markup here >*/

will be regarded as callouts. These will be collected, numbered and
rendered as a "callout bug" (a small icon with a number). After the
whole snippet is parsed, the callout list is generated. See
[@http://www.docbook.org/tdg/en/html/callout.html Callouts] for details.
Example:

[foo_bar]

Checkout [@../../test/stub.cpp stub.cpp] to see the actual code.

[endsect]

[endsect]
[endsect]

[section:install Installation and configuration]

This section provides some guidelines on how to install and configure
BoostBook and Quickbook under several operating systems.

Before continuing, it is very important that you keep this in mind: if you
try to build some documents and the process breaks due to misconfiguration,
be absolutely sure to delete any `bin` and `bin.v2` directories generated
by the build before trying again.  Otherwise your configuration fixes will
not take any effect.

[section:windows Windows 2000, XP, 2003, Vista]

[python]

[:['Section contributed by Julio M. Merino Vidal]]

The following instructions apply to any Windows system based on Windows
2000, including Windows XP, Windows 2003 Server and Windows Vista. The
paths shown below are taken from a Windows Vista machine; you will need to
adjust them to match your system in case you are running an older version.

# First of all you need to have a copy of `xsltproc` for Windows.  There
  are many ways to get this tool, but to keep things simple, use the
  [@http://www.zlatkovic.com/pub/libxml/ binary packages] made by Igor
  Zlatkovic.  At the very least, you need to download the following
  packages: `iconv`, `zlib`, `libxml2` and `libxslt`.

# Unpack all these packages in the same directory so that you get unique
  `bin`, `include` and `lib` directories within the hierarchy.  These
  instructions use `C:\Users\example\Documents\boost\xml` as the root for
  all files.

# From the command line, go to the `bin` directory and launch
  `xsltproc.exe` to ensure it works.  You should get usage information on
  screen.

# Download [@http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip Docbook XML
  4.2] and unpack it in the same directory used above.  That is:
  `C:\Users\example\Documents\boost\xml\docbook-xml`.

# Download the latest
  [@http://sourceforge.net/project/showfiles.php?group_id=21935&package_id=16608
  Docbook XSL] version and unpack it, again in the same directory
  used before.  To make things easier, rename the directory created
  during the extraction to `docbook-xsl` (bypassing the version name):
  `C:\Users\example\Documents\boost\xml\docbook-xsl`.

# Add the following to your `user-config.jam` file, which should live in
  your home directory (`%HOMEDRIVE%%HOMEPATH%`).  You must already have it
  somewhere or otherwise you could not be building Boost (i.e. missing
  tools configuration).

 using xsltproc
     : "C:/Users/example/Documents/boost/xml/bin/xsltproc.exe"
     ;

 using boostbook
     : "C:/Users/example/Documents/boost/xml/docbook-xsl"
     : "C:/Users/example/Documents/boost/xml/docbook-xml"
     ;

The above steps are enough to get a functional BoostBook setup.  Quickbook
will be automatically built when needed.  If you want to avoid these
rebuilds:

# Go to Quickbook's source directory (`BOOST_ROOT\tools\quickbook`).

# Build the utility by issuing `bjam --v2`.

# Copy the resulting `quickbook.exe` binary (located under the
  `BOOST_ROOT\bin.v2` hierarchy) to a safe place.  Following our previous
  example, you can install it into:
  `C:\Users\example\Documents\boost\xml\bin`.

# Add the following to your `user-config.jam` file:

 using quickbook
     : "C:/Users/example/Documents/boost/xml/bin/quickbook.exe"
     ;

[endsect]

[section:linux Debian, Ubuntu]

The following instructions apply to Debian and its derivatives. They are based
on a Ubuntu Edgy install but should work on other Debian based systems.

First install the `bjam`, `xsltproc`, `docbook-xsl` and `docbook-xml` packages.
For example, using `apt-get`:

    sudo apt-get install xsltprc docbook-xsl docbook-xml

If you're planning on building boost's documentation, you'll also need to
install the `doxygen` package as well.

Next, we need to configure Boost Build to compile BoostBook files. Add the
following to your `user-config.jam` file, which should be in your home
directory. If you don't have one, create a file containing this text. For more
information on setting up `user-config.jam`, see the
[@http://boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html Boost
Build documentation].

    using xsltproc ;

    using boostbook
        : /usr/share/xml/docbook/stylesheet/nwalsh
        : /usr/share/xml/docbook/schema/dtd/4.2
        ;

    # Remove this line if you're not using doxygen
    using doxygen ;

The above steps are enough to get a functional BoostBook setup.  Quickbook
will be automatically built when needed.  If you want to avoid these
rebuilds:

# Go to Quickbook's source directory (`BOOST_ROOT/tools/quickbook`).

# Build the utility by issuing `bjam --v2`.

# Copy the resulting `quickbook` binary (located under the
  `BOOST_ROOT/bin.v2` hierarchy) to a safe place.  The traditional location is
  `/usr/local/bin`.

# Add the following to your `user-config.jam` file, using the full path of the
  quickbook executable:

 using quickbook
     : /usr/local/bin/quickbook
     ;

[endsect]
[endsect] [/Installation and configuration]

[section:editors Editor Support]

Editing quickbook files is usually done with text editors both simple and
powerful. The following sections list the settings for some editors which can
help make editing quickbook files a bit easier.

[blurb __note__ You may submit your settings, tips, and suggestions to the
authors, or through the [@https://lists.sourceforge.net/lists/listinfo/boost-
docs Boost Docs mailing list].]

[section:scite Scintilla Text Editor]

[:['Section contributed by Dean Michael Berris]]

The Scintilla Text Editor (SciTE) is a free source code editor for Win32 and X.
It uses the SCIntilla source code editing component.

[blurb __tip__ SciTE can be downloaded from [@http://www.scintilla.org/SciTE.html]]

You can use the following settings to highlight quickbook tags when
editing quickbook files.

[pre'''
qbk=*.qbk
lexer.*.qbk=props
use.tabs.$(qbk)=0
tab.size.$(qbk)=4
indent.size.$(qbk)=4
style.props.32=$(font.base)
comment.stream.start.props=[/
comment.stream.end.props=]
comment.box.start.props=[/
comment.box.middle.props=
comment.box.end.props=]
''']

[blurb __note__ Thanks to Rene Rivera for the above SciTE settings.]

[endsect] [/scite]
[endsect] [/editors]

[section:faq Frequently Asked Questions]

[heading Can I use QuickBook for non-Boost documentation?]

QuickBook can be used for non-Boost documentation with a little extra work.

[:['Faq contributed by Michael Marcin]]

When building HTML documentation with BoostBook a Boost C++ Libraries header
is added to the files. When using QuickBook to document projects outside of
Boost this is not desirable. This behavior can be overridden at the BoostBook
level by specifying some XSLT options. When using Boost Build version 2 (BBv2)
this can be achieved by adding parameters to the BoostBook target declaration.

For example:
[pre
using quickbook ;

xml my_doc : my_doc.qbk ;

boostbook standalone
    :
        my_doc
    :
        <xsl:param>boost.image.src=images/my_project_logo.png
        <xsl:param>boost.image.alt="\\"My Project\\""
        <xsl:param>boost.image.w=100
        <xsl:param>boost.image.h=50
        <xsl:param>nav.layout=none
    ;
]

[endsect] [/faq]

[section:ref Quick Reference]

[cpp]

[template ordered_list_sample[]
[pre'''
# one
# two
# three
''']
]

[template unordered_list_sample[]
[pre'''
* one
* two
* three
''']
]

[template table_sample[]
[pre'''
[table Title
[[a][b][c]]
[[a][b][c]]
]
''']
]

[template var_list_sample[]
[pre'''
[variablelist Title
[[a][b]]
[[a][b]]
]
''']
]


[table Syntax Compendium
    [[To do this...]        [Use this...]                                   [See this...]]
    [[comment]              [[^'''[/ some comment]''']]                     [__comments__]]
    [[['italics]]           [[^'''['italics] or /italics/''']]              [__font_styles__ and __simple_formatting__]]
    [[[*bold]]              [[^'''[*bold] or *bold*''']]                    [__font_styles__ and __simple_formatting__]]
    [[[_underline]]         [[^'''[_underline] or _underline_''']]          [__font_styles__ and __simple_formatting__]]
    [[[^teletype]]          [[^'''[^teletype] or =teletype=''']]            [__font_styles__ and __simple_formatting__]]
    [[[-strikethrough]]     [[^'''[-strikethrough]''']]                     [__font_styles__ and __simple_formatting__]]
    [[[~replaceable]]       [[^'''[~replaceable]''']]                       [__replaceable__]]
    [[source mode]          [[^\[c++\]] or [^\[python\]]]                   [__source_mode__]]
    [[inline code]          [[^'''`int main();`''']]                        [__inline_code__]]
    [[code block]           [[^'''``int main();``''']]                      [__code__]]
    [[code escape]          [[^'''``from c++ to QuickBook``''']]            [__escape_back__]]
    [[line break]           [[^'''[br] or \n''']]                           [__line_break__ *DEPRECATED*]]
    [[anchor]               [[^'''[#anchor]''']]                            [__anchors__]]
    [[link]                 [[^'''[@http://www.boost.org Boost]''']]        [__links__]]
    [[anchor link]          [[^'''[link section.anchor Link text]''']]      [__anchor_links__]]
    [[refentry link]        [[^'''[link xml.refentry Link text]''']]        [__refentry_links__]]
    [[function link]        [[^'''[funcref fully::qualified::function_name Link text]''']]      [__code_links__]]
    [[class link]           [[^'''[classref fully::qualified::class_name Link text]''']]        [__code_links__]]
    [[member link]          [[^'''[memberref fully::qualified::member_name Link text]''']]      [__code_links__]]
    [[enum link]            [[^'''[enumref fully::qualified::enum_name Link text]''']]          [__code_links__]]
    [[macro link]           [[^'''[macroref MACRO_NAME Link text]''']]                          [__code_links__]]
    [[concept link]         [[^'''[conceptref ConceptName Link text]''']]                       [__code_links__]]
    [[header link]          [[^'''[headerref path/to/header.hpp Link text]''']]                 [__code_links__]]
    [[escape]               [[^\'\'\'escaped text (no processing/formatting)\'\'\']]            [__escape__]]
    [[single char escape]   [[^\\c]]                                        [__single_char_escape__]]
    [[images]               [[^'''[$image.jpg]''']]                         [__images__]]
    [[begin section]        [[^'''[section The Section Title]''']]          [__section__]]
    [[end section]          [[^'''[endsect]''']]                            [__section__]]
    [[paragraph]            [No markup. Paragraphs start left-flushed and are terminated by two or more newlines.]  [__paragraphs__]]
    [[ordered list]         [[ordered_list_sample]]                         [__ordered_lists__]]
    [[unordered list]       [[unordered_list_sample]]                       [__unordered_lists__]]
    [[code]                 [No markup. Preformatted code starts with a space or a tab.]        [__code__]]
    [[preformatted]         [[^'''[pre preformatted]''']]                   [__preformatted__]]
    [[block quote]          [[^'''[:sometext...]''']]                       [__blockquote__]]
    [[heading 1]            [[^'''[h1 Heading 1]''']]                       [__heading__]]
    [[heading 2]            [[^'''[h2 Heading 2]''']]                       [__heading__]]
    [[heading 3]            [[^'''[h3 Heading 3]''']]                       [__heading__]]
    [[heading 4]            [[^'''[h4 Heading 4]''']]                       [__heading__]]
    [[heading 5]            [[^'''[h5 Heading 5]''']]                       [__heading__]]
    [[heading 6]            [[^'''[h6 Heading 6]''']]                       [__heading__]]
    [[macro]                [[^'''[def macro_identifier some text]''']]     [__macros__]]
    [[template]             [[^'''[template[a b] [a] body [b]]''']]         [__templates__]]
    [[blurb]                [[^'''[blurb advertisement or note...]''']]     [__blurbs__]]
    [[admonition]           [[^'''[warning Warning text...]''']]            [__admonitions__]]
    [[table]                [[table_sample]]                                [__tables__]]
    [[variablelist]         [[var_list_sample]]                             [__variable_lists__]]
    [[include]              [[^'''[include someother.qbk]''']]              [__include__]]
]

[endsect]