1[/ 2 Copyright 2002,2004,2006 Joel de Guzman, Eric Niebler 3 Copyright 2010-2013 Daniel James 4 5 Distributed under the Boost Software License, Version 1.0. 6 (See accompanying file LICENSE_1_0.txt or copy at 7 http://www.boost.org/LICENSE_1_0.txt) 8] 9 10[chapter Language Versions 11 [quickbook 1.7] 12 [compatibility-mode 1.5] 13 [id quickbook.versions] 14 [source-mode teletype] 15] 16 17[section:upgrading Upgrading to a new version] 18 19To upgrade an existing document to a new version of quickbook, you will 20need to update the version in the docinfo block. 21For example, the existing docinfo block might look like: 22 23 [library Boost.Example 24 [quickbook 1.3] 25 ... 26 ] 27 28Change this to: 29 30 [library Boost.Example 31 [quickbook 1.7] 32 [compatibility-mode 1.3] 33 ... 34 ] 35 36The =compatibility-mode= tag ensures that it will generate similar output 37to the older version - most importantly is will generate the same ids, 38ensuring that links to the generated html won't break. 39 40Then try building it. Later versions have a stricter parser, so there might 41be errors. It's quite likely that you might need to fix some stray square brackets. 42They might need to be escaped. For example, 43to write out the half-open range \[a,b), use: `\[a,b)`. 44 45When upgrading to 1.6 or later, you might need to reconsider how templates 46and macros are defined. 47If you `include` a file to use its templates, you'll now need to `import` it 48instead as templates are now scoped by included files. Also, if you define 49templates and macros in your main quickbook file, you might want to put them 50into a separate file and `import` that, which allows the main documentation 51files to concentrate on the structure and contents of the document, making them 52easier to read. 53 54Now that headings can have ids, it can be a good idea to add ids to existing 55headings. This means that the headings will have more predictable ids which 56don't change when the text of the heading changes. In order to preserve 57links you can use the existing generated id as the heading. 58 59[endsect] 60 61[section:stable Stable Versions] 62 63Since quickbook 1.3 the `quickbook` attribute in the document block selects 64which version of the language to use. Not all changes to quickbook are 65implemented using a version switch, it's mainly just the changes that change 66the way a document is interpreted or would break existing documentation. 67 68[heading Quickbook 1.3 and later] 69 70* Introduced quickbook language versioning. 71* In the documentation info, allow phrase markup in license and purpose 72 attributes. 73* Fully qualified section and headers. Subsection names are concatenated to the 74 ID to avoid clashing. Example: `doc_name.sect_name.sub_sect_name.sub_sub_sect_name`. 75 76[heading Quickbook 1.5 and later] 77 78* Ignore template argument separators inside square brackets. 79* Don't separate the final template argument if the `..` separator was 80 used. i.e. never mix `..` and whitespace separators. 81* Statically scope templates and their arguments rather than dynamically 82 scope them. 83* Give table ids, and let you set them. 84* Allow spaces between the `:` character and ids in elements which can 85 have ids. 86 87[endsect:stable] 88 89[include 1_6.qbk] 90[include 1_7.qbk] 91