]>
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 Phrase Level Elements | |
11 | [quickbook 1.6] | |
12 | [compatibility-mode 1.5] | |
13 | [id quickbook.syntax.phrase] | |
14 | [source-mode teletype] | |
15 | ] | |
16 | ||
17 | [#quickbook.ref.font_styles] | |
18 | [section:font_styles Font Styles] | |
19 | ||
20 | ``` | |
21 | ['italic], [*bold], [_underline], [^teletype], [-strikethrough] | |
22 | ``` | |
23 | ||
24 | will generate: | |
25 | ||
26 | ['italic], [*bold], [_underline], [^teletype], [-strikethrough] | |
27 | ||
28 | Like all non-terminal phrase level elements, this can of course be nested: | |
29 | ||
30 | ``` | |
31 | [*['bold-italic]] | |
32 | ``` | |
33 | ||
34 | will generate: | |
35 | ||
36 | [*['bold-italic]] | |
37 | ||
38 | [endsect] [/font_styles] | |
39 | ||
40 | [#quickbook.ref.replaceable] | |
41 | [section:replaceable Replaceable] | |
42 | ||
43 | When you want content that may or must be replaced by the user, use the syntax: | |
44 | ||
45 | ``` | |
46 | [~replacement] | |
47 | ``` | |
48 | ||
49 | This will generate: | |
50 | ||
51 | [~replacement] | |
52 | ||
53 | [endsect] [/replaceable] | |
54 | ||
55 | [#quickbook.ref.quotations] | |
56 | [section:quotations Quotations] | |
57 | ||
58 | ``` | |
59 | ["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein | |
60 | ``` | |
61 | ||
62 | will generate: | |
63 | ||
64 | ["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein | |
65 | ||
66 | Note the proper left and right quote marks. Also, while you can simply use | |
67 | ordinary quote marks like "quoted", our quotation, above, will generate correct | |
68 | DocBook quotations (e.g. <quote>quoted</quote>). | |
69 | ||
70 | Like all phrase elements, quotations may be nested. Example: | |
71 | ||
72 | ``` | |
73 | ["Here's the rule for bargains: ["Do other men, for they would do you.] That's | |
74 | the true business precept.] | |
75 | ``` | |
76 | ||
77 | will generate: | |
78 | ||
79 | ["Here's the rule for bargains: ["Do other men, for they would do you.] | |
80 | That's the true business precept.] | |
81 | ||
82 | [endsect] [/quotations] | |
83 | ||
84 | [#quickbook.ref.simple_formatting] | |
85 | [section:simple_formatting Simple formatting] | |
86 | ||
87 | Simple markup for formatting text, common in many applications, is now supported: | |
88 | ||
89 | ``` | |
90 | /italic/, *bold*, _underline_, =teletype= | |
91 | ``` | |
92 | ||
93 | will generate: | |
94 | ||
95 | /italic/, *bold*, _underline_, =teletype= | |
96 | ||
97 | Unlike QuickBook's standard formatting scheme, the rules for simpler | |
98 | alternatives are much stricter[footnote Thanks to David Barrett, author of | |
99 | [@http://quinthar.com/qwikiwiki/index.php?page=Home Qwiki], for sharing | |
100 | these samples and teaching me these obscure formatting rules. I wasn't sure | |
101 | at all if __spirit__, being more or less a formal EBNF parser, can handle | |
102 | the context sensitivity and ambiguity.]. | |
103 | ||
104 | * Simple markups cannot nest. You can combine a simple markup with a nestable markup. | |
105 | * Simple markups cannot contain any other form of quickbook markup. | |
106 | * A non-space character must follow the leading markup | |
107 | * A non-space character must precede the trailing markup | |
108 | * A space or a punctuation must follow the trailing markup | |
109 | * If the matching markup cannot be found within a block, the formatting | |
110 | will not be applied. This is to ensure that un-matched formatting markups, | |
111 | which can be a common mistake, does not corrupt anything past a single block. | |
112 | We do not want the rest of the document to be rendered bold just because we | |
113 | forgot a trailing '*'. A single block is terminated by two end of lines or | |
114 | the close bracket: '\]'. | |
115 | * A line starting with the star will be interpreted as an unordered list. | |
116 | See __unordered_lists__. | |
117 | ||
118 | [table More Formatting Samples | |
119 | [[Markup] [Result]] | |
120 | [[`*Bold*`] [*Bold*]] | |
121 | [[`*Is bold*`] [*Is bold*]] | |
122 | [[`* Not bold* *Not bold * * Not bold *`] [* Not bold* *Not bold * * Not bold *]] | |
123 | [[`This*Isn't*Bold (no bold)`] [This*Isn't*Bold (no bold)]] | |
124 | [[`(*Bold Inside*) (parenthesis not bold)`] [(*Bold Inside*) (parenthesis not bold)]] | |
125 | [[`*(Bold Outside)* (parenthesis bold)`] [*(Bold Outside)* (parenthesis bold)]] | |
126 | [[`3*4*5 = 60 (no bold)`] [3*4*5 = 60 (no bold)]] | |
127 | [[`3 * 4 * 5 = 60 (no bold)`] [3 * 4 * 5 = 60 (no bold)]] | |
128 | [[`3 *4* 5 = 60 (4 is bold)`] [3 *4* 5 = 60 (4 is bold)]] | |
129 | [[`*This is bold* this is not *but this is*`] [*This is bold* this is not *but this is*]] | |
130 | [[`*This is bold*.`] [*This is bold*.]] | |
131 | [[`*B*. (bold B)`] [*B*. (bold B)]] | |
132 | [[`['*Bold-Italic*]`] [['*Bold-Italic*]]] | |
133 | [[`*side-by*/-side/`] [*side-by*/-side/]] | |
134 | ] | |
135 | ||
136 | As mentioned, simple markups cannot go past a single block. The text | |
137 | from "have" to "full" in the following paragraph will be rendered as | |
138 | bold: | |
139 | ||
140 | ``` | |
141 | Baa baa black sheep, *have you any wool? | |
142 | Yes sir, yes sir, three bags full!* | |
143 | One for the master, one for the dame, | |
144 | And one for the little boy who lives down the lane. | |
145 | ``` | |
146 | ||
147 | Baa baa black sheep, *have you any wool? | |
148 | Yes sir, yes sir, three bags full!* | |
149 | One for the master, one for the dame, | |
150 | And one for the little boy who lives down the lane. | |
151 | ||
152 | But in the following paragraph, bold is not applied: | |
153 | ||
154 | ``` | |
155 | Baa baa black sheep, *have you any wool? | |
156 | Yes sir, yes sir, three bags full! | |
157 | One for the master, one for the dame, | |
158 | And one for the little boy who lives down the lane. | |
159 | ``` | |
160 | ||
161 | Baa baa black sheep, *have you any wool? | |
162 | Yes sir, yes sir, three bags full! | |
163 | One for the master, one for the dame, | |
164 | And one for the little boy who lives down the lane. | |
165 | ||
166 | [endsect] [/simple_formatting] | |
167 | ||
168 | [#quickbook.ref.role] | |
169 | [section:role Role] | |
170 | ||
171 | This generates a docbook phrase with a `role` attribute, which can be used | |
172 | to classify the phrase. This can be used to mark text for a use that isn't | |
173 | covered elsewhere. The docbook `role` will generate a html class, which can | |
174 | be used to style text. And the xsl stylesheets can be customized to treat | |
175 | certain roles specially when generating pdfs. | |
176 | ||
177 | The boostbook css stylesheets, and xsl stylesheets | |
178 | contain support for a limited number of colours that can be used with | |
179 | `role`. For example if you write: | |
180 | ||
181 | [role red Text content] | |
182 | ||
183 | You'll get red text if you're using the boostbook css (for html) or | |
184 | the boostbook xsl for generating pdfs. | |
185 | ||
186 | The full list of colours that will be available is: | |
187 | ||
188 | * [role red red] | |
189 | * [role green green] | |
190 | * [role lime lime] | |
191 | * [role blue blue] | |
192 | * [role navy navy] | |
193 | * [role yellow yellow] | |
194 | * [role magenta magenta] | |
195 | * [role indigo indigo] | |
196 | * [role cyan cyan] | |
197 | * [role purple purple] | |
198 | * [role gold gold] | |
199 | * [role silver silver] | |
200 | * [role gray gray] | |
201 | ||
202 | [endsect] [/role] | |
203 | ||
204 | [#quickbook.ref.inline_code] | |
205 | [section:inline_code Inline code] | |
206 | ||
207 | Inlining code in paragraphs is quite common when writing C++ documentation. We | |
208 | provide a very simple markup for this. For example, this: | |
209 | ||
210 | ``` | |
211 | This text has inlined code `int main() { return 0; }` in it. | |
212 | ``` | |
213 | ||
214 | will generate: | |
215 | ||
216 | This text has inlined code `int main() { return 0; }` in it. The code will be | |
217 | syntax highlighted. | |
218 | ||
219 | [note We simply enclose the code with the tick: [^"\`"], not the | |
220 | single quote: `"'"`. Note too that [^\`some code\`] is preferred over | |
221 | `[^some code]`. ] | |
222 | ||
223 | [endsect] [/inline_code] | |
224 | ||
225 | [#quickbook.ref.code_blocks] | |
226 | [section:code_blocks Code blocks] | |
227 | ||
228 | Preformatted code simply starts with a space or a tab (See __code__). | |
229 | However, such a simple syntax cannot be used as phrase elements in lists | |
230 | (See __ordered_lists__ and __unordered_lists__), tables (See __tables__), | |
231 | etc. Inline code (see above) can. The problem is, inline code does not | |
232 | allow formatting with newlines, spaces, and tabs. These are lost. | |
233 | ||
234 | We provide a phrase level markup that is a mix between the two. By using the | |
235 | double-tick or triple-tick, instead of the single-tick, we are telling QuickBook | |
236 | to use preformatted blocks of code. Example: | |
237 | ||
238 | ``` | |
239 | ``\`\` `` | |
240 | #include <iostream> | |
241 | ||
242 | int main() | |
243 | { | |
244 | std::cout << "Hello, World!" << std::endl; | |
245 | return 0; | |
246 | } | |
247 | ``\`\`\ `` | |
248 | ``` | |
249 | ||
250 | or: | |
251 | ||
252 | ``` | |
253 | ``\`\`\` `` | |
254 | #include <iostream> | |
255 | ||
256 | int main() | |
257 | { | |
258 | std::cout << "Hello, World!" << std::endl; | |
259 | return 0; | |
260 | } | |
261 | ``\`\`\` `` | |
262 | ``` | |
263 | ||
264 | will generate: | |
265 | ||
266 | [c++] | |
267 | ||
268 | `` | |
269 | #include <iostream> | |
270 | ||
271 | int main() | |
272 | { | |
273 | std::cout << "Hello, World!" << std::endl; | |
274 | return 0; | |
275 | } | |
276 | `` | |
277 | ||
278 | [teletype] | |
279 | ||
280 | [endsect] [/code_blocks] | |
281 | ||
282 | [#quickbook.ref.source_mode] | |
283 | [section:source_mode Source Mode] | |
284 | ||
285 | If a document contains more than one type of source code then the source | |
286 | mode may be changed dynamically as the document is processed. All QuickBook | |
287 | documents are initially in C++ mode by default, though an alternative | |
288 | initial value may be set in the __document__ section. | |
289 | ||
290 | To change the source mode, use the [^\[source-mode\]] markup, where | |
291 | =source-mode= is one of the supported modes. For example, this: | |
292 | ||
293 | ``` | |
294 | Python's [python] `import` is rather like C++'s [c++] `#include`. A | |
295 | C++ comment `// looks like this` whereas a Python comment [python] | |
296 | `# looks like this`. | |
297 | ``` | |
298 | ||
299 | will generate: | |
300 | ||
301 | Python's [python] `import` is rather like C++'s [c++] `#include`. A | |
302 | C++ comment `// looks like this` whereas a Python comment [python] | |
303 | `#looks like this`. | |
304 | ||
305 | [teletype] | |
306 | ||
307 | [table Supported Source Modes | |
308 | [[Mode] [Source Mode Markup]] | |
309 | [[C++] [[^\[c++\]]]] | |
310 | [[Python] [[^\[python\]]]] | |
311 | [[Plain Text] [[^\[teletype\]]]] | |
312 | ] | |
313 | ||
314 | [note The source mode strings are lowercase.] | |
315 | ||
316 | [endsect] [/source_mode] | |
317 | ||
318 | [#quickbook.ref.line_break] | |
319 | [section:line_break line-break] | |
320 | ||
321 | ``` | |
322 | [br] | |
323 | ``` | |
324 | ||
325 | [warning `[br]` generates invalid docbook. It seems to mostly work okay but | |
326 | there might be problems, especially when using an alternative docbook | |
327 | processor.] | |
328 | ||
329 | [endsect] [/line_break] | |
330 | ||
331 | [#quickbook.ref.anchors] | |
332 | [section:anchors Anchors] | |
333 | ||
334 | ``` | |
335 | [#named_anchor] | |
336 | ``` | |
337 | ||
338 | A named anchor is a hook that can be referenced by a link elsewhere in the | |
339 | document. You can then reference an anchor with `[link named_anchor | |
340 | Some link text]`. See __anchor_links__, __section__ and __heading__. | |
341 | ||
342 | These anchors are global and can be accessed from anywhere in the | |
343 | quickbook documentation. Be careful to avoid clashes with anchors in | |
344 | other sections. | |
345 | ||
346 | [endsect] [/anchors] | |
347 | ||
348 | [#quickbook.ref.links] | |
349 | [section:links Links] | |
350 | ||
351 | ``` | |
352 | [@http://www.boost.org this is [*boost's] website....] | |
353 | ``` | |
354 | ||
355 | will generate: | |
356 | ||
357 | [@http://www.boost.org this is [*boost's] website....] | |
358 | ||
359 | URL links where the link text is the link itself is common. Example: | |
360 | ||
361 | ``` | |
362 | see http://spirit.sourceforge.net/ | |
363 | ``` | |
364 | ||
365 | so, when the text is absent in a link markup, the URL is assumed. Example: | |
366 | ||
367 | ``` | |
368 | see [@http://spirit.sourceforge.net/] | |
369 | ``` | |
370 | ||
371 | will generate: | |
372 | ||
373 | see [@http://spirit.sourceforge.net/] | |
374 | ||
375 | Boostbook also support a custom url schema for linking to files within | |
376 | the boost distribution: | |
377 | ||
378 | ``` | |
379 | [@boost:/libs/spirit/index.html the Boost.Spirit documentation] | |
380 | ``` | |
381 | ||
382 | will generate: [@boost:/libs/spirit/index.html the Boost.Spirit documentation] | |
383 | ||
384 | Note that this is only available when using BoostBook, and only for links | |
385 | - it can't be used for images. | |
386 | ||
387 | [endsect] [/links] | |
388 | ||
389 | [#quickbook.ref.anchor_links] | |
390 | [section:anchor_links Anchor links] | |
391 | ||
392 | You can link within a document using: | |
393 | ||
394 | ``` | |
395 | [link document_id.section_id.normalized_header_text The link text] | |
396 | ``` | |
397 | ||
398 | See sections __section__ and __heading__ for more info. | |
399 | ||
400 | [endsect] [/anchor_links] | |
401 | ||
402 | [#quickbook.ref.refentry_links] | |
403 | [section:refentry_links refentry links] | |
404 | ||
405 | In addition, you can link internally to an XML refentry like: | |
406 | ||
407 | ``` | |
408 | [link xml.refentry The link text] | |
409 | ``` | |
410 | ||
411 | This gets converted into [^<link linkend="xml.refentry">The link text</link>]. | |
412 | ||
413 | Like URLs, the link text is optional. If this is not present, the link text will | |
414 | automatically be the refentry. Example: | |
415 | ||
416 | ``` | |
417 | [link xml.refentry] | |
418 | ``` | |
419 | ||
420 | This gets converted into [^<link linkend="xml.refentry">xml.refentry</link>]. | |
421 | ||
422 | [endsect] [/refentry_links] | |
423 | ||
424 | [#quickbook.ref.code_links] | |
425 | [section:code_links Code Links] | |
426 | ||
427 | If you want to link to a function, class, member, enum, concept, global, or header in | |
428 | the reference section, you can use: | |
429 | ||
430 | ``` | |
431 | [funcref fully::qualified::function_name The link text] | |
432 | [classref fully::qualified::class_name The link text] | |
433 | [memberref fully::qualified::member_name The link text] | |
434 | [enumref fully::qualified::enum_name The link text] | |
435 | [macroref MACRO_NAME The link text] | |
436 | [conceptref ConceptName The link text] | |
437 | [headerref path/to/header.hpp The link text] | |
438 | [globalref fully::qualified::global The link text] | |
439 | ``` | |
440 | ||
441 | Again, the link text is optional. If this is not present, the link text will | |
442 | automatically be the function, class, member, enum, macro, concept, global, or header name. | |
443 | Example: | |
444 | ||
445 | ``` | |
446 | [classref boost::bar::baz] | |
447 | ``` | |
448 | ||
449 | would have "boost::bar::baz" as the link text. | |
450 | ||
451 | [endsect] [/code_links] | |
452 | ||
453 | [#quickbook.ref.escape] | |
454 | [section:escape Escape] | |
455 | ||
456 | The escape mark-up is used when we don't want to do any processing. | |
457 | ||
458 | ``` | |
459 | ''' | |
460 | escape (no processing/formatting) | |
461 | ''' | |
462 | ``` | |
463 | ||
464 | Escaping allows us to pass XML markup to __boostbook__ or __docbook__. For example: | |
465 | ||
466 | ``` | |
467 | ''' | |
468 | <emphasis role="bold">This is direct XML markup</emphasis> | |
469 | ''' | |
470 | ``` | |
471 | ||
472 | ''' | |
473 | <emphasis role="bold">This is direct XML markup</emphasis> | |
474 | ''' | |
475 | ||
476 | [important Be careful when using the escape. The text must conform to | |
477 | __boostbook__/__docbook__ syntax.] | |
478 | ||
479 | [endsect] [/escape] | |
480 | ||
481 | [#quickbook.ref.single_char_escape] | |
482 | [section:single_char_escape Single char escape] | |
483 | ||
484 | The backslash may be used to escape a single punctuation character. The | |
485 | punctuation immediately after the backslash is passed without any processing. | |
486 | This is useful when we need to escape QuickBook punctuations such as `[` and `]`. | |
487 | For example, how do you escape the triple quote? Simple: [^\\'\\'\\'] | |
488 | ||
489 | ||
490 | `\n` has a special meaning. It is used to generate line breaks. | |
491 | ||
492 | [warning `\n` is now deprecated, use [link quickbook.ref.line_break `[br]`] | |
493 | instead. Although, use it sparingly as it can generated invalid docbook] | |
494 | ||
495 | The escaped space: `\ ` also has a special meaning. The escaped space is removed | |
496 | from the output. | |
497 | ||
498 | [endsect] [/single_char_escape] | |
499 | ||
500 | [#quickbook.ref.unicode_escape] | |
501 | [section:unicode_escape Unicode escape] | |
502 | ||
503 | You can enter any 16-bit unicode character by using `\u` followed by its 4 digit | |
504 | hexadecimal code, or a 32-bit character by using `\U` followed by an 8 digit | |
505 | hexadecimal code. eg. | |
506 | ||
507 | ``` | |
508 | \u03B1 + \u03B2 | |
509 | ``` | |
510 | ||
511 | will generate: | |
512 | ||
513 | [: | |
514 | \u03B1 + \u03B2 | |
515 | ] | |
516 | ||
517 | [endsect] [/unicode_escape] | |
518 | ||
519 | [#quickbook.ref.images] | |
520 | [section:images Images] | |
521 | ||
522 | ``` | |
523 | [$image.jpg] | |
524 | ``` | |
525 | ||
526 | From version 1.5, you can also use | |
527 | [@http://www.docbook.org/tdg/en/html/imagedata.html | |
528 | DocBook imagedata attributes]: | |
529 | ||
530 | ``` | |
531 | [$image.jpg [width 200in] [height 200in]] | |
532 | ``` | |
533 | ||
534 | [endsect] [/images] | |
535 | ||
536 | [#quickbook.ref.footnotes] | |
537 | [section:footnotes Footnotes] | |
538 | ||
539 | As of version 1.3, QuickBook supports footnotes. Just put the text of the | |
540 | footnote in a `[footnote]` block, and the text will be put at the bottom | |
541 | of the current page. For example, this: | |
542 | ||
543 | ``` | |
544 | [footnote A sample footnote] | |
545 | ``` | |
546 | ||
547 | will generate this[footnote A sample footnote]. | |
548 | ||
549 | [endsect] [/footnotes] | |
550 | ||
551 | [#quickbook.ref.macro_expansion] | |
552 | [section:macro_expansion Macro Expansion] | |
553 | ||
554 | ``` | |
555 | __a_macro_identifier__ | |
556 | ``` | |
557 | ||
558 | See __macros__ for details. | |
559 | ||
560 | [endsect] [/macro_expansion] | |
561 | ||
562 | [#quickbook.ref.template_expansion] | |
563 | [section:template_expansion Template Expansion] | |
564 | ||
565 | ``` | |
566 | [a_template_identifier] | |
567 | ``` | |
568 | ||
569 | See __templates__ for details. | |
570 | ||
571 | [endsect] [/template_expansion] | |
572 | ||
573 | [#quickbook.ref.cond] | |
574 | [section:cond Conditional Generation] | |
575 | ||
576 | Like C++ `#ifdef`, you can generate phrases depending on the presence of | |
577 | a macro. Example: | |
578 | ||
579 | ``` | |
580 | [? __to_be__ To be or not to be] | |
581 | ``` | |
582 | ||
583 | [? __to_be__ To be or not to be] | |
584 | ||
585 | Here, the phrase "To be or not to be" will only be generated if the | |
586 | macro symbol `__to_be__` has been previously defined. The phrase | |
587 | above will not do anything since we haven't defined `__to_be__`. | |
588 | Now, let's define the symbol: | |
589 | ||
590 | ``` | |
591 | [def __to_be__] | |
592 | ``` | |
593 | ||
594 | [def __to_be__] | |
595 | ||
596 | And try again: | |
597 | ||
598 | [? __to_be__ To be or not to be] | |
599 | ||
600 | Yes! | |
601 | ||
602 | [endsect] [/cond] |