]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 | [section:1_6 Quickbook 1.6] | |
11 | ||
12 | Upgrading a document from an earlier version of quickbook shouldn't be too | |
13 | hard. The first thing to do is update the version in the docinfo block. | |
14 | For example, if you were updating the Xpressive documentation, the existing | |
15 | docinfo block looks like: | |
16 | ||
17 | [library Boost.Xpressive | |
18 | [quickbook 1.3] | |
19 | ... | |
20 | ] | |
21 | ||
22 | Change this to: | |
23 | ||
24 | [library Boost.Xpressive | |
25 | [quickbook 1.6] | |
26 | [compatibility-mode 1.3] | |
27 | ... | |
28 | ] | |
29 | ||
30 | The =compatibility-mode= tag ensures that automatically generated links | |
31 | won't change. It might turn out that it isn't required, but in Xpressive's | |
32 | case if it isn't included it will break a lot of links. | |
33 | ||
34 | Then try building it. You might need to fix some stray square brackets. The | |
35 | new version has a stricter parser which will have an error for brackets | |
36 | which don't pair up. They might be there by mistake, in which case they | |
37 | should probably be deleted, or if they're intentional escaped. For example, | |
38 | to write out the half-open range \[a,b), use: `\[a,b)`. | |
39 | ||
40 | Next, you might need to reconsider how templates and macros are defined. | |
41 | If you `include` a file to use its templates, you'll now need to `import` it | |
42 | instead as templates are now scoped by included files. Also, if you define | |
43 | templates and macros in your main quickbook file, you might want to put them | |
44 | into a separate file and `import` that, which allows the main documentation | |
45 | files to concentrate on the structure and contents of the document, making them | |
46 | easier to read. | |
47 | ||
48 | Now that headings can have ids, it can be a good idea to add ids to existing | |
49 | headings. This means that the headings will have more predictable ids which | |
50 | don't change when the text of the heading changes. In order to preserve | |
51 | links you can use the existing generated id as the heading. | |
52 | ||
53 | [section:docinfo Includes with docinfo] | |
54 | ||
55 | In quickbook 1.5 if you include a file which starts with a docinfo block, it's | |
56 | ignored and the file is expanded in place. In quickbook 1.6 it's treated as a | |
57 | document nested in the current position. So if it has an 'article' docinfo block, | |
58 | boostbook 'article' tags are used. | |
59 | ||
60 | It also mostly generates the same markup as if the file was converted separately - | |
61 | so for example, the same ids are generated, the document is processed using the | |
62 | language version specified in the docinfo block. If no language is specified it | |
63 | uses the default (1.1) not the version of the document that included it. This | |
64 | might seem surprising, but is requried so that quickbook will convert it the same | |
65 | way as if it was converted separately. | |
66 | ||
67 | So for the most part, includes with a docinfo are like an `xinclude`, apart from | |
68 | a couple of differences. Templates and macros defined in the parent document are | |
69 | used in the included document, and the id generator rewrites ids that clash | |
70 | between multiple documents. | |
71 | ||
72 | If an included document doesn't have a docinfo block, it's just included as | |
73 | before. | |
74 | ||
75 | [endsect] [/docinfo] | |
76 | ||
77 | [section:doc_info_macros Macros in docinfo block] | |
78 | ||
79 | You can now expand macros in text fields in the docinfo block. In the top | |
80 | docinfo block only the predefined macros are available, but in nested documents | |
81 | macros defined in the parent document are also available. | |
82 | ||
83 | There's a small bug here - this leaks into older versions for the `license` | |
84 | and `purpose` fields, but since only the predefined macros are available, it's | |
85 | unlikely to break any existing documents. So I'd rather not complicate the code | |
86 | further by fixing that. | |
87 | ||
88 | [endsect] | |
89 | ||
90 | [section:scope Scoping templates and macros] | |
91 | ||
92 | A long standing quickbook bug is that macros are scoped by file, but templates | |
93 | aren't. So you can define templates in a separate file and include them, but not | |
94 | macros. This has been fixed so that templates defined in one file won't 'leak' | |
95 | into another. | |
96 | ||
97 | But this means there's no way to define templates in a separate file - a useful | |
98 | feature. To do this the `import` element has been adapted to also support | |
99 | quickbook files. If a quickbook file is imported, the templates and macros | |
100 | defined in it are added to the current scope, but nothing else contained in that | |
101 | file is used. This could be used to create template and macro library files. | |
102 | This matches the existing semantics of importing code snippets. | |
103 | ||
104 | When importing templates, they're bound to the language version of the file | |
105 | they were defined in. This means that if you import them into a file with | |
106 | a different version it won't change the way they're interpreted. Although, | |
107 | as we'll see [link compatibility later], the generated boostbook is slightly | |
108 | different. | |
109 | ||
110 | [endsect] [/scope] | |
111 | ||
112 | [section:include Including C++ and python files] | |
113 | ||
114 | As `import` now supports quickbook files, `include` also supports source files. | |
115 | It includes any quickbook contained in comments outside of code snippets. | |
116 | Code snippets in the file are available to be expanded within the file but | |
117 | are scoped to the file. In exactly the same manner as when templates and macros | |
118 | are scoped in an included quickbook file. | |
119 | ||
120 | [endsect] [/include] | |
121 | ||
122 | [section:ids Id Generation] | |
123 | ||
124 | Id generation in quickbook 1.5 is a bit buggy, but that can't be fixed without a | |
125 | version switch as it will break existing documents. For example in quickbook 1.5 | |
126 | when you include a quickbook file, it stops using the explicit id from the | |
127 | documentation info and generates a new id from the document title to use instead. | |
128 | ||
129 | The id generator in quickbook 1.6 has been improved in some other ways to. When | |
130 | generating ids from section titles, table titles etc. it always uses the | |
131 | quickbook source rather than the generated boostbook to generate the id. It then | |
132 | cleans up the id slightly, trimming leading and trailing underscores and replacing | |
133 | multiple underscores with a single underscore. Then if the newly generated part | |
134 | of the id is longer than 32 characters it truncates it. | |
135 | ||
136 | While the new id generator generally creates better ids, it's more likely to | |
137 | generate duplicates so quickbook needs to handle duplicates better. When there | |
138 | are multiple identical ids, quickbook chooses one to use based on a priority | |
139 | list - anchors are preferred, then explicit document and section ids, then other | |
140 | explicit ids, followed by the generated ids. Then any other explicit ids in the | |
141 | document have numbers added to avoid duplicates - first the explicit ids in the | |
142 | order they appear and then the generated ids. A generated id which accidentally | |
143 | clashes with an explicit id should never change the explicit id. | |
144 | ||
145 | Older language versions still generate the same ids they always have, with the | |
146 | exception of duplicate ids which are handled using the new mechanism - this | |
147 | is not a breaking change since duplicate ids can't be linked to. | |
148 | ||
149 | [endsect] [/ids] | |
150 | ||
151 | [#compatibility] | |
152 | [section:compatibility Compatibility Mode] | |
153 | ||
154 | As mentioned before, changing the id generator will break links in documents | |
155 | written using an old language version. So to ease the transition a | |
156 | 'compatibility mode' is used, this just requires an extra attribute in the | |
157 | docinfo, for example if you're converting a 1.5 document to 1.6: | |
158 | ||
159 | [article Document | |
160 | [quickbook 1.6] | |
161 | [compatibility-mode 1.5] | |
162 | ] | |
163 | ||
164 | This means the document will be parsed as 1.6, using all the new features, but | |
165 | ids (and possibly other markup) will generated as they were for a 1.5 document. | |
166 | ||
167 | Compatibility mode is also implicitly used when generating templates written | |
168 | in a different language version to the current document. So the template is | |
169 | parsed in the version it was written for, but generates boostbook that's | |
170 | compatible with the current document. | |
171 | ||
172 | [endsect] [/compatibility] | |
173 | ||
174 | [section:version Version info outside of document info block] | |
175 | ||
176 | Can now use `quickbook` and `compatibility-mode` tags at the beginning of the | |
177 | file. Either before or without a document info block. This is useful for | |
178 | files just containing templates, which don't really need a document info | |
179 | block. | |
180 | ||
181 | If you don't specify `compatibility-mode`, the behaviour depends on whether or | |
182 | not you have a docinfo block. If you do it uses the file's quickbook version, | |
183 | if you don't it inherits the parent's compatibility mode even if you specify | |
184 | a quickbook version. This is the right thing to do - mixing compatibility modes | |
185 | within documents is problematic. It might actually be a mistake to allow them | |
186 | to specified outside docinfo blocks. | |
187 | ||
188 | This change is also backdated to older versions. So when including from an | |
189 | older version, the included file's version can be set (older versions | |
190 | ignore document info in included files). | |
191 | ||
192 | [endsect] | |
193 | ||
194 | [section:heading_ids Explicit Heading Ids] | |
195 | ||
196 | Headings can now be given explicit ids: | |
197 | ||
198 | [heading:id A heading with an explicit id] | |
199 | ||
200 | [endsect] [/heading_ids] | |
201 | ||
202 | [section:escapes Punctuation changes] | |
203 | ||
204 | In 1.6, quickbook is more consistent about how it parses punctuation. | |
205 | Escapes are now supported in links, anchors, table titles, image | |
206 | attributes etc. The flip side of this is that quickbook is now stricter | |
207 | about unescaped brackets. They can still be used, but need to match up, | |
208 | otherwise there's an error. | |
209 | ||
210 | Since quickbook now matches up square brackets it will fix some | |
211 | mis-parses. For example `[*[bold]]` used to parse as [*\[bold]\] - note | |
212 | that the closing square bracket isn't bold, now it parses as | |
213 | [*\[bold\]]. In this case it's just a subtle visual difference, but it | |
214 | could cause odd problems, for example when nested in a table cell. | |
215 | ||
216 | [endsect] [/escapes] | |
217 | ||
218 | [section:table Table Titles] | |
219 | ||
220 | Table titles are now parsed as phrases, so some markup is allowd: | |
221 | ||
222 | [table [*bold title]] | |
223 | ||
224 | Which is an empty table with a bold title. The title is no longer ended | |
225 | by a newline, but by either a closing square bracket, or two opening | |
226 | square brackets - which you get at the start of the table cells, so | |
227 | this now works: | |
228 | ||
229 | [table Simple[[heading 1][heading 2]][[cell 1][cell 2]]] | |
230 | ||
231 | [endsect] [/table] | |
232 | ||
233 | [section:xmlbase XML base] | |
234 | ||
235 | A problem when using `xi:include` tags in escaped boostbook is that you | |
236 | typically don't know which directory the boostbook file will be in, so | |
237 | it's impossible to use relative links. This can be fixed by adding an | |
238 | `xml:base` attribute to the document tag. To do this use the new | |
239 | `xmlbase` attribute in your document's docinfo block. For example to | |
240 | make escaped `xi:include`s be relative to the directory of the file: | |
241 | ||
242 | [library Library documentation | |
243 | [quickbook 1.6] | |
244 | [xmlbase .] | |
245 | ] | |
246 | ||
247 | Any paths in `xinclude` elements will be rewritten accordingly. Note that | |
248 | most documents won't need this, and probably shouldn't use it. Only use it | |
249 | if you're totally sure that you will need it. | |
250 | ||
251 | [endsect] [/xmlbase] | |
252 | ||
253 | [section:template_parser Improved template parser] | |
254 | ||
255 | There's a new parser for template declarations and parameters which does | |
256 | a better job of understanding escaped and bracketed text. Unfortunately | |
257 | it does not understand element names so there are some cases where it | |
258 | could go wrong. For example: | |
259 | ||
260 | [template doesnt_work[] | |
261 | [ordered_list | |
262 | [`code phrase`] | |
263 | ] | |
264 | ] | |
265 | ||
266 | In this case it will think the `[\`` is a template call and give a parse | |
267 | error. To work around this put an escaped space before the code phrase: | |
268 | ||
269 | [template works[] | |
270 | [ordered_list | |
271 | [\ `code phrase`] | |
272 | ] | |
273 | ] | |
274 | ||
275 | [endsect] | |
276 | ||
277 | [section:elements New Elements] | |
278 | ||
279 | New elements added in quickbook 1.6: | |
280 | ||
281 | * [link quickbook.ref.block `block`] | |
282 | * [link quickbook.ref.list_tags `ordered_list` and `itemized_list`] | |
283 | * [link quickbook.ref.role `role`] | |
284 | ||
285 | [endsect] [/ elements] | |
286 | ||
287 | [endsect] [/ Quickbok 1.6] |