[/
    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]