192 lines
5.1 KiB
Plaintext
192 lines
5.1 KiB
Plaintext
[/
|
|
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:context_error]
|
|
|
|
[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:phrase_parse_error]
|
|
|
|
[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:source_mode]
|
|
|
|
[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:callouts]
|
|
|
|
[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:listparagraphs]
|
|
|
|
[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:list_markup_in_tables]
|
|
|
|
[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:phrase_block_templates]
|
|
|
|
[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:glob]
|
|
|
|
[endsect:1_7]
|