boost/tools/quickbook/doc/1_7.qbk

[/
    Copyright 2002,2004,2006 Joel de Guzman, Eric Niebler
    Copyright 2012-2013 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)
]

[section:1_7 Quickbook 1.7]

[section:context_error Error for elements used in incorrect context]

Previously if you used an element in the wrong context it would just be
unprocessed, which was surprising. People often didn't realise that their
element hadn't been processed. So now it's an error.

[endsect]

[section:phrase_parse_error Error for invalid phrase elements]

If the body of a phrase element didn't parse, it would be just used
unprocessed. Now change it to be a hard error.

[endsect]

[section:source_mode Source mode for single entities]

1.7 introduces a new `!` element type for setting the source mode of a single
entity without changing the source mode otherwise. This can be used for
code blocks and other elements. For example:

```
[!c++]
    void foo() {};

[!python]``\`\`\`\ ``def foo():``\`\`\`\ ``
```

It can also be used to set the source mode for elements:

```
[!teletype][table
    [[code][meaning]]
    [[`+`][addition]]
]
```

When used before a section, it sets the source mode for the whole section.

If it appears at the beginning of a paragraph, it will be used for the
whole paragraph only if there's a newline, eg.

```
[!c++]
A declaration `void foo();` and a definition `void foo() {}`.
```

[endsect]

[section:callouts Callouts in code blocks]

Currently callouts can only be used in code snippets. 1.7 adds
support in normal code blocks. The same syntax is used as in
code snippets, the callout descriptions appear immediately
after the code block.

[endsect]

[section:escaped_docinfo_attributes Escaped docbook in docinfo blocks]

Quickbook docinfo attributes will probably never be as rich as docbook
attributes. To allow more flexible markup that is not supported by quickbook,
escaped docbook can be included in the docinfo block:

```
[article Some article
[quickbook 1.7]
'''<author>
    <firstname>John</firstname>
    <surname>Doe</surname>
    <email>john.doe@example.com</email>
</author>'''
]
```

The escaped docbook is always placed at the end of the docinfo block,
so it shouldn't be assumed that it will interleave with markup generated from
quickbook. A mixture
of quickbook and docbook attributes for the same information will not work
well.

[endsect] [/escaped_docinfo_attributes]

[section:listparagraphs Pargraphs in lists]

Paragraphs and block elements can now be used in lists:

[pre
* Para 1

  Para 2
  * Nested Para 1

    Nested Para 2

        Code block
  Para 3
]

generates:

* Para 1

  Para 2
  * Nested Para 1

    Nested Para 2

        Code block
  Para 3

[endsect]

[section:templates_in_attributes Templates in some attributes]

There's support for calling templates in link values, anchors, roles and
includes. This is sometimes a bit of a change, especially in places where
spaces are currently allowed, so I might try using a slightly different
grammar where required. I think I also need to add some validation, since
the parser can allow more symbols than some of the old ones.

[endsect] [/templates_in_attributes]

[section:list_markup_in_tables List Markup in Nested Blocks]

Can now place list markup in nested blocks, e.g in tables, variables lists etc.
Unfortunately indented code blocks are more tricky, because the contents of
these blocks are often indented already. It seemed easier to just not support
indented code blocks in this context than to try to work out sensible actions
for the edges cases. If you want to use code blocks in this context, you should
still be able to use explicit markup.

[endsect]

[section:phrase_block_templates Allow block elements in phrase templates]

Block elements can now be used in phrase templates, but paragraphs breaks aren't
allowed, so this is an error:

    [template paras[] Something or other.

    Second paragraph.]

If a phrase template only contains block elements, then it's practically
indistinguishable from a block template. So you'll get the same output from:

    [template foo[] [blurb Blah, blah, blah]]

as:

    [template foo[]
    [blurb Blah, blah, blah]
    ]

If a phrase template has phrase content mixed with block elements, it'll generate
output as if it was expanded inline.

[endsect]

[section:glob Including multiple files with Globs]

One can now include multiple files at once using a glob pattern for the
file reference:

    [include sub/*/*.qbk]
    [include include/*.h]

All the matching files, and intermediate irectories, will match and be
included. The glob pattern can be "\*" for matching zero or more characters,
"?" for matching a single character, "\[<c>-<c>\]" to match a character class,
"\[\^<char>-<char>\]" to exclusive match a character class, "\\\\" to escape
a glob special character which is then matched, and anything else is matched
to the character.

[note Because of the escaping in file references the "\\\\" glob escape is
a double "\\"; i.e. and escaped back-slash.]

[endsect]

[endsect] [/ Quickbok 1.7]