ceph/src/boost/tools/quickbook/doc/phrase.qbk

   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]