| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> |
| <title>Language Versions</title> |
| <link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css"> |
| <meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> |
| <link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> |
| <link rel="up" href="../quickbook.html" title="Chapter 41. Quickbook 1.6"> |
| <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.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.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> |
| <p> |
| Upgrading a document from an earlier version of quickbook shouldn't be too |
| hard. The first thing to do is update the version in the docinfo block. For |
| example, if you were updating the Xpressive documentation, the existing docinfo |
| block looks like: |
| </p> |
| <pre class="programlisting">[library Boost.Xpressive |
| [quickbook 1.3] |
| ... |
| ] |
| </pre> |
| <p> |
| Change this to: |
| </p> |
| <pre class="programlisting">[library Boost.Xpressive |
| [quickbook 1.6] |
| [compatibility-mode 1.3] |
| ... |
| ] |
| </pre> |
| <p> |
| The <code class="literal">compatibility-mode</code> tag ensures that automatically |
| generated links won't change. It might turn out that it isn't required, but |
| in Xpressive's case if it isn't included it will break a lot of links. |
| </p> |
| <p> |
| Then try building it. You might need to fix some stray square brackets. The |
| new version has a stricter parser which will have an error for brackets which |
| don't pair up. They might be there by mistake, in which case they should |
| probably be deleted, or if they're intentional escaped. For example, to write |
| out the half-open range [a,b), use: <code class="computeroutput">\[a,b)</code>. |
| </p> |
| <p> |
| Next, 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 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, 2011 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> |