]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | [/ |
2 | Copyright 2002,2004,2006 Joel de Guzman, Eric Niebler | |
3 | Copyright 2010-2011 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 Block Level Elements | |
11 | [quickbook 1.6] | |
12 | [compatibility-mode 1.5] | |
13 | [id quickbook.syntax.block] | |
14 | [source-mode teletype] | |
15 | ] | |
16 | ||
17 | [#quickbook.ref.xinclude] | |
18 | [section:xinclude xinclude] | |
19 | ||
20 | You can include another XML file with: | |
21 | ||
22 | ``` | |
23 | [xinclude file.xml] | |
24 | ``` | |
25 | ||
26 | This is useful when file.xml has been generated by Doxygen and contains your | |
27 | reference section. | |
28 | ||
29 | =xinclude= paths are normally used unchanged in the generated documentation, | |
30 | which will not work if you wish them to be relative to the current quickbook | |
31 | file. Quickbook can add a =xml:base= attribute to the boostbook documentation | |
32 | to specify where =xinclude= files should be found. For example, if you wish | |
33 | them to be relative to the current quickbook file: | |
34 | ||
35 | [article Article with xincludes | |
36 | [quickbook 1.6] | |
37 | [xmlbase .] | |
38 | ] | |
39 | ||
40 | [xinclude file.xml] | |
41 | ||
42 | Now the xinclude should work if =file.xml= is in the same directory as the | |
43 | quickbook file. Although it might not work if you distribute the generated | |
44 | files (as their relative directories can change). | |
45 | ||
46 | Say the article is generated in a sub-directory, by running something like: | |
47 | ||
48 | quickbook article.qbk --output-file=output/article.xml | |
49 | ||
50 | This will generate a boostbook root tag: | |
51 | ||
52 | <article id="article_with_xincludes" | |
53 | last-revision="$Date: 2013/08/20 08:26:48 $" | |
54 | xml:base=".." | |
55 | xmlns:xi="http://www.w3.org/2001/XInclude"> | |
56 | ||
57 | Because =xml:base= is set to =..=, the xml processor will know to look in | |
58 | the parent directory to find =file.xml=, which it comes across the | |
59 | =xi:include= tag. | |
60 | ||
61 | [endsect] [/xinclude] | |
62 | ||
63 | [#quickbook.ref.paragraphs] | |
64 | [section:paragraphs Paragraphs] | |
65 | ||
66 | Paragraphs start left-flushed and are terminated by two or more newlines. No | |
67 | markup is needed for paragraphs. QuickBook automatically detects paragraphs from | |
68 | the context. Block markups \[section, endsect, h1, h2, h3, h4, h5, h6, blurb, | |
69 | (block-quote) ':', pre, def, table and include \] may also terminate a paragraph. | |
70 | [/ <-- There's a space here. Don't remove. this is intentianal, for testing] | |
71 | This is a new paragraph... | |
72 | ||
73 | [endsect] [/paragraphs] | |
74 | ||
75 | [#quickbook.ref.lists] | |
76 | [section:lists Lists] | |
77 | [#quickbook.ref.ordered_lists] | |
78 | [section:ordered_lists Ordered lists] | |
79 | ||
80 | [pre | |
81 | # One | |
82 | # Two | |
83 | # Three | |
84 | ] | |
85 | ||
86 | will generate: | |
87 | ||
88 | # One | |
89 | # Two | |
90 | # Three | |
91 | ||
92 | [endsect] [/ordered_lists] | |
93 | [#quickbook.ref.list_hierarchies] | |
94 | [section:list_hierarchies List Hierarchies] | |
95 | ||
96 | List hierarchies are supported. Example: | |
97 | ||
98 | [pre | |
99 | # One | |
100 | # Two | |
101 | # Three | |
102 | # Three.a | |
103 | # Three.b | |
104 | # Three.c | |
105 | # Four | |
106 | # Four.a | |
107 | # Four.a.i | |
108 | # Four.a.ii | |
109 | # Five | |
110 | ] | |
111 | ||
112 | will generate: | |
113 | ||
114 | # One | |
115 | # Two | |
116 | # Three | |
117 | # Three.a | |
118 | # Three.b | |
119 | # Three.c | |
120 | # Fourth | |
121 | # Four.a | |
122 | # Four.a.i | |
123 | # Four.a.ii | |
124 | # Five | |
125 | ||
126 | [endsect] [/list_hierarchies] | |
127 | [#quickbook.ref.long_list_lines] | |
128 | [section:long_list_lines Long List Lines] | |
129 | ||
130 | Long lines will be wrapped appropriately. Example: | |
131 | ||
132 | [pre | |
133 | # A short item. | |
134 | # A very long item. A very long item. A very long item. | |
135 | A very long item. A very long item. A very long item. | |
136 | A very long item. A very long item. A very long item. | |
137 | A very long item. A very long item. A very long item. | |
138 | A very long item. A very long item. A very long item. | |
139 | # A short item. | |
140 | ] | |
141 | ||
142 | # A short item. | |
143 | # A very long item. A very long item. A very long item. | |
144 | A very long item. A very long item. A very long item. | |
145 | A very long item. A very long item. A very long item. | |
146 | A very long item. A very long item. A very long item. | |
147 | A very long item. A very long item. A very long item. | |
148 | # A short item. | |
149 | ||
150 | [endsect] [/long_list_lines] | |
151 | [#quickbook.ref.unordered_lists] | |
152 | [section:unordered_lists Unordered lists] | |
153 | ||
154 | ``` | |
155 | * First | |
156 | * Second | |
157 | * Third | |
158 | ``` | |
159 | ||
160 | will generate: | |
161 | ||
162 | * First | |
163 | * Second | |
164 | * Third | |
165 | ||
166 | [endsect] [/unordered_lists] | |
167 | [#quickbook.ref.mixed_lists] | |
168 | [section:mixed_lists Mixed lists] | |
169 | ||
170 | Mixed lists (ordered and unordered) are supported. Example: | |
171 | ||
172 | ``` | |
173 | # One | |
174 | # Two | |
175 | # Three | |
176 | * Three.a | |
177 | * Three.b | |
178 | * Three.c | |
179 | # Four | |
180 | ``` | |
181 | ||
182 | will generate: | |
183 | ||
184 | # One | |
185 | # Two | |
186 | # Three | |
187 | * Three.a | |
188 | * Three.b | |
189 | * Three.c | |
190 | # Four | |
191 | ||
192 | And... | |
193 | ||
194 | ``` | |
195 | # 1 | |
196 | * 1.a | |
197 | # 1.a.1 | |
198 | # 1.a.2 | |
199 | * 1.b | |
200 | # 2 | |
201 | * 2.a | |
202 | * 2.b | |
203 | # 2.b.1 | |
204 | # 2.b.2 | |
205 | * 2.b.2.a | |
206 | * 2.b.2.b | |
207 | ``` | |
208 | ||
209 | will generate: | |
210 | ||
211 | # 1 | |
212 | * 1.a | |
213 | # 1.a.1 | |
214 | # 1.a.2 | |
215 | * 1.b | |
216 | # 2 | |
217 | * 2.a | |
218 | * 2.b | |
219 | # 2.b.1 | |
220 | # 2.b.2 | |
221 | * 2.b.2.a | |
222 | * 2.b.2.b | |
223 | ||
224 | [endsect] [/mixed_lists] | |
225 | ||
226 | [#quickbook.ref.list_tags] | |
227 | [section:list_tags Explicit list tags] | |
228 | ||
229 | Sometimes the wiki-style list markup can be tricky to use, especially | |
230 | if you wish to include more complicated markup with the list. So in | |
231 | quickbook 1.6, an alternative way to mark up lists introduced: | |
232 | ||
233 | [ordered_list [item1][item2]] | |
234 | ||
235 | is equivalent to: | |
236 | ||
237 | # item1 | |
238 | # item2 | |
239 | ||
240 | And: | |
241 | ||
242 | [itemized_list [item1][item2]] | |
243 | ||
244 | is equivalent to: | |
245 | ||
246 | * item1 | |
247 | * item2 | |
248 | ||
249 | [endsect] [/list_tags] | |
250 | [endsect] [/lists] | |
251 | ||
252 | [#quickbook.ref.code] | |
253 | [section:code Code] | |
254 | ||
255 | Preformatted code starts with a space or a tab. The code will be | |
256 | syntax highlighted according to the current __source_mode__: | |
257 | ||
258 | [c++] | |
259 | ||
260 | #include <iostream> | |
261 | ||
262 | int main() | |
263 | { | |
264 | // Sample code | |
265 | std::cout << "Hello, World\n"; | |
266 | return 0; | |
267 | } | |
268 | ||
269 | [python] | |
270 | ||
271 | import cgi | |
272 | ||
273 | def cookForHtml(text): | |
274 | '''"Cooks" the input text for HTML.''' | |
275 | ||
276 | return cgi.escape(text) | |
277 | ||
278 | [teletype] | |
279 | ||
280 | Macros that are already defined are expanded in source code. Example: | |
281 | ||
282 | ``` | |
283 | [def __array__ [@http://www.boost.org/doc/html/array/reference.html array]] | |
284 | [def __boost__ [@http://www.boost.org/libs/libraries.htm boost]] | |
285 | ||
286 | using __boost__::__array__; | |
287 | ``` | |
288 | ||
289 | Generates: | |
290 | ||
291 | [def __array__ [@http://www.boost.org/doc/html/array/reference.html array]] | |
292 | [def __boost__ [@http://www.boost.org/libs/libraries.htm boost]] | |
293 | ||
294 | using __boost__::__array__; | |
295 | ||
296 | [endsect] [/code] | |
297 | ||
298 | [#quickbook.ref.escape_back] | |
299 | [section:escape_back Escaping Back To QuickBook] | |
300 | ||
301 | Inside code, code blocks and inline code, QuickBook does not allow any | |
302 | markup to avoid conflicts with the target syntax (e.g. c++). In case you | |
303 | need to switch back to QuickBook markup inside code, you can do so using a | |
304 | language specific /escape-back/ delimiter. In C++ and Python, the delimiter | |
305 | is the double tick (back-quote): "\`\`" and "\`\`". Example: | |
306 | ||
307 | ``` | |
308 | void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``() | |
309 | { | |
310 | } | |
311 | ``` | |
312 | ||
313 | Will generate: | |
314 | ||
315 | void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``() | |
316 | { | |
317 | } | |
318 | ||
319 | When escaping from code to QuickBook, only phrase level markups are | |
320 | allowed. Block level markups like lists, tables etc. are not allowed. | |
321 | ||
322 | [endsect] [/escaping_back_to_quickbook] | |
323 | ||
324 | [#quickbook.ref.preformatted] | |
325 | [section:preformatted Preformatted] | |
326 | ||
327 | Sometimes, you don't want some preformatted text to be parsed as source code. In such | |
328 | cases, use the [^\[pre ... \]] markup block. | |
329 | ||
330 | ``` | |
331 | [pre | |
332 | ||
333 | Some *preformatted* text Some *preformatted* text | |
334 | ||
335 | Some *preformatted* text Some *preformatted* text | |
336 | ||
337 | Some *preformatted* text Some *preformatted* text | |
338 | ||
339 | ] | |
340 | ``` | |
341 | ||
342 | Spaces, tabs and newlines are rendered as-is. Unlike all quickbook block level | |
343 | markup, pre (and Code) are the only ones that allow multiple newlines. The | |
344 | markup above will generate: | |
345 | ||
346 | [pre | |
347 | ||
348 | Some *preformatted* text Some *preformatted* text | |
349 | ||
350 | Some *preformatted* text Some *preformatted* text | |
351 | ||
352 | Some *preformatted* text Some *preformatted* text | |
353 | ||
354 | ] | |
355 | ||
356 | Notice that unlike Code, phrase markup such as font style is still permitted | |
357 | inside =pre= blocks. | |
358 | ||
359 | [endsect] [/preformatted] | |
360 | ||
361 | [#quickbook.ref.blockquote] | |
362 | [section:blockquote Blockquote] | |
363 | ||
364 | [pre | |
365 | '''[:sometext...]''' | |
366 | ] | |
367 | ||
368 | [:Indents the paragraph. This applies to one paragraph only.] | |
369 | ||
370 | [endsect] [/blockquote] | |
371 | ||
372 | [#quickbook.ref.admonitions] | |
373 | [section:admonitions Admonitions] | |
374 | ||
375 | ``` | |
376 | [note This is a note] | |
377 | [tip This is a tip] | |
378 | [important This is important] | |
379 | [caution This is a caution] | |
380 | [warning This is a warning] | |
381 | ``` | |
382 | ||
383 | generates __docbook__ admonitions: | |
384 | ||
385 | [note This is a note] | |
386 | [tip This is a tip] | |
387 | [important This is important] | |
388 | [caution This is a caution] | |
389 | [warning This is a warning] | |
390 | ||
391 | These are the only admonitions supported by __docbook__. So, | |
392 | for example [^\[information This is some information\]] is unlikely | |
393 | to produce the desired effect. | |
394 | ||
395 | [endsect] [/admonitions] | |
396 | ||
397 | [#quickbook.ref.headings] | |
398 | [section:headings Headings] | |
399 | ||
400 | ``` | |
401 | [h1 Heading 1] | |
402 | [h2 Heading 2] | |
403 | [h3 Heading 3] | |
404 | [h4 Heading 4] | |
405 | [h5 Heading 5] | |
406 | [h6 Heading 6] | |
407 | ``` | |
408 | ||
409 | [h1 Heading 1] | |
410 | [h2 Heading 2] | |
411 | [h3 Heading 3] | |
412 | [h4 Heading 4] | |
413 | [h5 Heading 5] | |
414 | [h6 Heading 6] | |
415 | ||
416 | You can specify an id for a heading: | |
417 | ||
418 | ``` | |
419 | [h1:heading_id A heading to link to] | |
420 | ``` | |
421 | ||
422 | To link to it, you'll need to include the enclosing section's id: | |
423 | ||
424 | ``` | |
425 | [link document_id.section_id.heading_id The link text] | |
426 | ``` | |
427 | ||
428 | Although you can preceed a heading by an [link quickbook.ref.anchors anchor] | |
429 | if you wish to use a location independent link. | |
430 | ||
431 | If a heading doesn't have an id, one will be automatically generated | |
432 | with a normalized name with | |
433 | [^name="document_id.section_id.normalized_header_text"] (i.e. valid | |
434 | characters are =a-z=, =A-Z=, =0-9= and =_=. All non-valid characters are | |
435 | converted to underscore and all upper-case are converted to lower-case. | |
436 | For example: Heading 1 in section Section 2 will be normalized to | |
437 | [^section_2.heading_1]). You can use: | |
438 | ||
439 | ``` | |
440 | [link document_id.section_id.normalized_header_text The link text] | |
441 | ``` | |
442 | ||
443 | to link to them. See __anchor_links__ and __section__ for more info. | |
444 | ||
445 | [note Specifying heading ids is a quickbook 1.6 feature, earlier | |
446 | versions don't support them.] | |
447 | ||
448 | [endsect] [/headings] | |
449 | ||
450 | [#quickbook.ref.generic_heading] | |
451 | [section:generic_heading Generic Heading] | |
452 | ||
453 | In cases when you don't want to care about the heading level (1 to 6), you | |
454 | can use the /Generic Heading/: | |
455 | ||
456 | ``` | |
457 | [heading Heading] | |
458 | ``` | |
459 | ||
460 | The /Generic Heading/ assumes the level, plus one, of the innermost section | |
461 | where it is placed. For example, if it is placed in the outermost section, | |
462 | then, it assumes /h2/. | |
463 | ||
464 | Headings are often used as an alternative to sections. It is used | |
465 | particularly if you do not want to start a new section. In many cases, | |
466 | however, headings in a particular section is just flat. Example: | |
467 | ||
468 | ``` | |
469 | [section A] | |
470 | [h2 X] | |
471 | [h2:link_id Y] | |
472 | [h2 Z] | |
473 | [endsect] | |
474 | ``` | |
475 | ||
476 | Here we use h2 assuming that section A is the outermost level. If it is | |
477 | placed in an inner level, you'll have to use h3, h4, etc. depending on | |
478 | where the section is. In general, it is the section level plus one. It is | |
479 | rather tedious, however, to scan the section level everytime. If you | |
480 | rewrite the example above as shown below, this will be automatic: | |
481 | ||
482 | ``` | |
483 | [section A] | |
484 | [heading X] | |
485 | [heading Y] | |
486 | [heading Z] | |
487 | [endsect] | |
488 | ``` | |
489 | ||
490 | They work well regardless where you place them. You can rearrange sections | |
491 | at will without any extra work to ensure correct heading levels. In fact, | |
492 | with /section/ and /heading/, you have all you need. /h1/../h6/ becomes | |
493 | redundant. /h1/../h6/ might be deprecated in the future. | |
494 | ||
495 | [endsect] [/generic_heading] | |
496 | ||
497 | [#quickbook.ref.macros] | |
498 | [section:macros Macros] | |
499 | ||
500 | ``` | |
501 | [def macro_identifier some text] | |
502 | ``` | |
503 | ||
504 | When a macro is defined, the identifier replaces the text anywhere in the | |
505 | file, in paragraphs, in markups, etc. macro_identifier is a string of non- | |
506 | white space characters except '\]'. A macro may not follow an alphabetic | |
507 | character or the underscore. The replacement text can be any phrase (even | |
508 | marked up). Example: | |
509 | ||
510 | ``` | |
511 | [def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&type=1]] | |
512 | sf_logo | |
513 | ``` | |
514 | ||
515 | Now everywhere the sf_logo is placed, the picture will be inlined. | |
516 | ||
517 | [def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&type=1]] | |
518 | sf_logo | |
519 | ||
520 | [tip It's a good idea to use macro identifiers that are distinguishable. | |
521 | For instance, in this document, macro identifiers have two leading and | |
522 | trailing underscores (e.g. [^\__spirit__]). The reason is to avoid | |
523 | unwanted macro replacement.] | |
524 | ||
525 | Links (URLS) and images are good candidates for macros. *1*) They tend to | |
526 | change a lot. It is a good idea to place all links and images in one place near the top | |
527 | to make it easy to make changes. *2*) The syntax is not pretty. It's easier to read and | |
528 | write, e.g. [^\__spirit__] than `[@http://spirit.sourceforge.net Spirit]`. | |
529 | ||
530 | Some more examples: | |
531 | ||
532 | ``` | |
533 | [def ``\:-)`` [$theme/smiley.png]] | |
534 | [def ``\__spirit__`` [@http://spirit.sourceforge.net Spirit]] | |
535 | ``` | |
536 | ||
537 | (See __images__ and __links__) | |
538 | ||
539 | Invoking these macros: | |
540 | ||
541 | ``` | |
542 | Hi ``\__spirit__`` ``\:-)`` | |
543 | ``` | |
544 | ||
545 | will generate this: | |
546 | ||
547 | Hi __spirit__ :-) | |
548 | ||
549 | [endsect] [/macros] | |
550 | ||
551 | [#quickbook.ref.predefined_macros] | |
552 | [section:predefined_macros Predefined Macros] | |
553 | ||
554 | Quickbook has some predefined macros that you can already use. | |
555 | ||
556 | [table Predefined Macros | |
557 | [[Macro] [Meaning] [Example]] | |
558 | [[[^\__DATE__]] [Today's date] [__DATE__]] | |
559 | [[[^\__TIME__]] [The current time] [__TIME__]] | |
560 | [[[^\__FILENAME__]][Quickbook source filename] [__FILENAME__]] | |
561 | ] | |
562 | ||
563 | [endsect] [/predefined_macros] | |
564 | ||
565 | [#quickbook.ref.templates] | |
566 | [section:templates Templates] | |
567 | ||
568 | Templates provide a more versatile text substitution mechanism. Templates | |
569 | come in handy when you need to create parameterizable, multi-line, | |
570 | boilerplate text that you specify once and expand many times. Templates | |
571 | accept one or more arguments. These arguments act like place-holders for | |
572 | text replacement. Unlike simple macros, which are limited to phrase level | |
573 | markup, templates can contain block level markup (e.g. paragraphs, code | |
574 | blocks and tables). | |
575 | ||
576 | Example template: | |
577 | ||
578 | ``` | |
579 | [template person[name age what] | |
580 | ||
581 | Hi, my name is [name]. I am [age] years old. I am a [what]. | |
582 | ||
583 | ] | |
584 | ``` | |
585 | ||
586 | [template person[name age what] | |
587 | ||
588 | Hi, my name is [name]. I am [age] years old. I am a [what]. | |
589 | ||
590 | ] | |
591 | ||
592 | [#quickbook.ref.template_identifier] | |
593 | [heading Template Identifier] | |
594 | ||
595 | Template identifiers can either consist of: | |
596 | ||
597 | * An initial alphabetic character or the underscore, followed by | |
598 | zero or more alphanumeric characters or the underscore. This is | |
599 | similar to your typical C/C++ identifier. | |
600 | * A single character punctuation (a non-alphanumeric printable character) | |
601 | ||
602 | [heading Formal Template Arguments] | |
603 | ||
604 | Template formal arguments are identifiers consisting of an initial | |
605 | alphabetic character or the underscore, followed by zero or more | |
606 | alphanumeric characters or the underscore. This is similar to your typical | |
607 | C/C++ identifier. | |
608 | ||
609 | A template formal argument temporarily hides a template of the same name at | |
610 | the point where the [link quickbook.ref.template_expansion | |
611 | template is expanded]. Note that the body of the [^person] template above | |
612 | refers to [^name] [^age] and [^what] as [^\[name\]] [^\[age\]] and | |
613 | [^\[what\]]. [^name] [^age] and [^what] are actually templates that exist | |
614 | in the duration of the template call. | |
615 | ||
616 | [heading Template Body] | |
617 | ||
618 | The template body can be just about any QuickBook block or phrase. There | |
619 | are actually two forms. Templates may be phrase or block level. Phrase | |
620 | templates are of the form: | |
621 | ||
622 | ``` | |
623 | [template sample[arg1 arg2...argN] replacement text... ] | |
624 | ``` | |
625 | ||
626 | Block templates are of the form: | |
627 | ||
628 | ``` | |
629 | [template sample[arg1 arg2...argN] | |
630 | replacement text... | |
631 | ] | |
632 | ``` | |
633 | ||
634 | The basic rule is as follows: if a newline immediately follows the argument | |
635 | list, then it is a block template, otherwise, it is a phrase template. | |
636 | Phrase templates are typically expanded as part of phrases. Like macros, | |
637 | block level elements are not allowed in phrase templates. | |
638 | ||
639 | [heading Template Expansion] | |
640 | ||
641 | You expand a template this way: | |
642 | ||
643 | ``` | |
644 | [template_identifier arg1..arg2..arg3] | |
645 | ``` | |
646 | ||
647 | At template expansion, you supply the actual arguments. The template will | |
648 | be expanded with your supplied arguments. Example: | |
649 | ||
650 | ``` | |
651 | [person James Bond..39..Spy] | |
652 | [person Santa Clause..87..Big Red Fatso] | |
653 | ``` | |
654 | ||
655 | Which will expand to: | |
656 | ||
657 | [person James Bond..39..Spy] | |
658 | [person Santa Clause..87..Big Red Fatso] | |
659 | ||
660 | [caution A word of caution: Templates are recursive. A template can call | |
661 | another template or even itself, directly or indirectly. There are no | |
662 | control structures in QuickBook (yet) so this will always mean infinite | |
663 | recursion. QuickBook can detect this situation and report an error if | |
664 | recursion exceeds a certain limit.] | |
665 | ||
666 | Each actual argument can be a word, a text fragment or just about any [link | |
667 | quickbook.syntax.phrase QuickBook phrase]. Arguments are separated by the | |
668 | double dot [^".."] and terminated by the close parenthesis. | |
669 | ||
670 | Note that templates and template parameters can't be expanded | |
671 | everywhere, only where text is interpreted as a phrase. So they can't be | |
672 | expanded in places such as table titles and link's urls. If you want to | |
673 | use a template to generate a link based of the template parameter, you | |
674 | can't use a normal link and will need to use escaped docbook instead. | |
675 | Example: | |
676 | ||
677 | [teletype] | |
678 | ``` | |
679 | [template boost_ticket[key] '''<ulink url="https://svn.boost.org/trac/boost/ticket/'''[key]'''">#'''[key]'''</ulink>'''] | |
680 | ||
681 | [boost_ticket 2035] | |
682 | ``` | |
683 | ||
684 | will expand to: | |
685 | ||
686 | [template boost_ticket[key] '''<ulink url="https://svn.boost.org/trac/boost/ticket/'''[key]'''">#'''[key]'''</ulink>'''] | |
687 | ||
688 | [boost_ticket 2035] | |
689 | ||
690 | [caution Since quickbook doesn't understand the context where the | |
691 | parameter is being used, it will interpret it as quickbook markup, so | |
692 | when writing a template like this, you'll need to escape any meaningful | |
693 | punctuation.] | |
694 | ||
695 | [heading Nullary Templates] | |
696 | ||
697 | Nullary templates look and act like simple macros. Example: | |
698 | ||
699 | ``` | |
700 | [template alpha[]'''&#945;'''] | |
701 | [template beta[]'''&#946;'''] | |
702 | ``` | |
703 | ||
704 | [template alpha[]'''α'''] | |
705 | [template beta[]'''β'''] | |
706 | ||
707 | Expanding: | |
708 | ||
709 | ```Some squigles...[*[alpha][beta]]``` | |
710 | ||
711 | We have: | |
712 | ||
713 | Some squiggles...[*[alpha][beta]] | |
714 | ||
715 | The difference with macros are | |
716 | ||
717 | * The explicit [link quickbook.ref.template_expansion | |
718 | template expansion syntax]. This is an advantage because, now, we don't | |
719 | have to use obscure naming conventions like double underscores (e.g. | |
720 | \_\_alpha\_\_) to avoid unwanted | |
721 | macro replacement. | |
722 | * The template is expanded at the point where it is invoked. A macro is | |
723 | expanded immediately at its point of declaration. This is subtle and | |
724 | can cause a slight difference in behavior especially if you refer to | |
725 | other macros and templates in the body. | |
726 | ||
727 | The empty brackets after the template identifier ([^alpha\[\]]) indicates no | |
728 | arguments. If the template body does not look like a template argument list, we | |
729 | can elide the empty brackets. Example: | |
730 | ||
731 | ``` | |
732 | [template aristotle_quote Aristotle: [*['Education is the best provision | |
733 | for the journey to old age.]]] | |
734 | ``` | |
735 | ||
736 | [template aristotle_quote\ Aristotle: [*['Education is the best provision | |
737 | for the journey to old age.]]] | |
738 | ||
739 | Expanding: | |
740 | ||
741 | ``` | |
742 | Here's a quote from [aristotle_quote]. | |
743 | ``` | |
744 | ||
745 | We have: | |
746 | ||
747 | Here's a quote from [aristotle_quote]. | |
748 | ||
749 | The disadvantage is that you can't avoid the space between the template | |
750 | identifier, `aristotle_quote`, and the template body "Aristotle...". This space | |
751 | will be part of the template body. If that space is unwanted, use empty | |
752 | brackets or use the space escape: "`\ `". Example: | |
753 | ||
754 | ``` | |
755 | [template tag\ _tag] | |
756 | ``` | |
757 | ||
758 | [template tag\ _tag] | |
759 | ||
760 | Then expanding: | |
761 | ||
762 | ``` | |
763 | `struct` x[tag]; | |
764 | ``` | |
765 | ||
766 | We have: | |
767 | ||
768 | `struct` x[tag]; | |
769 | ||
770 | You have a couple of ways to do it. I personally prefer the explicit empty | |
771 | brackets, though. | |
772 | ||
773 | [heading Simple Arguments] | |
774 | ||
775 | As mentioned, arguments are separated by the double dot [^".."]. Alternatively, | |
776 | if the double dot isn't used and more than one argument is expected, QuickBook | |
777 | uses whitespace to separate the arguments, following this logic: | |
778 | ||
779 | * Break the last argument into two, at the first space found ([^'', '\\n', | |
780 | \\t' or '\\r']). | |
781 | * Repeat until there are enough arguments or if there are no more spaces | |
782 | found (in which case, an error is reported). | |
783 | ||
784 | For example: | |
785 | ||
786 | ``` | |
787 | [template simple[a b c d] [a][b][c][d]] | |
788 | [simple w x y z] | |
789 | ``` | |
790 | ||
791 | will produce: | |
792 | ||
793 | [template simple[a b c d] [a][b][c][d]] | |
794 | [simple w x y z] | |
795 | ||
796 | "w x y z" is initially treated as a single argument because we didn't | |
797 | supply any [^".."] separators. However, since [^simple] expects 4 | |
798 | arguments, "w x y z" is broken down iteratively (applying the logic above) | |
799 | until we have "w", "x", "y" and "z". | |
800 | ||
801 | QuickBook only tries to get the arguments it needs. For example: | |
802 | ||
803 | ``` | |
804 | [simple w x y z trail] | |
805 | ``` | |
806 | ||
807 | will produce: | |
808 | ||
809 | [simple w x y z trail] | |
810 | ||
811 | The arguments being: "w", "x", "y" and "z trail". | |
812 | ||
813 | [caution The behavior described here is for QuickBook 1.5. In older versions you | |
814 | could use both the double dot and whitespace as separators in the same template | |
815 | call. If your document is marked up as an older version, it will use the old | |
816 | behavior, which is described in the | |
817 | [@http://www.boost.org/doc/libs/1_40_0/doc/html/quickbook/syntax.html#quickbook.syntax.block.templates.simple_arguments | |
818 | QuickBook 1.4 documentation].] | |
819 | ||
820 | [heading Punctuation Templates] | |
821 | ||
822 | With templates, one of our objectives is to allow us to rewrite QuickBook | |
823 | in QuickBook (as a qbk library). For that to happen, we need to accommodate | |
824 | single character punctuation templates which are fairly common in | |
825 | QuickBook. You might have noticed that single character punctuations are | |
826 | allowed as [link quickbook.ref.template_identifier | |
827 | template identifiers]. Example: | |
828 | ||
829 | ``` | |
830 | [template ![bar] <hey>[bar]</hey>] | |
831 | ``` | |
832 | ||
833 | Now, expanding this: | |
834 | ||
835 | ``` | |
836 | [!baz] | |
837 | ``` | |
838 | ||
839 | We will have: | |
840 | ||
841 | [pre | |
842 | <hey>baz</hey> | |
843 | ] | |
844 | ||
845 | [endsect] [/templates] | |
846 | ||
847 | [#quickbook.ref.blurbs] | |
848 | [section:blurbs Blurbs] | |
849 | ||
850 | ``` | |
851 | [blurb ``\:-)`` [*An eye catching advertisement or note...] | |
852 | ||
853 | __spirit__ is an object-oriented recursive-descent parser generator framework | |
854 | implemented using template meta-programming techniques. Expression templates | |
855 | allow us to approximate the syntax of Extended Backus-Normal Form (EBNF) | |
856 | completely in C++. | |
857 | ] | |
858 | ``` | |
859 | ||
860 | will generate this: | |
861 | ||
862 | [blurb :-) [*An eye catching advertisement or note...] | |
863 | ||
864 | __spirit__ is an object-oriented recursive-descent parser generator | |
865 | framework implemented using template meta-programming techniques. Expression | |
866 | templates allow us to approximate the syntax of Extended Backus-Normal Form | |
867 | (EBNF) completely in C++. | |
868 | ] | |
869 | ||
870 | [note Prefer [link quickbook.ref.admonitions admonitions] wherever | |
871 | appropriate.] | |
872 | ||
873 | [endsect] [/blurbs] | |
874 | ||
875 | [#quickbook.ref.tables] | |
876 | [section:tables Tables] | |
877 | ||
878 | ``` | |
879 | [table:id A Simple Table | |
880 | [[Heading 1] [Heading 2] [Heading 3]] | |
881 | [[R0-C0] [R0-C1] [R0-C2]] | |
882 | [[R1-C0] [R1-C1] [R1-C2]] | |
883 | [[R2-C0] [R2-C1] [R2-C2]] | |
884 | ] | |
885 | ``` | |
886 | ||
887 | will generate: | |
888 | ||
889 | [table:id A Simple Table | |
890 | [[Heading 1] [Heading 2] [Heading 3]] | |
891 | [[R0-C0] [R0-C1] [R0-C2]] | |
892 | [[R1-C0] [R1-C1] [R1-C2]] | |
893 | [[R2-C0] [R2-C1] [R2-C2]] | |
894 | ] | |
895 | ||
896 | The table title is optional. The first row of the table is automatically | |
897 | treated as the table header; that is, it is wrapped in [^<thead>...</thead>] | |
898 | XML tags. Note that unlike the original QuickDoc, the columns are nested in | |
899 | [cells... ]. | |
900 | ||
901 | Giving tables an id is a new feature for quickbook 1.5 onwards. As with | |
902 | sections, the id is optional. If the table has a title but no id, an id will | |
903 | be generated from the title. The table above can be linked to using: | |
904 | ||
905 | ``` | |
906 | [link quickbook.syntax.block.tables.id link to table] | |
907 | ``` | |
908 | ||
909 | which will generate: | |
910 | ||
911 | [link quickbook.syntax.block.tables.id link to table] | |
912 | ||
913 | The syntax is free-format and allows big cells to be formatted | |
914 | nicely. Example: | |
915 | ||
916 | ``` | |
917 | [table Table with fat cells | |
918 | [[Heading 1] [Heading 2]] | |
919 | [ | |
920 | [Row 0, Col 0: a small cell] | |
921 | [ | |
922 | Row 0, Col 1: a big fat cell with paragraphs | |
923 | ||
924 | Boost provides free peer-reviewed portable C++ source libraries. | |
925 | ||
926 | We emphasize libraries that work well with the C++ Standard Library. | |
927 | Boost libraries are intended to be widely useful, and usable across | |
928 | a broad spectrum of applications. The Boost license encourages both | |
929 | commercial and non-commercial use. | |
930 | ] | |
931 | ] | |
932 | [ | |
933 | [Row 1, Col 0: a small cell] | |
934 | [Row 1, Col 1: a small cell] | |
935 | ] | |
936 | ] | |
937 | ``` | |
938 | ||
939 | and thus: | |
940 | ||
941 | [table Table with fat cells | |
942 | [[Heading 1] [Heading 2]] | |
943 | [ | |
944 | [Row 0, Col 0: a small cell] | |
945 | [ | |
946 | Row 0, Col 1: a big fat cell with paragraphs | |
947 | ||
948 | Boost provides free peer-reviewed portable C++ source libraries. | |
949 | [/ <-- There's a space here. Don't remove. This is intentional, for testing] | |
950 | We emphasize libraries that work well with the C++ Standard Library. | |
951 | Boost libraries are intended to be widely useful, and usable across | |
952 | a broad spectrum of applications. The Boost license encourages both | |
953 | commercial and non-commercial use. | |
954 | ] | |
955 | ] | |
956 | [ | |
957 | [Row 1, Col 0: a small cell] | |
958 | [Row 1, Col 1: a small cell] | |
959 | ] | |
960 | ] | |
961 | ||
962 | Here's how to have preformatted blocks of code in a table cell: | |
963 | ||
964 | ``` | |
965 | [table Table with code | |
966 | [[Comment] [Code]] | |
967 | [ | |
968 | [My first program] | |
969 | [``\`\`\ `` | |
970 | #include <iostream> | |
971 | ||
972 | int main() | |
973 | { | |
974 | std::cout << "Hello, World!" << std::endl; | |
975 | return 0; | |
976 | } | |
977 | ``\`\`\ ``] | |
978 | ] | |
979 | ] | |
980 | ``` | |
981 | ||
982 | [table Table with code | |
983 | [[Comment] [Code]] | |
984 | [ | |
985 | [My first program] | |
986 | [`` | |
987 | #include <iostream> | |
988 | ||
989 | int main() | |
990 | { | |
991 | std::cout << "Hello, World!" << std::endl; | |
992 | return 0; | |
993 | } | |
994 | ``] | |
995 | ] | |
996 | ] | |
997 | ||
998 | [endsect] [/tables] | |
999 | ||
1000 | [#quickbook.ref.variable_lists] | |
1001 | [section:variable_lists Variable Lists] | |
1002 | ||
1003 | ``` | |
1004 | [variablelist A Variable List | |
1005 | [[term 1] [The definition of term 1]] | |
1006 | [[term 2] [The definition of term 2]] | |
1007 | [[term 3] [ | |
1008 | The definition of term 3. | |
1009 | ||
1010 | Definitions may contain paragraphs. | |
1011 | ]] | |
1012 | ] | |
1013 | ``` | |
1014 | ||
1015 | will generate: | |
1016 | ||
1017 | [variablelist A Variable List | |
1018 | [[term 1] [The definition of term 1]] | |
1019 | [[term 2] [The definition of term 2]] | |
1020 | [[term 3] [ | |
1021 | The definition of term 3. | |
1022 | ||
1023 | Definitions may contain paragraphs. | |
1024 | ]] | |
1025 | ] | |
1026 | ||
1027 | The rules for variable lists are the same as for tables, except that | |
1028 | only 2 "columns" are allowed. The first column contains the terms, and | |
1029 | the second column contains the definitions. Those familiar with HTML | |
1030 | will recognize this as a "definition list". | |
1031 | ||
1032 | [endsect] [/variable_lists] | |
1033 | ||
1034 | [#quickbook.ref.include] | |
1035 | [section:include Include] | |
1036 | ||
1037 | You can include one QuickBook file from another. The syntax is simply: | |
1038 | ||
1039 | ``` | |
1040 | [include someother.qbk] | |
1041 | ``` | |
1042 | ||
1043 | In quickbook 1.6 and later, if the included file has a | |
1044 | [link quickbook.ref.docinfo docinfo block] then it will create a nested | |
1045 | document. This will be processed as a standalone document, although any macros | |
1046 | or templates from the enclosing file will still be defined. | |
1047 | ||
1048 | Otherwise the included file will be processed as if it had been cut and pasted | |
1049 | into the current document, with the following exceptions: | |
1050 | ||
1051 | * The '''__FILENAME__''' predefined macro will reflect the name of the | |
1052 | file currently being processed. | |
1053 | * Any macros or templates defined in the included file are scoped to that file, | |
1054 | i.e. they are not added to the enclosing file. | |
1055 | ||
1056 | [note In quickbook 1.5 and earlier templates weren't scoped in included files. | |
1057 | If you want to use templates or macros from a file in quickbook 1.6, | |
1058 | use [link quickbook.ref.import import] instead.] | |
1059 | ||
1060 | The [^\[include\]] directive lets you specify a document id to use for the | |
1061 | included file. You can specify the id like this: | |
1062 | ||
1063 | ``` | |
1064 | [include:someid someother.qbk] | |
1065 | ``` | |
1066 | ||
1067 | All auto-generated anchors will use the document id as a unique prefix. So | |
1068 | for instance, if there is a top section in someother.qbk named "Intro", the | |
1069 | named anchor for that section will be "someid.intro", and you can link to | |
1070 | it with [^\[link someid.intro The Intro\]]. | |
1071 | ||
1072 | If the included file has a docinfo block, an id specified in an [^\[include\]] | |
1073 | directive will overwrite it. | |
1074 | ||
1075 | You can also include C, C++ and python source files. This will include any | |
1076 | quickbook blocks in the file that aren't inside of named code snippets. See | |
1077 | the [link quickbook.ref.import Import section] for syntax details. For example, | |
1078 | say you included this file: | |
1079 | ||
1080 | /** | |
1081 | * Hello world example | |
1082 | */ | |
1083 | ||
1084 | // In this comment, the backtick indicates that this is a | |
1085 | // quickbook source block that will be included. | |
1086 | ||
1087 | /*` | |
1088 | First include the appropriate header: [hello_includes] | |
1089 | Then write your main function: [hello_main] | |
1090 | */ | |
1091 | ||
1092 | // This defines a code snippet, the syntax is | |
1093 | // described in the import section. It's available | |
1094 | // in the whole of this source file, not just after | |
1095 | // its definition. | |
1096 | ||
1097 | //[hello_includes | |
1098 | #include <iostream> | |
1099 | //] | |
1100 | ||
1101 | //[hello_main | |
1102 | int main() { | |
1103 | std::cout << "Hello, trivial example" << std::endl; | |
1104 | } | |
1105 | //] | |
1106 | ||
1107 | It will generate: | |
1108 | ||
1109 | First include the appropriate header: | |
1110 | ||
1111 | #include <iostream> | |
1112 | ||
1113 | Then write your main function: | |
1114 | ||
1115 | int main() { | |
1116 | std::cout << "Hello, trivial example" << std::endl; | |
1117 | } | |
1118 | ||
1119 | [endsect] [/include] | |
1120 | ||
1121 | [#quickbook.ref.import] | |
1122 | [section:import Import] | |
1123 | ||
1124 | In quickbook 1.6 and later if you wish to use a template, macro or code | |
1125 | snippet from a file, you need to import it. This will not include any | |
1126 | of the content from that file, but will pull templates, macros and code | |
1127 | snippets into the current file's scope. | |
1128 | ||
1129 | With quickbook files, this allows you to create template and macro | |
1130 | libraries. For python (indicated by the `.py` extension), C or | |
1131 | C++ files this allows you to include code snippets from source files, | |
1132 | so that your code examples can be kept up to date and fully tested. | |
1133 | ||
1134 | [/ Old justification text, might move this into a new section: | |
1135 | ||
1136 | When documenting code, you'd surely need to present code from actual source | |
1137 | files. While it is possible to copy some code and paste them in your QuickBook | |
1138 | file, doing so is error prone and the extracted code in the documentation tends | |
1139 | to get out of sync with the actual code as the code evolves. The problem, as | |
1140 | always, is that once documentation is written, the tendency is for the docs to | |
1141 | languish in the archives without maintenance. | |
1142 | ||
1143 | QuickBook's import facility provides a nice solution. | |
1144 | ] | |
1145 | ||
1146 | [heading Example] | |
1147 | ||
1148 | You can effortlessly import code snippets from source code into your QuickBook. | |
1149 | The following illustrates how this is done: | |
1150 | ||
1151 | ``` | |
1152 | [import ../test/stub.cpp] | |
1153 | [foo] | |
1154 | [bar] | |
1155 | ``` | |
1156 | ||
1157 | The first line: | |
1158 | ||
1159 | ``` | |
1160 | [import ../test/stub.cpp] | |
1161 | ``` | |
1162 | ||
1163 | collects specially marked-up code snippets from | |
1164 | [@boost:/tools/quickbook/test/stub.cpp stub.cpp] | |
1165 | and places them in your QuickBook file as virtual templates. Each of the | |
1166 | specially marked-up code snippets has a name (e.g. `foo` and `bar` in the | |
1167 | example above). This shall be the template identifier for that particular code | |
1168 | snippet. The second and third line above does the actual template expansion: | |
1169 | ||
1170 | ``` | |
1171 | [foo] | |
1172 | [bar] | |
1173 | ``` | |
1174 | ||
1175 | And the result is: | |
1176 | ||
1177 | [import ../test/stub.cpp] | |
1178 | [foo] | |
1179 | [bar] | |
1180 | ||
1181 | [heading Code Snippet Markup] | |
1182 | ||
1183 | Note how the code snippets in [@boost:/tools/quickbook/test/stub.cpp stub.cpp] | |
1184 | get marked up. We use distinguishable comments following the form: | |
1185 | ||
1186 | //[id | |
1187 | some code here | |
1188 | //] | |
1189 | ||
1190 | The first comment line above initiates a named code-snippet. This prefix will | |
1191 | not be visible in quickbook. The entire code-snippet in between `//[id` and | |
1192 | `//]` will be inserted as a template in quickbook with name ['/id/]. The comment | |
1193 | `//]` ends a code-snippet This too will not be visible in quickbook. | |
1194 | ||
1195 | [heading Special Comments] | |
1196 | ||
1197 | Special comments of the form: | |
1198 | ||
1199 | //` some [*quickbook] markup here | |
1200 | ||
1201 | and: | |
1202 | ||
1203 | /*` some [*quickbook] markup here */ | |
1204 | ||
1205 | will be parsed by QuickBook. This can contain quickbook /blocks/ (e.g. sections, | |
1206 | paragraphs, tables, etc). In the first case, the initial slash-slash, tick and | |
1207 | white-space shall be ignored. In the second, the initial slash-star-tick and the | |
1208 | final star-slash shall be ignored. | |
1209 | ||
1210 | Special comments of the form: | |
1211 | ||
1212 | /*<- this C++ comment will be ignored ->*/ | |
1213 | ||
1214 | or | |
1215 | ||
1216 | /*<-*/ "this c++ code will be ignored" /*->*/ | |
1217 | ||
1218 | or | |
1219 | ||
1220 | //<- | |
1221 | private: | |
1222 | int some_member; | |
1223 | //-> | |
1224 | ||
1225 | can be used to inhibit code from passing through to quickbook. All text between | |
1226 | the delimeters will simply be ignored. | |
1227 | ||
1228 | Comments of this form: | |
1229 | ||
1230 | //=int main() {} | |
1231 | ||
1232 | or | |
1233 | ||
1234 | /*=foo()*/ | |
1235 | ||
1236 | will be displayed as code that isn't in comments. This allows you to | |
1237 | include some code in the snippet but not actually use it when | |
1238 | compiling your example. | |
1239 | ||
1240 | [heading Callouts] | |
1241 | ||
1242 | Special comments of the form: | |
1243 | ||
1244 | /*< some [*quickbook] markup here >*/ | |
1245 | ||
1246 | will be regarded as callouts. These will be collected, numbered and | |
1247 | rendered as a "callout bug" (a small icon with a number). After the | |
1248 | whole snippet is parsed, the callout list is generated. See | |
1249 | [@http://www.docbook.org/tdg/en/html/callout.html Callouts] for details. | |
1250 | Example: | |
1251 | ||
1252 | [foo_bar] | |
1253 | ||
1254 | This is the actual code: | |
1255 | ||
1256 | //[ foo_bar | |
1257 | std::string foo_bar() /*< The /Mythical/ FooBar. | |
1258 | See [@http://en.wikipedia.org/wiki/Foobar Foobar for details] >*/ | |
1259 | { | |
1260 | return "foo-bar"; /*< return 'em, foo-bar man! >*/ | |
1261 | } | |
1262 | //] | |
1263 | ||
1264 | The callouts bugs are placed exactly where the special callout comment | |
1265 | is situated. It can be anywhere in the code. The bugs can be rather | |
1266 | obtrusive, however. They get in the way of the clarity of the code. | |
1267 | Another special callout comment style is available: | |
1268 | ||
1269 | /*<< some [*quickbook] markup here >>*/ | |
1270 | ||
1271 | This is the line-oriented version of the callout. With this, the "bug" | |
1272 | is placed at the very left of the code block, away from the actual code. | |
1273 | By placing it at the far left, the code is rendered un-obscured. | |
1274 | Example: | |
1275 | ||
1276 | [class_] | |
1277 | ||
1278 | See the actual code here: | |
1279 | [@boost:/tools/quickbook/test/stub.cpp tools/quickbook/test/stub.cpp] | |
1280 | ||
1281 | [endsect] [/import] | |
1282 | ||
1283 | [#quickbook.ref.block] | |
1284 | [section:block Plain blocks] | |
1285 | ||
1286 | `block` is a plain block element, that doesn't wrap its contents | |
1287 | in any docbook or boostbook tags. This can be useful when using | |
1288 | escaped docbook block tags, such as: | |
1289 | ||
1290 | [template chapter[title] | |
1291 | [block'''<chapter><title>'''[title]'''</title>'''] | |
1292 | ] | |
1293 | ||
1294 | [template chapterend | |
1295 | [block'''</chapter>'''] | |
1296 | ] | |
1297 | ||
1298 | [chapter An example chapter] | |
1299 | ||
1300 | Content | |
1301 | ||
1302 | [chapterend] | |
1303 | ||
1304 | Without the `block` element, the `chapter` and `chapterend` templates | |
1305 | would be wrapped in paragraph tags. | |
1306 | ||
1307 | [note In this example, the template body has to start with a newline so that | |
1308 | the template will be interpreted in block mode.] | |
1309 | ||
1310 | [endsect] [/block] |