91 lines
3.1 KiB
Plaintext
91 lines
3.1 KiB
Plaintext
[/
|
|
Copyright 2002,2004,2006 Joel de Guzman, Eric Niebler
|
|
Copyright 2010-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)
|
|
]
|
|
|
|
[chapter Language Versions
|
|
[quickbook 1.7]
|
|
[compatibility-mode 1.5]
|
|
[id quickbook.versions]
|
|
[source-mode teletype]
|
|
]
|
|
|
|
[section:upgrading Upgrading to a new version]
|
|
|
|
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:
|
|
|
|
[library Boost.Example
|
|
[quickbook 1.3]
|
|
...
|
|
]
|
|
|
|
Change this to:
|
|
|
|
[library Boost.Example
|
|
[quickbook 1.7]
|
|
[compatibility-mode 1.3]
|
|
...
|
|
]
|
|
|
|
The =compatibility-mode= 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.
|
|
|
|
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: `\[a,b)`.
|
|
|
|
When upgrading to 1.6 or later, you might need to reconsider how templates
|
|
and macros are defined.
|
|
If you `include` a file to use its templates, you'll now need to `import` 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 `import` that, which allows the main documentation
|
|
files to concentrate on the structure and contents of the document, making them
|
|
easier to read.
|
|
|
|
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.
|
|
|
|
[endsect]
|
|
|
|
[section:stable Stable Versions]
|
|
|
|
Since quickbook 1.3 the `quickbook` 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.
|
|
|
|
[heading Quickbook 1.3 and later]
|
|
|
|
* Introduced quickbook language versioning.
|
|
* In the documentation info, allow phrase markup in license and purpose
|
|
attributes.
|
|
* Fully qualified section and headers. Subsection names are concatenated to the
|
|
ID to avoid clashing. Example: `doc_name.sect_name.sub_sect_name.sub_sub_sect_name`.
|
|
|
|
[heading Quickbook 1.5 and later]
|
|
|
|
* Ignore template argument separators inside square brackets.
|
|
* Don't separate the final template argument if the `..` separator was
|
|
used. i.e. never mix `..` and whitespace separators.
|
|
* Statically scope templates and their arguments rather than dynamically
|
|
scope them.
|
|
* Give table ids, and let you set them.
|
|
* Allow spaces between the `:` character and ids in elements which can
|
|
have ids.
|
|
|
|
[endsect:stable]
|
|
|
|
[include 1_6.qbk]
|
|
[include 1_7.qbk]
|