731 lines
36 KiB
HTML
731 lines
36 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
||
<html>
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
||
<title>Language Versions</title>
|
||
<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
|
||
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
|
||
<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
|
||
<link rel="up" href="../quickbook.html" title="Chapter 51. Quickbook 1.7">
|
||
<link rel="prev" href="syntax/block.html" title="Block Level Elements">
|
||
<link rel="next" href="install.html" title="Installation and configuration">
|
||
</head>
|
||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||
<table cellpadding="2" width="100%"><tr>
|
||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
|
||
<td align="center"><a href="../../../index.html">Home</a></td>
|
||
<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
|
||
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
|
||
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
|
||
<td align="center"><a href="../../../more/index.htm">More</a></td>
|
||
</tr></table>
|
||
<hr>
|
||
<div class="spirit-nav">
|
||
<a accesskey="p" href="syntax/block.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../quickbook.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="install.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||
<a name="quickbook.versions"></a>Language Versions</h2></div></div></div>
|
||
<div class="toc"><dl class="toc">
|
||
<dt><span class="section"><a href="versions.html#quickbook.versions.upgrading">Upgrading to a new version</a></span></dt>
|
||
<dt><span class="section"><a href="versions.html#quickbook.versions.stable">Stable Versions</a></span></dt>
|
||
<dt><span class="section"><a href="versions.html#language_versions.1_6">Quickbook 1.6</a></span></dt>
|
||
<dt><span class="section"><a href="versions.html#language_versions.1_7">Quickbook 1.7</a></span></dt>
|
||
</dl></div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="quickbook.versions.upgrading"></a><a class="link" href="versions.html#quickbook.versions.upgrading" title="Upgrading to a new version">Upgrading to a new version</a>
|
||
</h3></div></div></div>
|
||
<p>
|
||
To upgrade an existing document to a new version of quickbook, you will need
|
||
to update the version in the docinfo block. For example, the existing docinfo
|
||
block might look like:
|
||
</p>
|
||
<pre class="programlisting">[library Boost.Example
|
||
[quickbook 1.3]
|
||
...
|
||
]
|
||
</pre>
|
||
<p>
|
||
Change this to:
|
||
</p>
|
||
<pre class="programlisting">[library Boost.Example
|
||
[quickbook 1.7]
|
||
[compatibility-mode 1.3]
|
||
...
|
||
]
|
||
</pre>
|
||
<p>
|
||
The <code class="literal">compatibility-mode</code> tag ensures that it will generate
|
||
similar output to the older version - most importantly is will generate the
|
||
same ids, ensuring that links to the generated html won't break.
|
||
</p>
|
||
<p>
|
||
Then try building it. Later versions have a stricter parser, so there might
|
||
be errors. It's quite likely that you might need to fix some stray square
|
||
brackets. They might need to be escaped. For example, to write out the half-open
|
||
range [a,b), use: <code class="computeroutput">\[a,b)</code>.
|
||
</p>
|
||
<p>
|
||
When upgrading to 1.6 or later, you might need to reconsider how templates
|
||
and macros are defined. If you <code class="computeroutput">include</code> a file to use its templates,
|
||
you'll now need to <code class="computeroutput">import</code> it instead as templates are now scoped
|
||
by included files. Also, if you define templates and macros in your main
|
||
quickbook file, you might want to put them into a separate file and <code class="computeroutput">import</code>
|
||
that, which allows the main documentation files to concentrate on the structure
|
||
and contents of the document, making them easier to read.
|
||
</p>
|
||
<p>
|
||
Now that headings can have ids, it can be a good idea to add ids to existing
|
||
headings. This means that the headings will have more predictable ids which
|
||
don't change when the text of the heading changes. In order to preserve links
|
||
you can use the existing generated id as the heading.
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="quickbook.versions.stable"></a><a class="link" href="versions.html#quickbook.versions.stable" title="Stable Versions">Stable Versions</a>
|
||
</h3></div></div></div>
|
||
<p>
|
||
Since quickbook 1.3 the <code class="computeroutput">quickbook</code> attribute in the document
|
||
block selects which version of the language to use. Not all changes to quickbook
|
||
are implemented using a version switch, it's mainly just the changes that
|
||
change the way a document is interpreted or would break existing documentation.
|
||
</p>
|
||
<h4>
|
||
<a name="quickbook.versions.stable.h0"></a>
|
||
<span class="phrase"><a name="quickbook.versions.stable.quickbook_1_3_and_later"></a></span><a class="link" href="versions.html#quickbook.versions.stable.quickbook_1_3_and_later">Quickbook
|
||
1.3 and later</a>
|
||
</h4>
|
||
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
|
||
<li class="listitem">
|
||
Introduced quickbook language versioning.
|
||
</li>
|
||
<li class="listitem">
|
||
In the documentation info, allow phrase markup in license and purpose
|
||
attributes.
|
||
</li>
|
||
<li class="listitem">
|
||
Fully qualified section and headers. Subsection names are concatenated
|
||
to the ID to avoid clashing. Example: <code class="computeroutput">doc_name.sect_name.sub_sect_name.sub_sub_sect_name</code>.
|
||
</li>
|
||
</ul></div>
|
||
<h4>
|
||
<a name="quickbook.versions.stable.h1"></a>
|
||
<span class="phrase"><a name="quickbook.versions.stable.quickbook_1_5_and_later"></a></span><a class="link" href="versions.html#quickbook.versions.stable.quickbook_1_5_and_later">Quickbook
|
||
1.5 and later</a>
|
||
</h4>
|
||
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
|
||
<li class="listitem">
|
||
Ignore template argument separators inside square brackets.
|
||
</li>
|
||
<li class="listitem">
|
||
Don't separate the final template argument if the <code class="computeroutput">..</code> separator
|
||
was used. i.e. never mix <code class="computeroutput">..</code> and whitespace separators.
|
||
</li>
|
||
<li class="listitem">
|
||
Statically scope templates and their arguments rather than dynamically
|
||
scope them.
|
||
</li>
|
||
<li class="listitem">
|
||
Give table ids, and let you set them.
|
||
</li>
|
||
<li class="listitem">
|
||
Allow spaces between the <code class="computeroutput">:</code> character and ids in elements
|
||
which can have ids.
|
||
</li>
|
||
</ul></div>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="language_versions.1_6"></a><a class="link" href="versions.html#language_versions.1_6" title="Quickbook 1.6">Quickbook 1.6</a>
|
||
</h3></div></div></div>
|
||
<div class="toc"><dl class="toc">
|
||
<dt><span class="section"><a href="versions.html#language_versions.1_6.docinfo">Includes with docinfo</a></span></dt>
|
||
<dt><span class="section"><a href="versions.html#language_versions.1_6.doc_info_macros">Macros in docinfo
|
||
block</a></span></dt>
|
||
<dt><span class="section"><a href="versions.html#language_versions.1_6.scope">Scoping templates and
|
||
macros</a></span></dt>
|
||
<dt><span class="section"><a href="versions.html#language_versions.1_6.include">Including C++ and python
|
||
files</a></span></dt>
|
||
<dt><span class="section"><a href="versions.html#language_versions.1_6.ids">Id Generation</a></span></dt>
|
||
<dt><span class="section"><a href="versions.html#language_versions.1_6.compatibility">Compatibility
|
||
Mode</a></span></dt>
|
||
<dt><span class="section"><a href="versions.html#language_versions.1_6.version">Version info outside
|
||
of document info block</a></span></dt>
|
||
<dt><span class="section"><a href="versions.html#language_versions.1_6.heading_ids">Explicit Heading
|
||
Ids</a></span></dt>
|
||
<dt><span class="section"><a href="versions.html#language_versions.1_6.escapes">Punctuation changes</a></span></dt>
|
||
<dt><span class="section"><a href="versions.html#language_versions.1_6.table">Table Titles</a></span></dt>
|
||
<dt><span class="section"><a href="versions.html#language_versions.1_6.xmlbase">XML base</a></span></dt>
|
||
<dt><span class="section"><a href="versions.html#language_versions.1_6.template_parser">Improved template
|
||
parser</a></span></dt>
|
||
<dt><span class="section"><a href="versions.html#language_versions.1_6.elements">New Elements</a></span></dt>
|
||
</dl></div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="language_versions.1_6.docinfo"></a><a class="link" href="versions.html#language_versions.1_6.docinfo" title="Includes with docinfo">Includes with docinfo</a>
|
||
</h4></div></div></div>
|
||
<p>
|
||
In quickbook 1.5 if you include a file which starts with a docinfo block,
|
||
it's ignored and the file is expanded in place. In quickbook 1.6 it's treated
|
||
as a document nested in the current position. So if it has an 'article'
|
||
docinfo block, boostbook 'article' tags are used.
|
||
</p>
|
||
<p>
|
||
It also mostly generates the same markup as if the file was converted separately
|
||
- so for example, the same ids are generated, the document is processed
|
||
using the language version specified in the docinfo block. If no language
|
||
is specified it uses the default (1.1) not the version of the document
|
||
that included it. This might seem surprising, but is requried so that quickbook
|
||
will convert it the same way as if it was converted separately.
|
||
</p>
|
||
<p>
|
||
So for the most part, includes with a docinfo are like an <code class="computeroutput">xinclude</code>,
|
||
apart from a couple of differences. Templates and macros defined in the
|
||
parent document are used in the included document, and the id generator
|
||
rewrites ids that clash between multiple documents.
|
||
</p>
|
||
<p>
|
||
If an included document doesn't have a docinfo block, it's just included
|
||
as before.
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="language_versions.1_6.doc_info_macros"></a><a class="link" href="versions.html#language_versions.1_6.doc_info_macros" title="Macros in docinfo block">Macros in docinfo
|
||
block</a>
|
||
</h4></div></div></div>
|
||
<p>
|
||
You can now expand macros in text fields in the docinfo block. In the top
|
||
docinfo block only the predefined macros are available, but in nested documents
|
||
macros defined in the parent document are also available.
|
||
</p>
|
||
<p>
|
||
There's a small bug here - this leaks into older versions for the <code class="computeroutput">license</code>
|
||
and <code class="computeroutput">purpose</code> fields, but since only the predefined macros are
|
||
available, it's unlikely to break any existing documents. So I'd rather
|
||
not complicate the code further by fixing that.
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="language_versions.1_6.scope"></a><a class="link" href="versions.html#language_versions.1_6.scope" title="Scoping templates and macros">Scoping templates and
|
||
macros</a>
|
||
</h4></div></div></div>
|
||
<p>
|
||
A long standing quickbook bug is that macros are scoped by file, but templates
|
||
aren't. So you can define templates in a separate file and include them,
|
||
but not macros. This has been fixed so that templates defined in one file
|
||
won't 'leak' into another.
|
||
</p>
|
||
<p>
|
||
But this means there's no way to define templates in a separate file -
|
||
a useful feature. To do this the <code class="computeroutput">import</code> element has been adapted
|
||
to also support quickbook files. If a quickbook file is imported, the templates
|
||
and macros defined in it are added to the current scope, but nothing else
|
||
contained in that file is used. This could be used to create template and
|
||
macro library files. This matches the existing semantics of importing code
|
||
snippets.
|
||
</p>
|
||
<p>
|
||
When importing templates, they're bound to the language version of the
|
||
file they were defined in. This means that if you import them into a file
|
||
with a different version it won't change the way they're interpreted. Although,
|
||
as we'll see <a class="link" href="versions.html#compatibility">later</a>, the generated
|
||
boostbook is slightly different.
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="language_versions.1_6.include"></a><a class="link" href="versions.html#language_versions.1_6.include" title="Including C++ and python files">Including C++ and python
|
||
files</a>
|
||
</h4></div></div></div>
|
||
<p>
|
||
As <code class="computeroutput">import</code> now supports quickbook files, <code class="computeroutput">include</code>
|
||
also supports source files. It includes any quickbook contained in comments
|
||
outside of code snippets. Code snippets in the file are available to be
|
||
expanded within the file but are scoped to the file. In exactly the same
|
||
manner as when templates and macros are scoped in an included quickbook
|
||
file.
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="language_versions.1_6.ids"></a><a class="link" href="versions.html#language_versions.1_6.ids" title="Id Generation">Id Generation</a>
|
||
</h4></div></div></div>
|
||
<p>
|
||
Id generation in quickbook 1.5 is a bit buggy, but that can't be fixed
|
||
without a version switch as it will break existing documents. For example
|
||
in quickbook 1.5 when you include a quickbook file, it stops using the
|
||
explicit id from the documentation info and generates a new id from the
|
||
document title to use instead.
|
||
</p>
|
||
<p>
|
||
The id generator in quickbook 1.6 has been improved in some other ways
|
||
to. When generating ids from section titles, table titles etc. it always
|
||
uses the quickbook source rather than the generated boostbook to generate
|
||
the id. It then cleans up the id slightly, trimming leading and trailing
|
||
underscores and replacing multiple underscores with a single underscore.
|
||
Then if the newly generated part of the id is longer than 32 characters
|
||
it truncates it.
|
||
</p>
|
||
<p>
|
||
While the new id generator generally creates better ids, it's more likely
|
||
to generate duplicates so quickbook needs to handle duplicates better.
|
||
When there are multiple identical ids, quickbook chooses one to use based
|
||
on a priority list - anchors are preferred, then explicit document and
|
||
section ids, then other explicit ids, followed by the generated ids. Then
|
||
any other explicit ids in the document have numbers added to avoid duplicates
|
||
- first the explicit ids in the order they appear and then the generated
|
||
ids. A generated id which accidentally clashes with an explicit id should
|
||
never change the explicit id.
|
||
</p>
|
||
<p>
|
||
Older language versions still generate the same ids they always have, with
|
||
the exception of duplicate ids which are handled using the new mechanism
|
||
- this is not a breaking change since duplicate ids can't be linked to.
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="language_versions.1_6.compatibility"></a><a name="compatibility"></a><a class="link" href="versions.html#language_versions.1_6.compatibility" title="Compatibility Mode">Compatibility
|
||
Mode</a>
|
||
</h4></div></div></div>
|
||
<p>
|
||
As mentioned before, changing the id generator will break links in documents
|
||
written using an old language version. So to ease the transition a 'compatibility
|
||
mode' is used, this just requires an extra attribute in the docinfo, for
|
||
example if you're converting a 1.5 document to 1.6:
|
||
</p>
|
||
<pre class="programlisting">[article Document
|
||
[quickbook 1.6]
|
||
[compatibility-mode 1.5]
|
||
]
|
||
</pre>
|
||
<p>
|
||
This means the document will be parsed as 1.6, using all the new features,
|
||
but ids (and possibly other markup) will generated as they were for a 1.5
|
||
document.
|
||
</p>
|
||
<p>
|
||
Compatibility mode is also implicitly used when generating templates written
|
||
in a different language version to the current document. So the template
|
||
is parsed in the version it was written for, but generates boostbook that's
|
||
compatible with the current document.
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="language_versions.1_6.version"></a><a class="link" href="versions.html#language_versions.1_6.version" title="Version info outside of document info block">Version info outside
|
||
of document info block</a>
|
||
</h4></div></div></div>
|
||
<p>
|
||
Can now use <code class="computeroutput">quickbook</code> and <code class="computeroutput">compatibility-mode</code>
|
||
tags at the beginning of the file. Either before or without a document
|
||
info block. This is useful for files just containing templates, which don't
|
||
really need a document info block.
|
||
</p>
|
||
<p>
|
||
If you don't specify <code class="computeroutput">compatibility-mode</code>, the behaviour depends
|
||
on whether or not you have a docinfo block. If you do it uses the file's
|
||
quickbook version, if you don't it inherits the parent's compatibility
|
||
mode even if you specify a quickbook version. This is the right thing to
|
||
do - mixing compatibility modes within documents is problematic. It might
|
||
actually be a mistake to allow them to specified outside docinfo blocks.
|
||
</p>
|
||
<p>
|
||
This change is also backdated to older versions. So when including from
|
||
an older version, the included file's version can be set (older versions
|
||
ignore document info in included files).
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="language_versions.1_6.heading_ids"></a><a class="link" href="versions.html#language_versions.1_6.heading_ids" title="Explicit Heading Ids">Explicit Heading
|
||
Ids</a>
|
||
</h4></div></div></div>
|
||
<p>
|
||
Headings can now be given explicit ids:
|
||
</p>
|
||
<pre class="programlisting">[heading:id A heading with an explicit id]
|
||
</pre>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="language_versions.1_6.escapes"></a><a class="link" href="versions.html#language_versions.1_6.escapes" title="Punctuation changes">Punctuation changes</a>
|
||
</h4></div></div></div>
|
||
<p>
|
||
In 1.6, quickbook is more consistent about how it parses punctuation. Escapes
|
||
are now supported in links, anchors, table titles, image attributes etc.
|
||
The flip side of this is that quickbook is now stricter about unescaped
|
||
brackets. They can still be used, but need to match up, otherwise there's
|
||
an error.
|
||
</p>
|
||
<p>
|
||
Since quickbook now matches up square brackets it will fix some mis-parses.
|
||
For example <code class="computeroutput">[*[bold]]</code> used to parse as <span class="bold"><strong>[bold</strong></span>]
|
||
- note that the closing square bracket isn't bold, now it parses as <span class="bold"><strong>[bold]</strong></span>. In this case it's just a subtle visual difference,
|
||
but it could cause odd problems, for example when nested in a table cell.
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="language_versions.1_6.table"></a><a class="link" href="versions.html#language_versions.1_6.table" title="Table Titles">Table Titles</a>
|
||
</h4></div></div></div>
|
||
<p>
|
||
Table titles are now parsed as phrases, so some markup is allowd:
|
||
</p>
|
||
<pre class="programlisting">[table [*bold title]]
|
||
</pre>
|
||
<p>
|
||
Which is an empty table with a bold title. The title is no longer ended
|
||
by a newline, but by either a closing square bracket, or two opening square
|
||
brackets - which you get at the start of the table cells, so this now works:
|
||
</p>
|
||
<pre class="programlisting">[table Simple[[heading 1][heading 2]][[cell 1][cell 2]]]
|
||
</pre>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="language_versions.1_6.xmlbase"></a><a class="link" href="versions.html#language_versions.1_6.xmlbase" title="XML base">XML base</a>
|
||
</h4></div></div></div>
|
||
<p>
|
||
A problem when using <code class="computeroutput">xi:include</code> tags in escaped boostbook
|
||
is that you typically don't know which directory the boostbook file will
|
||
be in, so it's impossible to use relative links. This can be fixed by adding
|
||
an <code class="computeroutput">xml:base</code> attribute to the document tag. To do this use
|
||
the new <code class="computeroutput">xmlbase</code> attribute in your document's docinfo block.
|
||
For example to make escaped <code class="computeroutput">xi:include</code>s be relative to the
|
||
directory of the file:
|
||
</p>
|
||
<pre class="programlisting">[library Library documentation
|
||
[quickbook 1.6]
|
||
[xmlbase .]
|
||
]
|
||
</pre>
|
||
<p>
|
||
Any paths in <code class="computeroutput">xinclude</code> elements will be rewritten accordingly.
|
||
Note that most documents won't need this, and probably shouldn't use it.
|
||
Only use it if you're totally sure that you will need it.
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="language_versions.1_6.template_parser"></a><a class="link" href="versions.html#language_versions.1_6.template_parser" title="Improved template parser">Improved template
|
||
parser</a>
|
||
</h4></div></div></div>
|
||
<p>
|
||
There's a new parser for template declarations and parameters which does
|
||
a better job of understanding escaped and bracketed text. Unfortunately
|
||
it does not understand element names so there are some cases where it could
|
||
go wrong. For example:
|
||
</p>
|
||
<pre class="programlisting">[template doesnt_work[]
|
||
[ordered_list
|
||
[`code phrase`]
|
||
]
|
||
]
|
||
</pre>
|
||
<p>
|
||
In this case it will think the <code class="computeroutput">[\</code>` is a template call and
|
||
give a parse error. To work around this put an escaped space before the
|
||
code phrase:
|
||
</p>
|
||
<pre class="programlisting">[template works[]
|
||
[ordered_list
|
||
[\ `code phrase`]
|
||
]
|
||
]
|
||
</pre>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="language_versions.1_6.elements"></a><a class="link" href="versions.html#language_versions.1_6.elements" title="New Elements">New Elements</a>
|
||
</h4></div></div></div>
|
||
<p>
|
||
New elements added in quickbook 1.6:
|
||
</p>
|
||
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
|
||
<li class="listitem">
|
||
<a class="link" href="syntax/block.html#quickbook.ref.block"><code class="computeroutput">block</code></a>
|
||
</li>
|
||
<li class="listitem">
|
||
<a class="link" href="syntax/block.html#quickbook.ref.list_tags"><code class="computeroutput">ordered_list</code> and
|
||
<code class="computeroutput">itemized_list</code></a>
|
||
</li>
|
||
<li class="listitem">
|
||
<a class="link" href="syntax/phrase.html#quickbook.ref.role"><code class="computeroutput">role</code></a>
|
||
</li>
|
||
</ul></div>
|
||
</div>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="language_versions.1_7"></a><a class="link" href="versions.html#language_versions.1_7" title="Quickbook 1.7">Quickbook 1.7</a>
|
||
</h3></div></div></div>
|
||
<div class="toc"><dl class="toc">
|
||
<dt><span class="section"><a href="versions.html#language_versions.1_7.context_error">Error for elements
|
||
used in incorrect context</a></span></dt>
|
||
<dt><span class="section"><a href="versions.html#language_versions.1_7.phrase_parse_error">Error for
|
||
invalid phrase elements</a></span></dt>
|
||
<dt><span class="section"><a href="versions.html#language_versions.1_7.source_mode">Source mode for
|
||
single entities</a></span></dt>
|
||
<dt><span class="section"><a href="versions.html#language_versions.1_7.callouts">Callouts in code blocks</a></span></dt>
|
||
<dt><span class="section"><a href="versions.html#language_versions.1_7.escaped_docinfo_attributes">Escaped
|
||
docbook in docinfo blocks</a></span></dt>
|
||
<dt><span class="section"><a href="versions.html#language_versions.1_7.listparagraphs">Pargraphs in
|
||
lists</a></span></dt>
|
||
<dt><span class="section"><a href="versions.html#language_versions.1_7.templates_in_attributes">Templates
|
||
in some attributes</a></span></dt>
|
||
<dt><span class="section"><a href="versions.html#language_versions.1_7.list_markup_in_tables">List Markup
|
||
in Nested Blocks</a></span></dt>
|
||
<dt><span class="section"><a href="versions.html#language_versions.1_7.phrase_block_templates">Allow
|
||
block elements in phrase templates</a></span></dt>
|
||
<dt><span class="section"><a href="versions.html#language_versions.1_7.glob">Including multiple files
|
||
with Globs</a></span></dt>
|
||
</dl></div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="language_versions.1_7.context_error"></a><a class="link" href="versions.html#language_versions.1_7.context_error" title="Error for elements used in incorrect context">Error for elements
|
||
used in incorrect context</a>
|
||
</h4></div></div></div>
|
||
<p>
|
||
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.
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="language_versions.1_7.phrase_parse_error"></a><a class="link" href="versions.html#language_versions.1_7.phrase_parse_error" title="Error for invalid phrase elements">Error for
|
||
invalid phrase elements</a>
|
||
</h4></div></div></div>
|
||
<p>
|
||
If the body of a phrase element didn't parse, it would be just used unprocessed.
|
||
Now change it to be a hard error.
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="language_versions.1_7.source_mode"></a><a class="link" href="versions.html#language_versions.1_7.source_mode" title="Source mode for single entities">Source mode for
|
||
single entities</a>
|
||
</h4></div></div></div>
|
||
<p>
|
||
1.7 introduces a new <code class="computeroutput">!</code> 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:
|
||
</p>
|
||
<pre class="programlisting">[!c++]
|
||
void foo() {};
|
||
|
||
[!python]```def foo():```
|
||
</pre>
|
||
<p>
|
||
It can also be used to set the source mode for elements:
|
||
</p>
|
||
<pre class="programlisting">[!teletype][table
|
||
[[code][meaning]]
|
||
[[`+`][addition]]
|
||
]
|
||
</pre>
|
||
<p>
|
||
When used before a section, it sets the source mode for the whole section.
|
||
</p>
|
||
<p>
|
||
If it appears at the beginning of a paragraph, it will be used for the
|
||
whole paragraph only if there's a newline, eg.
|
||
</p>
|
||
<pre class="programlisting">[!c++]
|
||
A declaration `void foo();` and a definition `void foo() {}`.
|
||
</pre>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="language_versions.1_7.callouts"></a><a class="link" href="versions.html#language_versions.1_7.callouts" title="Callouts in code blocks">Callouts in code blocks</a>
|
||
</h4></div></div></div>
|
||
<p>
|
||
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.
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="language_versions.1_7.escaped_docinfo_attributes"></a><a class="link" href="versions.html#language_versions.1_7.escaped_docinfo_attributes" title="Escaped docbook in docinfo blocks">Escaped
|
||
docbook in docinfo blocks</a>
|
||
</h4></div></div></div>
|
||
<p>
|
||
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:
|
||
</p>
|
||
<pre class="programlisting">[article Some article
|
||
[quickbook 1.7]
|
||
'''<author>
|
||
<firstname>John</firstname>
|
||
<surname>Doe</surname>
|
||
<email>john.doe@example.com</email>
|
||
</author>'''
|
||
]
|
||
</pre>
|
||
<p>
|
||
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.
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="language_versions.1_7.listparagraphs"></a><a class="link" href="versions.html#language_versions.1_7.listparagraphs" title="Pargraphs in lists">Pargraphs in
|
||
lists</a>
|
||
</h4></div></div></div>
|
||
<p>
|
||
Paragraphs and block elements can now be used in lists:
|
||
</p>
|
||
<pre class="programlisting">* Para 1
|
||
|
||
Para 2
|
||
* Nested Para 1
|
||
|
||
Nested Para 2
|
||
|
||
Code block
|
||
Para 3
|
||
</pre>
|
||
<p>
|
||
generates:
|
||
</p>
|
||
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
|
||
<p class="simpara">
|
||
Para 1
|
||
</p>
|
||
<p class="simpara">
|
||
Para 2
|
||
</p>
|
||
<p class="simpara">
|
||
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
|
||
<p class="simpara">
|
||
Nested Para 1
|
||
</p>
|
||
<p class="simpara">
|
||
Nested Para 2
|
||
</p>
|
||
<pre class="programlisting">Code block
|
||
</pre>
|
||
</li></ul></div>
|
||
</p>
|
||
<p class="simpara">
|
||
Para 3
|
||
</p>
|
||
</li></ul></div>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="language_versions.1_7.templates_in_attributes"></a><a class="link" href="versions.html#language_versions.1_7.templates_in_attributes" title="Templates in some attributes">Templates
|
||
in some attributes</a>
|
||
</h4></div></div></div>
|
||
<p>
|
||
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.
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="language_versions.1_7.list_markup_in_tables"></a><a class="link" href="versions.html#language_versions.1_7.list_markup_in_tables" title="List Markup in Nested Blocks">List Markup
|
||
in Nested Blocks</a>
|
||
</h4></div></div></div>
|
||
<p>
|
||
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.
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="language_versions.1_7.phrase_block_templates"></a><a class="link" href="versions.html#language_versions.1_7.phrase_block_templates" title="Allow block elements in phrase templates">Allow
|
||
block elements in phrase templates</a>
|
||
</h4></div></div></div>
|
||
<p>
|
||
Block elements can now be used in phrase templates, but paragraphs breaks
|
||
aren't allowed, so this is an error:
|
||
</p>
|
||
<pre class="programlisting">[template paras[] Something or other.
|
||
|
||
Second paragraph.]
|
||
</pre>
|
||
<p>
|
||
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:
|
||
</p>
|
||
<pre class="programlisting">[template foo[] [blurb Blah, blah, blah]]
|
||
</pre>
|
||
<p>
|
||
as:
|
||
</p>
|
||
<pre class="programlisting">[template foo[]
|
||
[blurb Blah, blah, blah]
|
||
]
|
||
</pre>
|
||
<p>
|
||
If a phrase template has phrase content mixed with block elements, it'll
|
||
generate output as if it was expanded inline.
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="language_versions.1_7.glob"></a><a class="link" href="versions.html#language_versions.1_7.glob" title="Including multiple files with Globs">Including multiple files
|
||
with Globs</a>
|
||
</h4></div></div></div>
|
||
<p>
|
||
One can now include multiple files at once using a glob pattern for the
|
||
file reference:
|
||
</p>
|
||
<pre class="programlisting">[include sub/*/*.qbk]
|
||
[include include/*.h]
|
||
</pre>
|
||
<p>
|
||
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.
|
||
</p>
|
||
<div class="note"><table border="0" summary="Note">
|
||
<tr>
|
||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td>
|
||
<th align="left">Note</th>
|
||
</tr>
|
||
<tr><td align="left" valign="top"><p>
|
||
Because of the escaping in file references the "\\" glob escape
|
||
is a double "\"; i.e. and escaped back-slash.
|
||
</p></td></tr>
|
||
</table></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||
<td align="left"></td>
|
||
<td align="right"><div class="copyright-footer">Copyright © 2002, 2004, 2006 Joel de Guzman,
|
||
Eric Niebler<br>Copyright © 2010-2017 Daniel James<p>
|
||
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
|
||
</p>
|
||
</div></td>
|
||
</tr></table>
|
||
<hr>
|
||
<div class="spirit-nav">
|
||
<a accesskey="p" href="syntax/block.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../quickbook.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="install.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
|
||
</div>
|
||
</body>
|
||
</html>
|