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.7] 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 24will generate: 25 26['italic], [*bold], [_underline], [^teletype], [-strikethrough] 27 28Like all non-terminal phrase level elements, this can of course be nested: 29 30``` 31[*['bold-italic]] 32``` 33 34will generate: 35 36[*['bold-italic]] 37 38[endsect:font_styles] 39 40[#quickbook.ref.replaceable] 41[section:replaceable Replaceable] 42 43When you want content that may or must be replaced by the user, use the syntax: 44 45``` 46[~replacement] 47``` 48 49This 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 62will generate: 63 64["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein 65 66Note the proper left and right quote marks. Also, while you can simply use 67ordinary quote marks like "quoted", our quotation, above, will generate correct 68DocBook quotations (e.g. <quote>quoted</quote>). 69 70Like 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 74the true business precept.] 75``` 76 77will generate: 78 79["Here's the rule for bargains: ["Do other men, for they would do you.] 80That's the true business precept.] 81 82[endsect:quotations] 83 84[#quickbook.ref.simple_formatting] 85[section:simple_formatting Simple formatting] 86 87Simple markup for formatting text, common in many applications, is now supported: 88 89``` 90/italic/, *bold*, _underline_, =teletype= 91``` 92 93will generate: 94 95/italic/, *bold*, _underline_, =teletype= 96 97Unlike QuickBook's standard formatting scheme, the rules for simpler 98alternatives are much stricter[footnote Thanks to David Barrett, author of 99[@http://quinthar.com/qwikiwiki/index.php?page=Home Qwiki], for sharing 100these samples and teaching me these obscure formatting rules. I wasn't sure 101at all if __spirit__, being more or less a formal EBNF parser, can handle 102the 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 136As mentioned, simple markups cannot go past a single block. The text 137from "have" to "full" in the following paragraph will be rendered as 138bold: 139 140``` 141Baa baa black sheep, *have you any wool? 142Yes sir, yes sir, three bags full!* 143One for the master, one for the dame, 144And one for the little boy who lives down the lane. 145``` 146 147Baa baa black sheep, *have you any wool? 148Yes sir, yes sir, three bags full!* 149One for the master, one for the dame, 150And one for the little boy who lives down the lane. 151 152But in the following paragraph, bold is not applied: 153 154``` 155Baa baa black sheep, *have you any wool? 156Yes sir, yes sir, three bags full! 157One for the master, one for the dame, 158And one for the little boy who lives down the lane. 159``` 160 161Baa baa black sheep, *have you any wool? 162Yes sir, yes sir, three bags full! 163One for the master, one for the dame, 164And 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 171This generates a docbook phrase with a `role` attribute, which can be used 172to classify the phrase. This can be used to mark text for a use that isn't 173covered elsewhere. The docbook `role` will generate a html class, which can 174be used to style text. And the xsl stylesheets can be customized to treat 175certain roles specially when generating pdfs. 176 177The boostbook css stylesheets, and xsl stylesheets 178contain 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 183You'll get red text if you're using the boostbook css (for html) or 184the boostbook xsl for generating pdfs. 185 186The 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 207Inlining code in paragraphs is quite common when writing C++ documentation. We 208provide a very simple markup for this. For example, this: 209 210``` 211This text has inlined code `int main() { return 0; }` in it. 212``` 213 214will generate: 215 216This text has inlined code `int main() { return 0; }` in it. The code will be 217syntax highlighted. 218 219[note We simply enclose the code with the tick: [^"\`"], not the 220single 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 228Preformatted code simply starts with a space or a tab (See __code__). 229However, such a simple syntax cannot be used as phrase elements in lists 230(See __ordered_lists__ and __unordered_lists__), tables (See __tables__), 231etc. Inline code (see above) can. The problem is, inline code does not 232allow formatting with newlines, spaces, and tabs. These are lost. 233 234We provide a phrase level markup that is a mix between the two. By using the 235double-tick or triple-tick, instead of the single-tick, we are telling QuickBook 236to 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 250or: 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 264will 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 285If a document contains more than one type of source code then the source 286mode may be changed dynamically as the document is processed. All QuickBook 287documents are initially in C++ mode by default, though an alternative 288initial value may be set in the __document__ section. 289 290To change the source mode, use the [^\[source-mode\]] markup, where 291=source-mode= is one of the supported modes. For example, this: 292 293``` 294Python's [python] `import` is rather like C++'s [c++] `#include`. A 295C++ comment `// looks like this` whereas a Python comment [python] 296`# looks like this`. 297``` 298 299will generate: 300 301Python's [python] `import` is rather like C++'s [c++] `#include`. A 302C++ comment `// looks like this` whereas a Python comment [python] 303`#looks like this`. 304 305[teletype] 306 307Quickbook 1.7 introduced the `!` element which can be used to set the 308source mode of the following element: 309 310``` 311[teletype] 312Example in C++: [!c++] `int main() {}`, 313example with no highlighting: `int main() {}`. 314``` 315 316will generate: 317 318[teletype] 319Example in C++: [!c++] `int main() {}`, 320example with no highlighting: `int main() {}`. 321 322In order to change the source mode for a whole paragraph, put 323the `!` element on a separate line before the paragraph: 324 325``` 326[!c++] 327`int main() {}` is highlighted as C++, as is `//example`. 328 329[!c++] `int main() {}` is also highlighted as C++, 330but `//example` isn't. 331``` 332 333generates: 334 335[!c++] 336`int main() {}` is highlighted as C++, as is `//example`. 337 338[!c++] `int main() {}` is also highlighted as C++, 339but `//example` isn't. 340 341The `!` element can also be used to set the source mode for blocks 342and sections. For example: 343 344``` 345[!python] 346[section:python Section in which all code samples use python] 347 348[/...] 349 350[endsect:python] 351 352[!c++] 353[section:cpp Section in which all code samples use C++] 354 355[/...] 356 357[endsect:cpp] 358``` 359 360Or to set the source mode for a table: 361 362``` 363[!teletype] 364[table 365 [[code][meaning]] 366 [[`+`][addition]] 367] 368``` 369 370[teletype] 371 372[table Supported Source Modes 373 [[Mode] [Source Mode Markup]] 374 [[C++] [[^\[c++\]]]] 375 [[Python] [[^\[python\]]]] 376 [[Plain Text] [[^\[teletype\]]]] 377] 378 379[note The source mode strings are lowercase.] 380 381[endsect:source_mode] 382 383[#quickbook.ref.line_break] 384[section:line_break line-break] 385 386``` 387[br] 388``` 389 390[warning `[br]` generates invalid docbook. It seems to mostly work okay but 391there might be problems, especially when using an alternative docbook 392processor.] 393 394[endsect:line_break] 395 396[#quickbook.ref.anchors] 397[section:anchors Anchors] 398 399``` 400[#named_anchor] 401``` 402 403A named anchor is a hook that can be referenced by a link elsewhere in the 404document. You can then reference an anchor with `[link named_anchor 405Some link text]`. See __anchor_links__, __section__ and __heading__. 406 407These anchors are global and can be accessed from anywhere in the 408quickbook documentation. Be careful to avoid clashes with anchors in 409other sections. 410 411[endsect:anchors] 412 413[#quickbook.ref.links] 414[section:links Links] 415 416``` 417[@http://www.boost.org this is [*boost's] website....] 418``` 419 420will generate: 421 422[@http://www.boost.org this is [*boost's] website....] 423 424URL links where the link text is the link itself is common. Example: 425 426``` 427see http://spirit.sourceforge.net/ 428``` 429 430so, when the text is absent in a link markup, the URL is assumed. Example: 431 432``` 433see [@http://spirit.sourceforge.net/] 434``` 435 436will generate: 437 438see [@http://spirit.sourceforge.net/] 439 440Boostbook also support a custom url schema for linking to files within 441the boost distribution: 442 443``` 444[@boost:/libs/spirit/index.html the Boost.Spirit documentation] 445``` 446 447will generate: [@boost:/libs/spirit/index.html the Boost.Spirit documentation] 448 449Note that this is only available when using BoostBook, and only for links 450- it can't be used for images. 451 452[endsect:links] 453 454[#quickbook.ref.anchor_links] 455[section:anchor_links Anchor links] 456 457You can link within a document using: 458 459``` 460[link document_id.section_id.normalized_header_text The link text] 461``` 462 463See sections __section__ and __heading__ for more info. 464 465[endsect:anchor_links] 466 467[#quickbook.ref.refentry_links] 468[section:refentry_links refentry links] 469 470In addition, you can link internally to an XML refentry like: 471 472``` 473[link xml.refentry The link text] 474``` 475 476This gets converted into [^<link linkend="xml.refentry">The link text</link>]. 477 478Like URLs, the link text is optional. If this is not present, the link text will 479automatically be the refentry. Example: 480 481``` 482[link xml.refentry] 483``` 484 485This gets converted into [^<link linkend="xml.refentry">xml.refentry</link>]. 486 487[endsect:refentry_links] 488 489[#quickbook.ref.code_links] 490[section:code_links Code Links] 491 492If you want to link to a function, class, member, enum, concept, global, or header in 493the reference section, you can use: 494 495``` 496[funcref fully::qualified::function_name The link text] 497[classref fully::qualified::class_name The link text] 498[memberref fully::qualified::member_name The link text] 499[enumref fully::qualified::enum_name The link text] 500[macroref MACRO_NAME The link text] 501[conceptref ConceptName The link text] 502[headerref path/to/header.hpp The link text] 503[globalref fully::qualified::global The link text] 504``` 505 506Again, the link text is optional. If this is not present, the link text will 507automatically be the function, class, member, enum, macro, concept, global, or header name. 508Example: 509 510``` 511[classref boost::bar::baz] 512``` 513 514would have "boost::bar::baz" as the link text. 515 516[endsect:code_links] 517 518[#quickbook.ref.escape] 519[section:escape Escape] 520 521The escape mark-up is used when we don't want to do any processing. 522 523``` 524''' 525escape (no processing/formatting) 526''' 527``` 528 529Escaping allows us to pass XML markup to __boostbook__ or __docbook__. For example: 530 531``` 532''' 533<emphasis role="bold">This is direct XML markup</emphasis> 534''' 535``` 536 537''' 538<emphasis role="bold">This is direct XML markup</emphasis> 539''' 540 541[important Be careful when using the escape. The text must conform to 542__boostbook__/__docbook__ syntax.] 543 544[endsect:escape] 545 546[#quickbook.ref.single_char_escape] 547[section:single_char_escape Single char escape] 548 549The backslash may be used to escape a single punctuation character. The 550punctuation immediately after the backslash is passed without any processing. 551This is useful when we need to escape QuickBook punctuations such as `[` and `]`. 552For example, how do you escape the triple quote? Simple: [^\\'\\'\\'] 553 554 555`\n` has a special meaning. It is used to generate line breaks. 556 557[warning `\n` is now deprecated, use [link quickbook.ref.line_break `[br]`] 558instead. Although, use it sparingly as it can generated invalid docbook] 559 560The escaped space: `\ ` also has a special meaning. The escaped space is removed 561from the output. 562 563[endsect:single_char_escape] 564 565[#quickbook.ref.unicode_escape] 566[section:unicode_escape Unicode escape] 567 568You can enter any 16-bit unicode character by using `\u` followed by its 4 digit 569hexadecimal code, or a 32-bit character by using `\U` followed by an 8 digit 570hexadecimal code. eg. 571 572``` 573\u03B1 + \u03B2 574``` 575 576will generate: 577 578[: 579\u03B1 + \u03B2 580] 581 582[endsect:unicode_escape] 583 584[#quickbook.ref.images] 585[section:images Images] 586 587``` 588[$image.jpg] 589``` 590 591From version 1.5, you can also use 592[@http://www.docbook.org/tdg/en/html/imagedata.html 593DocBook imagedata attributes]: 594 595``` 596[$image.jpg [width 200in] [height 200in]] 597``` 598 599[endsect:images] 600 601[#quickbook.ref.footnotes] 602[section:footnotes Footnotes] 603 604As of version 1.3, QuickBook supports footnotes. Just put the text of the 605footnote in a `[footnote]` block, and the text will be put at the bottom 606of the current page. For example, this: 607 608``` 609[footnote A sample footnote] 610``` 611 612will generate this[footnote A sample footnote]. 613 614[endsect:footnotes] 615 616[#quickbook.ref.macro_expansion] 617[section:macro_expansion Macro Expansion] 618 619``` 620__a_macro_identifier__ 621``` 622 623See __macros__ for details. 624 625[endsect:macro_expansion] 626 627[#quickbook.ref.template_expansion] 628[section:template_expansion Template Expansion] 629 630``` 631[a_template_identifier] 632``` 633 634See __templates__ for details. 635 636[endsect:template_expansion] 637 638[#quickbook.ref.cond] 639[section:cond Conditional Generation] 640 641Like C++ `#ifdef`, you can generate phrases depending on the presence of 642a macro. Example: 643 644``` 645[? __to_be__ To be or not to be] 646``` 647 648Here, the phrase "To be or not to be" will only be generated if the 649macro symbol `__to_be__` has been previously defined. The phrase 650above will not do anything since we haven't defined `__to_be__`. 651Now, let's define the symbol: 652 653``` 654[def __to_be__] 655 656[? __to_be__ To be or not to be] 657``` 658 659Which results in: 660 661``` 662To be or not to be 663``` 664 665In quickbook 1.7, you can generate output when a macro isn't defined: 666 667``` 668[?! __to_be__ Not to be] 669``` 670 671 672[endsect:cond] 673