2
Copyright 2002,2004,2006 Joel de Guzman, Eric Niebler
3
Copyright 2010-2011 Daniel James
5
Distributed under the Boost Software License, Version 1.0.
6
(See accompanying file LICENSE_1_0.txt or copy at
7
http://www.boost.org/LICENSE_1_0.txt)
10
[chapter Block Level Elements
12
[compatibility-mode 1.5]
13
[id quickbook.syntax.block]
14
[source-mode teletype]
19
You can include another XML file with:
25
This is useful when file.xml has been generated by Doxygen and contains your
32
Paragraphs start left-flushed and are terminated by two or more newlines. No
33
markup is needed for paragraphs. QuickBook automatically detects paragraphs from
34
the context. Block markups \[section, endsect, h1, h2, h3, h4, h5, h6, blurb,
35
(block-quote) ':', pre, def, table and include \] may also terminate a paragraph.
36
[/ <-- There's a space here. Don't remove. this is intentianal, for testing]
37
This is a new paragraph...
39
[endsect] [/Paragraphs]
42
[section Ordered lists]
56
[endsect] [/Ordered lists]
57
[section List Hierarchies]
59
List hierarchies are supported. Example:
89
[endsect] [/List Hierarchies]
90
[section Long List Lines]
92
Long lines will be wrapped appropriately. Example:
96
# A very long item. A very long item. A very long item.
97
A very long item. A very long item. A very long item.
98
A very long item. A very long item. A very long item.
99
A very long item. A very long item. A very long item.
100
A very long item. A very long item. A very long item.
105
# A very long item. A very long item. A very long item.
106
A very long item. A very long item. A very long item.
107
A very long item. A very long item. A very long item.
108
A very long item. A very long item. A very long item.
109
A very long item. A very long item. A very long item.
112
[endsect] [/Long list lines]
113
[section Unordered lists]
127
[endsect] [/Unordered lists]
128
[section Mixed lists]
130
Mixed lists (ordered and unordered) are supported. Example:
184
[endsect] [/Mixed lists]
189
Preformatted code starts with a space or a tab. The code will be
190
syntax highlighted according to the current __source_mode__:
199
std::cout << "Hello, World\n";
207
def cookForHtml(text):
208
'''"Cooks" the input text for HTML.'''
210
return cgi.escape(text)
214
Macros that are already defined are expanded in source code. Example:
217
[def __array__ [@http://www.boost.org/doc/html/array/reference.html array]]
218
[def __boost__ [@http://www.boost.org/libs/libraries.htm boost]]
220
using __boost__::__array__;
225
[def __array__ [@http://www.boost.org/doc/html/array/reference.html array]]
226
[def __boost__ [@http://www.boost.org/libs/libraries.htm boost]]
228
using __boost__::__array__;
232
[section:escape_back Escaping Back To QuickBook]
234
Inside code, code blocks and inline code, QuickBook does not allow any
235
markup to avoid conflicts with the target syntax (e.g. c++). In case you
236
need to switch back to QuickBook markup inside code, you can do so using a
237
language specific /escape-back/ delimiter. In C++ and Python, the delimiter
238
is the double tick (back-quote): "\`\`" and "\`\`". Example:
241
void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``()
248
void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``()
252
When escaping from code to QuickBook, only phrase level markups are
253
allowed. Block level markups like lists, tables etc. are not allowed.
255
[endsect] [/Escaping back to quickbook]
257
[section Preformatted]
259
Sometimes, you don't want some preformatted text to be parsed as source code. In such
260
cases, use the [^\[pre ... \]] markup block.
265
Some *preformatted* text Some *preformatted* text
267
Some *preformatted* text Some *preformatted* text
269
Some *preformatted* text Some *preformatted* text
274
Spaces, tabs and newlines are rendered as-is. Unlike all quickbook block level
275
markup, pre (and Code) are the only ones that allow multiple newlines. The
276
markup above will generate:
280
Some *preformatted* text Some *preformatted* text
282
Some *preformatted* text Some *preformatted* text
284
Some *preformatted* text Some *preformatted* text
288
Notice that unlike Code, phrase markup such as font style is still permitted
291
[endsect] [/Preformatted]
299
[:Indents the paragraph. This applies to one paragraph only.]
301
[endsect] [/Blockquote]
303
[section Admonitions]
306
[note This is a note]
308
[important This is important]
309
[caution This is a caution]
310
[warning This is a warning]
313
generates __docbook__ admonitions:
315
[note This is a note]
317
[important This is important]
318
[caution This is a caution]
319
[warning This is a warning]
321
These are the only admonitions supported by __docbook__. So,
322
for example [^\[information This is some information\]] is unlikely
323
to produce the desired effect.
325
[endsect] [/Admonitions]
345
Headings 1-3 \[h1 h2 and h3\] will automatically have anchors with
346
normalized names with
347
[^name="document_id.section_id.normalized_header_text"] (i.e. valid
348
characters are =a-z=, =A-Z=, =0-9= and =_=. All non-valid characters are
349
converted to underscore and all upper-case are converted to lower-case.
350
For example: Heading 1 in section Section 2 will be normalized to
351
[^section_2.heading_1]). You can use:
354
[link document_id.section_id.normalized_header_text The link text]
357
to link to them. See __anchor_links__ and __section__ for more info.
359
[endsect] [/Headings]
361
[section Generic Heading]
363
In cases when you don't want to care about the heading level (1 to 6), you
364
can use the /Generic Heading/:
370
The /Generic Heading/ assumes the level, plus one, of the innermost section
371
where it is placed. For example, if it is placed in the outermost section,
372
then, it assumes /h2/.
374
Headings are often used as an alternative to sections. It is used
375
particularly if you do not want to start a new section. In many cases,
376
however, headings in a particular section is just flat. Example:
386
Here we use h2 assuming that section A is the outermost level. If it is
387
placed in an inner level, you'll have to use h3, h4, etc. depending on
388
where the section is. In general, it is the section level plus one. It is
389
rather tedious, however, to scan the section level everytime. If you
390
rewrite the example above as shown below, this will be automatic:
400
They work well regardless where you place them. You can rearrange sections
401
at will without any extra work to ensure correct heading levels. In fact,
402
with /section/ and /heading/, you have all you need. /h1/../h6/ becomes
403
redundant. /h1/../h6/ might be deprecated in the future.
405
[endsect] [/Generic Heading]
410
[def macro_identifier some text]
413
When a macro is defined, the identifier replaces the text anywhere in the
414
file, in paragraphs, in markups, etc. macro_identifier is a string of non-
415
white space characters except '\]'. A macro may not follow an alphabetic
416
character or the underscore. The replacement text can be any phrase (even
420
[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&type=1]]
424
Now everywhere the sf_logo is placed, the picture will be inlined.
426
[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&type=1]]
429
[tip It's a good idea to use macro identifiers that are distinguishable.
430
For instance, in this document, macro identifiers have two leading and
431
trailing underscores (e.g. [^\__spirit__]). The reason is to avoid
432
unwanted macro replacement.]
434
Links (URLS) and images are good candidates for macros. *1*) They tend to
435
change a lot. It is a good idea to place all links and images in one place near the top
436
to make it easy to make changes. *2*) The syntax is not pretty. It's easier to read and
437
write, e.g. [^\__spirit__] than `[@http://spirit.sourceforge.net Spirit]`.
442
[def ``\:-)`` [$theme/smiley.png]]
443
[def ``\__spirit__`` [@http://spirit.sourceforge.net Spirit]]
446
(See __images__ and __links__)
448
Invoking these macros:
451
Hi ``\__spirit__`` ``\:-)``
460
[section Predefined Macros]
462
Quickbook has some predefined macros that you can already use.
464
[table Predefined Macros
465
[[Macro] [Meaning] [Example]]
466
[[[^\__DATE__]] [Today's date] [__DATE__]]
467
[[[^\__TIME__]] [The current time] [__TIME__]]
468
[[[^\__FILENAME__]][Quickbook source filename] [__FILENAME__]]
471
[endsect] [/Predefined Macros]
475
Templates provide a more versatile text substitution mechanism. Templates
476
come in handy when you need to create parameterizable, multi-line,
477
boilerplate text that you specify once and expand many times. Templates
478
accept one or more arguments. These arguments act like place-holders for
479
text replacement. Unlike simple macros, which are limited to phrase level
480
markup, templates can contain block level markup (e.g. paragraphs, code
486
[template person[name age what]
488
Hi, my name is [name]. I am [age] years old. I am a [what].
493
[template person[name age what]
495
Hi, my name is [name]. I am [age] years old. I am a [what].
499
[heading Template Identifier]
501
Template identifiers can either consist of:
503
* An initial alphabetic character or the underscore, followed by
504
zero or more alphanumeric characters or the underscore. This is
505
similar to your typical C/C++ identifier.
506
* A single character punctuation (a non-alphanumeric printable character)
508
[heading Formal Template Arguments]
510
Template formal arguments are identifiers consisting of an initial
511
alphabetic character or the underscore, followed by zero or more
512
alphanumeric characters or the underscore. This is similar to your typical
515
A template formal argument temporarily hides a template of the same name at
516
the point where the [link quickbook.syntax.block.templates.template_expansion
517
template is expanded]. Note that the body of the [^person] template above
518
refers to [^name] [^age] and [^what] as [^\[name\]] [^\[age\]] and
519
[^\[what\]]. [^name] [^age] and [^what] are actually templates that exist
520
in the duration of the template call.
522
[heading Template Body]
524
The template body can be just about any QuickBook block or phrase. There
525
are actually two forms. Templates may be phrase or block level. Phrase
526
templates are of the form:
529
[template sample[arg1 arg2...argN] replacement text... ]
532
Block templates are of the form:
535
[template sample[arg1 arg2...argN]
540
The basic rule is as follows: if a newline immediately follows the argument
541
list, then it is a block template, otherwise, it is a phrase template.
542
Phrase templates are typically expanded as part of phrases. Like macros,
543
block level elements are not allowed in phrase templates.
545
[heading Template Expansion]
547
You expand a template this way:
550
[template_identifier arg1..arg2..arg3]
553
At template expansion, you supply the actual arguments. The template will
554
be expanded with your supplied arguments. Example:
557
[person James Bond..39..Spy]
558
[person Santa Clause..87..Big Red Fatso]
561
Which will expand to:
563
[person James Bond..39..Spy]
564
[person Santa Clause..87..Big Red Fatso]
566
[caution A word of caution: Templates are recursive. A template can call
567
another template or even itself, directly or indirectly. There are no
568
control structures in QuickBook (yet) so this will always mean infinite
569
recursion. QuickBook can detect this situation and report an error if
570
recursion exceeds a certain limit.]
572
Each actual argument can be a word, a text fragment or just about any [link
573
quickbook.syntax.phrase QuickBook phrase]. Arguments are separated by the
574
double dot [^".."] and terminated by the close parenthesis.
576
Note that templates and template parameters can't be expanded
577
everywhere, only where text is interpreted as a phrase. So they can't be
578
expanded in places such as table titles and link's urls. If you want to
579
use a template to generate a link based of the template parameter, you
580
can't use a normal link and will need to use escaped docbook instead.
585
[template boost_ticket[key] '''<ulink url="https://svn.boost.org/trac/boost/ticket/'''[key]'''">#'''[key]'''</ulink>''']
592
[template boost_ticket[key] '''<ulink url="https://svn.boost.org/trac/boost/ticket/'''[key]'''">#'''[key]'''</ulink>''']
596
[caution Since quickbook doesn't understand the context where the
597
parameter is being used, it will interpret it as quickbook markup, so
598
when writing a template like this, you'll need to escape any meaningful
601
[heading Nullary Templates]
603
Nullary templates look and act like simple macros. Example:
606
[template alpha[]'''&#945;''']
607
[template beta[]'''&#946;''']
610
[template alpha[]'''α''']
611
[template beta[]'''β''']
615
```Some squigles...[*[alpha][beta]]```
619
Some squiggles...[*[alpha][beta]]
621
The difference with macros are
623
* The explicit [link quickbook.syntax.block.templates.template_expansion
624
template expansion syntax]. This is an advantage because, now, we don't
625
have to use obscure naming conventions like double underscores (e.g.
626
\_\_alpha\_\_) to avoid unwanted
628
* The template is expanded at the point where it is invoked. A macro is
629
expanded immediately at its point of declaration. This is subtle and
630
can cause a slight difference in behavior especially if you refer to
631
other macros and templates in the body.
633
The empty brackets after the template identifier ([^alpha\[\]]) indicates no
634
arguments. If the template body does not look like a template argument list, we
635
can elide the empty brackets. Example:
638
[template aristotle_quote Aristotle: [*['Education is the best provision
639
for the journey to old age.]]]
642
[template aristotle_quote\ Aristotle: [*['Education is the best provision
643
for the journey to old age.]]]
648
Here's a quote from [aristotle_quote].
653
Here's a quote from [aristotle_quote].
655
The disadvantage is that you can't avoid the space between the template
656
identifier, `aristotle_quote`, and the template body "Aristotle...". This space
657
will be part of the template body. If that space is unwanted, use empty
658
brackets or use the space escape: "`\ `". Example:
676
You have a couple of ways to do it. I personally prefer the explicit empty
679
[heading Simple Arguments]
681
As mentioned, arguments are separated by the double dot [^".."]. Alternatively,
682
if the double dot isn't used and more than one argument is expected, QuickBook
683
uses whitespace to separate the arguments, following this logic:
685
* Break the last argument into two, at the first space found ([^'', '\\n',
687
* Repeat until there are enough arguments or if there are no more spaces
688
found (in which case, an error is reported).
693
[template simple[a b c d] [a][b][c][d]]
699
[template simple[a b c d] [a][b][c][d]]
702
"w x y z" is initially treated as a single argument because we didn't
703
supply any [^".."] separators. However, since [^simple] expects 4
704
arguments, "w x y z" is broken down iteratively (applying the logic above)
705
until we have "w", "x", "y" and "z".
707
QuickBook only tries to get the arguments it needs. For example:
710
[simple w x y z trail]
715
[simple w x y z trail]
717
The arguments being: "w", "x", "y" and "z trail".
719
[caution The behavior described here is for QuickBook 1.5. In older versions you
720
could use both the double dot and whitespace as separators in the same template
721
call. If your document is marked up as an older version, it will use the old
722
behavior, which is described in the
723
[@http://www.boost.org/doc/libs/1_40_0/doc/html/quickbook/syntax.html#quickbook.syntax.block.templates.simple_arguments
724
QuickBook 1.4 documentation].]
726
[heading Punctuation Templates]
728
With templates, one of our objectives is to allow us to rewrite QuickBook
729
in QuickBook (as a qbk library). For that to happen, we need to accommodate
730
single character punctuation templates which are fairly common in
731
QuickBook. You might have noticed that single character punctuations are
732
allowed as [link quickbook.syntax.block.templates.template_identifier
733
template identifiers]. Example:
736
[template ![bar] <hey>[bar]</hey>]
751
[endsect] [/Templates]
756
[blurb ``\:-)`` [*An eye catching advertisement or note...]
758
__spirit__ is an object-oriented recursive-descent parser generator framework
759
implemented using template meta-programming techniques. Expression templates
760
allow us to approximate the syntax of Extended Backus-Normal Form (EBNF)
767
[blurb :-) [*An eye catching advertisement or note...]
769
__spirit__ is an object-oriented recursive-descent parser generator
770
framework implemented using template meta-programming techniques. Expression
771
templates allow us to approximate the syntax of Extended Backus-Normal Form
772
(EBNF) completely in C++.
775
[note Prefer [link quickbook.syntax.block.admonitions admonitions] wherever
783
[table:id A Simple Table
784
[[Heading 1] [Heading 2] [Heading 3]]
785
[[R0-C0] [R0-C1] [R0-C2]]
786
[[R1-C0] [R1-C1] [R1-C2]]
787
[[R2-C0] [R2-C1] [R2-C2]]
793
[table:id A Simple Table
794
[[Heading 1] [Heading 2] [Heading 3]]
795
[[R0-C0] [R0-C1] [R0-C2]]
796
[[R1-C0] [R1-C1] [R1-C2]]
797
[[R2-C0] [R2-C1] [R2-C2]]
800
The table title is optional. The first row of the table is automatically
801
treated as the table header; that is, it is wrapped in [^<thead>...</thead>]
802
XML tags. Note that unlike the original QuickDoc, the columns are nested in
805
Giving tables an id is a new feature for quickbook 1.5 onwards. As with
806
sections, the id is optional. If the table has a title but no id, an id will
807
be generated from the title. The table above can be linked to using:
810
[link quickbook.syntax.block.tables.id link to table]
815
[link quickbook.syntax.block.tables.id link to table]
817
The syntax is free-format and allows big cells to be formatted
821
[table Table with fat cells
822
[[Heading 1] [Heading 2]]
824
[Row 0, Col 0: a small cell]
826
Row 0, Col 1: a big fat cell with paragraphs
828
Boost provides free peer-reviewed portable C++ source libraries.
830
We emphasize libraries that work well with the C++ Standard Library.
831
Boost libraries are intended to be widely useful, and usable across
832
a broad spectrum of applications. The Boost license encourages both
833
commercial and non-commercial use.
837
[Row 1, Col 0: a small cell]
838
[Row 1, Col 1: a small cell]
845
[table Table with fat cells
846
[[Heading 1] [Heading 2]]
848
[Row 0, Col 0: a small cell]
850
Row 0, Col 1: a big fat cell with paragraphs
852
Boost provides free peer-reviewed portable C++ source libraries.
853
[/ <-- There's a space here. Don't remove. This is intentional, for testing]
854
We emphasize libraries that work well with the C++ Standard Library.
855
Boost libraries are intended to be widely useful, and usable across
856
a broad spectrum of applications. The Boost license encourages both
857
commercial and non-commercial use.
861
[Row 1, Col 0: a small cell]
862
[Row 1, Col 1: a small cell]
866
Here's how to have preformatted blocks of code in a table cell:
869
[table Table with code
878
std::cout << "Hello, World!" << std::endl;
886
[table Table with code
895
std::cout << "Hello, World!" << std::endl;
904
[section Variable Lists]
907
[variablelist A Variable List
908
[[term 1] [The definition of term 1]]
909
[[term 2] [The definition of term 2]]
911
The definition of term 3.
913
Definitions may contain paragraphs.
920
[variablelist A Variable List
921
[[term 1] [The definition of term 1]]
922
[[term 2] [The definition of term 2]]
924
The definition of term 3.
926
Definitions may contain paragraphs.
930
The rules for variable lists are the same as for tables, except that
931
only 2 "columns" are allowed. The first column contains the terms, and
932
the second column contains the definitions. Those familiar with HTML
933
will recognize this as a "definition list".
935
[endsect] [/Variable Lists]
939
You can include one QuickBook file from another. The syntax is simply:
942
[include someother.qbk]
945
The included file will be processed as if it had been cut and pasted
946
into the current document, with the following exceptions:
948
* The '''__FILENAME__''' predefined macro will reflect the name of the
949
file currently being processed.
950
* Any macros defined in the included file are scoped to that file.
952
The [^\[include\]] directive lets you specify a document id to use for the
953
included file. When this id is not explicitly specified, the id defaults to
954
the filename ("someother", in the example above). You can specify the id
958
[include:someid someother.qbk]
961
All auto-generated anchors will use the document id as a unique prefix. So
962
for instance, if there is a top section in someother.qbk named "Intro", the
963
named anchor for that section will be "someid.intro", and you can link to
964
it with [^\[link someid.intro The Intro\]].
970
When documenting code, you'd surely need to present code from actual source
971
files. While it is possible to copy some code and paste them in your QuickBook
972
file, doing so is error prone and the extracted code in the documentation tends
973
to get out of sync with the actual code as the code evolves. The problem, as
974
always, is that once documentation is written, the tendency is for the docs to
975
languish in the archives without maintenance.
977
QuickBook's import facility provides a nice solution.
981
You can effortlessly import code snippets from source code into your QuickBook.
982
The following illustrates how this is done:
985
[import ../test/stub.cpp]
993
[import ../test/stub.cpp]
996
collects specially marked-up code snippets from
997
[@boost:/tools/quickbook/test/stub.cpp stub.cpp]
998
and places them in your QuickBook file as virtual templates. Each of the
999
specially marked-up code snippets has a name (e.g. `foo` and `bar` in the
1000
example above). This shall be the template identifier for that particular code
1001
snippet. The second and third line above does the actual template expansion:
1010
[import ../test/stub.cpp]
1014
[heading Code Snippet Markup]
1016
Note how the code snippets in [@boost:/tools/quickbook/test/stub.cpp stub.cpp]
1017
get marked up. We use distinguishable comments following the form:
1023
The first comment line above initiates a named code-snippet. This prefix will
1024
not be visible in quickbook. The entire code-snippet in between `//[id` and
1025
`//]` will be inserted as a template in quickbook with name ['/id/]. The comment
1026
`//]` ends a code-snippet This too will not be visible in quickbook.
1028
[heading Special Comments]
1030
Special comments of the form:
1032
//` some [*quickbook] markup here
1036
/*` some [*quickbook] markup here */
1038
will be parsed by QuickBook. This can contain quickbook /blocks/ (e.g. sections,
1039
paragraphs, tables, etc). In the first case, the initial slash-slash, tick and
1040
white-space shall be ignored. In the second, the initial slash-star-tick and the
1041
final star-slash shall be ignored.
1043
Special comments of the form:
1045
/*<- this C++ comment will be ignored ->*/
1049
/*<-*/ "this c++ code will be ignored" /*->*/
1058
can be used to inhibit code from passing through to quickbook. All text between
1059
the delimeters will simply be ignored.
1061
Comments of this form:
1069
will be displayed as code that isn't in comments. This allows you to
1070
include some code in the snippet but not actually use it when
1071
compiling your example.
1075
Special comments of the form:
1077
/*< some [*quickbook] markup here >*/
1079
will be regarded as callouts. These will be collected, numbered and
1080
rendered as a "callout bug" (a small icon with a number). After the
1081
whole snippet is parsed, the callout list is generated. See
1082
[@http://www.docbook.org/tdg/en/html/callout.html Callouts] for details.
1087
This is the actual code:
1090
std::string foo_bar() /*< The /Mythical/ FooBar.
1091
See [@http://en.wikipedia.org/wiki/Foobar Foobar for details] >*/
1093
return "foo-bar"; /*< return 'em, foo-bar man! >*/
1097
The callouts bugs are placed exactly where the special callout comment
1098
is situated. It can be anywhere in the code. The bugs can be rather
1099
obtrusive, however. They get in the way of the clarity of the code.
1100
Another special callout comment style is available:
1102
/*<< some [*quickbook] markup here >>*/
1104
This is the line-oriented version of the callout. With this, the "bug"
1105
is placed at the very left of the code block, away from the actual code.
1106
By placing it at the far left, the code is rendered un-obscured.
1111
See the actual code here: [@boost:/tools/quickbook/test/stub.cpp]