bump version to 12.2.2-pve1

[ceph.git] / ceph / src / boost / tools / quickbook / doc / block.qbk

[/
    Copyright 2002,2004,2006 Joel de Guzman, Eric Niebler
    Copyright 2010-2011 Daniel James

    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)
]

[chapter Block Level Elements
    [quickbook 1.6]
    [compatibility-mode 1.5]
    [id quickbook.syntax.block]
    [source-mode teletype]
]

[#quickbook.ref.xinclude]
[section:xinclude xinclude]

You can include another XML file with:

```
[xinclude file.xml]
```

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

=xinclude= paths are normally used unchanged in the generated documentation,
which will not work if you wish them to be relative to the current quickbook
file. Quickbook can add a =xml:base= attribute to the boostbook documentation
to specify where =xinclude= files should be found. For example, if you wish
them to be relative to the current quickbook file:

    [article Article with xincludes
    [quickbook 1.6]
    [xmlbase .]
    ]

    [xinclude file.xml]

Now the xinclude should work if =file.xml= is in the same directory as the
quickbook file. Although it might not work if you distribute the generated
files (as their relative directories can change).

Say the article is generated in a sub-directory, by running something like:

    quickbook article.qbk --output-file=output/article.xml

This will generate a boostbook root tag:

    <article id="article_with_xincludes"
        last-revision="$Date: 2013/08/20 08:26:48 $"
        xml:base=".."
        xmlns:xi="http://www.w3.org/2001/XInclude">

Because =xml:base= is set to =..=, the xml processor will know to look in
the parent directory to find =file.xml=, which it comes across the
=xi:include= tag.

[endsect] [/xinclude]

[#quickbook.ref.paragraphs]
[section:paragraphs 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.
 [/ <-- There's a space here. Don't remove. this is intentianal, for testing]
This is a new paragraph...

[endsect] [/paragraphs]

[#quickbook.ref.lists]
[section:lists Lists]
[#quickbook.ref.ordered_lists]
[section:ordered_lists Ordered lists]

[pre
# One
# Two
# Three
]

will generate:

# One
# Two
# Three

[endsect] [/ordered_lists]
[#quickbook.ref.list_hierarchies]
[section:list_hierarchies 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] [/list_hierarchies]
[#quickbook.ref.long_list_lines]
[section:long_list_lines 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] [/long_list_lines]
[#quickbook.ref.unordered_lists]
[section:unordered_lists Unordered lists]

```
* First
* Second
* Third
```

will generate:

* First
* Second
* Third

[endsect] [/unordered_lists]
[#quickbook.ref.mixed_lists]
[section:mixed_lists Mixed lists]

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

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

will generate:

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

And...

```
# 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] [/mixed_lists]

[#quickbook.ref.list_tags]
[section:list_tags Explicit list tags]

Sometimes the wiki-style list markup can be tricky to use, especially
if you wish to include more complicated markup with the list. So in
quickbook 1.6, an alternative way to mark up lists introduced:

    [ordered_list [item1][item2]]

is equivalent to:

    # item1
    # item2

And:

    [itemized_list [item1][item2]]

is equivalent to:

    * item1
    * item2

[endsect] [/list_tags]
[endsect] [/lists]

[#quickbook.ref.code]
[section:code 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)

[teletype]

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

```
[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] [/code]

[#quickbook.ref.escape_back]
[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:

```
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] [/escaping_back_to_quickbook]

[#quickbook.ref.preformatted]
[section:preformatted Preformatted]

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

```
[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] [/preformatted]

[#quickbook.ref.blockquote]
[section:blockquote Blockquote]

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

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

[endsect] [/blockquote]

[#quickbook.ref.admonitions]
[section:admonitions 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]
```

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] [/admonitions]

[#quickbook.ref.headings]
[section:headings Headings]

```
[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]

You can specify an id for a heading:

```
[h1:heading_id A heading to link to]
```

To link to it, you'll need to include the enclosing section's id:

```
[link document_id.section_id.heading_id The link text]
```

Although you can preceed a heading by an [link quickbook.ref.anchors anchor]
if you wish to use a location independent link.

If a heading doesn't have an id, one will be automatically generated
with a normalized name with
[^name="document_id.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:

```
[link document_id.section_id.normalized_header_text The link text]
```

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

[note Specifying heading ids is a quickbook 1.6 feature, earlier
      versions don't support them.]

[endsect] [/headings]

[#quickbook.ref.generic_heading]
[section:generic_heading Generic Heading]

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

```
[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:

```
[section A]
[h2 X]
[h2:link_id 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:

```
[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] [/generic_heading]

[#quickbook.ref.macros]
[section:macros Macros]

```
[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:

```
[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:

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

(See __images__ and __links__)

Invoking these macros:

```
Hi ``\__spirit__``  ``\:-)``
```

will generate this:

Hi __spirit__ :-)

[endsect] [/macros]

[#quickbook.ref.predefined_macros]
[section:predefined_macros 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] [/predefined_macros]

[#quickbook.ref.templates]
[section:templates 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:

```
[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].

]

[#quickbook.ref.template_identifier]
[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.ref.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:

```
[template sample[arg1 arg2...argN] replacement text... ]
```

Block templates are of the form:

```
[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:

```
[template_identifier arg1..arg2..arg3]
```

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

```
[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.

Note that templates and template parameters can't be expanded
everywhere, only where text is interpreted as a phrase. So they can't be
expanded in places such as table titles and link's urls. If you want to
use a template to generate a link based of the template parameter, you
can't use a normal link and will need to use escaped docbook instead.
Example:

[teletype]
```
[template boost_ticket[key] '''<ulink url="https://svn.boost.org/trac/boost/ticket/'''[key]'''">#'''[key]'''</ulink>''']

[boost_ticket 2035]
```

will expand to:

[template boost_ticket[key] '''<ulink url="https://svn.boost.org/trac/boost/ticket/'''[key]'''">#'''[key]'''</ulink>''']

[boost_ticket 2035]

[caution Since quickbook doesn't understand the context where the
parameter is being used, it will interpret it as quickbook markup, so
when writing a template like this, you'll need to escape any meaningful
punctuation.]

[heading Nullary Templates]

Nullary templates look and act like simple macros. Example:

```
[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:

```Some squigles...[*[alpha][beta]]```

We have:

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

The difference with macros are

* The explicit [link quickbook.ref.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:

```
[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:

```
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:

```
[template tag\ _tag]
```

[template tag\ _tag]

Then expanding:

```
`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 [^".."]. Alternatively,
if the double dot isn't used and more than one argument is expected, QuickBook
uses whitespace to separate the 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:

```
[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:

```
[simple w x y z trail]
```

will produce:

[simple w x y z trail]

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

[caution The behavior described here is for QuickBook 1.5. In older versions you
could use both the double dot and whitespace as separators in the same template
call. If your document is marked up as an older version, it will use the old
behavior, which is described in the
[@http://www.boost.org/doc/libs/1_40_0/doc/html/quickbook/syntax.html#quickbook.syntax.block.templates.simple_arguments
QuickBook 1.4 documentation].]

[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.ref.template_identifier
template identifiers]. Example:

```
[template ![bar] <hey>[bar]</hey>]
```

Now, expanding this:

```
[!baz]
```

We will have:

[pre
<hey>baz</hey>
]

[endsect] [/templates]

[#quickbook.ref.blurbs]
[section:blurbs Blurbs]

```
[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.ref.admonitions admonitions] wherever
appropriate.]

[endsect] [/blurbs]

[#quickbook.ref.tables]
[section:tables Tables]

```
[table:id 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:id 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]]
]

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... ].

Giving tables an id is a new feature for quickbook 1.5 onwards. As with
sections, the id is optional. If the table has a title but no id, an id will
be generated from the title. The table above can be linked to using:

```
[link quickbook.syntax.block.tables.id link to table]
```

which will generate:

[link quickbook.syntax.block.tables.id link to table]

The syntax is free-format and allows big cells to be formatted
nicely. Example:

```
[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.
 [/ <-- There's a space here. Don't remove. This is intentional, for testing]
            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:

```
[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] [/tables]

[#quickbook.ref.variable_lists]
[section:variable_lists Variable Lists]

```
[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.

    Definitions may contain paragraphs.
    ]]
]
```

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.

    Definitions may contain paragraphs.
    ]]
]

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] [/variable_lists]

[#quickbook.ref.include]
[section:include Include]

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

```
[include someother.qbk]
```

In quickbook 1.6 and later, if the included file has a
[link quickbook.ref.docinfo docinfo block] then it will create a nested
document. This will be processed as a standalone document, although any macros
or templates from the enclosing file will still be defined.

Otherwise 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 or templates defined in the included file are scoped to that file,
  i.e. they are not added to the enclosing file.

[note In quickbook 1.5 and earlier templates weren't scoped in included files.
If you want to use templates or macros from a file in quickbook 1.6,
use [link quickbook.ref.import import] instead.]

The [^\[include\]] directive lets you specify a document id to use for the
included file. You can specify the id like this:

```
[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\]].

If the included file has a docinfo block, an id specified in an [^\[include\]]
directive will overwrite it.

You can also include C, C++ and python source files. This will include any
quickbook blocks in the file that aren't inside of named code snippets. See
the [link quickbook.ref.import Import section] for syntax details. For example,
say you included this file:

    /**
     * Hello world example
     */

    // In this comment, the backtick indicates that this is a
    // quickbook source block that will be included.

    /*`
    First include the appropriate header: [hello_includes]
    Then write your main function: [hello_main]
    */

    // This defines a code snippet, the syntax is
    // described in the import section. It's available
    // in the whole of this source file, not just after
    // its definition.

    //[hello_includes
    #include <iostream>
    //]

    //[hello_main
    int main() {
        std::cout << "Hello, trivial example" << std::endl;
    }
    //]

It will generate:

    First include the appropriate header:

        #include <iostream>

    Then write your main function:

        int main() {
            std::cout << "Hello, trivial example" << std::endl;
        }

[endsect] [/include]

[#quickbook.ref.import]
[section:import Import]

In quickbook 1.6 and later if you wish to use a template, macro or code
snippet from a file, you need to import it. This will not include any
of the content from that file, but will pull templates, macros and code
snippets into the current file's scope.

With quickbook files, this allows you to create template and macro
libraries. For python (indicated by the `.py` extension), C or
C++ files this allows you to include code snippets from source files,
so that your code examples can be kept up to date and fully tested.

[/ Old justification text, might move this into a new section:

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:

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

The first line:

```
[import ../test/stub.cpp]
```

collects specially marked-up code snippets from
[@boost:/tools/quickbook/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:

```
[foo]
[bar]
```

And the result is:

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

[heading Code Snippet Markup]

Note how the code snippets in [@boost:/tools/quickbook/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.

Special comments of the form:

    /*<- this C++ comment will be ignored ->*/

or

    /*<-*/ "this c++ code  will be ignored" /*->*/

or

    //<-
    private:
        int some_member;
    //->

can be used to inhibit code from passing through to quickbook. All text between
the delimeters will simply be ignored.

Comments of this form:

    //=int main() {}

or

    /*=foo()*/

will be displayed as code that isn't in comments. This allows you to
include some code in the snippet but not actually use it when
compiling your example.

[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]

This is the actual code:

    //[ foo_bar
    std::string foo_bar() /*< The /Mythical/ FooBar.
                          See [@http://en.wikipedia.org/wiki/Foobar Foobar for details] >*/
    {
        return "foo-bar"; /*< return 'em, foo-bar man! >*/
    }
    //]

The callouts bugs are placed exactly where the special callout comment
is situated. It can be anywhere in the code. The bugs can be rather
obtrusive, however. They get in the way of the clarity of the code.
Another special callout comment style is available:

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

This is the line-oriented version of the callout. With this, the "bug"
is placed at the very left of the code block, away from the actual code.
By placing it at the far left, the code is rendered un-obscured.
Example:

[class_]

See the actual code here:
[@boost:/tools/quickbook/test/stub.cpp tools/quickbook/test/stub.cpp]

[endsect] [/import]

[#quickbook.ref.block]
[section:block Plain blocks]

`block` is a plain block element, that doesn't wrap its contents
in any docbook or boostbook tags. This can be useful when using
escaped docbook block tags, such as:

    [template chapter[title]
    [block'''<chapter><title>'''[title]'''</title>''']
    ]

    [template chapterend
    [block'''</chapter>''']
    ]

    [chapter An example chapter]

    Content

    [chapterend]

Without the `block` element, the `chapter` and `chapterend` templates
would be wrapped in paragraph tags.

[note In this example, the template body has to start with a newline so that
the template will be interpreted in block mode.]

[endsect] [/block]