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.