1 | [article Quickbook |
---|
2 | [quickbook 1.3] |
---|
3 | [version 1.3] |
---|
4 | [authors [de Guzman, Joel], [Niebler, Eric]] |
---|
5 | [copyright 2002 2004 Joel de Guzman, Eric Niebler] |
---|
6 | [purpose /WikiWiki/ style documentation tool] |
---|
7 | [license |
---|
8 | Distributed under the Boost Software License, Version 1.0. |
---|
9 | (See accompanying file LICENSE_1_0.txt or copy at |
---|
10 | [@http://www.boost.org/LICENSE_1_0.txt]) |
---|
11 | ] |
---|
12 | ] |
---|
13 | |
---|
14 | [/ QuickBook Document version 1.3 ] |
---|
15 | [/ Sept 24, 2002 ] |
---|
16 | [/ Sept 2, 2004 ] |
---|
17 | [/ Feb 14, 2005 ] |
---|
18 | [/ Sept 13, 2005 ] |
---|
19 | |
---|
20 | [/ Some links] |
---|
21 | |
---|
22 | [def __note__ [$images/note.png]] |
---|
23 | [def __alert__ [$images/alert.png]] |
---|
24 | [def __tip__ [$images/tip.png]] |
---|
25 | [def :-) [$images/smiley.png]] |
---|
26 | [def __spirit__ [@http://spirit.sourceforge.net Spirit]] |
---|
27 | [def __boostbook__ [@http://www.boost.org/doc/html/boostbook.html BoostBook]] |
---|
28 | [def __docbook__ [@http://www.docbook.org/ DocBook]] |
---|
29 | |
---|
30 | [def __comments__ [link quickbook.syntax.comments Comments]] |
---|
31 | |
---|
32 | [def __font_styles__ [link quickbook.syntax.phrase.font_styles Font Styles]] |
---|
33 | [def __quotations__ [link quickbook.syntax.phrase.quotations Quotations]] |
---|
34 | [def __replaceable__ [link quickbook.syntax.phrase.replaceable Replaceble]] |
---|
35 | [def __simple_formatting__ [link quickbook.syntax.phrase.simple_formatting formatting Simple formatting]] |
---|
36 | [def __inline_code__ [link quickbook.syntax.phrase.inline_code Inline code]] |
---|
37 | [def __code_blocks__ [link quickbook.syntax.phrase.code_blocks Code blocks]] |
---|
38 | [def __source_mode__ [link quickbook.syntax.phrase.source_mode Source Mode]] |
---|
39 | [def __line_break__ [link quickbook.syntax.phrase.line_break line-break]] |
---|
40 | [def __anchors__ [link quickbook.syntax.phrase.anchors Anchors]] |
---|
41 | [def __links__ [link quickbook.syntax.phrase.links Links]] |
---|
42 | [def __anchor_links__ [link quickbook.syntax.phrase.anchor_links Anchor links]] |
---|
43 | [def __refentry_links__ [link quickbook.syntax.phrase.refentry_links refentry links]] |
---|
44 | [def __code_links__ [link quickbook.syntax.phrase.code_links function, class, member, enum or header links]] |
---|
45 | [def __escape__ [link quickbook.syntax.phrase.escape Escape]] |
---|
46 | [def __single_char_escape__ [link quickbook.syntax.phrase.single_char_escape Single char escape]] |
---|
47 | [def __images__ [link quickbook.syntax.phrase.images Images]] |
---|
48 | |
---|
49 | [def __document__ [link quickbook.syntax.block.document Document]] |
---|
50 | [def __section__ [link quickbook.syntax.block.section Section]] |
---|
51 | [def __xinclude__ [link quickbook.syntax.block.xinclude xinclude]] |
---|
52 | [def __paragraphs__ [link quickbook.syntax.block.paragraphs Paragraphs]] |
---|
53 | [def __ordered_lists__ [link quickbook.syntax.block.lists.ordered_lists Ordered lists]] |
---|
54 | [def __list_hierarchies__ [link quickbook.syntax.block.lists.list_hierarchies List Hierarchies]] |
---|
55 | [def __long_list_lines__ [link quickbook.syntax.block.lists.long_list_lines Long List Lines]] |
---|
56 | [def __unordered_lists__ [link quickbook.syntax.block.lists.unordered_lists Unordered lists]] |
---|
57 | [def __mixed_lists__ [link quickbook.syntax.block.lists.mixed_lists Mixed lists]] |
---|
58 | [def __code__ [link quickbook.syntax.block.code Code]] |
---|
59 | [def __escape_back__ [link quickbook.syntax.block.escape_back Escaping Back To QuickBook]] |
---|
60 | [def __preformatted__ [link quickbook.syntax.block.preformatted Preformatted]] |
---|
61 | [def __blockquote__ [link quickbook.syntax.block.blockquote Blockquote]] |
---|
62 | [def __heading__ [link quickbook.syntax.block.headings Heading]] |
---|
63 | [def __macros__ [link quickbook.syntax.block.macros Macros]] |
---|
64 | [def __predefined_macros__ [link quickbook.syntax.block.predefined_macros Predefined Macros]] |
---|
65 | [def __blurbs__ [link quickbook.syntax.block.blurbs Blurbs]] |
---|
66 | [def __admonitions__ [link quickbook.syntax.block.admonitions Admonitions]] |
---|
67 | [def __tables__ [link quickbook.syntax.block.tables Tables]] |
---|
68 | [def __variable_lists__ [link quickbook.syntax.block.variable_lists Variable Lists]] |
---|
69 | [def __include__ [link quickbook.syntax.block.include Include]] |
---|
70 | |
---|
71 | [section:intro Introduction] |
---|
72 | |
---|
73 | [:[*['["Why program by hand in five days what you can spend five years of your |
---|
74 | life automating?]]]\n\n-- Terrence Parr, author ANTLR/PCCTS] |
---|
75 | |
---|
76 | Well, QuickBook started as a weekend hack. It was originally intended to be a |
---|
77 | sample application using __spirit__. What is it? What you are viewing now, this |
---|
78 | documentation, is autogenerated by QuickBook. These files were generated from |
---|
79 | one master: |
---|
80 | |
---|
81 | [:[@../quickbook.qbk quickbook.qbk]] |
---|
82 | |
---|
83 | Originally named QuickDoc, this funky tool that never dies evolved into a |
---|
84 | funkier tool thanks to Eric Niebler who resurrected the project making it |
---|
85 | generate __boostbook__ instead of HTML. The __boostbook__ documentation format |
---|
86 | is an extension of __docbook__, an SGML or XML based format for describing |
---|
87 | documentation. |
---|
88 | |
---|
89 | QuickBook is a WikiWiki style documentation tool geared towards C++ |
---|
90 | documentation using simple rules and markup for simple formatting tasks. |
---|
91 | QuickBook extends the WikiWiki concept. Like the WikiWiki, QuickBook documents are |
---|
92 | simple text files. A single QuickBook document can generate a fully linked set |
---|
93 | of nice HTML and PostScript/PDF documents complete with images and syntax- |
---|
94 | colorized source code. |
---|
95 | |
---|
96 | Features include: |
---|
97 | |
---|
98 | * generate __boostbook__ xml, to generate HTML, PostScript and PDF |
---|
99 | * simple markup to link to Doxygen-generated entities |
---|
100 | * macro system for simple text substitution |
---|
101 | * simple markup for italics, bold, preformatted, blurbs, code samples, |
---|
102 | tables, URLs, anchors, images, etc. |
---|
103 | * automatic syntax coloring of code samples |
---|
104 | * CSS support |
---|
105 | |
---|
106 | [endsect] |
---|
107 | |
---|
108 | [section:change_log Change Log] |
---|
109 | |
---|
110 | [h3 Version 1.3] |
---|
111 | |
---|
112 | * Quickbook file inclusion \[include\]. |
---|
113 | * Better xml output (pretty layout). Check out the generated XML. |
---|
114 | * Regression testing facility: to make sure your document will always be |
---|
115 | compatible (full backward compatibility) regardless of changes to |
---|
116 | QuickBook. |
---|
117 | * Code cleanup and refactoring. |
---|
118 | * Allow phrase markup in the doc-info. |
---|
119 | * Preformatted code blocks via \`\`code\`\` (double ticks) allows code in tables |
---|
120 | and lists, for example. |
---|
121 | * Quickbook versioning; allows full backward compatibility. You have to add |
---|
122 | \[quickbook 1.3\] to the doc-info header to enable the new features. Without |
---|
123 | this, QuickBook will assume that the document is a pre-1.3 document. |
---|
124 | * Better (intuitive) paragraph termination. Some markups may terminate a paragraph. |
---|
125 | Example:`` |
---|
126 | [section x] |
---|
127 | blah... |
---|
128 | [endsect]`` |
---|
129 | * Fully qualified section and headers. Subsection names are concatenated to the |
---|
130 | ID to avoid clashing. Example: `doc_name.sect_name.sub_sect_name.sub_sub_sect_name` |
---|
131 | * Better and whitespace handling in code snippets. |
---|
132 | * \[xinclude\] fixes up the relative path to the target XML file when |
---|
133 | input_directory is not the same as the output_directory. |
---|
134 | * Allow untitled tables. |
---|
135 | * Allow phrase markups in section titles. |
---|
136 | * Allow escaping back to QuickBook from code, code blocks and inline code. |
---|
137 | * Footnotes, with the \[footnote This is the footnote\] syntax. |
---|
138 | * Post-processor bug fix for escaped XML code that it does not recognize. |
---|
139 | * Replaceable, with the \[~replacement\] syntax. |
---|
140 | |
---|
141 | [endsect] |
---|
142 | |
---|
143 | [section:syntax Syntax Summary] |
---|
144 | |
---|
145 | A QuickBook document is composed of one or more blocks. An example of |
---|
146 | a block is the paragraph or a C++ code snippet. Some blocks have |
---|
147 | special mark-ups. Blocks, except code snippets which have their own |
---|
148 | grammar (C++ or Python), are composed of one or more phrases. A phrase |
---|
149 | can be a simple contiguous run of characters. Phrases can have special |
---|
150 | mark-ups. Marked up phrases can recursively contain other phrases, but |
---|
151 | cannot contain blocks. A terminal is a self contained block-level or |
---|
152 | phrase-level element that does not nest anything. |
---|
153 | |
---|
154 | Blocks, in general, are delimited by two end-of-lines (the block terminator). |
---|
155 | Phrases in each block cannot contain a block terminator. This way, syntax errors |
---|
156 | such as un-matched closing brackets do not go haywire and corrupt anything past |
---|
157 | a single block. |
---|
158 | |
---|
159 | [section Comments] |
---|
160 | |
---|
161 | Can be placed anywhere. |
---|
162 | |
---|
163 | [pre |
---|
164 | '''[/ comment (no output generated) ]''' |
---|
165 | ] |
---|
166 | |
---|
167 | [endsect] |
---|
168 | |
---|
169 | [section:phrase Phrase Level Elements] |
---|
170 | |
---|
171 | [section Font Styles] |
---|
172 | |
---|
173 | [pre''' |
---|
174 | ['italic], [*bold], [_underline], [^teletype], [-strikethrough] |
---|
175 | '''] |
---|
176 | |
---|
177 | will generate: |
---|
178 | |
---|
179 | ['italic], [*bold], [_underline], [^teletype], [-strikethrough] |
---|
180 | |
---|
181 | Like all non-terminal phrase level elements, this can of course be nested: |
---|
182 | |
---|
183 | [pre''' |
---|
184 | [*['bold-italic]] |
---|
185 | '''] |
---|
186 | |
---|
187 | will generate: |
---|
188 | |
---|
189 | [*['bold-italic]] |
---|
190 | |
---|
191 | [endsect] |
---|
192 | |
---|
193 | [section Replaceable] |
---|
194 | |
---|
195 | When you want content that may or must be replaced by the user, use the syntax: |
---|
196 | |
---|
197 | [pre''' |
---|
198 | [~replacement] |
---|
199 | '''] |
---|
200 | |
---|
201 | This will generate: |
---|
202 | |
---|
203 | [~replacement] |
---|
204 | |
---|
205 | [endsect] |
---|
206 | |
---|
207 | [section Quotations] |
---|
208 | |
---|
209 | [pre''' |
---|
210 | ["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein |
---|
211 | '''] |
---|
212 | |
---|
213 | will generate: |
---|
214 | |
---|
215 | ["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein |
---|
216 | |
---|
217 | Note the proper left and right quote marks. Also, while you can simply use |
---|
218 | ordinary quote marks like "quoted", our quotation, above, will generate correct |
---|
219 | DocBook quotations (e.g. <quote>quoted</quote>). |
---|
220 | |
---|
221 | Like all phrase elements, quotations may be nested. Example: |
---|
222 | |
---|
223 | [pre''' |
---|
224 | ["Here's the rule for bargains: ["Do other men, for they would do you.] That's |
---|
225 | the true business precept.] |
---|
226 | '''] |
---|
227 | |
---|
228 | will generate: |
---|
229 | |
---|
230 | ["Here's the rule for bargains: ["Do other men, for they would do you.] |
---|
231 | That's the true business precept.] |
---|
232 | |
---|
233 | [endsect] |
---|
234 | [section Simple formatting] |
---|
235 | |
---|
236 | Simple markup for formatting text, common in many applications, is now supported: |
---|
237 | |
---|
238 | [pre''' |
---|
239 | /italic/, *bold*, _underline_, =teletype= |
---|
240 | '''] |
---|
241 | |
---|
242 | will generate: |
---|
243 | |
---|
244 | /italic/, *bold*, _underline_, =teletype= |
---|
245 | |
---|
246 | Unlike QuickBook's standard formatting scheme, the rules for simpler alternatives |
---|
247 | are much stricter. |
---|
248 | |
---|
249 | * Simple markups cannot nest. You can combine a simple markup with a nestable markup. |
---|
250 | * A non-space character must follow the leading markup |
---|
251 | * A non-space character must precede the trailing markup |
---|
252 | * A space or a punctuation must follow the trailing markup |
---|
253 | * If the matching markup cannot be found within a line, the formatting |
---|
254 | will not be applied. This is to ensure that un-matched formatting markups, |
---|
255 | which can be a common mistake, does not corrupt anything past a single line. |
---|
256 | We do not want the rest of the document to be rendered bold just because we |
---|
257 | forgot a trailing '*'. |
---|
258 | * A line starting with the star will be interpreted as an unordered list. |
---|
259 | See __unordered_lists__. |
---|
260 | |
---|
261 | [table More Formatting Samples |
---|
262 | [[Markup] [Result]] |
---|
263 | [[[^'''*Bold*''']] [*Bold*]] |
---|
264 | [[[^'''*Is bold*''']] [*Is bold*]] |
---|
265 | [[[^'''* Not bold* *Not bold * * Not bold *''']] [* Not bold* *Not bold * * Not bold *]] |
---|
266 | [[[^'''This*Isn't*Bold (no bold)''']] [This*Isn't*Bold (no bold)]] |
---|
267 | [[[^'''(*Bold Inside*) (parenthesis not bold)''']] [(*Bold Inside*) (parenthesis not bold)]] |
---|
268 | [[[^'''*(Bold Outside)* (parenthesis bold)''']] [*(Bold Outside)* (parenthesis bold)]] |
---|
269 | [[[^'''3*4*5 = 60 (no bold)''']] [3*4*5 = 60 (no bold)]] |
---|
270 | [[[^'''3 * 4 * 5 = 60 (no bold)''']] [3 * 4 * 5 = 60 (no bold)]] |
---|
271 | [[[^'''3 *4* 5 = 60 (4 is bold)''']] [3 *4* 5 = 60 (4 is bold)]] |
---|
272 | [[[^'''*This is bold* this is not *but this is*''']][*This is bold* this is not *but this is*]] |
---|
273 | [[[^'''*This is bold*.''']] [*This is bold*.]] |
---|
274 | [[[^'''*B*. (bold B)''']] [*B*. (bold B)]] |
---|
275 | [[[^'''['*Bold-Italic*]''']] [['*Bold-Italic*]]] |
---|
276 | ] |
---|
277 | |
---|
278 | [blurb __note__ Thanks to David Barrett, author of |
---|
279 | [@http://quinthar.com/qwikiwiki/index.php?page=Home Qwiki], for sharing these samples |
---|
280 | and teaching me these obscure formatting rules. I wasn't sure at all if __spirit__, |
---|
281 | being more or less a formal EBNF parser, can handle the context sensitivity and ambiguity.] |
---|
282 | |
---|
283 | [endsect] |
---|
284 | [section Inline code] |
---|
285 | |
---|
286 | Inlining code in paragraphs is quite common when writing C++ documentation. We |
---|
287 | provide a very simple markup for this. For example, this: |
---|
288 | |
---|
289 | [pre''' |
---|
290 | This text has inlined code `int main() { return 0; }` in it. |
---|
291 | '''] |
---|
292 | |
---|
293 | will generate: |
---|
294 | |
---|
295 | This text has inlined code `int main() { return 0; }` in it. The code will be |
---|
296 | syntax highlighted. |
---|
297 | |
---|
298 | [blurb __note__ |
---|
299 | Note that we simply enclose the code with the tick: [^'''"`"'''], not the |
---|
300 | single quote: `"'"`. Note too that [^'''`some code`'''] is preferred over |
---|
301 | [^'''[^some code]''']. |
---|
302 | ] |
---|
303 | |
---|
304 | [endsect] |
---|
305 | [section Code blocks] |
---|
306 | |
---|
307 | Preformatted code simply starts with a space or a tab (See __code__). |
---|
308 | However, such a simple syntax cannot be used as phrase elements in lists |
---|
309 | (See __ordered_lists__ and __unordered_lists__), tables (See __tables__), |
---|
310 | etc. Inline code (see above) can. The problem is, inline code does not |
---|
311 | allow formatting with newlines, spaces, and tabs. These are lost. |
---|
312 | |
---|
313 | We provide a phrase level markup that is a mix between the two. By using the |
---|
314 | double-tick, instead of the single-tick, we are telling QuickBook to use |
---|
315 | preformatted blocks of code. Example: |
---|
316 | |
---|
317 | [pre |
---|
318 | \`\` |
---|
319 | #include <iostream> |
---|
320 | |
---|
321 | int main() |
---|
322 | { |
---|
323 | std::cout << "Hello, World!" << std::endl; |
---|
324 | return 0; |
---|
325 | } |
---|
326 | \`\` |
---|
327 | ] |
---|
328 | |
---|
329 | will generate: |
---|
330 | |
---|
331 | `` |
---|
332 | #include <iostream> |
---|
333 | |
---|
334 | int main() |
---|
335 | { |
---|
336 | std::cout << "Hello, World!" << std::endl; |
---|
337 | return 0; |
---|
338 | } |
---|
339 | `` |
---|
340 | |
---|
341 | [endsect] |
---|
342 | [section Source Mode] |
---|
343 | |
---|
344 | If a document contains more than one type of source code then the source |
---|
345 | mode may be changed dynamically as the document is processed. All QuickBook |
---|
346 | documents are initially in C++ mode by default, though an alternative |
---|
347 | initial value may be set in the __document__ section. |
---|
348 | |
---|
349 | To change the source mode, use the [^\[source-mode\]] markup, where |
---|
350 | =source-mode= is one of the supported modes. For example, this: |
---|
351 | |
---|
352 | [pre''' |
---|
353 | Python's [python] `import` is rather like C++'s [c++] `#include`. A |
---|
354 | C++ comment `// looks like this` whereas a Python comment [python] |
---|
355 | `# looks like this`. |
---|
356 | '''] |
---|
357 | |
---|
358 | will generate: |
---|
359 | |
---|
360 | Python's [python] `import` is rather like C++'s [c++] `#include`. A |
---|
361 | C++ comment `// looks like this` whereas a Python comment [python] |
---|
362 | `#looks like this`. |
---|
363 | |
---|
364 | [table Supported Source Modes |
---|
365 | [[Mode] [Source Mode Markup]] |
---|
366 | [[C++] [[^\[c++\]]]] |
---|
367 | [[Python] [[^\[python\]]]] |
---|
368 | ] |
---|
369 | |
---|
370 | [blurb __note__ The source mode strings are lowercase.] |
---|
371 | |
---|
372 | [endsect] |
---|
373 | [section line-break] |
---|
374 | |
---|
375 | [pre''' |
---|
376 | [br] |
---|
377 | '''] |
---|
378 | |
---|
379 | [blurb __note__ Note that `\n` is now preferred over `[br]`.] |
---|
380 | |
---|
381 | [endsect] |
---|
382 | [section Anchors] |
---|
383 | |
---|
384 | [pre''' |
---|
385 | [#named_anchor] |
---|
386 | '''] |
---|
387 | |
---|
388 | A named anchor is a hook that can be referenced by a link elsewhere in the |
---|
389 | document. You can then reference an anchor with [^'''[link named_anchor |
---|
390 | Some link text]''']. See __anchor_links__, __section__ and __heading__. |
---|
391 | |
---|
392 | [endsect] |
---|
393 | [section Links] |
---|
394 | |
---|
395 | [pre''' |
---|
396 | [@http://www.boost.org this is [*boost's] website....] |
---|
397 | '''] |
---|
398 | |
---|
399 | will generate: |
---|
400 | |
---|
401 | [@http://www.boost.org this is [*boost's] website....] |
---|
402 | |
---|
403 | URL links where the link text is the link itself is common. Example: |
---|
404 | |
---|
405 | [pre''' |
---|
406 | see http://spirit.sourceforge.net/ |
---|
407 | '''] |
---|
408 | |
---|
409 | so, when the text is absent in a link markup, the URL is assumed. Example: |
---|
410 | |
---|
411 | [pre |
---|
412 | see '''[@http://spirit.sourceforge.net/]''' |
---|
413 | ] |
---|
414 | |
---|
415 | will generate: |
---|
416 | |
---|
417 | see [@http://spirit.sourceforge.net/] |
---|
418 | |
---|
419 | [endsect] |
---|
420 | [section Anchor links] |
---|
421 | |
---|
422 | You can link within a document using: |
---|
423 | |
---|
424 | [pre''' |
---|
425 | [link section_id.normalized_header_text The link text] |
---|
426 | '''] |
---|
427 | |
---|
428 | See sections __section__ and __heading__ for more info. |
---|
429 | |
---|
430 | [endsect] |
---|
431 | [section refentry links] |
---|
432 | |
---|
433 | In addition, you can link internally to an XML refentry like: |
---|
434 | |
---|
435 | [pre''' |
---|
436 | [link xml.refentry The link text] |
---|
437 | '''] |
---|
438 | |
---|
439 | This gets converted into [^<link linkend="xml.refentry">The link text</link>]. |
---|
440 | |
---|
441 | Like URLs, the link text is optional. If this is not present, the link text will |
---|
442 | automatically be the refentry. Example: |
---|
443 | |
---|
444 | [pre''' |
---|
445 | [link xml.refentry] |
---|
446 | '''] |
---|
447 | |
---|
448 | This gets converted into [^<link linkend="xml.refentry">xml.refentry</link>]. |
---|
449 | |
---|
450 | [endsect] |
---|
451 | [section:code_links Code Links] |
---|
452 | |
---|
453 | If you want to link to a function, class, member, enum or header in the reference |
---|
454 | section, you can use: |
---|
455 | |
---|
456 | [pre''' |
---|
457 | [funcref fully::qualified::function_name The link text] |
---|
458 | [classref fully::qualified::class_name The link text] |
---|
459 | [memberref fully::qualified::member_name The link text] |
---|
460 | [enumref fully::qualified::enum_name The link text] |
---|
461 | [headerref path/to/header.hpp The link text] |
---|
462 | '''] |
---|
463 | |
---|
464 | Again, the link text is optional. If this is not present, the link text will |
---|
465 | automatically be the function, class, member or enum. Example: |
---|
466 | |
---|
467 | [pre''' |
---|
468 | [classref boost::bar::baz] |
---|
469 | '''] |
---|
470 | |
---|
471 | would have "boost::bar::baz" as the link text. |
---|
472 | |
---|
473 | [endsect] |
---|
474 | [section Escape] |
---|
475 | |
---|
476 | The escape mark-up is used when we don't want to do any processing. |
---|
477 | |
---|
478 | [pre |
---|
479 | \'\'\' |
---|
480 | escape (no processing/formatting) |
---|
481 | \'\'\' |
---|
482 | ] |
---|
483 | |
---|
484 | Escaping allows us to pass XML markup to __boostbook__ or __docbook__. For example: |
---|
485 | |
---|
486 | [pre |
---|
487 | \'\'\' |
---|
488 | <emphasis role="bold">This is direct XML markup</emphasis> |
---|
489 | \'\'\' |
---|
490 | ] |
---|
491 | |
---|
492 | ''' |
---|
493 | <emphasis role="bold">This is direct XML markup</emphasis> |
---|
494 | ''' |
---|
495 | |
---|
496 | [blurb __alert__ Be careful when using the escape. The text must conform to |
---|
497 | __boostbook__/__docbook__ syntax.] |
---|
498 | |
---|
499 | [endsect] |
---|
500 | [section Single char escape] |
---|
501 | |
---|
502 | The backslash may be used to escape a single punctuation character. The |
---|
503 | punctuation immediately after the backslash is passed without any processing. |
---|
504 | This is useful when we need to escape QuickBook punctuations such as `[` and `]`. |
---|
505 | For example, how do you escape the triple quote? Simple: [^\\'\\'\\'] |
---|
506 | |
---|
507 | `\n` has a special meaning. It is used to generate line breaks. Note that `\n` |
---|
508 | is now preferred over `[br]`. |
---|
509 | |
---|
510 | [endsect] |
---|
511 | [section Images] |
---|
512 | |
---|
513 | [pre''' |
---|
514 | [$image.jpg] |
---|
515 | '''] |
---|
516 | |
---|
517 | [endsect] |
---|
518 | [section Footnotes] |
---|
519 | |
---|
520 | As of version 1.3, QuickBook supports footnotes. Just put the text of the |
---|
521 | footnote in a `[footnote]` block, and the text will be put at the bottom |
---|
522 | of the current page. For example, this: |
---|
523 | |
---|
524 | [pre''' |
---|
525 | [footnote A sample footnote] |
---|
526 | '''] |
---|
527 | |
---|
528 | will generate this[footnote A sample footnote]. |
---|
529 | |
---|
530 | [endsect] |
---|
531 | [endsect] |
---|
532 | [section:block Block Level Elements] |
---|
533 | |
---|
534 | [section Document] |
---|
535 | |
---|
536 | Every document must begin with a Document Info section, which should look |
---|
537 | like this: |
---|
538 | |
---|
539 | [pre''' |
---|
540 | [document-type The Document Title |
---|
541 | [quickbook 1.3] |
---|
542 | [version 1.0] |
---|
543 | [id the_document_name] |
---|
544 | [dirname the_document_dir] |
---|
545 | [copyright 2000 2002 2003 Joe Blow, Jane Doe] |
---|
546 | [purpose The document's reason for being] |
---|
547 | [category The document's category] |
---|
548 | [authors [Blow, Joe], [Doe, Jane]] |
---|
549 | [license The document's license] |
---|
550 | [source-mode source-type] |
---|
551 | ] |
---|
552 | '''] |
---|
553 | |
---|
554 | Where document-type is one of: |
---|
555 | |
---|
556 | * book |
---|
557 | * article |
---|
558 | * library |
---|
559 | * chapter |
---|
560 | * part |
---|
561 | * appendix |
---|
562 | * preface |
---|
563 | * qandadiv |
---|
564 | * qandaset |
---|
565 | * reference |
---|
566 | * set |
---|
567 | |
---|
568 | quickbook 1.3 declares the version of quickbook the document is written for. |
---|
569 | In its absence, version 1.1 is assumed. |
---|
570 | |
---|
571 | =version=, =id=, =dirname=, =copyright=, =purpose=, =category=, =authors=, |
---|
572 | =license=, =last-revision= and =source-mode= are optional information. |
---|
573 | |
---|
574 | =source-type= is a lowercase string setting the initial __source_mode__. If |
---|
575 | the =source-mode= field is omitted, a default value of =c++= will be used. |
---|
576 | |
---|
577 | [endsect] |
---|
578 | [section Section] |
---|
579 | |
---|
580 | Starting a new section is accomplished with: |
---|
581 | |
---|
582 | [pre''' |
---|
583 | [section:id The Section Title] |
---|
584 | '''] |
---|
585 | |
---|
586 | where /id/ is optional. id will be the filename of the generated section. |
---|
587 | If it is not present, "The Section Title" will be normalized and become the id. |
---|
588 | Valid characters are =a-Z=, =A-Z=, =0-9= and =_=. All non-valid characters are |
---|
589 | converted to underscore and all upper-case are converted to lower case. |
---|
590 | Thus: "The Section Title" will be normalized to "the_section_title". |
---|
591 | |
---|
592 | End a section with: |
---|
593 | |
---|
594 | [pre''' |
---|
595 | [endsect] |
---|
596 | '''] |
---|
597 | |
---|
598 | Sections can nest, and that results in a hierarchy in the table of contents. |
---|
599 | |
---|
600 | [endsect] |
---|
601 | [section xinclude] |
---|
602 | |
---|
603 | You can include another XML file with: |
---|
604 | |
---|
605 | [pre''' |
---|
606 | [xinclude file.xml] |
---|
607 | '''] |
---|
608 | |
---|
609 | This is useful when file.xml has been generated by Doxygen and contains your |
---|
610 | reference section. |
---|
611 | |
---|
612 | [endsect] |
---|
613 | [section Paragraphs] |
---|
614 | |
---|
615 | Paragraphs start left-flushed and are terminated by two or more newlines. No |
---|
616 | markup is needed for paragraphs. QuickBook automatically detects paragraphs from |
---|
617 | the context. Block markups \[section, endsect, h1, h2, h3, h4, h5, h6, blurb, |
---|
618 | (block-quote) ':', pre, def, table and include \] may also terminate a paragraph. |
---|
619 | |
---|
620 | [endsect] |
---|
621 | |
---|
622 | [section Lists] |
---|
623 | [section Ordered lists] |
---|
624 | |
---|
625 | [pre |
---|
626 | # One |
---|
627 | # Two |
---|
628 | # Three |
---|
629 | ] |
---|
630 | |
---|
631 | will generate: |
---|
632 | |
---|
633 | # One |
---|
634 | # Two |
---|
635 | # Three |
---|
636 | |
---|
637 | [endsect] |
---|
638 | [section List Hierarchies] |
---|
639 | |
---|
640 | List hierarchies are supported. Example: |
---|
641 | |
---|
642 | [pre |
---|
643 | # One |
---|
644 | # Two |
---|
645 | # Three |
---|
646 | # Three.a |
---|
647 | # Three.b |
---|
648 | # Three.c |
---|
649 | # Four |
---|
650 | # Four.a |
---|
651 | # Four.a.i |
---|
652 | # Four.a.ii |
---|
653 | # Five |
---|
654 | ] |
---|
655 | |
---|
656 | will generate: |
---|
657 | |
---|
658 | # One |
---|
659 | # Two |
---|
660 | # Three |
---|
661 | # Three.a |
---|
662 | # Three.b |
---|
663 | # Three.c |
---|
664 | # Fourth |
---|
665 | # Four.a |
---|
666 | # Four.a.i |
---|
667 | # Four.a.ii |
---|
668 | # Five |
---|
669 | |
---|
670 | [endsect] |
---|
671 | [section Long List Lines] |
---|
672 | |
---|
673 | Long lines will be wrapped appropriately. Example: |
---|
674 | |
---|
675 | [pre |
---|
676 | # A short item. |
---|
677 | # A very long item. A very long item. A very long item. |
---|
678 | A very long item. A very long item. A very long item. |
---|
679 | A very long item. A very long item. A very long item. |
---|
680 | A very long item. A very long item. A very long item. |
---|
681 | A very long item. A very long item. A very long item. |
---|
682 | # A short item. |
---|
683 | ] |
---|
684 | |
---|
685 | # A short item. |
---|
686 | # A very long item. A very long item. A very long item. |
---|
687 | A very long item. A very long item. A very long item. |
---|
688 | A very long item. A very long item. A very long item. |
---|
689 | A very long item. A very long item. A very long item. |
---|
690 | A very long item. A very long item. A very long item. |
---|
691 | # A short item. |
---|
692 | |
---|
693 | [endsect] |
---|
694 | [section Unordered lists] |
---|
695 | |
---|
696 | [pre''' |
---|
697 | * First |
---|
698 | * Second |
---|
699 | * Third |
---|
700 | '''] |
---|
701 | |
---|
702 | will generate: |
---|
703 | |
---|
704 | * First |
---|
705 | * Second |
---|
706 | * Third |
---|
707 | |
---|
708 | [endsect] |
---|
709 | [section Mixed lists] |
---|
710 | |
---|
711 | Mixed lists (ordered and unordered) are supported. Example: |
---|
712 | |
---|
713 | [pre''' |
---|
714 | # One |
---|
715 | # Two |
---|
716 | # Three |
---|
717 | * Three.a |
---|
718 | * Three.b |
---|
719 | * Three.c |
---|
720 | # Four |
---|
721 | '''] |
---|
722 | |
---|
723 | will generate: |
---|
724 | |
---|
725 | # One |
---|
726 | # Two |
---|
727 | # Three |
---|
728 | * Three.a |
---|
729 | * Three.b |
---|
730 | * Three.c |
---|
731 | # Four |
---|
732 | |
---|
733 | And... |
---|
734 | |
---|
735 | [pre''' |
---|
736 | # 1 |
---|
737 | * 1.a |
---|
738 | # 1.a.1 |
---|
739 | # 1.a.2 |
---|
740 | * 1.b |
---|
741 | # 2 |
---|
742 | * 2.a |
---|
743 | * 2.b |
---|
744 | # 2.b.1 |
---|
745 | # 2.b.2 |
---|
746 | * 2.b.2.a |
---|
747 | * 2.b.2.b |
---|
748 | '''] |
---|
749 | |
---|
750 | will generate: |
---|
751 | |
---|
752 | # 1 |
---|
753 | * 1.a |
---|
754 | # 1.a.1 |
---|
755 | # 1.a.2 |
---|
756 | * 1.b |
---|
757 | # 2 |
---|
758 | * 2.a |
---|
759 | * 2.b |
---|
760 | # 2.b.1 |
---|
761 | # 2.b.2 |
---|
762 | * 2.b.2.a |
---|
763 | * 2.b.2.b |
---|
764 | |
---|
765 | [endsect] |
---|
766 | [endsect] |
---|
767 | |
---|
768 | [section Code] |
---|
769 | |
---|
770 | Preformatted code starts with a space or a tab. The code will be |
---|
771 | syntax highlighted according to the current __source_mode__: |
---|
772 | |
---|
773 | [c++] |
---|
774 | |
---|
775 | #include <iostream> |
---|
776 | |
---|
777 | int main() |
---|
778 | { |
---|
779 | // Sample code |
---|
780 | std::cout << "Hello, World\n"; |
---|
781 | return 0; |
---|
782 | } |
---|
783 | |
---|
784 | [python] |
---|
785 | |
---|
786 | import cgi |
---|
787 | |
---|
788 | def cookForHtml(text): |
---|
789 | '''"Cooks" the input text for HTML.''' |
---|
790 | |
---|
791 | return cgi.escape(text) |
---|
792 | |
---|
793 | Macros that are already defined are expanded in source code. Example: |
---|
794 | |
---|
795 | [pre''' |
---|
796 | [def __array__ [@http://www.boost.org/doc/html/array/reference.html array]] |
---|
797 | [def __boost__ [@http://www.boost.org/libs/libraries.htm boost]] |
---|
798 | |
---|
799 | using __boost__::__array__; |
---|
800 | '''] |
---|
801 | |
---|
802 | Generates: |
---|
803 | |
---|
804 | [def __array__ [@http://www.boost.org/doc/html/array/reference.html array]] |
---|
805 | [def __boost__ [@http://www.boost.org/libs/libraries.htm boost]] |
---|
806 | |
---|
807 | using __boost__::__array__; |
---|
808 | |
---|
809 | [endsect] |
---|
810 | [section:escape_back Escaping Back To QuickBook] |
---|
811 | |
---|
812 | Inside code, code blocks and inline code, QuickBook does not allow any |
---|
813 | markup to avoid conflicts with the target syntax (e.g. c++). In case you |
---|
814 | need to switch back to QuickBook markup inside code, you can do so using a |
---|
815 | language specific /escape-back/ delimiter. In C++ and Python, the delimiter |
---|
816 | is the double tick (back-quote): "\`\`" and "\`\`". Example: |
---|
817 | |
---|
818 | [pre''' |
---|
819 | void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``() |
---|
820 | { |
---|
821 | } |
---|
822 | '''] |
---|
823 | |
---|
824 | Will generate: |
---|
825 | |
---|
826 | void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``() |
---|
827 | { |
---|
828 | } |
---|
829 | |
---|
830 | When escaping from code to QuickBook, only phrase level markups are |
---|
831 | allowed. Block level markups like lists, tables etc. are not allowed. |
---|
832 | |
---|
833 | [endsect] |
---|
834 | [section Preformatted] |
---|
835 | |
---|
836 | Sometimes, you don't want some preformatted text to be parsed as C++. In such |
---|
837 | cases, use the [^[pre ... \]] markup block. |
---|
838 | |
---|
839 | [pre''' |
---|
840 | [pre |
---|
841 | |
---|
842 | Some *preformatted* text Some *preformatted* text |
---|
843 | |
---|
844 | Some *preformatted* text Some *preformatted* text |
---|
845 | |
---|
846 | Some *preformatted* text Some *preformatted* text |
---|
847 | |
---|
848 | ] |
---|
849 | '''] |
---|
850 | |
---|
851 | Spaces, tabs and newlines are rendered as-is. Unlike all quickbook block level |
---|
852 | markup, pre (and Code) are the only ones that allow multiple newlines. The |
---|
853 | markup above will generate: |
---|
854 | |
---|
855 | [pre |
---|
856 | |
---|
857 | Some *preformatted* text Some *preformatted* text |
---|
858 | |
---|
859 | Some *preformatted* text Some *preformatted* text |
---|
860 | |
---|
861 | Some *preformatted* text Some *preformatted* text |
---|
862 | |
---|
863 | ] |
---|
864 | |
---|
865 | Notice that unlike Code, phrase markup such as font style is still permitted |
---|
866 | inside =pre= blocks. |
---|
867 | |
---|
868 | [endsect] |
---|
869 | [section Blockquote] |
---|
870 | |
---|
871 | [pre |
---|
872 | '''[:sometext...]''' |
---|
873 | ] |
---|
874 | |
---|
875 | [:Indents the paragraph. This applies to one paragraph only.] |
---|
876 | |
---|
877 | [endsect] |
---|
878 | [section Admonitions] |
---|
879 | |
---|
880 | [pre''' |
---|
881 | [note This is a note] |
---|
882 | [tip This is a tip] |
---|
883 | [important This is important] |
---|
884 | [caution This is a caution] |
---|
885 | [warning This is a warning] |
---|
886 | '''] |
---|
887 | |
---|
888 | generates __docbook__ admonitions: |
---|
889 | |
---|
890 | [note This is a note] |
---|
891 | [tip This is a tip] |
---|
892 | [important This is important] |
---|
893 | [caution This is a caution] |
---|
894 | [warning This is a warning] |
---|
895 | |
---|
896 | These are the only admonitions supported by __docbook__. So, |
---|
897 | for example [^\[information This is some information\]] is unlikely |
---|
898 | to produce the desired effect. |
---|
899 | |
---|
900 | [endsect] |
---|
901 | [section Headings] |
---|
902 | |
---|
903 | [pre''' |
---|
904 | [h1 Heading 1] |
---|
905 | [h2 Heading 2] |
---|
906 | [h3 Heading 3] |
---|
907 | [h4 Heading 4] |
---|
908 | [h5 Heading 5] |
---|
909 | [h6 Heading 6] |
---|
910 | '''] |
---|
911 | |
---|
912 | [h1 Heading 1] |
---|
913 | [h2 Heading 2] |
---|
914 | [h3 Heading 3] |
---|
915 | [h4 Heading 4] |
---|
916 | [h5 Heading 5] |
---|
917 | [h6 Heading 6] |
---|
918 | |
---|
919 | Headings 1-3 \[h1 h2 and h3\] will automatically have anchors with normalized |
---|
920 | names with [^name="section_id.normalized_header_text"] (i.e. valid characters are |
---|
921 | =a-z=, =A-Z=, =0-9= and =_=. All non-valid characters are converted to underscore |
---|
922 | and all upper-case are converted to lower-case. For example: Heading |
---|
923 | 1 in section Section 2 will be normalized to [^section_2.heading_1]). You can use: |
---|
924 | |
---|
925 | [pre''' |
---|
926 | [link section_id.normalized_header_text The link text] |
---|
927 | '''] |
---|
928 | |
---|
929 | to link to them. See __anchor_links__ and __section__ for more info. |
---|
930 | |
---|
931 | [endsect] |
---|
932 | [section Macros] |
---|
933 | |
---|
934 | [pre''' |
---|
935 | [def macro_identifier some text] |
---|
936 | '''] |
---|
937 | |
---|
938 | When a macro is defined, the identifier replaces the text anywhere in the file, |
---|
939 | in paragraphs, in markups, etc. macro_identifier is a string of non-white space |
---|
940 | characters except '\]' while the replacement text can be any phrase (even |
---|
941 | marked up). Example: |
---|
942 | |
---|
943 | [pre''' |
---|
944 | [def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&type=1]] |
---|
945 | sf_logo |
---|
946 | '''] |
---|
947 | |
---|
948 | Now everywhere the sf_logo is placed, the picture will be inlined. |
---|
949 | |
---|
950 | [def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&type=1]] |
---|
951 | sf_logo |
---|
952 | |
---|
953 | [blurb __tip__ It's a good idea to use macro identifiers that are distinguishable. |
---|
954 | For instance, in this document, macro identifiers have two leading and trailing |
---|
955 | underscores (e.g. [^'''__spirit__''']). The reason is to avoid unwanted macro replacement.] |
---|
956 | |
---|
957 | Links (URLS) and images are good candidates for macros. *1*) They tend to |
---|
958 | change a lot. It is a good idea to place all links and images in one place near the top |
---|
959 | to make it easy to make changes. *2*) The syntax is not pretty. It's easier to read and |
---|
960 | write, e.g. [^'''__spirit__'''] than [^'''[@http://spirit.sourceforge.net Spirit]''']. |
---|
961 | |
---|
962 | Some more examples: |
---|
963 | |
---|
964 | [pre''' |
---|
965 | [def :-) [$theme/smiley.png]] |
---|
966 | [def __spirit__ [@http://spirit.sourceforge.net Spirit]] |
---|
967 | '''] |
---|
968 | |
---|
969 | (See __images__ and __links__) |
---|
970 | |
---|
971 | Invoking these macros: |
---|
972 | |
---|
973 | [pre''' |
---|
974 | Hi __spirit__ :-) |
---|
975 | '''] |
---|
976 | |
---|
977 | will generate this: |
---|
978 | |
---|
979 | Hi __spirit__ :-) |
---|
980 | |
---|
981 | [endsect] |
---|
982 | [section Predefined Macros] |
---|
983 | |
---|
984 | Quickbook has some predefined macros that you can already use. |
---|
985 | |
---|
986 | [table Predefined Macros |
---|
987 | [[Macro] [Meaning] [Example]] |
---|
988 | [['''__DATE__'''] [Today's date] [__DATE__]] |
---|
989 | [['''__TIME__'''] [The current time] [__TIME__]] |
---|
990 | [['''__FILENAME__'''] [Quickbook source filename] [__FILENAME__]] |
---|
991 | ] |
---|
992 | |
---|
993 | [endsect] |
---|
994 | [section Blurbs] |
---|
995 | |
---|
996 | [pre''' |
---|
997 | [blurb :-) [*An eye catching advertisement or note...]\n\n |
---|
998 | __spirit__ is an object-oriented recursive-descent parser generator framework |
---|
999 | implemented using template meta-programming techniques. Expression templates |
---|
1000 | allow us to approximate the syntax of Extended Backus-Normal Form (EBNF) |
---|
1001 | completely in C++. |
---|
1002 | ] |
---|
1003 | '''] |
---|
1004 | |
---|
1005 | will generate this: |
---|
1006 | |
---|
1007 | [blurb :-) [*An eye catching advertisement or note...]\n\n |
---|
1008 | __spirit__ is an object-oriented recursive-descent parser generator |
---|
1009 | framework implemented using template meta-programming techniques. Expression |
---|
1010 | templates allow us to approximate the syntax of Extended Backus-Normal Form |
---|
1011 | (EBNF) completely in C++. |
---|
1012 | ] |
---|
1013 | |
---|
1014 | [endsect] |
---|
1015 | [section Tables] |
---|
1016 | |
---|
1017 | [pre''' |
---|
1018 | [table A Simple Table |
---|
1019 | [[Heading 1] [Heading 2] [Heading 3]] |
---|
1020 | [[R0-C0] [R0-C1] [R0-C2]] |
---|
1021 | [[R1-C0] [R1-C1] [R1-C2]] |
---|
1022 | [[R2-C0] [R2-C1] [R2-C2]] |
---|
1023 | ] |
---|
1024 | '''] |
---|
1025 | |
---|
1026 | will generate: |
---|
1027 | |
---|
1028 | [table A Simple Table |
---|
1029 | [[Heading 1] [Heading 2] [Heading 3]] |
---|
1030 | [[R0-C0] [R0-C1] [R0-C2]] |
---|
1031 | [[R2-C0] [R2-C1] [R2-C2]] |
---|
1032 | [[R3-C0] [R3-C1] [R3-C2]] |
---|
1033 | ] |
---|
1034 | |
---|
1035 | The table title is optional. The first row of the table is automatically |
---|
1036 | treated as the table header; that is, it is wrapped in |
---|
1037 | [^<thead>...</thead>] XML tags. Note that unlike the original QuickDoc, the |
---|
1038 | columns are nested in [ cells... ]. The syntax is free-format and allows |
---|
1039 | big cells to be formatted nicely. Example: |
---|
1040 | |
---|
1041 | [pre''' |
---|
1042 | [table Table with fat cells |
---|
1043 | [[Heading 1] [Heading 2]] |
---|
1044 | [ |
---|
1045 | [Row 0, Col 0: a small cell] |
---|
1046 | [ |
---|
1047 | Row 0, Col 1: |
---|
1048 | A very big cell...A very big cell...A very big cell... |
---|
1049 | A very big cell...A very big cell...A very big cell... |
---|
1050 | A very big cell...A very big cell...A very big cell... |
---|
1051 | ] |
---|
1052 | ] |
---|
1053 | [ |
---|
1054 | [Row 1, Col 0: a small cell] |
---|
1055 | [Row 1, Col 1: a small cell] |
---|
1056 | ] |
---|
1057 | ] |
---|
1058 | '''] |
---|
1059 | |
---|
1060 | and thus: |
---|
1061 | |
---|
1062 | [table Table with fat cells |
---|
1063 | [[Heading 1] [Heading 2]] |
---|
1064 | [ |
---|
1065 | [Row 0, Col 0: a small cell] |
---|
1066 | [ |
---|
1067 | Row 0, Col 1: |
---|
1068 | A very big cell...A very big cell...A very big cell... |
---|
1069 | A very big cell...A very big cell...A very big cell... |
---|
1070 | A very big cell...A very big cell...A very big cell... |
---|
1071 | ] |
---|
1072 | ] |
---|
1073 | [ |
---|
1074 | [Row 1, Col 0: a small cell] |
---|
1075 | [Row 1, Col 1: a small cell] |
---|
1076 | ] |
---|
1077 | ] |
---|
1078 | |
---|
1079 | Here's how to have preformatted blocks of code in a table cell: |
---|
1080 | |
---|
1081 | [pre''' |
---|
1082 | [table Table with code |
---|
1083 | [[Comment] [Code]] |
---|
1084 | [ |
---|
1085 | [My first program] |
---|
1086 | ['''\`\` |
---|
1087 | #include <iostream> |
---|
1088 | |
---|
1089 | int main() |
---|
1090 | { |
---|
1091 | std::cout << "Hello, World!" << std::endl; |
---|
1092 | return 0; |
---|
1093 | } |
---|
1094 | \`\`'''] |
---|
1095 | ] |
---|
1096 | ] |
---|
1097 | '''] |
---|
1098 | |
---|
1099 | [table Table with code |
---|
1100 | [[Comment] [Code]] |
---|
1101 | [ |
---|
1102 | [My first program] |
---|
1103 | [`` |
---|
1104 | #include <iostream> |
---|
1105 | |
---|
1106 | int main() |
---|
1107 | { |
---|
1108 | std::cout << "Hello, World!" << std::endl; |
---|
1109 | return 0; |
---|
1110 | } |
---|
1111 | ``] |
---|
1112 | ] |
---|
1113 | ] |
---|
1114 | |
---|
1115 | [endsect] |
---|
1116 | [section Variable Lists] |
---|
1117 | |
---|
1118 | [pre''' |
---|
1119 | [variablelist A Variable List |
---|
1120 | [[term 1] [The definition of term 1]] |
---|
1121 | [[term 2] [The definition of term 2]] |
---|
1122 | [[term 3] [The definition of term 3]] |
---|
1123 | ] |
---|
1124 | '''] |
---|
1125 | |
---|
1126 | will generate: |
---|
1127 | |
---|
1128 | [variablelist A Variable List |
---|
1129 | [[term 1] [The definition of term 1]] |
---|
1130 | [[term 2] [The definition of term 2]] |
---|
1131 | [[term 3] [The definition of term 3]] |
---|
1132 | ] |
---|
1133 | |
---|
1134 | The rules for variable lists are the same as for tables, except that |
---|
1135 | only 2 "columns" are allowed. The first column contains the terms, and |
---|
1136 | the second column contains the definitions. Those familiar with HTML |
---|
1137 | will recognize this as a "definition list". |
---|
1138 | |
---|
1139 | [endsect] |
---|
1140 | [section Include] |
---|
1141 | |
---|
1142 | You can include one QuickBook file from another. The syntax is simply: |
---|
1143 | |
---|
1144 | [pre''' |
---|
1145 | [include someother.qbk] |
---|
1146 | '''] |
---|
1147 | |
---|
1148 | The included file will be processed as if it had be cut and pasted |
---|
1149 | into the current document, with the following exceptions: |
---|
1150 | |
---|
1151 | * The '''__FILENAME__''' predefined macro will reflect the name of the |
---|
1152 | file currently being processed. |
---|
1153 | * Any macros defined in the included file are scoped to that file. |
---|
1154 | |
---|
1155 | As the number of included QuickBook files grows, so too does the |
---|
1156 | likelihood of two sections having the same name. Since QuickBook generates |
---|
1157 | an anchor for each section based on the section name, it is possible to |
---|
1158 | end up with two identically named anchors, leading to link ambiguities. |
---|
1159 | To resolve these ambiguities, the [^\[include\]] directive lets you |
---|
1160 | specify a document id to use for the included file. You can use it like |
---|
1161 | this: |
---|
1162 | |
---|
1163 | [pre''' |
---|
1164 | [include:someid someother.qbk] |
---|
1165 | '''] |
---|
1166 | |
---|
1167 | When using this form, all auto-generated anchors will use "someid" as |
---|
1168 | a unique prefix. So for instance, if there is a section in someother.qbk |
---|
1169 | named "Intro", the named anchor for that section will be "someid.intro", |
---|
1170 | and you can link to it with [^\[link someid.intro The Intro\]]. |
---|
1171 | |
---|
1172 | [endsect] |
---|
1173 | [endsect] |
---|
1174 | [endsect] |
---|
1175 | [section:ref Quick Reference] |
---|
1176 | |
---|
1177 | [table Syntax Compendium |
---|
1178 | [[To do this...] [Use this...] [See this...]] |
---|
1179 | [[comment] [[^'''[/ some comment]''']] [__comments__]] |
---|
1180 | [[['italics]] [[^'''['italics] or /italics/''']] [__font_styles__ and __simple_formatting__]] |
---|
1181 | [[[*bold]] [[^'''[*bold] or *bold*''']] [__font_styles__ and __simple_formatting__]] |
---|
1182 | [[[_underline]] [[^'''[_underline] or _underline_''']] [__font_styles__ and __simple_formatting__]] |
---|
1183 | [[[^teletype]] [[^'''[^teletype] or =teletype=''']] [__font_styles__ and __simple_formatting__]] |
---|
1184 | [[[-strikethrough]] [[^'''[-strikethrough]''']] [__font_styles__ and __simple_formatting__]] |
---|
1185 | [[[~replaceable]] [[^'''[~replaceable]''']] [__replaceable__]] |
---|
1186 | [[source mode] [[^\[c++\]] or [^\[python\]]] [__source_mode__]] |
---|
1187 | [[inline code] [[^'''`int main();`''']] [__inline_code__]] |
---|
1188 | [[code block] [[^'''``int main();``''']] [__code__]] |
---|
1189 | [[code escape] [[^'''``from c++ to QuickBook``''']] [__escape_back__]] |
---|
1190 | [[line break] [[^'''[br] or \n''']] [__line_break__]] |
---|
1191 | [[anchor] [[^'''[#anchor]''']] [__anchors__]] |
---|
1192 | [[link] [[^'''[@http://www.boost.org Boost]''']] [__links__]] |
---|
1193 | [[anchor link] [[^'''[link section.anchor Link text]''']] [__anchor_links__]] |
---|
1194 | [[refentry link] [[^'''[link xml.refentry Link text]''']] [__refentry_links__]] |
---|
1195 | [[function link] [[^'''[funcref fully::qualified::function_name Link text]''']] [__code_links__]] |
---|
1196 | [[class link] [[^'''[classref fully::qualified::class_name Link text]''']] [__code_links__]] |
---|
1197 | [[member link] [[^'''[memberref fully::qualified::member_name Link text]''']] [__code_links__]] |
---|
1198 | [[enum link] [[^'''[enumref fully::qualified::enum_name Link text]''']] [__code_links__]] |
---|
1199 | [[header link] [[^'''[headerref path/to/header.hpp Link text]''']] [__code_links__]] |
---|
1200 | [[escape] [[^\'\'\'escaped text (no processing/formatting)\'\'\']] [__escape__]] |
---|
1201 | [[single char escape] [[^\\c]] [__single_char_escape__]] |
---|
1202 | [[images] [[^'''[$image.jpg]''']] [__images__]] |
---|
1203 | [[begin section] [[^'''[section The Section Title]''']] [__section__]] |
---|
1204 | [[end section] [[^'''[endsect]''']] [__section__]] |
---|
1205 | [[paragraph] [No markup. Paragraphs start left-flushed and are terminated by two or more newlines.] [__paragraphs__]] |
---|
1206 | [[ordered list] [[^# one\n# two\n# three\n]] [__ordered_lists__]] |
---|
1207 | [[unordered list] [[^\* one\n\* two\n\* three\n]] [__unordered_lists__]] |
---|
1208 | [[code] [No markup. Preformatted code starts with a space or a tab.] [__code__]] |
---|
1209 | [[preformatted] [[^'''[pre preformatted]''']] [__preformatted__]] |
---|
1210 | [[block quote] [[^'''[:sometext...]''']] [__blockquote__]] |
---|
1211 | [[heading 1] [[^'''[h1 Heading 1]''']] [__heading__]] |
---|
1212 | [[heading 2] [[^'''[h2 Heading 2]''']] [__heading__]] |
---|
1213 | [[heading 3] [[^'''[h3 Heading 3]''']] [__heading__]] |
---|
1214 | [[heading 4] [[^'''[h4 Heading 4]''']] [__heading__]] |
---|
1215 | [[heading 5] [[^'''[h5 Heading 5]''']] [__heading__]] |
---|
1216 | [[heading 6] [[^'''[h6 Heading 6]''']] [__heading__]] |
---|
1217 | [[macro] [[^'''[def macro_identifier some text]''']] [__macros__]] |
---|
1218 | [[blurb] [[^'''[blurb advertisement or note...]''']] [__blurbs__]] |
---|
1219 | [[admonition] [[^'''[warning Warning text...]''']] [__admonitions__]] |
---|
1220 | [[table] [[^[table Title\n \[\[a\]\[b\]\[c\]\]\n \[\[a\]\[b\]\[c\]\]\n\]]] [__tables__]] |
---|
1221 | [[variablelist] [[^[variablelist Title\n \[\[a\]\[b\]\]\n \[\[a\]\[b\]\]\n\]]] [__variable_lists__]] |
---|
1222 | [[include] [[^'''[include someother.qbk]''']] [__include__]] |
---|
1223 | ] |
---|
1224 | |
---|
1225 | [endsect] |
---|