1<?xml version="1.0" encoding="UTF-8"?> 2<!DOCTYPE article PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> 3<article id="quickbook" last-revision="DEBUG MODE Date: 2000/12/20 12:00:00 $" xmlns:xi="http://www.w3.org/2001/XInclude"> 4 <title>Quickbook 1.4</title> 5 <articleinfo> 6 <authorgroup> 7 <author> 8 <firstname>Joel</firstname> <surname>de Guzman</surname> 9 </author> 10 <author> 11 <firstname>Eric</firstname> <surname>Niebler</surname> 12 </author> 13 </authorgroup> 14 <copyright> 15 <year>2002</year> <year>2004</year> <year>2006</year> <holder>Joel de Guzman, 16 Eric Niebler</holder> 17 </copyright> 18 <legalnotice id="quickbook.legal"> 19 <para> 20 Distributed under the Boost Software License, Version 1.0. (See accompanying 21 file LICENSE_1_0.txt or copy at <ulink url="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</ulink>) 22 </para> 23 </legalnotice> 24 <articlepurpose> 25 <emphasis>WikiWiki</emphasis> style documentation tool 26 </articlepurpose> 27 </articleinfo> 28 <section id="quickbook.intro"> 29 <title><link linkend="quickbook.intro">Introduction</link></title> 30 <blockquote> 31 <para> 32 <emphasis role="bold"><emphasis><quote>Why program by hand in five days what 33 you can spend five years of your life automating?</quote></emphasis></emphasis> 34 </para> 35 <para> 36 -- Terrence Parr, author ANTLR/PCCTS 37 </para> 38 </blockquote> 39 <para> 40 Well, QuickBook started as a weekend hack. It was originally intended to be 41 a sample application using <ulink url="http://spirit.sourceforge.net">Spirit</ulink>. 42 What is it? What you are viewing now, this documentation, is autogenerated 43 by QuickBook. These files were generated from one master: 44 </para> 45 <blockquote> 46 <para> 47 <ulink url="../quickbook.qbk">quickbook.qbk</ulink> 48 </para> 49 </blockquote> 50 <para> 51 Originally named QuickDoc, this funky tool that never dies evolved into a funkier 52 tool thanks to Eric Niebler who resurrected the project making it generate 53 <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink> 54 instead of HTML. The <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink> 55 documentation format is an extension of <ulink url="http://www.docbook.org/">DocBook</ulink>, 56 an SGML or XML based format for describing documentation. 57 </para> 58 <para> 59 QuickBook is a WikiWiki style documentation tool geared towards C++ documentation 60 using simple rules and markup for simple formatting tasks. QuickBook extends 61 the WikiWiki concept. Like the WikiWiki, QuickBook documents are simple text 62 files. A single QuickBook document can generate a fully linked set of nice 63 HTML and PostScript/PDF documents complete with images and syntax- colorized 64 source code. 65 </para> 66 <para> 67 Features include: 68 </para> 69 <itemizedlist> 70 <listitem> 71 <simpara> 72 generate <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink> 73 xml, to generate HTML, PostScript and PDF 74 </simpara> 75 </listitem> 76 <listitem> 77 <simpara> 78 simple markup to link to Doxygen-generated entities 79 </simpara> 80 </listitem> 81 <listitem> 82 <simpara> 83 macro system for simple text substitution 84 </simpara> 85 </listitem> 86 <listitem> 87 <simpara> 88 simple markup for italics, bold, preformatted, blurbs, code samples, tables, 89 URLs, anchors, images, etc. 90 </simpara> 91 </listitem> 92 <listitem> 93 <simpara> 94 automatic syntax coloring of code samples 95 </simpara> 96 </listitem> 97 <listitem> 98 <simpara> 99 CSS support 100 </simpara> 101 </listitem> 102 </itemizedlist> 103 </section> 104 <section id="quickbook.change_log"> 105 <title><link linkend="quickbook.change_log">Change Log</link></title> 106 <bridgehead renderas="sect3" id="quickbook.change_log.h0"> 107 <phrase id="quickbook.change_log.version_1_3"/><link linkend="quickbook.change_log.version_1_3">Version 108 1.3</link> 109 </bridgehead> 110 <itemizedlist> 111 <listitem> 112 <simpara> 113 Quickbook file inclusion [include]. 114 </simpara> 115 </listitem> 116 <listitem> 117 <simpara> 118 Better xml output (pretty layout). Check out the generated XML. 119 </simpara> 120 </listitem> 121 <listitem> 122 <simpara> 123 Regression testing facility: to make sure your document will always be 124 compatible (full backward compatibility) regardless of changes to QuickBook. 125 </simpara> 126 </listitem> 127 <listitem> 128 <simpara> 129 Code cleanup and refactoring. 130 </simpara> 131 </listitem> 132 <listitem> 133 <simpara> 134 Allow phrase markup in the doc-info. 135 </simpara> 136 </listitem> 137 <listitem> 138 <simpara> 139 Preformatted code blocks via ``code`` (double ticks) allows code in tables 140 and lists, for example. 141 </simpara> 142 </listitem> 143 <listitem> 144 <simpara> 145 Quickbook versioning; allows full backward compatibility. You have to add 146 [quickbook 1.3] to the doc-info header to enable the new features. Without 147 this, QuickBook will assume that the document is a pre-1.3 document. 148 </simpara> 149 </listitem> 150 <listitem> 151 <simpara> 152 Better (intuitive) paragraph termination. Some markups may terminate a 153 paragraph. Example: 154<programlisting><phrase role="special">[</phrase><phrase role="identifier">section</phrase> <phrase role="identifier">x</phrase><phrase role="special">]</phrase> 155<phrase role="identifier">blah</phrase><phrase role="special">...</phrase> 156<phrase role="special">[</phrase><phrase role="identifier">endsect</phrase><phrase role="special">]</phrase></programlisting> 157 </simpara> 158 </listitem> 159 <listitem> 160 <simpara> 161 Fully qualified section and headers. Subsection names are concatenated 162 to the ID to avoid clashing. Example: <code><phrase role="identifier">doc_name</phrase><phrase 163 role="special">.</phrase><phrase role="identifier">sect_name</phrase><phrase 164 role="special">.</phrase><phrase role="identifier">sub_sect_name</phrase><phrase 165 role="special">.</phrase><phrase role="identifier">sub_sub_sect_name</phrase></code> 166 </simpara> 167 </listitem> 168 <listitem> 169 <simpara> 170 Better &nbsp; and whitespace handling in code snippets. 171 </simpara> 172 </listitem> 173 <listitem> 174 <simpara> 175 [xinclude] fixes up the relative path to the target XML file when input_directory 176 is not the same as the output_directory. 177 </simpara> 178 </listitem> 179 <listitem> 180 <simpara> 181 Allow untitled tables. 182 </simpara> 183 </listitem> 184 <listitem> 185 <simpara> 186 Allow phrase markups in section titles. 187 </simpara> 188 </listitem> 189 <listitem> 190 <simpara> 191 Allow escaping back to QuickBook from code, code blocks and inline code. 192 </simpara> 193 </listitem> 194 <listitem> 195 <simpara> 196 Footnotes, with the [footnote This is the footnote] syntax. 197 </simpara> 198 </listitem> 199 <listitem> 200 <simpara> 201 Post-processor bug fix for escaped XML code that it does not recognize. 202 </simpara> 203 </listitem> 204 <listitem> 205 <simpara> 206 Replaceable, with the [~replacement] syntax. 207 </simpara> 208 </listitem> 209 <listitem> 210 <simpara> 211 Generic Headers 212 </simpara> 213 </listitem> 214 <listitem> 215 <simpara> 216 Code changes to allow full recursion (i.e. Collectors and push/pop functions) 217 </simpara> 218 </listitem> 219 <listitem> 220 <simpara> 221 Various code cleanup/maintenance 222 </simpara> 223 </listitem> 224 <listitem> 225 <simpara> 226 Templates! 227 </simpara> 228 </listitem> 229 <listitem> 230 <simpara> 231 [conceptref] for referencing BoostBook <concept> entities. 232 </simpara> 233 </listitem> 234 <listitem> 235 <simpara> 236 Allow escape of spaces. The escaped space is removed from the output. Syntax: 237 <code><phrase role="special">\</phrase> </code>. 238 </simpara> 239 </listitem> 240 <listitem> 241 <simpara> 242 Nested comments are now allowed. 243 </simpara> 244 </listitem> 245 <listitem> 246 <simpara> 247 Quickbook blocks can nest inside comments. 248 </simpara> 249 </listitem> 250 <listitem> 251 <simpara> 252 <link linkend="quickbook.syntax.block.import">Import</link> facility. 253 </simpara> 254 </listitem> 255 <listitem> 256 <simpara> 257 Callouts on imported code 258 </simpara> 259 </listitem> 260 <listitem> 261 <simpara> 262 Simple markups can now span a whole block. 263 </simpara> 264 </listitem> 265 <listitem> 266 <simpara> 267 <link linkend="quickbook.syntax.block.blurbs">Blurbs</link>, <link linkend="quickbook.syntax.block.admonitions">Admonitions</link> 268 and table cells (see <link linkend="quickbook.syntax.block.tables">Tables</link>) 269 may now contain paragraphs. 270 </simpara> 271 </listitem> 272 <listitem> 273 <simpara> 274 <code><phrase role="special">\</phrase><phrase role="identifier">n</phrase></code> 275 and <code><phrase role="special">[</phrase><phrase role="identifier">br</phrase><phrase 276 role="special">]</phrase></code> are now deprecated. 277 </simpara> 278 </listitem> 279 </itemizedlist> 280 </section> 281 <section id="quickbook.syntax"> 282 <title><link linkend="quickbook.syntax">Syntax Summary</link></title> 283 <para> 284 A QuickBook document is composed of one or more blocks. An example of a block 285 is the paragraph or a C++ code snippet. Some blocks have special mark-ups. 286 Blocks, except code snippets which have their own grammar (C++ or Python), 287 are composed of one or more phrases. A phrase can be a simple contiguous run 288 of characters. Phrases can have special mark-ups. Marked up phrases can recursively 289 contain other phrases, but cannot contain blocks. A terminal is a self contained 290 block-level or phrase-level element that does not nest anything. 291 </para> 292 <para> 293 Blocks, in general, are delimited by two end-of-lines (the block terminator). 294 Phrases in each block cannot contain a block terminator. This way, syntax errors 295 such as un-matched closing brackets do not go haywire and corrupt anything 296 past a single block. 297 </para> 298 <section id="quickbook.syntax.comments"> 299 <title><link linkend="quickbook.syntax.comments">Comments</link></title> 300 <para> 301 Can be placed anywhere. 302 </para> 303<programlisting><!--quickbook-escape-prefix-->[/ comment (no output generated) ]<!--quickbook-escape-postfix--> 304</programlisting> 305<programlisting><!--quickbook-escape-prefix-->[/ comments can be nested [/ some more here] ]<!--quickbook-escape-postfix--> 306</programlisting> 307<programlisting><!--quickbook-escape-prefix-->[/ Quickbook blocks can nest inside comments. [*Comment this out too!] ]<!--quickbook-escape-postfix--> 308</programlisting> 309 </section> 310 <section id="quickbook.syntax.phrase"> 311 <title><link linkend="quickbook.syntax.phrase">Phrase Level Elements</link></title> 312 <section id="quickbook.syntax.phrase.font_styles"> 313 <title><link linkend="quickbook.syntax.phrase.font_styles">Font Styles</link></title> 314<programlisting><!--quickbook-escape-prefix-->['italic], [*bold], [_underline], [^teletype], [-strikethrough] 315<!--quickbook-escape-postfix--></programlisting> 316 <para> 317 will generate: 318 </para> 319 <para> 320 <emphasis>italic</emphasis>, <emphasis role="bold">bold</emphasis>, <emphasis 321 role="underline">underline</emphasis>, <literal>teletype</literal>, <emphasis 322 role="strikethrough">strikethrough</emphasis> 323 </para> 324 <para> 325 Like all non-terminal phrase level elements, this can of course be nested: 326 </para> 327<programlisting><!--quickbook-escape-prefix-->[*['bold-italic]] 328<!--quickbook-escape-postfix--></programlisting> 329 <para> 330 will generate: 331 </para> 332 <para> 333 <emphasis role="bold"><emphasis>bold-italic</emphasis></emphasis> 334 </para> 335 </section> 336 <section id="quickbook.syntax.phrase.replaceable"> 337 <title><link linkend="quickbook.syntax.phrase.replaceable">Replaceable</link></title> 338 <para> 339 When you want content that may or must be replaced by the user, use the 340 syntax: 341 </para> 342<programlisting><!--quickbook-escape-prefix-->[~replacement] 343<!--quickbook-escape-postfix--></programlisting> 344 <para> 345 This will generate: 346 </para> 347 <para> 348 <replaceable>replacement</replaceable> 349 </para> 350 </section> 351 <section id="quickbook.syntax.phrase.quotations"> 352 <title><link linkend="quickbook.syntax.phrase.quotations">Quotations</link></title> 353<programlisting><!--quickbook-escape-prefix-->["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein 354<!--quickbook-escape-postfix--></programlisting> 355 <para> 356 will generate: 357 </para> 358 <para> 359 <quote>A question that sometimes drives me hazy: am I or are the others 360 crazy?</quote>--Einstein 361 </para> 362 <para> 363 Note the proper left and right quote marks. Also, while you can simply 364 use ordinary quote marks like "quoted", our quotation, above, 365 will generate correct DocBook quotations (e.g. <quote>quoted</quote>). 366 </para> 367 <para> 368 Like all phrase elements, quotations may be nested. Example: 369 </para> 370<programlisting><!--quickbook-escape-prefix-->["Here's the rule for bargains: ["Do other men, for they would do you.] That's 371the true business precept.] 372<!--quickbook-escape-postfix--></programlisting> 373 <para> 374 will generate: 375 </para> 376 <para> 377 <quote>Here's the rule for bargains: <quote>Do other men, for they would 378 do you.</quote> That's the true business precept.</quote> 379 </para> 380 </section> 381 <section id="quickbook.syntax.phrase.simple_formatting"> 382 <title><link linkend="quickbook.syntax.phrase.simple_formatting">Simple formatting</link></title> 383 <para> 384 Simple markup for formatting text, common in many applications, is now 385 supported: 386 </para> 387<programlisting><!--quickbook-escape-prefix-->/italic/, *bold*, _underline_, =teletype= 388<!--quickbook-escape-postfix--></programlisting> 389 <para> 390 will generate: 391 </para> 392 <para> 393 <emphasis>italic</emphasis>, <emphasis role="bold">bold</emphasis>, <emphasis 394 role="underline">underline</emphasis>, <literal>teletype</literal> 395 </para> 396 <para> 397 Unlike QuickBook's standard formatting scheme, the rules for simpler alternatives 398 are much stricter<footnote id="quickbook.syntax.phrase.simple_formatting.f0"> 399 <para> 400 Thanks to David Barrett, author of <ulink url="http://quinthar.com/qwikiwiki/index.php?page=Home">Qwiki</ulink>, 401 for sharing these samples and teaching me these obscure formatting rules. 402 I wasn't sure at all if <ulink url="http://spirit.sourceforge.net">Spirit</ulink>, 403 being more or less a formal EBNF parser, can handle the context sensitivity 404 and ambiguity. 405 </para> 406 </footnote>. 407 </para> 408 <itemizedlist> 409 <listitem> 410 <simpara> 411 Simple markups cannot nest. You can combine a simple markup with a 412 nestable markup. 413 </simpara> 414 </listitem> 415 <listitem> 416 <simpara> 417 Simple markups cannot contain any other form of quickbook markup. 418 </simpara> 419 </listitem> 420 <listitem> 421 <simpara> 422 A non-space character must follow the leading markup 423 </simpara> 424 </listitem> 425 <listitem> 426 <simpara> 427 A non-space character must precede the trailing markup 428 </simpara> 429 </listitem> 430 <listitem> 431 <simpara> 432 A space or a punctuation must follow the trailing markup 433 </simpara> 434 </listitem> 435 <listitem> 436 <simpara> 437 If the matching markup cannot be found within a block, the formatting 438 will not be applied. This is to ensure that un-matched formatting markups, 439 which can be a common mistake, does not corrupt anything past a single 440 block. We do not want the rest of the document to be rendered bold 441 just because we forgot a trailing '*'. A single block is terminated 442 by two end of lines or the close bracket: ']'. 443 </simpara> 444 </listitem> 445 <listitem> 446 <simpara> 447 A line starting with the star will be interpreted as an unordered list. 448 See <link linkend="quickbook.syntax.block.lists.unordered_lists">Unordered 449 lists</link>. 450 </simpara> 451 </listitem> 452 </itemizedlist> 453 <table frame="all" id="quickbook.syntax.phrase.simple_formatting.t0"> 454 <title>More Formatting Samples</title> 455 <tgroup cols="2"> 456 <thead> 457 <row> 458 <entry> 459 <para> 460 Markup 461 </para> 462 </entry> 463 <entry> 464 <para> 465 Result 466 </para> 467 </entry> 468 </row> 469 </thead> 470 <tbody> 471 <row> 472 <entry> 473 <para> 474 <literal>*Bold*</literal> 475 </para> 476 </entry> 477 <entry> 478 <para> 479 <emphasis role="bold">Bold</emphasis> 480 </para> 481 </entry> 482 </row> 483 <row> 484 <entry> 485 <para> 486 <literal>*Is bold*</literal> 487 </para> 488 </entry> 489 <entry> 490 <para> 491 <emphasis role="bold">Is bold</emphasis> 492 </para> 493 </entry> 494 </row> 495 <row> 496 <entry> 497 <para> 498 <literal>* Not bold* *Not bold * * Not bold *</literal> 499 </para> 500 </entry> 501 <entry> 502 <para> 503 * Not bold* *Not bold * * Not bold * 504 </para> 505 </entry> 506 </row> 507 <row> 508 <entry> 509 <para> 510 <literal>This*Isn't*Bold (no bold)</literal> 511 </para> 512 </entry> 513 <entry> 514 <para> 515 This*Isn't*Bold (no bold) 516 </para> 517 </entry> 518 </row> 519 <row> 520 <entry> 521 <para> 522 <literal>(*Bold Inside*) (parenthesis not bold)</literal> 523 </para> 524 </entry> 525 <entry> 526 <para> 527 (<emphasis role="bold">Bold Inside</emphasis>) (parenthesis not 528 bold) 529 </para> 530 </entry> 531 </row> 532 <row> 533 <entry> 534 <para> 535 <literal>*(Bold Outside)* (parenthesis bold)</literal> 536 </para> 537 </entry> 538 <entry> 539 <para> 540 <emphasis role="bold">(Bold Outside)</emphasis> (parenthesis 541 bold) 542 </para> 543 </entry> 544 </row> 545 <row> 546 <entry> 547 <para> 548 <literal>3*4*5 = 60 (no bold)</literal> 549 </para> 550 </entry> 551 <entry> 552 <para> 553 3*4*5 = 60 (no bold) 554 </para> 555 </entry> 556 </row> 557 <row> 558 <entry> 559 <para> 560 <literal>3 * 4 * 5 = 60 (no bold)</literal> 561 </para> 562 </entry> 563 <entry> 564 <para> 565 3 * 4 * 5 = 60 (no bold) 566 </para> 567 </entry> 568 </row> 569 <row> 570 <entry> 571 <para> 572 <literal>3 *4* 5 = 60 (4 is bold)</literal> 573 </para> 574 </entry> 575 <entry> 576 <para> 577 3 <emphasis role="bold">4</emphasis> 5 = 60 (4 is bold) 578 </para> 579 </entry> 580 </row> 581 <row> 582 <entry> 583 <para> 584 <literal>*This is bold* this is not *but this is*</literal> 585 </para> 586 </entry> 587 <entry> 588 <para> 589 <emphasis role="bold">This is bold</emphasis> this is not <emphasis 590 role="bold">but this is</emphasis> 591 </para> 592 </entry> 593 </row> 594 <row> 595 <entry> 596 <para> 597 <literal>*This is bold*.</literal> 598 </para> 599 </entry> 600 <entry> 601 <para> 602 <emphasis role="bold">This is bold</emphasis>. 603 </para> 604 </entry> 605 </row> 606 <row> 607 <entry> 608 <para> 609 <literal>*B*. (bold B)</literal> 610 </para> 611 </entry> 612 <entry> 613 <para> 614 <emphasis role="bold">B</emphasis>. (bold B) 615 </para> 616 </entry> 617 </row> 618 <row> 619 <entry> 620 <para> 621 <literal>['*Bold-Italic*]</literal> 622 </para> 623 </entry> 624 <entry> 625 <para> 626 <emphasis><emphasis role="bold">Bold-Italic</emphasis></emphasis> 627 </para> 628 </entry> 629 </row> 630 <row> 631 <entry> 632 <para> 633 <literal>*side-by*/-side/</literal> 634 </para> 635 </entry> 636 <entry> 637 <para> 638 <emphasis role="bold">side-by</emphasis><emphasis>-side</emphasis> 639 </para> 640 </entry> 641 </row> 642 </tbody> 643 </tgroup> 644 </table> 645 <para> 646 As mentioned, simple markups cannot go past a single block. The text from 647 "have" to "full" in the following paragraph will be 648 rendered as bold: 649 </para> 650<programlisting><!--quickbook-escape-prefix-->Baa baa black sheep, *have you any wool? 651Yes sir, yes sir, three bags full!* 652One for the master, one for the dame, 653And one for the little boy who lives down the lane. 654<!--quickbook-escape-postfix--></programlisting> 655 <para> 656 Baa baa black sheep, <emphasis role="bold">have you any wool? Yes sir, 657 yes sir, three bags full!</emphasis> One for the master, one for the dame, 658 And one for the little boy who lives down the lane. 659 </para> 660 <para> 661 But in the following paragraph, bold is not applied: 662 </para> 663<programlisting><!--quickbook-escape-prefix-->Baa baa black sheep, *have you any wool? 664Yes sir, yes sir, three bags full! 665One for the master, one for the dame, 666And one for the little boy who lives down the lane. 667<!--quickbook-escape-postfix--></programlisting> 668 <para> 669 Baa baa black sheep, *have you any wool? Yes sir, yes sir, three bags full! 670 One for the master, one for the dame, And one for the little boy who lives 671 down the lane. 672 </para> 673 </section> 674 <section id="quickbook.syntax.phrase.inline_code"> 675 <title><link linkend="quickbook.syntax.phrase.inline_code">Inline code</link></title> 676 <para> 677 Inlining code in paragraphs is quite common when writing C++ documentation. 678 We provide a very simple markup for this. For example, this: 679 </para> 680<programlisting><!--quickbook-escape-prefix-->This text has inlined code `int main() { return 0; }` in it. 681<!--quickbook-escape-postfix--></programlisting> 682 <para> 683 will generate: 684 </para> 685 <para> 686 This text has inlined code <code><phrase role="keyword">int</phrase> <phrase 687 role="identifier">main</phrase><phrase role="special">()</phrase> <phrase 688 role="special">{</phrase> <phrase role="keyword">return</phrase> <phrase 689 role="number">0</phrase><phrase role="special">;</phrase> <phrase role="special">}</phrase></code> 690 in it. The code will be syntax highlighted. 691 </para> 692 <note> 693 <para> 694 We simply enclose the code with the tick: <literal>"`"</literal>, not the 695 single quote: <code><phrase role="string">"'"</phrase></code>. 696 Note too that <literal>`some code`</literal> is preferred over <literal>[^some code]</literal>. 697 </para> 698 </note> 699 </section> 700 <section id="quickbook.syntax.phrase.code_blocks"> 701 <title><link linkend="quickbook.syntax.phrase.code_blocks">Code blocks</link></title> 702 <para> 703 Preformatted code simply starts with a space or a tab (See <link linkend="quickbook.syntax.block.code">Code</link>). 704 However, such a simple syntax cannot be used as phrase elements in lists 705 (See <link linkend="quickbook.syntax.block.lists.ordered_lists">Ordered 706 lists</link> and <link linkend="quickbook.syntax.block.lists.unordered_lists">Unordered 707 lists</link>), tables (See <link linkend="quickbook.syntax.block.tables">Tables</link>), 708 etc. Inline code (see above) can. The problem is, inline code does not 709 allow formatting with newlines, spaces, and tabs. These are lost. 710 </para> 711 <para> 712 We provide a phrase level markup that is a mix between the two. By using 713 the double-tick, instead of the single-tick, we are telling QuickBook to 714 use preformatted blocks of code. Example: 715 </para> 716<programlisting>`` 717 #include <iostream> 718 719 int main() 720 { 721 std::cout << "Hello, World!" << std::endl; 722 return 0; 723 } 724`` 725</programlisting> 726 <para> 727 will generate: 728 </para> 729 <para> 730<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">iostream</phrase><phrase role="special">></phrase> 731 732<phrase role="keyword">int</phrase> <phrase role="identifier">main</phrase><phrase role="special">()</phrase> 733<phrase role="special">{</phrase> 734 <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="string">"Hello, World!"</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase> 735 <phrase role="keyword">return</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase> 736<phrase role="special">}</phrase> 737</programlisting> 738 </para> 739 </section> 740 <section id="quickbook.syntax.phrase.source_mode"> 741 <title><link linkend="quickbook.syntax.phrase.source_mode">Source Mode</link></title> 742 <para> 743 If a document contains more than one type of source code then the source 744 mode may be changed dynamically as the document is processed. All QuickBook 745 documents are initially in C++ mode by default, though an alternative initial 746 value may be set in the <link linkend="quickbook.syntax.block.document">Document</link> 747 section. 748 </para> 749 <para> 750 To change the source mode, use the <literal>[source-mode]</literal> markup, 751 where <literal>source-mode</literal> is one of the supported modes. For 752 example, this: 753 </para> 754<programlisting><!--quickbook-escape-prefix-->Python's [python] `import` is rather like C++'s [c++] `#include`. A 755C++ comment `// looks like this` whereas a Python comment [python] 756`# looks like this`. 757<!--quickbook-escape-postfix--></programlisting> 758 <para> 759 will generate: 760 </para> 761 <para> 762 Python's <code><phrase role="keyword">import</phrase></code> is rather 763 like C++'s <code><phrase role="preprocessor">#include</phrase></code>. 764 A C++ comment <code><phrase role="comment">// looks like this</phrase></code> 765 whereas a Python comment <code><phrase role="comment">#looks like this</phrase></code>. 766 </para> 767 <table frame="all" id="quickbook.syntax.phrase.source_mode.t0"> 768 <title>Supported Source Modes</title> 769 <tgroup cols="2"> 770 <thead> 771 <row> 772 <entry> 773 <para> 774 Mode 775 </para> 776 </entry> 777 <entry> 778 <para> 779 Source Mode Markup 780 </para> 781 </entry> 782 </row> 783 </thead> 784 <tbody> 785 <row> 786 <entry> 787 <para> 788 C++ 789 </para> 790 </entry> 791 <entry> 792 <para> 793 <literal>[c++]</literal> 794 </para> 795 </entry> 796 </row> 797 <row> 798 <entry> 799 <para> 800 Python 801 </para> 802 </entry> 803 <entry> 804 <para> 805 <literal>[python]</literal> 806 </para> 807 </entry> 808 </row> 809 </tbody> 810 </tgroup> 811 </table> 812 <note> 813 <para> 814 The source mode strings are lowercase. 815 </para> 816 </note> 817 </section> 818 <section id="quickbook.syntax.phrase.line_break"> 819 <title><link linkend="quickbook.syntax.phrase.line_break">line-break</link></title> 820<programlisting><!--quickbook-escape-prefix-->[br] 821<!--quickbook-escape-postfix--></programlisting> 822 <warning> 823 <para> 824 <code><phrase role="special">[</phrase><phrase role="identifier">br</phrase><phrase 825 role="special">]</phrase></code> is now deprecated. <link linkend="quickbook.syntax.block.blurbs">Blurbs</link>, 826 <link linkend="quickbook.syntax.block.admonitions">Admonitions</link> 827 and table cells (see <link linkend="quickbook.syntax.block.tables">Tables</link>) 828 may now contain paragraphs. 829 </para> 830 </warning> 831 </section> 832 <section id="quickbook.syntax.phrase.anchors"> 833 <title><link linkend="quickbook.syntax.phrase.anchors">Anchors</link></title> 834<programlisting><!--quickbook-escape-prefix-->[#named_anchor] 835<!--quickbook-escape-postfix--></programlisting> 836 <para> 837 A named anchor is a hook that can be referenced by a link elsewhere in 838 the document. You can then reference an anchor with <literal>[link named_anchor 839Some link text]</literal>. 840 See <link linkend="quickbook.syntax.phrase.anchor_links">Anchor links</link>, 841 <link linkend="quickbook.syntax.block.section">Section</link> and <link 842 linkend="quickbook.syntax.block.headings">Heading</link>. 843 </para> 844 </section> 845 <section id="quickbook.syntax.phrase.links"> 846 <title><link linkend="quickbook.syntax.phrase.links">Links</link></title> 847<programlisting><!--quickbook-escape-prefix-->[@http://www.boost.org this is [*boost's] website....] 848<!--quickbook-escape-postfix--></programlisting> 849 <para> 850 will generate: 851 </para> 852 <para> 853 <ulink url="http://www.boost.org">this is <emphasis role="bold">boost's</emphasis> 854 website....</ulink> 855 </para> 856 <para> 857 URL links where the link text is the link itself is common. Example: 858 </para> 859<programlisting><!--quickbook-escape-prefix-->see http://spirit.sourceforge.net/ 860<!--quickbook-escape-postfix--></programlisting> 861 <para> 862 so, when the text is absent in a link markup, the URL is assumed. Example: 863 </para> 864<programlisting>see <!--quickbook-escape-prefix-->[@http://spirit.sourceforge.net/]<!--quickbook-escape-postfix--> 865</programlisting> 866 <para> 867 will generate: 868 </para> 869 <para> 870 see <ulink url="http://spirit.sourceforge.net/">http://spirit.sourceforge.net/</ulink> 871 </para> 872 </section> 873 <section id="quickbook.syntax.phrase.anchor_links"> 874 <title><link linkend="quickbook.syntax.phrase.anchor_links">Anchor links</link></title> 875 <para> 876 You can link within a document using: 877 </para> 878<programlisting><!--quickbook-escape-prefix-->[link section_id.normalized_header_text The link text] 879<!--quickbook-escape-postfix--></programlisting> 880 <para> 881 See sections <link linkend="quickbook.syntax.block.section">Section</link> 882 and <link linkend="quickbook.syntax.block.headings">Heading</link> for 883 more info. 884 </para> 885 </section> 886 <section id="quickbook.syntax.phrase.refentry_links"> 887 <title><link linkend="quickbook.syntax.phrase.refentry_links">refentry links</link></title> 888 <para> 889 In addition, you can link internally to an XML refentry like: 890 </para> 891<programlisting><!--quickbook-escape-prefix-->[link xml.refentry The link text] 892<!--quickbook-escape-postfix--></programlisting> 893 <para> 894 This gets converted into <literal><link linkend="xml.refentry">The 895 link text</link></literal>. 896 </para> 897 <para> 898 Like URLs, the link text is optional. If this is not present, the link 899 text will automatically be the refentry. Example: 900 </para> 901<programlisting><!--quickbook-escape-prefix-->[link xml.refentry] 902<!--quickbook-escape-postfix--></programlisting> 903 <para> 904 This gets converted into <literal><link linkend="xml.refentry">xml.refentry</link></literal>. 905 </para> 906 </section> 907 <section id="quickbook.syntax.phrase.code_links"> 908 <title><link linkend="quickbook.syntax.phrase.code_links">Code Links</link></title> 909 <para> 910 If you want to link to a function, class, member, enum, concept or header 911 in the reference section, you can use: 912 </para> 913<programlisting><!--quickbook-escape-prefix-->[funcref fully::qualified::function_name The link text] 914[classref fully::qualified::class_name The link text] 915[memberref fully::qualified::member_name The link text] 916[enumref fully::qualified::enum_name The link text] 917[macroref MACRO_NAME The link text] 918[conceptref ConceptName The link text] 919[headerref path/to/header.hpp The link text] 920<!--quickbook-escape-postfix--></programlisting> 921 <para> 922 Again, the link text is optional. If this is not present, the link text 923 will automatically be the function, class, member, enum, macro, concept 924 or header. Example: 925 </para> 926<programlisting><!--quickbook-escape-prefix-->[classref boost::bar::baz] 927<!--quickbook-escape-postfix--></programlisting> 928 <para> 929 would have "boost::bar::baz" as the link text. 930 </para> 931 </section> 932 <section id="quickbook.syntax.phrase.escape"> 933 <title><link linkend="quickbook.syntax.phrase.escape">Escape</link></title> 934 <para> 935 The escape mark-up is used when we don't want to do any processing. 936 </para> 937<programlisting>''' 938escape (no processing/formatting) 939''' 940</programlisting> 941 <para> 942 Escaping allows us to pass XML markup to <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink> 943 or <ulink url="http://www.docbook.org/">DocBook</ulink>. For example: 944 </para> 945<programlisting>''' 946<emphasis role="bold">This is direct XML markup</emphasis> 947''' 948</programlisting> 949 <para> 950 <emphasis role="bold">This is direct XML markup</emphasis> 951 </para> 952 <important> 953 <para> 954 Be careful when using the escape. The text must conform to <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink>/<ulink 955 url="http://www.docbook.org/">DocBook</ulink> syntax. 956 </para> 957 </important> 958 </section> 959 <section id="quickbook.syntax.phrase.single_char_escape"> 960 <title><link linkend="quickbook.syntax.phrase.single_char_escape">Single 961 char escape</link></title> 962 <para> 963 The backslash may be used to escape a single punctuation character. The 964 punctuation immediately after the backslash is passed without any processing. 965 This is useful when we need to escape QuickBook punctuations such as <code><phrase 966 role="special">[</phrase></code> and <code><phrase role="special">]</phrase></code>. 967 For example, how do you escape the triple quote? Simple: <literal>\'\'\'</literal> 968 </para> 969 <para> 970 <code><phrase role="special">\</phrase><phrase role="identifier">n</phrase></code> 971 has a special meaning. It is used to generate line breaks. 972 </para> 973 <warning> 974 <para> 975 <code><phrase role="special">\</phrase><phrase role="identifier">n</phrase></code> 976 and <code><phrase role="special">[</phrase><phrase role="identifier">br</phrase><phrase 977 role="special">]</phrase></code> are now deprecated. <link linkend="quickbook.syntax.block.blurbs">Blurbs</link>, 978 <link linkend="quickbook.syntax.block.admonitions">Admonitions</link> 979 and table cells (see <link linkend="quickbook.syntax.block.tables">Tables</link>) 980 may now contain paragraphs. 981 </para> 982 </warning> 983 <para> 984 The escaped space: <code><phrase role="special">\</phrase> </code> also 985 has a special meaning. The escaped space is removed from the output. 986 </para> 987 </section> 988 <section id="quickbook.syntax.phrase.images"> 989 <title><link linkend="quickbook.syntax.phrase.images">Images</link></title> 990<programlisting><!--quickbook-escape-prefix-->[$image.jpg] 991<!--quickbook-escape-postfix--></programlisting> 992 </section> 993 <section id="quickbook.syntax.phrase.footnotes"> 994 <title><link linkend="quickbook.syntax.phrase.footnotes">Footnotes</link></title> 995 <para> 996 As of version 1.3, QuickBook supports footnotes. Just put the text of the 997 footnote in a <code><phrase role="special">[</phrase><phrase role="identifier">footnote</phrase><phrase 998 role="special">]</phrase></code> block, and the text will be put at the 999 bottom of the current page. For example, this: 1000 </para> 1001<programlisting><!--quickbook-escape-prefix-->[footnote A sample footnote] 1002<!--quickbook-escape-postfix--></programlisting> 1003 <para> 1004 will generate this<footnote id="quickbook.syntax.phrase.footnotes.f0"> 1005 <para> 1006 A sample footnote 1007 </para> 1008 </footnote>. 1009 </para> 1010 <section id="quickbook.syntax.phrase.footnotes.macro_expansion"> 1011 <title><link linkend="quickbook.syntax.phrase.footnotes.macro_expansion">Macro 1012 Expansion</link></title> 1013<programlisting><!--quickbook-escape-prefix-->__a_macro_identifier__ 1014<!--quickbook-escape-postfix--></programlisting> 1015 <para> 1016 See <link linkend="quickbook.syntax.block.macros">Macros</link> for details. 1017 </para> 1018 </section> 1019 <section id="quickbook.syntax.phrase.footnotes.template_expansion"> 1020 <title><link linkend="quickbook.syntax.phrase.footnotes.template_expansion">Template 1021 Expansion</link></title> 1022<programlisting><!--quickbook-escape-prefix-->[a_template_identifier] 1023<!--quickbook-escape-postfix--></programlisting> 1024 <para> 1025 See <link linkend="quickbook.syntax.block.templates">Templates</link> 1026 for details. 1027 </para> 1028 </section> 1029 </section> 1030 </section> 1031 <section id="quickbook.syntax.block"> 1032 <title><link linkend="quickbook.syntax.block">Block Level Elements</link></title> 1033 <section id="quickbook.syntax.block.document"> 1034 <title><link linkend="quickbook.syntax.block.document">Document</link></title> 1035 <para> 1036 Every document must begin with a Document Info section, which should look 1037 like this: 1038 </para> 1039<programlisting><!--quickbook-escape-prefix-->[document-type The Document Title 1040 [quickbook 1.3] 1041 [version 1.0] 1042 [id the_document_name] 1043 [dirname the_document_dir] 1044 [copyright 2000 2002 2003 Joe Blow, Jane Doe] 1045 [purpose The document's reason for being] 1046 [category The document's category] 1047 [authors [Blow, Joe], [Doe, Jane]] 1048 [license The document's license] 1049 [source-mode source-type] 1050] 1051<!--quickbook-escape-postfix--></programlisting> 1052 <para> 1053 Where document-type is one of: 1054 </para> 1055 <itemizedlist> 1056 <listitem> 1057 <simpara> 1058 book 1059 </simpara> 1060 </listitem> 1061 <listitem> 1062 <simpara> 1063 article 1064 </simpara> 1065 </listitem> 1066 <listitem> 1067 <simpara> 1068 library 1069 </simpara> 1070 </listitem> 1071 <listitem> 1072 <simpara> 1073 chapter 1074 </simpara> 1075 </listitem> 1076 <listitem> 1077 <simpara> 1078 part 1079 </simpara> 1080 </listitem> 1081 <listitem> 1082 <simpara> 1083 appendix 1084 </simpara> 1085 </listitem> 1086 <listitem> 1087 <simpara> 1088 preface 1089 </simpara> 1090 </listitem> 1091 <listitem> 1092 <simpara> 1093 qandadiv 1094 </simpara> 1095 </listitem> 1096 <listitem> 1097 <simpara> 1098 qandaset 1099 </simpara> 1100 </listitem> 1101 <listitem> 1102 <simpara> 1103 reference 1104 </simpara> 1105 </listitem> 1106 <listitem> 1107 <simpara> 1108 set 1109 </simpara> 1110 </listitem> 1111 </itemizedlist> 1112 <para> 1113 quickbook 1.3 declares the version of quickbook the document is written 1114 for. In its absence, version 1.1 is assumed. 1115 </para> 1116 <para> 1117 <literal>version</literal>, <literal>id</literal>, <literal>dirname</literal>, 1118 <literal>copyright</literal>, <literal>purpose</literal>, <literal>category</literal>, 1119 <literal>authors</literal>, <literal>license</literal>, <literal>last-revision</literal> 1120 and <literal>source-mode</literal> are optional information. 1121 </para> 1122 <para> 1123 <literal>source-type</literal> is a lowercase string setting the initial 1124 <link linkend="quickbook.syntax.phrase.source_mode">Source Mode</link>. 1125 If the <literal>source-mode</literal> field is omitted, a default value 1126 of <literal>c++</literal> will be used. 1127 </para> 1128 </section> 1129 <section id="quickbook.syntax.block.section"> 1130 <title><link linkend="quickbook.syntax.block.section">Section</link></title> 1131 <para> 1132 Starting a new section is accomplished with: 1133 </para> 1134<programlisting><!--quickbook-escape-prefix-->[section:id The Section Title] 1135<!--quickbook-escape-postfix--></programlisting> 1136 <para> 1137 where <emphasis>id</emphasis> is optional. id will be the filename of the 1138 generated section. If it is not present, "The Section Title" 1139 will be normalized and become the id. Valid characters are <literal>a-Z</literal>, 1140 <literal>A-Z</literal>, <literal>0-9</literal> and <literal>_</literal>. 1141 All non-valid characters are converted to underscore and all upper-case 1142 are converted to lower case. Thus: "The Section Title" will be 1143 normalized to "the_section_title". 1144 </para> 1145 <para> 1146 End a section with: 1147 </para> 1148<programlisting><!--quickbook-escape-prefix-->[endsect] 1149<!--quickbook-escape-postfix--></programlisting> 1150 <para> 1151 Sections can nest, and that results in a hierarchy in the table of contents. 1152 </para> 1153 </section> 1154 <section id="quickbook.syntax.block.xinclude"> 1155 <title><link linkend="quickbook.syntax.block.xinclude">xinclude</link></title> 1156 <para> 1157 You can include another XML file with: 1158 </para> 1159<programlisting><!--quickbook-escape-prefix-->[xinclude file.xml] 1160<!--quickbook-escape-postfix--></programlisting> 1161 <para> 1162 This is useful when file.xml has been generated by Doxygen and contains 1163 your reference section. 1164 </para> 1165 </section> 1166 <section id="quickbook.syntax.block.paragraphs"> 1167 <title><link linkend="quickbook.syntax.block.paragraphs">Paragraphs</link></title> 1168 <para> 1169 Paragraphs start left-flushed and are terminated by two or more newlines. 1170 No markup is needed for paragraphs. QuickBook automatically detects paragraphs 1171 from the context. Block markups [section, endsect, h1, h2, h3, h4, h5, 1172 h6, blurb, (block-quote) ':', pre, def, table and include ] may also terminate 1173 a paragraph. 1174 </para> 1175 </section> 1176 <section id="quickbook.syntax.block.lists"> 1177 <title><link linkend="quickbook.syntax.block.lists">Lists</link></title> 1178 <section id="quickbook.syntax.block.lists.ordered_lists"> 1179 <title><link linkend="quickbook.syntax.block.lists.ordered_lists">Ordered 1180 lists</link></title> 1181<programlisting># One 1182# Two 1183# Three 1184</programlisting> 1185 <para> 1186 will generate: 1187 </para> 1188 <orderedlist> 1189 <listitem> 1190 <simpara> 1191 One 1192 </simpara> 1193 </listitem> 1194 <listitem> 1195 <simpara> 1196 Two 1197 </simpara> 1198 </listitem> 1199 <listitem> 1200 <simpara> 1201 Three 1202 </simpara> 1203 </listitem> 1204 </orderedlist> 1205 </section> 1206 <section id="quickbook.syntax.block.lists.list_hierarchies"> 1207 <title><link linkend="quickbook.syntax.block.lists.list_hierarchies">List 1208 Hierarchies</link></title> 1209 <para> 1210 List hierarchies are supported. Example: 1211 </para> 1212<programlisting># One 1213# Two 1214# Three 1215 # Three.a 1216 # Three.b 1217 # Three.c 1218# Four 1219 # Four.a 1220 # Four.a.i 1221 # Four.a.ii 1222# Five 1223</programlisting> 1224 <para> 1225 will generate: 1226 </para> 1227 <orderedlist> 1228 <listitem> 1229 <simpara> 1230 One 1231 </simpara> 1232 </listitem> 1233 <listitem> 1234 <simpara> 1235 Two 1236 </simpara> 1237 </listitem> 1238 <listitem> 1239 <simpara> 1240 Three 1241 <orderedlist> 1242 <listitem> 1243 <simpara> 1244 Three.a 1245 </simpara> 1246 </listitem> 1247 <listitem> 1248 <simpara> 1249 Three.b 1250 </simpara> 1251 </listitem> 1252 <listitem> 1253 <simpara> 1254 Three.c 1255 </simpara> 1256 </listitem> 1257 </orderedlist> 1258 </simpara> 1259 </listitem> 1260 <listitem> 1261 <simpara> 1262 Fourth 1263 <orderedlist> 1264 <listitem> 1265 <simpara> 1266 Four.a 1267 <orderedlist> 1268 <listitem> 1269 <simpara> 1270 Four.a.i 1271 </simpara> 1272 </listitem> 1273 <listitem> 1274 <simpara> 1275 Four.a.ii 1276 </simpara> 1277 </listitem> 1278 </orderedlist> 1279 </simpara> 1280 </listitem> 1281 </orderedlist> 1282 </simpara> 1283 </listitem> 1284 <listitem> 1285 <simpara> 1286 Five 1287 </simpara> 1288 </listitem> 1289 </orderedlist> 1290 </section> 1291 <section id="quickbook.syntax.block.lists.long_list_lines"> 1292 <title><link linkend="quickbook.syntax.block.lists.long_list_lines">Long 1293 List Lines</link></title> 1294 <para> 1295 Long lines will be wrapped appropriately. Example: 1296 </para> 1297<programlisting># A short item. 1298# A very long item. A very long item. A very long item. 1299 A very long item. A very long item. A very long item. 1300 A very long item. A very long item. A very long item. 1301 A very long item. A very long item. A very long item. 1302 A very long item. A very long item. A very long item. 1303# A short item. 1304</programlisting> 1305 <orderedlist> 1306 <listitem> 1307 <simpara> 1308 A short item. 1309 </simpara> 1310 </listitem> 1311 <listitem> 1312 <simpara> 1313 A very long item. A very long item. A very long item. A very long 1314 item. A very long item. A very long item. A very long item. A very 1315 long item. A very long item. A very long item. A very long item. 1316 A very long item. A very long item. A very long item. A very long 1317 item. 1318 </simpara> 1319 </listitem> 1320 <listitem> 1321 <simpara> 1322 A short item. 1323 </simpara> 1324 </listitem> 1325 </orderedlist> 1326 </section> 1327 <section id="quickbook.syntax.block.lists.unordered_lists"> 1328 <title><link linkend="quickbook.syntax.block.lists.unordered_lists">Unordered 1329 lists</link></title> 1330<programlisting><!--quickbook-escape-prefix-->* First 1331* Second 1332* Third 1333<!--quickbook-escape-postfix--></programlisting> 1334 <para> 1335 will generate: 1336 </para> 1337 <itemizedlist> 1338 <listitem> 1339 <simpara> 1340 First 1341 </simpara> 1342 </listitem> 1343 <listitem> 1344 <simpara> 1345 Second 1346 </simpara> 1347 </listitem> 1348 <listitem> 1349 <simpara> 1350 Third 1351 </simpara> 1352 </listitem> 1353 </itemizedlist> 1354 </section> 1355 <section id="quickbook.syntax.block.lists.mixed_lists"> 1356 <title><link linkend="quickbook.syntax.block.lists.mixed_lists">Mixed lists</link></title> 1357 <para> 1358 Mixed lists (ordered and unordered) are supported. Example: 1359 </para> 1360<programlisting><!--quickbook-escape-prefix--># One 1361# Two 1362# Three 1363 * Three.a 1364 * Three.b 1365 * Three.c 1366# Four 1367<!--quickbook-escape-postfix--></programlisting> 1368 <para> 1369 will generate: 1370 </para> 1371 <orderedlist> 1372 <listitem> 1373 <simpara> 1374 One 1375 </simpara> 1376 </listitem> 1377 <listitem> 1378 <simpara> 1379 Two 1380 </simpara> 1381 </listitem> 1382 <listitem> 1383 <simpara> 1384 Three 1385 <itemizedlist> 1386 <listitem> 1387 <simpara> 1388 Three.a 1389 </simpara> 1390 </listitem> 1391 <listitem> 1392 <simpara> 1393 Three.b 1394 </simpara> 1395 </listitem> 1396 <listitem> 1397 <simpara> 1398 Three.c 1399 </simpara> 1400 </listitem> 1401 </itemizedlist> 1402 </simpara> 1403 </listitem> 1404 <listitem> 1405 <simpara> 1406 Four 1407 </simpara> 1408 </listitem> 1409 </orderedlist> 1410 <para> 1411 And... 1412 </para> 1413<programlisting><!--quickbook-escape-prefix--># 1 1414 * 1.a 1415 # 1.a.1 1416 # 1.a.2 1417 * 1.b 1418# 2 1419 * 2.a 1420 * 2.b 1421 # 2.b.1 1422 # 2.b.2 1423 * 2.b.2.a 1424 * 2.b.2.b 1425<!--quickbook-escape-postfix--></programlisting> 1426 <para> 1427 will generate: 1428 </para> 1429 <orderedlist> 1430 <listitem> 1431 <simpara> 1432 1 1433 <itemizedlist> 1434 <listitem> 1435 <simpara> 1436 1.a 1437 <orderedlist> 1438 <listitem> 1439 <simpara> 1440 1.a.1 1441 </simpara> 1442 </listitem> 1443 <listitem> 1444 <simpara> 1445 1.a.2 1446 </simpara> 1447 </listitem> 1448 </orderedlist> 1449 </simpara> 1450 </listitem> 1451 <listitem> 1452 <simpara> 1453 1.b 1454 </simpara> 1455 </listitem> 1456 </itemizedlist> 1457 </simpara> 1458 </listitem> 1459 <listitem> 1460 <simpara> 1461 2 1462 <itemizedlist> 1463 <listitem> 1464 <simpara> 1465 2.a 1466 </simpara> 1467 </listitem> 1468 <listitem> 1469 <simpara> 1470 2.b 1471 <orderedlist> 1472 <listitem> 1473 <simpara> 1474 2.b.1 1475 </simpara> 1476 </listitem> 1477 <listitem> 1478 <simpara> 1479 2.b.2 1480 <itemizedlist> 1481 <listitem> 1482 <simpara> 1483 2.b.2.a 1484 </simpara> 1485 </listitem> 1486 <listitem> 1487 <simpara> 1488 2.b.2.b 1489 </simpara> 1490 </listitem> 1491 </itemizedlist> 1492 </simpara> 1493 </listitem> 1494 </orderedlist> 1495 </simpara> 1496 </listitem> 1497 </itemizedlist> 1498 </simpara> 1499 </listitem> 1500 </orderedlist> 1501 </section> 1502 </section> 1503 <section id="quickbook.syntax.block.code"> 1504 <title><link linkend="quickbook.syntax.block.code">Code</link></title> 1505 <para> 1506 Preformatted code starts with a space or a tab. The code will be syntax 1507 highlighted according to the current <link linkend="quickbook.syntax.phrase.source_mode">Source 1508 Mode</link>: 1509 </para> 1510<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">iostream</phrase><phrase role="special">></phrase> 1511 1512<phrase role="keyword">int</phrase> <phrase role="identifier">main</phrase><phrase role="special">()</phrase> 1513<phrase role="special">{</phrase> 1514 <phrase role="comment">// Sample code</phrase> 1515 <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="string">"Hello, World\n"</phrase><phrase role="special">;</phrase> 1516 <phrase role="keyword">return</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase> 1517<phrase role="special">}</phrase> 1518</programlisting> 1519<programlisting><phrase role="keyword">import</phrase> <phrase role="identifier">cgi</phrase> 1520 1521<phrase role="keyword">def</phrase> <phrase role="identifier">cookForHtml</phrase><phrase role="special">(</phrase><phrase role="identifier">text</phrase><phrase role="special">):</phrase> 1522 <phrase role="string">'''"Cooks" the input text for HTML.'''</phrase> 1523 1524 <phrase role="keyword">return</phrase> <phrase role="identifier">cgi</phrase><phrase role="special">.</phrase><phrase role="identifier">escape</phrase><phrase role="special">(</phrase><phrase role="identifier">text</phrase><phrase role="special">)</phrase> 1525</programlisting> 1526 <para> 1527 Macros that are already defined are expanded in source code. Example: 1528 </para> 1529<programlisting><!--quickbook-escape-prefix-->[def __array__ [@http://www.boost.org/doc/html/array/reference.html array]] 1530[def __boost__ [@http://www.boost.org/libs/libraries.htm boost]] 1531 1532 using __boost__::__array__; 1533<!--quickbook-escape-postfix--></programlisting> 1534 <para> 1535 Generates: 1536 </para> 1537<programlisting><phrase role="keyword">using</phrase> <ulink url="http://www.boost.org/libs/libraries.htm">boost</ulink><phrase role="special">::</phrase><ulink url="http://www.boost.org/doc/html/array/reference.html">array</ulink><phrase role="special">;</phrase> 1538</programlisting> 1539 </section> 1540 <section id="quickbook.syntax.block.escape_back"> 1541 <title><link linkend="quickbook.syntax.block.escape_back">Escaping Back To 1542 QuickBook</link></title> 1543 <para> 1544 Inside code, code blocks and inline code, QuickBook does not allow any 1545 markup to avoid conflicts with the target syntax (e.g. c++). In case you 1546 need to switch back to QuickBook markup inside code, you can do so using 1547 a language specific <emphasis>escape-back</emphasis> delimiter. In C++ 1548 and Python, the delimiter is the double tick (back-quote): "``" 1549 and "``". Example: 1550 </para> 1551<programlisting><!--quickbook-escape-prefix-->void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``() 1552{ 1553} 1554<!--quickbook-escape-postfix--></programlisting> 1555 <para> 1556 Will generate: 1557 </para> 1558<programlisting><phrase role="keyword">void</phrase> <ulink url="http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz">foo</ulink><phrase role="special">()</phrase> 1559<phrase role="special">{</phrase> 1560<phrase role="special">}</phrase> 1561</programlisting> 1562 <para> 1563 When escaping from code to QuickBook, only phrase level markups are allowed. 1564 Block level markups like lists, tables etc. are not allowed. 1565 </para> 1566 </section> 1567 <section id="quickbook.syntax.block.preformatted"> 1568 <title><link linkend="quickbook.syntax.block.preformatted">Preformatted</link></title> 1569 <para> 1570 Sometimes, you don't want some preformatted text to be parsed as C++. In 1571 such cases, use the <literal>[pre ... ]</literal> markup block. 1572 </para> 1573<programlisting><!--quickbook-escape-prefix-->[pre 1574 1575 Some *preformatted* text Some *preformatted* text 1576 1577 Some *preformatted* text Some *preformatted* text 1578 1579 Some *preformatted* text Some *preformatted* text 1580 1581] 1582<!--quickbook-escape-postfix--></programlisting> 1583 <para> 1584 Spaces, tabs and newlines are rendered as-is. Unlike all quickbook block 1585 level markup, pre (and Code) are the only ones that allow multiple newlines. 1586 The markup above will generate: 1587 </para> 1588<programlisting>Some <emphasis role="bold">preformatted</emphasis> text Some <emphasis role="bold">preformatted</emphasis> text 1589 1590 Some <emphasis role="bold">preformatted</emphasis> text Some <emphasis role="bold">preformatted</emphasis> text 1591 1592 Some <emphasis role="bold">preformatted</emphasis> text Some <emphasis role="bold">preformatted</emphasis> text 1593 1594</programlisting> 1595 <para> 1596 Notice that unlike Code, phrase markup such as font style is still permitted 1597 inside <literal>pre</literal> blocks. 1598 </para> 1599 </section> 1600 <section id="quickbook.syntax.block.blockquote"> 1601 <title><link linkend="quickbook.syntax.block.blockquote">Blockquote</link></title> 1602<programlisting><!--quickbook-escape-prefix-->[:sometext...]<!--quickbook-escape-postfix--> 1603</programlisting> 1604 <blockquote> 1605 <para> 1606 Indents the paragraph. This applies to one paragraph only. 1607 </para> 1608 </blockquote> 1609 </section> 1610 <section id="quickbook.syntax.block.admonitions"> 1611 <title><link linkend="quickbook.syntax.block.admonitions">Admonitions</link></title> 1612<programlisting><!--quickbook-escape-prefix-->[note This is a note] 1613[tip This is a tip] 1614[important This is important] 1615[caution This is a caution] 1616[warning This is a warning] 1617<!--quickbook-escape-postfix--></programlisting> 1618 <para> 1619 generates <ulink url="http://www.docbook.org/">DocBook</ulink> admonitions: 1620 </para> 1621 <note> 1622 <para> 1623 This is a note 1624 </para> 1625 </note> 1626 <tip> 1627 <para> 1628 This is a tip 1629 </para> 1630 </tip> 1631 <important> 1632 <para> 1633 This is important 1634 </para> 1635 </important> 1636 <caution> 1637 <para> 1638 This is a caution 1639 </para> 1640 </caution> 1641 <warning> 1642 <para> 1643 This is a warning 1644 </para> 1645 </warning> 1646 <para> 1647 These are the only admonitions supported by <ulink url="http://www.docbook.org/">DocBook</ulink>. 1648 So, for example <literal>[information This is some information]</literal> 1649 is unlikely to produce the desired effect. 1650 </para> 1651 </section> 1652 <section id="quickbook.syntax.block.headings"> 1653 <title><link linkend="quickbook.syntax.block.headings">Headings</link></title> 1654<programlisting><!--quickbook-escape-prefix-->[h1 Heading 1] 1655[h2 Heading 2] 1656[h3 Heading 3] 1657[h4 Heading 4] 1658[h5 Heading 5] 1659[h6 Heading 6] 1660<!--quickbook-escape-postfix--></programlisting> 1661 <bridgehead renderas="sect1" id="quickbook.syntax.block.headings.h0"> 1662 <phrase id="quickbook.syntax.block.headings.heading_1"/><link linkend="quickbook.syntax.block.headings.heading_1">Heading 1663 1</link> 1664 </bridgehead> 1665 <bridgehead renderas="sect2" id="quickbook.syntax.block.headings.h1"> 1666 <phrase id="quickbook.syntax.block.headings.heading_2"/><link linkend="quickbook.syntax.block.headings.heading_2">Heading 1667 2</link> 1668 </bridgehead> 1669 <bridgehead renderas="sect3" id="quickbook.syntax.block.headings.h2"> 1670 <phrase id="quickbook.syntax.block.headings.heading_3"/><link linkend="quickbook.syntax.block.headings.heading_3">Heading 1671 3</link> 1672 </bridgehead> 1673 <bridgehead renderas="sect4" id="quickbook.syntax.block.headings.h3"> 1674 <phrase id="quickbook.syntax.block.headings.heading_4"/><link linkend="quickbook.syntax.block.headings.heading_4">Heading 1675 4</link> 1676 </bridgehead> 1677 <bridgehead renderas="sect5" id="quickbook.syntax.block.headings.h4"> 1678 <phrase id="quickbook.syntax.block.headings.heading_5"/><link linkend="quickbook.syntax.block.headings.heading_5">Heading 1679 5</link> 1680 </bridgehead> 1681 <bridgehead renderas="sect6" id="quickbook.syntax.block.headings.h5"> 1682 <phrase id="quickbook.syntax.block.headings.heading_6"/><link linkend="quickbook.syntax.block.headings.heading_6">Heading 1683 6</link> 1684 </bridgehead> 1685 <para> 1686 Headings 1-3 [h1 h2 and h3] will automatically have anchors with normalized 1687 names with <literal>name="section_id.normalized_header_text"</literal> 1688 (i.e. valid characters are <literal>a-z</literal>, <literal>A-Z</literal>, 1689 <literal>0-9</literal> and <literal>_</literal>. All non-valid characters 1690 are converted to underscore and all upper-case are converted to lower-case. 1691 For example: Heading 1 in section Section 2 will be normalized to <literal>section_2.heading_1</literal>). 1692 You can use: 1693 </para> 1694<programlisting><!--quickbook-escape-prefix-->[link section_id.normalized_header_text The link text] 1695<!--quickbook-escape-postfix--></programlisting> 1696 <para> 1697 to link to them. See <link linkend="quickbook.syntax.phrase.anchor_links">Anchor 1698 links</link> and <link linkend="quickbook.syntax.block.section">Section</link> 1699 for more info. 1700 </para> 1701 </section> 1702 <section id="quickbook.syntax.block.generic_heading"> 1703 <title><link linkend="quickbook.syntax.block.generic_heading">Generic Heading</link></title> 1704 <para> 1705 In cases when you don't want to care about the heading level (1 to 6), 1706 you can use the <emphasis>Generic Heading</emphasis>: 1707 </para> 1708<programlisting><!--quickbook-escape-prefix-->[heading Heading] 1709<!--quickbook-escape-postfix--></programlisting> 1710 <para> 1711 The <emphasis>Generic Heading</emphasis> assumes the level, plus one, of 1712 the innermost section where it is placed. For example, if it is placed 1713 in the outermost section, then, it assumes <emphasis>h2</emphasis>. 1714 </para> 1715 <para> 1716 Headings are often used as an alternative to sections. It is used particularly 1717 if you do not want to start a new section. In many cases, however, headings 1718 in a particular section is just flat. Example: 1719 </para> 1720<programlisting><!--quickbook-escape-prefix-->[section A] 1721[h2 X] 1722[h2 Y] 1723[h2 Z] 1724[endsect] 1725<!--quickbook-escape-postfix--></programlisting> 1726 <para> 1727 Here we use h2 assuming that section A is the outermost level. If it is 1728 placed in an inner level, you'll have to use h3, h4, etc. depending on 1729 where the section is. In general, it is the section level plus one. It 1730 is rather tedious, however, to scan the section level everytime. If you 1731 rewrite the example above as shown below, this will be automatic: 1732 </para> 1733<programlisting><!--quickbook-escape-prefix-->[section A] 1734[heading X] 1735[heading Y] 1736[heading Z] 1737[endsect] 1738<!--quickbook-escape-postfix--></programlisting> 1739 <para> 1740 They work well regardless where you place them. You can rearrange sections 1741 at will without any extra work to ensure correct heading levels. In fact, 1742 with <emphasis>section</emphasis> and <emphasis>heading</emphasis>, you 1743 have all you need. <emphasis>h1</emphasis>..<emphasis>h6</emphasis> becomes 1744 redundant. <emphasis>h1</emphasis>..<emphasis>h6</emphasis> might be deprecated 1745 in the future. 1746 </para> 1747 </section> 1748 <section id="quickbook.syntax.block.macros"> 1749 <title><link linkend="quickbook.syntax.block.macros">Macros</link></title> 1750<programlisting><!--quickbook-escape-prefix-->[def macro_identifier some text] 1751<!--quickbook-escape-postfix--></programlisting> 1752 <para> 1753 When a macro is defined, the identifier replaces the text anywhere in the 1754 file, in paragraphs, in markups, etc. macro_identifier is a string of non- 1755 white space characters except ']'. A macro may not follow an alphabetic 1756 character or the underscore. The replacement text can be any phrase (even 1757 marked up). Example: 1758 </para> 1759<programlisting><!--quickbook-escape-prefix-->[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&type=1]] 1760sf_logo 1761<!--quickbook-escape-postfix--></programlisting> 1762 <para> 1763 Now everywhere the sf_logo is placed, the picture will be inlined. 1764 </para> 1765 <para> 1766 <inlinemediaobject><imageobject><imagedata fileref="http://sourceforge.net/sflogo.php?group_id=28447&type=1"></imagedata></imageobject> 1767 <textobject> 1768 <phrase>sflogo</phrase> 1769 </textobject> 1770 </inlinemediaobject> 1771 </para> 1772 <tip> 1773 <para> 1774 It's a good idea to use macro identifiers that are distinguishable. For 1775 instance, in this document, macro identifiers have two leading and trailing 1776 underscores (e.g. <literal>__spirit__</literal>). The reason is to avoid unwanted 1777 macro replacement. 1778 </para> 1779 </tip> 1780 <para> 1781 Links (URLS) and images are good candidates for macros. <emphasis role="bold">1</emphasis>) 1782 They tend to change a lot. It is a good idea to place all links and images 1783 in one place near the top to make it easy to make changes. <emphasis role="bold">2</emphasis>) 1784 The syntax is not pretty. It's easier to read and write, e.g. <literal>__spirit__</literal> 1785 than <literal>[@http://spirit.sourceforge.net Spirit]</literal>. 1786 </para> 1787 <para> 1788 Some more examples: 1789 </para> 1790<programlisting><!--quickbook-escape-prefix-->[def :-) [$theme/smiley.png]] 1791[def __spirit__ [@http://spirit.sourceforge.net Spirit]] 1792<!--quickbook-escape-postfix--></programlisting> 1793 <para> 1794 (See <link linkend="quickbook.syntax.phrase.images">Images</link> and 1795 <link linkend="quickbook.syntax.phrase.links">Links</link>) 1796 </para> 1797 <para> 1798 Invoking these macros: 1799 </para> 1800<programlisting><!--quickbook-escape-prefix-->Hi __spirit__ :-) 1801<!--quickbook-escape-postfix--></programlisting> 1802 <para> 1803 will generate this: 1804 </para> 1805 <para> 1806 Hi <ulink url="http://spirit.sourceforge.net">Spirit</ulink> <inlinemediaobject><imageobject><imagedata 1807 fileref="images/smiley.png"></imagedata></imageobject> 1808 <textobject> 1809 <phrase>smiley</phrase> 1810 </textobject> 1811 </inlinemediaobject> 1812 </para> 1813 </section> 1814 <section id="quickbook.syntax.block.predefined_macros"> 1815 <title><link linkend="quickbook.syntax.block.predefined_macros">Predefined 1816 Macros</link></title> 1817 <para> 1818 Quickbook has some predefined macros that you can already use. 1819 </para> 1820 <table frame="all" id="quickbook.syntax.block.predefined_macros.t0"> 1821 <title>Predefined Macros</title> 1822 <tgroup cols="3"> 1823 <thead> 1824 <row> 1825 <entry> 1826 <para> 1827 Macro 1828 </para> 1829 </entry> 1830 <entry> 1831 <para> 1832 Meaning 1833 </para> 1834 </entry> 1835 <entry> 1836 <para> 1837 Example 1838 </para> 1839 </entry> 1840 </row> 1841 </thead> 1842 <tbody> 1843 <row> 1844 <entry> 1845 <para> 1846 __DATE__ 1847 </para> 1848 </entry> 1849 <entry> 1850 <para> 1851 Today's date 1852 </para> 1853 </entry> 1854 <entry> 1855 <para> 1856 2000-Dec-20 1857 </para> 1858 </entry> 1859 </row> 1860 <row> 1861 <entry> 1862 <para> 1863 __TIME__ 1864 </para> 1865 </entry> 1866 <entry> 1867 <para> 1868 The current time 1869 </para> 1870 </entry> 1871 <entry> 1872 <para> 1873 12:00:00 PM 1874 </para> 1875 </entry> 1876 </row> 1877 <row> 1878 <entry> 1879 <para> 1880 __FILENAME__ 1881 </para> 1882 </entry> 1883 <entry> 1884 <para> 1885 Quickbook source filename 1886 </para> 1887 </entry> 1888 <entry> 1889 <para> 1890 quickbook_manual-1_4.quickbook 1891 </para> 1892 </entry> 1893 </row> 1894 </tbody> 1895 </tgroup> 1896 </table> 1897 </section> 1898 <section id="quickbook.syntax.block.templates"> 1899 <title><link linkend="quickbook.syntax.block.templates">Templates</link></title> 1900 <para> 1901 Templates provide a more versatile text substitution mechanism. Templates 1902 come in handy when you need to create parameterizable, multi-line, boilerplate 1903 text that you specify once and expand many times. Templates accept one 1904 or more arguments. These arguments act like place-holders for text replacement. 1905 Unlike simple macros, which are limited to phrase level markup, templates 1906 can contain block level markup (e.g. paragraphs, code blocks and tables). 1907 </para> 1908 <para> 1909 Example template: 1910 </para> 1911<programlisting><!--quickbook-escape-prefix-->[template person[name age what] 1912 1913Hi, my name is [name]. I am [age] years old. I am a [what]. 1914 1915] 1916<!--quickbook-escape-postfix--></programlisting> 1917 <bridgehead renderas="sect5" id="quickbook.syntax.block.templates.h0"> 1918 <phrase id="quickbook.syntax.block.templates.template_identifier"/><link 1919 linkend="quickbook.syntax.block.templates.template_identifier">Template 1920 Identifier</link> 1921 </bridgehead> 1922 <para> 1923 Template identifiers can either consist of: 1924 </para> 1925 <itemizedlist> 1926 <listitem> 1927 <simpara> 1928 An initial alphabetic character or the underscore, followed by zero 1929 or more alphanumeric characters or the underscore. This is similar 1930 to your typical C/C++ identifier. 1931 </simpara> 1932 </listitem> 1933 <listitem> 1934 <simpara> 1935 A single character punctuation (a non-alphanumeric printable character) 1936 </simpara> 1937 </listitem> 1938 </itemizedlist> 1939 <bridgehead renderas="sect5" id="quickbook.syntax.block.templates.h1"> 1940 <phrase id="quickbook.syntax.block.templates.formal_template_arguments"/><link 1941 linkend="quickbook.syntax.block.templates.formal_template_arguments">Formal 1942 Template Arguments</link> 1943 </bridgehead> 1944 <para> 1945 Template formal arguments are identifiers consisting of an initial alphabetic 1946 character or the underscore, followed by zero or more alphanumeric characters 1947 or the underscore. This is similar to your typical C/C++ identifier. 1948 </para> 1949 <para> 1950 A template formal argument temporarily hides a template of the same name 1951 at the point where the <link linkend="quickbook.syntax.block.templates.template_expansion">template 1952 is expanded</link>. Note that the body of the <literal>person</literal> 1953 template above refers to <literal>name</literal> <literal>age</literal> 1954 and <literal>what</literal> as <literal>[name]</literal> <literal>[age]</literal> 1955 and <literal>[what]</literal>. <literal>name</literal> <literal>age</literal> 1956 and <literal>what</literal> are actually templates that exist in the duration 1957 of the template call. 1958 </para> 1959 <bridgehead renderas="sect5" id="quickbook.syntax.block.templates.h2"> 1960 <phrase id="quickbook.syntax.block.templates.template_body"/><link linkend="quickbook.syntax.block.templates.template_body">Template 1961 Body</link> 1962 </bridgehead> 1963 <para> 1964 The template body can be just about any QuickBook block or phrase. There 1965 are actually two forms. Templates may be phrase or block level. Phrase 1966 templates are of the form: 1967 </para> 1968<programlisting><!--quickbook-escape-prefix-->[template sample[arg1 arg2...argN] replacement text... ] 1969<!--quickbook-escape-postfix--></programlisting> 1970 <para> 1971 Block templates are of the form: 1972 </para> 1973<programlisting><!--quickbook-escape-prefix-->[template sample[arg1 arg2...argN] 1974replacement text... 1975] 1976<!--quickbook-escape-postfix--></programlisting> 1977 <para> 1978 The basic rule is as follows: if a newline immediately follows the argument 1979 list, then it is a block template, otherwise, it is a phrase template. 1980 Phrase templates are typically expanded as part of phrases. Like macros, 1981 block level elements are not allowed in phrase templates. 1982 </para> 1983 <bridgehead renderas="sect5" id="quickbook.syntax.block.templates.h3"> 1984 <phrase id="quickbook.syntax.block.templates.template_expansion"/><link 1985 linkend="quickbook.syntax.block.templates.template_expansion">Template 1986 Expansion</link> 1987 </bridgehead> 1988 <para> 1989 You expand a template this way: 1990 </para> 1991<programlisting><!--quickbook-escape-prefix-->[template_identifier arg1..arg2..arg3] 1992<!--quickbook-escape-postfix--></programlisting> 1993 <para> 1994 At template expansion, you supply the actual arguments. The template will 1995 be expanded with your supplied arguments. Example: 1996 </para> 1997<programlisting><!--quickbook-escape-prefix-->[person James Bond..39..Spy] 1998[person Santa Clause..87..Big Red Fatso] 1999<!--quickbook-escape-postfix--></programlisting> 2000 <para> 2001 Which will expand to: 2002 </para> 2003 <para> 2004 Hi, my name is James Bond. I am 39 years old. I am a Spy. 2005 </para> 2006 <para> 2007 Hi, my name is Santa Clause. I am 87 years old. I am a Big Red Fatso. 2008 </para> 2009 <caution> 2010 <para> 2011 A word of caution: Templates are recursive. A template can call another 2012 template or even itself, directly or indirectly. There are no control 2013 structures in QuickBook (yet) so this will always mean infinite recursion. 2014 QuickBook can detect this situation and report an error if recursion 2015 exceeds a certain limit. 2016 </para> 2017 </caution> 2018 <para> 2019 Each actual argument can be a word, a text fragment or just about any 2020 <link linkend="quickbook.syntax.phrase">QuickBook phrase</link>. Arguments 2021 are separated by the double dot <literal>".."</literal> and terminated 2022 by the close parenthesis. 2023 </para> 2024 <bridgehead renderas="sect5" id="quickbook.syntax.block.templates.h4"> 2025 <phrase id="quickbook.syntax.block.templates.nullary_templates"/><link 2026 linkend="quickbook.syntax.block.templates.nullary_templates">Nullary Templates</link> 2027 </bridgehead> 2028 <para> 2029 Nullary templates look and act like simple macros. Example: 2030 </para> 2031<programlisting><!--quickbook-escape-prefix-->[template alpha[]'''&#945;'''] 2032[template beta[]'''&#946;'''] 2033<!--quickbook-escape-postfix--></programlisting> 2034 <para> 2035 Expanding: 2036 </para> 2037<programlisting><!--quickbook-escape-prefix-->Some squigles...[*[alpha][beta]]<!--quickbook-escape-postfix--></programlisting> 2038 <para> 2039 We have: 2040 </para> 2041 <para> 2042 Some squiggles...<emphasis role="bold">αβ</emphasis> 2043 </para> 2044 <para> 2045 The difference with macros are 2046 </para> 2047 <itemizedlist> 2048 <listitem> 2049 <simpara> 2050 The explicit <link linkend="quickbook.syntax.block.templates.template_expansion">template 2051 expansion syntax</link>. This is an advantage because, now, we don't 2052 have to use obscure naming conventions like double underscores (e.g. 2053 __alpha__) to avoid unwanted macro replacement. 2054 </simpara> 2055 </listitem> 2056 <listitem> 2057 <simpara> 2058 The template is expanded at the point where it is invoked. A macro 2059 is expanded immediately at its point of declaration. This is subtle 2060 and can cause a slight difference in behavior especially if you refer 2061 to other macros and templates in the body. 2062 </simpara> 2063 </listitem> 2064 </itemizedlist> 2065 <para> 2066 The empty brackets after the template identifier (<literal>alpha[]</literal>) 2067 indicates no arguments. If the template body does not look like a template 2068 argument list, we can elide the empty brackets. Example: 2069 </para> 2070<programlisting><!--quickbook-escape-prefix-->[template aristotle_quote Aristotle: [*['Education is the best provision 2071for the journey to old age.]]] 2072<!--quickbook-escape-postfix--></programlisting> 2073 <para> 2074 Expanding: 2075 </para> 2076<programlisting><!--quickbook-escape-prefix-->Here's a quote from [aristotle_quote]. 2077<!--quickbook-escape-postfix--></programlisting> 2078 <para> 2079 We have: 2080 </para> 2081 <para> 2082 Here's a quote from Aristotle: <emphasis role="bold"><emphasis>Education 2083 is the best provision for the journey to old age.</emphasis></emphasis>. 2084 </para> 2085 <para> 2086 The disadvantage is that you can't avoid the space between the template 2087 identifier, <code><phrase role="identifier">aristotle_quote</phrase></code>, 2088 and the template body "Aristotle...". This space will be part 2089 of the template body. If that space is unwanted, use empty brackets or 2090 use the space escape: "<code><phrase role="special">\</phrase> </code>". 2091 Example: 2092 </para> 2093<programlisting><!--quickbook-escape-prefix-->[template tag\ _tag] 2094<!--quickbook-escape-postfix--></programlisting> 2095 <para> 2096 Then expanding: 2097 </para> 2098<programlisting><!--quickbook-escape-prefix-->`struct` x[tag]; 2099<!--quickbook-escape-postfix--></programlisting> 2100 <para> 2101 We have: 2102 </para> 2103 <para> 2104 <code><phrase role="keyword">struct</phrase></code> x_tag; 2105 </para> 2106 <para> 2107 You have a couple of ways to do it. I personally prefer the explicit empty 2108 brackets, though. 2109 </para> 2110 <bridgehead renderas="sect5" id="quickbook.syntax.block.templates.h5"> 2111 <phrase id="quickbook.syntax.block.templates.simple_arguments"/><link linkend="quickbook.syntax.block.templates.simple_arguments">Simple 2112 Arguments</link> 2113 </bridgehead> 2114 <para> 2115 As mentioned, arguments are separated by the double dot <literal>".."</literal>. 2116 If there are less arguments passed than expected, QuickBook attempts to 2117 break the last argument into two or more arguments following this logic: 2118 </para> 2119 <itemizedlist> 2120 <listitem> 2121 <simpara> 2122 Break the last argument into two, at the first space found (<literal>'', 2123 '\n', \t' or '\r'</literal>). 2124 </simpara> 2125 </listitem> 2126 <listitem> 2127 <simpara> 2128 Repeat until there are enough arguments or if there are no more spaces 2129 found (in which case, an error is reported). 2130 </simpara> 2131 </listitem> 2132 </itemizedlist> 2133 <para> 2134 For example: 2135 </para> 2136<programlisting><!--quickbook-escape-prefix-->[template simple[a b c d] [a][b][c][d]] 2137[simple w x y z] 2138<!--quickbook-escape-postfix--></programlisting> 2139 <para> 2140 will produce: 2141 </para> 2142 <para> 2143 wxyz 2144 </para> 2145 <para> 2146 "w x y z" is initially treated as a single argument because we 2147 didn't supply any <literal>".."</literal> separators. However, 2148 since <literal>simple</literal> expects 4 arguments, "w x y z" 2149 is broken down iteratively (applying the logic above) until we have "w", 2150 "x", "y" and "z". 2151 </para> 2152 <para> 2153 QuickBook only tries to get the arguments it needs. For example: 2154 </para> 2155<programlisting><!--quickbook-escape-prefix-->[simple w x y z trail] 2156<!--quickbook-escape-postfix--></programlisting> 2157 <para> 2158 will produce: 2159 </para> 2160 <para> 2161 wxyz trail 2162 </para> 2163 <para> 2164 The arguments being: "w", "x", "y" and "z 2165 trail". 2166 </para> 2167 <para> 2168 It should be obvious now that for simple arguments with no spaces, we can 2169 get by without separating the arguments with <literal>".."</literal> 2170 separators. It is possible to combine <literal>".."</literal> 2171 separators with the argument passing simplification presented above. Example: 2172 </para> 2173<programlisting><!--quickbook-escape-prefix-->[simple what do you think ..m a n?] 2174<!--quickbook-escape-postfix--></programlisting> 2175 <para> 2176 will produce: 2177 </para> 2178 <para> 2179 what do you think man? 2180 </para> 2181 <bridgehead renderas="sect5" id="quickbook.syntax.block.templates.h6"> 2182 <phrase id="quickbook.syntax.block.templates.punctuation_templates"/><link 2183 linkend="quickbook.syntax.block.templates.punctuation_templates">Punctuation 2184 Templates</link> 2185 </bridgehead> 2186 <para> 2187 With templates, one of our objectives is to allow us to rewrite QuickBook 2188 in QuickBook (as a qbk library). For that to happen, we need to accommodate 2189 single character punctuation templates which are fairly common in QuickBook. 2190 You might have noticed that single character punctuations are allowed as 2191 <link linkend="quickbook.syntax.block.templates.template_identifier">template 2192 identifiers</link>. Example: 2193 </para> 2194<programlisting><!--quickbook-escape-prefix-->[template ![bar] <!--quickbook-escape-postfix--><hey><!--quickbook-escape-prefix-->[bar]<!--quickbook-escape-postfix--></hey><!--quickbook-escape-prefix-->] 2195<!--quickbook-escape-postfix--></programlisting> 2196 <para> 2197 Now, expanding this: 2198 </para> 2199<programlisting><!--quickbook-escape-prefix-->[!baz] 2200<!--quickbook-escape-postfix--></programlisting> 2201 <para> 2202 We will have: 2203 </para> 2204<programlisting><hey>baz</hey> 2205</programlisting> 2206 </section> 2207 <section id="quickbook.syntax.block.blurbs"> 2208 <title><link linkend="quickbook.syntax.block.blurbs">Blurbs</link></title> 2209<programlisting><!--quickbook-escape-prefix-->[blurb :-) [*An eye catching advertisement or note...] 2210 2211 __spirit__ is an object-oriented recursive-descent parser generator framework 2212 implemented using template meta-programming techniques. Expression templates 2213 allow us to approximate the syntax of Extended Backus-Normal Form (EBNF) 2214 completely in C++. 2215] 2216<!--quickbook-escape-postfix--></programlisting> 2217 <para> 2218 will generate this: 2219 </para> 2220 <sidebar role="blurb"> 2221 <para> 2222 <inlinemediaobject><imageobject><imagedata fileref="images/smiley.png"></imagedata></imageobject> 2223 <textobject> 2224 <phrase>smiley</phrase> 2225 </textobject> 2226 </inlinemediaobject> <emphasis role="bold">An eye catching advertisement 2227 or note...</emphasis> 2228 </para> 2229 <para> 2230 <ulink url="http://spirit.sourceforge.net">Spirit</ulink> is an object-oriented 2231 recursive-descent parser generator framework implemented using template 2232 meta-programming techniques. Expression templates allow us to approximate 2233 the syntax of Extended Backus-Normal Form (EBNF) completely in C++. 2234 </para> 2235 </sidebar> 2236 <note> 2237 <para> 2238 Prefer <link linkend="quickbook.syntax.block.admonitions">admonitions</link> 2239 wherever appropriate. 2240 </para> 2241 </note> 2242 </section> 2243 <section id="quickbook.syntax.block.tables"> 2244 <title><link linkend="quickbook.syntax.block.tables">Tables</link></title> 2245<programlisting><!--quickbook-escape-prefix-->[table A Simple Table 2246 [[Heading 1] [Heading 2] [Heading 3]] 2247 [[R0-C0] [R0-C1] [R0-C2]] 2248 [[R1-C0] [R1-C1] [R1-C2]] 2249 [[R2-C0] [R2-C1] [R2-C2]] 2250] 2251<!--quickbook-escape-postfix--></programlisting> 2252 <para> 2253 will generate: 2254 </para> 2255 <table frame="all" id="quickbook.syntax.block.tables.t0"> 2256 <title>A Simple Table</title> 2257 <tgroup cols="3"> 2258 <thead> 2259 <row> 2260 <entry> 2261 <para> 2262 Heading 1 2263 </para> 2264 </entry> 2265 <entry> 2266 <para> 2267 Heading 2 2268 </para> 2269 </entry> 2270 <entry> 2271 <para> 2272 Heading 3 2273 </para> 2274 </entry> 2275 </row> 2276 </thead> 2277 <tbody> 2278 <row> 2279 <entry> 2280 <para> 2281 R0-C0 2282 </para> 2283 </entry> 2284 <entry> 2285 <para> 2286 R0-C1 2287 </para> 2288 </entry> 2289 <entry> 2290 <para> 2291 R0-C2 2292 </para> 2293 </entry> 2294 </row> 2295 <row> 2296 <entry> 2297 <para> 2298 R2-C0 2299 </para> 2300 </entry> 2301 <entry> 2302 <para> 2303 R2-C1 2304 </para> 2305 </entry> 2306 <entry> 2307 <para> 2308 R2-C2 2309 </para> 2310 </entry> 2311 </row> 2312 <row> 2313 <entry> 2314 <para> 2315 R3-C0 2316 </para> 2317 </entry> 2318 <entry> 2319 <para> 2320 R3-C1 2321 </para> 2322 </entry> 2323 <entry> 2324 <para> 2325 R3-C2 2326 </para> 2327 </entry> 2328 </row> 2329 </tbody> 2330 </tgroup> 2331 </table> 2332 <para> 2333 The table title is optional. The first row of the table is automatically 2334 treated as the table header; that is, it is wrapped in <literal><thead>...</thead></literal> 2335 XML tags. Note that unlike the original QuickDoc, the columns are nested 2336 in [ cells... ]. The syntax is free-format and allows big cells to be formatted 2337 nicely. Example: 2338 </para> 2339<programlisting><!--quickbook-escape-prefix-->[table Table with fat cells 2340 [[Heading 1] [Heading 2]] 2341 [ 2342 [Row 0, Col 0: a small cell] 2343 [ 2344 Row 0, Col 1: a big fat cell with paragraphs 2345 2346 Boost provides free peer-reviewed portable C++ source libraries. 2347 2348 We emphasize libraries that work well with the C++ Standard Library. 2349 Boost libraries are intended to be widely useful, and usable across 2350 a broad spectrum of applications. The Boost license encourages both 2351 commercial and non-commercial use. 2352 ] 2353 ] 2354 [ 2355 [Row 1, Col 0: a small cell] 2356 [Row 1, Col 1: a small cell] 2357 ] 2358] 2359<!--quickbook-escape-postfix--></programlisting> 2360 <para> 2361 and thus: 2362 </para> 2363 <table frame="all" id="quickbook.syntax.block.tables.t1"> 2364 <title>Table with fat cells</title> 2365 <tgroup cols="2"> 2366 <thead> 2367 <row> 2368 <entry> 2369 <para> 2370 Heading 1 2371 </para> 2372 </entry> 2373 <entry> 2374 <para> 2375 Heading 2 2376 </para> 2377 </entry> 2378 </row> 2379 </thead> 2380 <tbody> 2381 <row> 2382 <entry> 2383 <para> 2384 Row 0, Col 0: a small cell 2385 </para> 2386 </entry> 2387 <entry> 2388 <para> 2389 Row 0, Col 1: a big fat cell with paragraphs 2390 </para> 2391 <para> 2392 Boost provides free peer-reviewed portable C++ source libraries. 2393 </para> 2394 <para> 2395 We emphasize libraries that work well with the C++ Standard Library. 2396 Boost libraries are intended to be widely useful, and usable 2397 across a broad spectrum of applications. The Boost license encourages 2398 both commercial and non-commercial use. 2399 </para> 2400 </entry> 2401 </row> 2402 <row> 2403 <entry> 2404 <para> 2405 Row 1, Col 0: a small cell 2406 </para> 2407 </entry> 2408 <entry> 2409 <para> 2410 Row 1, Col 1: a small cell 2411 </para> 2412 </entry> 2413 </row> 2414 </tbody> 2415 </tgroup> 2416 </table> 2417 <para> 2418 Here's how to have preformatted blocks of code in a table cell: 2419 </para> 2420<programlisting><!--quickbook-escape-prefix-->[table Table with code 2421 [[Comment] [Code]] 2422 [ 2423 [My first program] 2424 [<!--quickbook-escape-postfix-->`` 2425 #include <iostream> 2426 2427 int main() 2428 { 2429 std::cout << "Hello, World!" << std::endl; 2430 return 0; 2431 } 2432 ``<!--quickbook-escape-prefix-->] 2433 ] 2434] 2435<!--quickbook-escape-postfix--></programlisting> 2436 <table frame="all" id="quickbook.syntax.block.tables.t2"> 2437 <title>Table with code</title> 2438 <tgroup cols="2"> 2439 <thead> 2440 <row> 2441 <entry> 2442 <para> 2443 Comment 2444 </para> 2445 </entry> 2446 <entry> 2447 <para> 2448 Code 2449 </para> 2450 </entry> 2451 </row> 2452 </thead> 2453 <tbody> 2454 <row> 2455 <entry> 2456 <para> 2457 My first program 2458 </para> 2459 </entry> 2460 <entry> 2461 <para> 2462<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">iostream</phrase><phrase role="special">></phrase> 2463 2464<phrase role="keyword">int</phrase> <phrase role="identifier">main</phrase><phrase role="special">()</phrase> 2465<phrase role="special">{</phrase> 2466 <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="string">"Hello, World!"</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase> 2467 <phrase role="keyword">return</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase> 2468<phrase role="special">}</phrase> 2469</programlisting> 2470 </para> 2471 </entry> 2472 </row> 2473 </tbody> 2474 </tgroup> 2475 </table> 2476 </section> 2477 <section id="quickbook.syntax.block.variable_lists"> 2478 <title><link linkend="quickbook.syntax.block.variable_lists">Variable Lists</link></title> 2479<programlisting><!--quickbook-escape-prefix-->[variablelist A Variable List 2480 [[term 1] [The definition of term 1]] 2481 [[term 2] [The definition of term 2]] 2482 [[term 3] [The definition of term 3]] 2483] 2484<!--quickbook-escape-postfix--></programlisting> 2485 <para> 2486 will generate: 2487 </para> 2488 <variablelist> 2489 <title>A Variable List</title> 2490 <varlistentry> 2491 <term>term 1</term> 2492 <listitem> 2493 <para> 2494 The definition of term 1 2495 </para> 2496 </listitem> 2497 </varlistentry> 2498 <varlistentry> 2499 <term>term 2</term> 2500 <listitem> 2501 <para> 2502 The definition of term 2 2503 </para> 2504 </listitem> 2505 </varlistentry> 2506 <varlistentry> 2507 <term>term 3</term> 2508 <listitem> 2509 <para> 2510 The definition of term 3 2511 </para> 2512 </listitem> 2513 </varlistentry> 2514 </variablelist> 2515 <para> 2516 The rules for variable lists are the same as for tables, except that only 2517 2 "columns" are allowed. The first column contains the terms, 2518 and the second column contains the definitions. Those familiar with HTML 2519 will recognize this as a "definition list". 2520 </para> 2521 </section> 2522 <section id="quickbook.syntax.block.include"> 2523 <title><link linkend="quickbook.syntax.block.include">Include</link></title> 2524 <para> 2525 You can include one QuickBook file from another. The syntax is simply: 2526 </para> 2527<programlisting><!--quickbook-escape-prefix-->[include someother.qbk] 2528<!--quickbook-escape-postfix--></programlisting> 2529 <para> 2530 The included file will be processed as if it had been cut and pasted into 2531 the current document, with the following exceptions: 2532 </para> 2533 <itemizedlist> 2534 <listitem> 2535 <simpara> 2536 The __FILENAME__ predefined macro will reflect the name of the file currently being 2537 processed. 2538 </simpara> 2539 </listitem> 2540 <listitem> 2541 <simpara> 2542 Any macros defined in the included file are scoped to that file. 2543 </simpara> 2544 </listitem> 2545 </itemizedlist> 2546 <para> 2547 The <literal>[include]</literal> directive lets you specify a document 2548 id to use for the included file. When this id is not explicitly specified, 2549 the id defaults to the filename ("someother", in the example 2550 above). You can specify the id like this: 2551 </para> 2552<programlisting><!--quickbook-escape-prefix-->[include:someid someother.qbk] 2553<!--quickbook-escape-postfix--></programlisting> 2554 <para> 2555 All auto-generated anchors will use the document id as a unique prefix. 2556 So for instance, if there is a top section in someother.qbk named "Intro", 2557 the named anchor for that section will be "someid.intro", and 2558 you can link to it with <literal>[link someid.intro The Intro]</literal>. 2559 </para> 2560 </section> 2561 <section id="quickbook.syntax.block.import"> 2562 <title><link linkend="quickbook.syntax.block.import">Import</link></title> 2563 <para> 2564 When documenting code, you'd surely need to present code from actual source 2565 files. While it is possible to copy some code and paste them in your QuickBook 2566 file, doing so is error prone and the extracted code in the documentation 2567 tends to get out of sync with the actual code as the code evolves. The 2568 problem, as always, is that once documentation is written, the tendency 2569 is for the docs to languish in the archives without maintenance. 2570 </para> 2571 <para> 2572 QuickBook's import facility provides a nice solution. 2573 </para> 2574 <bridgehead renderas="sect5" id="quickbook.syntax.block.import.h0"> 2575 <phrase id="quickbook.syntax.block.import.example"/><link linkend="quickbook.syntax.block.import.example">Example</link> 2576 </bridgehead> 2577 <para> 2578 You can effortlessly import code snippets from source code into your QuickBook. 2579 The following illustrates how this is done: 2580 </para> 2581<programlisting><!--quickbook-escape-prefix-->[import ../test/stub.cpp] 2582[foo] 2583[bar] 2584<!--quickbook-escape-postfix--></programlisting> 2585 <para> 2586 The first line: 2587 </para> 2588<programlisting><!--quickbook-escape-prefix-->[import ../test/stub.cpp] 2589<!--quickbook-escape-postfix--></programlisting> 2590 <para> 2591 collects specially marked-up code snippets from <ulink url="../../test/stub.cpp">stub.cpp</ulink> 2592 and places them in your QuickBook file as virtual templates. Each of the 2593 specially marked-up code snippets has a name (e.g. <code><phrase role="identifier">foo</phrase></code> 2594 and <code><phrase role="identifier">bar</phrase></code> in the example 2595 above). This shall be the template identifier for that particular code 2596 snippet. The second and third line above does the actual template expansion: 2597 </para> 2598<programlisting><!--quickbook-escape-prefix-->[foo] 2599[bar] 2600<!--quickbook-escape-postfix--></programlisting> 2601 <para> 2602 And the result is: 2603 </para> 2604 <para> 2605 This is the <emphasis role="bold"><emphasis>foo</emphasis></emphasis> function. 2606 </para> 2607 <para> 2608 This description can have paragraphs... 2609 </para> 2610 <itemizedlist> 2611 <listitem> 2612 <simpara> 2613 lists 2614 </simpara> 2615 </listitem> 2616 <listitem> 2617 <simpara> 2618 etc. 2619 </simpara> 2620 </listitem> 2621 </itemizedlist> 2622 <para> 2623 And any quickbook block markup. 2624 </para> 2625 <para> 2626<programlisting><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">foo</phrase><phrase role="special">()</phrase> 2627<phrase role="special">{</phrase> 2628 <phrase role="comment">// return 'em, foo man!</phrase> 2629 <phrase role="keyword">return</phrase> <phrase role="string">"foo"</phrase><phrase role="special">;</phrase> 2630<phrase role="special">}</phrase> 2631</programlisting> 2632 </para> 2633 <para> 2634 This is the <emphasis role="bold"><emphasis>bar</emphasis></emphasis> function 2635 </para> 2636 <para> 2637<programlisting><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">bar</phrase><phrase role="special">()</phrase> 2638<phrase role="special">{</phrase> 2639 <phrase role="comment">// return 'em, bar man!</phrase> 2640 <phrase role="keyword">return</phrase> <phrase role="string">"bar"</phrase><phrase role="special">;</phrase> 2641<phrase role="special">}</phrase> 2642</programlisting> 2643 </para> 2644 <para> 2645 Some trailing text here 2646 </para> 2647 <bridgehead renderas="sect5" id="quickbook.syntax.block.import.h1"> 2648 <phrase id="quickbook.syntax.block.import.code_snippet_markup"/><link linkend="quickbook.syntax.block.import.code_snippet_markup">Code 2649 Snippet Markup</link> 2650 </bridgehead> 2651 <para> 2652 Note how the code snippets in <ulink url="../../test/stub.cpp">stub.cpp</ulink> 2653 get marked up. We use distinguishable comments following the form: 2654 </para> 2655<programlisting><phrase role="comment">//[id</phrase> 2656<phrase role="identifier">some</phrase> <phrase role="identifier">code</phrase> <phrase role="identifier">here</phrase> 2657<phrase role="comment">//]</phrase> 2658</programlisting> 2659 <para> 2660 The first comment line above initiates a named code-snippet. This prefix 2661 will not be visible in quickbook. The entire code-snippet in between <code><phrase 2662 role="comment">//[id</phrase></code> and <code><phrase role="comment">//]</phrase></code> 2663 will be inserted as a template in quickbook with name <emphasis><emphasis>id</emphasis></emphasis>. 2664 The comment <code><phrase role="comment">//]</phrase></code> ends a code-snippet 2665 This too will not be visible in quickbook. 2666 </para> 2667 <bridgehead renderas="sect5" id="quickbook.syntax.block.import.h2"> 2668 <phrase id="quickbook.syntax.block.import.special_comments"/><link linkend="quickbook.syntax.block.import.special_comments">Special 2669 Comments</link> 2670 </bridgehead> 2671 <para> 2672 Special comments of the form: 2673 </para> 2674<programlisting><phrase role="comment">//` some [*quickbook] markup here</phrase> 2675</programlisting> 2676 <para> 2677 and: 2678 </para> 2679<programlisting><phrase role="comment">/*` some [*quickbook] markup here */</phrase> 2680</programlisting> 2681 <para> 2682 will be parsed by QuickBook. This can contain quickbook <emphasis>blocks</emphasis> 2683 (e.g. sections, paragraphs, tables, etc). In the first case, the initial 2684 slash-slash, tick and white-space shall be ignored. In the second, the 2685 initial slash-star-tick and the final star-slash shall be ignored. 2686 </para> 2687 <bridgehead renderas="sect5" id="quickbook.syntax.block.import.h3"> 2688 <phrase id="quickbook.syntax.block.import.callouts"/><link linkend="quickbook.syntax.block.import.callouts">Callouts</link> 2689 </bridgehead> 2690 <para> 2691 Special comments of the form: 2692 </para> 2693<programlisting><phrase role="comment">/*< some [*quickbook] markup here >*/</phrase> 2694</programlisting> 2695 <para> 2696 will be regarded as callouts. These will be collected, numbered and rendered 2697 as a "callout bug" (a small icon with a number). After the whole 2698 snippet is parsed, the callout list is generated. See <ulink url="http://www.docbook.org/tdg/en/html/callout.html">Callouts</ulink> 2699 for details. Example: 2700 </para> 2701 <para> 2702<programlisting><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">foo_bar</phrase><phrase role="special">()</phrase> <co id="quickbook.syntax.block.import.c0" linkends="quickbook.syntax.block.import.c1" /> 2703<phrase role="special">{</phrase> 2704 <phrase role="keyword">return</phrase> <phrase role="string">"foo-bar"</phrase><phrase role="special">;</phrase> <co id="quickbook.syntax.block.import.c2" linkends="quickbook.syntax.block.import.c3" /> 2705<phrase role="special">}</phrase> 2706</programlisting> 2707 </para> 2708 <calloutlist> 2709 <callout arearefs="quickbook.syntax.block.import.c0" id="quickbook.syntax.block.import.c1"> 2710 <para> 2711 The <emphasis>Mythical</emphasis> FooBar. See <ulink url="http://en.wikipedia.org/wiki/Foobar">Foobar 2712 for details</ulink> 2713 </para> 2714 </callout> 2715 <callout arearefs="quickbook.syntax.block.import.c2" id="quickbook.syntax.block.import.c3"> 2716 <para> 2717 return 'em, foo-bar man! 2718 </para> 2719 </callout> 2720 </calloutlist> 2721 <para> 2722 Checkout <ulink url="../../test/stub.cpp">stub.cpp</ulink> to see the actual 2723 code. 2724 </para> 2725 </section> 2726 </section> 2727 </section> 2728 <section id="quickbook.install"> 2729 <title><link linkend="quickbook.install">Installation and configuration</link></title> 2730 <para> 2731 This section provides some guidelines on how to install and configure BoostBook 2732 and Quickbook under several operating systems. 2733 </para> 2734 <para> 2735 Before continuing, it is very important that you keep this in mind: if you 2736 try to build some documents and the process breaks due to misconfiguration, 2737 be absolutely sure to delete any <code><phrase role="identifier">bin</phrase></code> 2738 and <code><phrase role="identifier">bin</phrase><phrase role="special">.</phrase><phrase 2739 role="identifier">v2</phrase></code> directories generated by the build before 2740 trying again. Otherwise your configuration fixes will not take any effect. 2741 </para> 2742 <section id="quickbook.install.windows"> 2743 <title><link linkend="quickbook.install.windows">Windows 2000, XP, 2003, Vista</link></title> 2744 <blockquote> 2745 <para> 2746 <emphasis>Section contributed by Julio M. Merino Vidal</emphasis> 2747 </para> 2748 </blockquote> 2749 <para> 2750 The following instructions apply to any Windows system based on Windows 2000, 2751 including Windows XP, Windows 2003 Server and Windows Vista. The paths shown 2752 below are taken from a Windows Vista machine; you will need to adjust them 2753 to match your system in case you are running an older version. 2754 </para> 2755 <orderedlist> 2756 <listitem> 2757 <simpara> 2758 First of all you need to have a copy of <code><phrase role="identifier">xsltproc</phrase></code> 2759 for Windows. There are many ways to get this tool, but to keep things 2760 simple, use the <ulink url="http://www.zlatkovic.com/pub/libxml/">binary 2761 packages</ulink> made by Igor Zlatkovic. At the very least, you need 2762 to download the following packages: <code><phrase role="identifier">iconv</phrase></code>, 2763 <code><phrase role="identifier">zlib</phrase></code>, <code><phrase role="identifier">libxml2</phrase></code> 2764 and <code><phrase role="identifier">libxslt</phrase></code>. 2765 </simpara> 2766 </listitem> 2767 <listitem> 2768 <simpara> 2769 Unpack all these packages in the same directory so that you get unique 2770 <code><phrase role="identifier">bin</phrase></code>, <code><phrase role="identifier">include</phrase></code> 2771 and <code><phrase role="identifier">lib</phrase></code> directories within 2772 the hierarchy. These instructions use <code><phrase role="identifier">C</phrase><phrase 2773 role="special">:\</phrase><phrase role="identifier">Users</phrase><phrase 2774 role="special">\</phrase><phrase role="identifier">example</phrase><phrase 2775 role="special">\</phrase><phrase role="identifier">Documents</phrase><phrase 2776 role="special">\</phrase><phrase role="identifier">boost</phrase><phrase 2777 role="special">\</phrase><phrase role="identifier">xml</phrase></code> 2778 as the root for all files. 2779 </simpara> 2780 </listitem> 2781 <listitem> 2782 <simpara> 2783 From the command line, go to the <code><phrase role="identifier">bin</phrase></code> 2784 directory and launch <code><phrase role="identifier">xsltproc</phrase><phrase 2785 role="special">.</phrase><phrase role="identifier">exe</phrase></code> 2786 to ensure it works. You should get usage information on screen. 2787 </simpara> 2788 </listitem> 2789 <listitem> 2790 <simpara> 2791 Download <ulink url="http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip">Docbook 2792 XML 4.2</ulink> and unpack it in the same directory used above. That 2793 is: <code><phrase role="identifier">C</phrase><phrase role="special">:\</phrase><phrase 2794 role="identifier">Users</phrase><phrase role="special">\</phrase><phrase 2795 role="identifier">example</phrase><phrase role="special">\</phrase><phrase 2796 role="identifier">Documents</phrase><phrase role="special">\</phrase><phrase 2797 role="identifier">boost</phrase><phrase role="special">\</phrase><phrase 2798 role="identifier">xml</phrase><phrase role="special">\</phrase><phrase 2799 role="identifier">docbook</phrase><phrase role="special">-</phrase><phrase 2800 role="identifier">xml</phrase></code>. 2801 </simpara> 2802 </listitem> 2803 <listitem> 2804 <simpara> 2805 Download the latest <ulink url="http://sourceforge.net/project/showfiles.php?group_id=21935&package_id=16608">Docbook 2806 XSL</ulink> version and unpack it, again in the same directory used before. 2807 To make things easier, rename the directory created during the extraction 2808 to <code><phrase role="identifier">docbook</phrase><phrase role="special">-</phrase><phrase 2809 role="identifier">xsl</phrase></code> (bypassing the version name): 2810 <code><phrase role="identifier">C</phrase><phrase role="special">:\</phrase><phrase 2811 role="identifier">Users</phrase><phrase role="special">\</phrase><phrase 2812 role="identifier">example</phrase><phrase role="special">\</phrase><phrase 2813 role="identifier">Documents</phrase><phrase role="special">\</phrase><phrase 2814 role="identifier">boost</phrase><phrase role="special">\</phrase><phrase 2815 role="identifier">xml</phrase><phrase role="special">\</phrase><phrase 2816 role="identifier">docbook</phrase><phrase role="special">-</phrase><phrase 2817 role="identifier">xsl</phrase></code>. 2818 </simpara> 2819 </listitem> 2820 <listitem> 2821 <simpara> 2822 Add the following to your <code><phrase role="identifier">user</phrase><phrase 2823 role="special">-</phrase><phrase role="identifier">config</phrase><phrase 2824 role="special">.</phrase><phrase role="identifier">jam</phrase></code> 2825 file, which should live in your home directory (<code><phrase role="special">%</phrase><phrase 2826 role="identifier">HOMEDRIVE</phrase><phrase role="special">%%</phrase><phrase 2827 role="identifier">HOMEPATH</phrase><phrase role="special">%</phrase></code>). 2828 You must already have it somewhere or otherwise you could not be building 2829 Boost (i.e. missing tools configuration). 2830 </simpara> 2831 </listitem> 2832 </orderedlist> 2833<programlisting><phrase role="identifier">using</phrase> <phrase role="identifier">xsltproc</phrase> 2834 <phrase role="special">:</phrase> <phrase role="string">"C:/Users/example/Documents/boost/xml/bin/xsltproc.exe"</phrase> 2835 <phrase role="special">;</phrase> 2836 2837<phrase role="identifier">using</phrase> <phrase role="identifier">boostbook</phrase> 2838 <phrase role="special">:</phrase> <phrase role="string">"C:/Users/example/Documents/boost/xml/docbook-xsl"</phrase> 2839 <phrase role="special">:</phrase> <phrase role="string">"C:/Users/example/Documents/boost/xml/docbook-xml"</phrase> 2840 <phrase role="special">;</phrase> 2841</programlisting> 2842 <para> 2843 The above steps are enough to get a functional BoostBook setup. Quickbook 2844 will be automatically built when needed. If you want to avoid these rebuilds: 2845 </para> 2846 <orderedlist> 2847 <listitem> 2848 <simpara> 2849 Go to Quickbook's source directory (<code><phrase role="identifier">BOOST_ROOT</phrase><phrase 2850 role="special">\</phrase><phrase role="identifier">tools</phrase><phrase 2851 role="special">\</phrase><phrase role="identifier">quickbook</phrase></code>). 2852 </simpara> 2853 </listitem> 2854 <listitem> 2855 <simpara> 2856 Build the utility by issuing <code><phrase role="identifier">bjam</phrase> 2857 <phrase role="special">--</phrase><phrase role="identifier">v2</phrase></code>. 2858 </simpara> 2859 </listitem> 2860 <listitem> 2861 <simpara> 2862 Copy the resulting <code><phrase role="identifier">quickbook</phrase><phrase 2863 role="special">.</phrase><phrase role="identifier">exe</phrase></code> 2864 binary (located under the <code><phrase role="identifier">BOOST_ROOT</phrase><phrase 2865 role="special">\</phrase><phrase role="identifier">bin</phrase><phrase 2866 role="special">.</phrase><phrase role="identifier">v2</phrase></code> 2867 hierarchy) to a safe place. Following our previous example, you can install 2868 it into: <code><phrase role="identifier">C</phrase><phrase role="special">:\</phrase><phrase 2869 role="identifier">Users</phrase><phrase role="special">\</phrase><phrase 2870 role="identifier">example</phrase><phrase role="special">\</phrase><phrase 2871 role="identifier">Documents</phrase><phrase role="special">\</phrase><phrase 2872 role="identifier">boost</phrase><phrase role="special">\</phrase><phrase 2873 role="identifier">xml</phrase><phrase role="special">\</phrase><phrase 2874 role="identifier">bin</phrase></code>. 2875 </simpara> 2876 </listitem> 2877 <listitem> 2878 <simpara> 2879 Add the following to your <code><phrase role="identifier">user</phrase><phrase 2880 role="special">-</phrase><phrase role="identifier">config</phrase><phrase 2881 role="special">.</phrase><phrase role="identifier">jam</phrase></code> 2882 file: 2883 </simpara> 2884 </listitem> 2885 </orderedlist> 2886<programlisting><phrase role="identifier">using</phrase> <phrase role="identifier">quickbook</phrase> 2887 <phrase role="special">:</phrase> <phrase role="string">"C:/Users/example/Documents/boost/xml/bin/quickbook.exe"</phrase> 2888 <phrase role="special">;</phrase> 2889</programlisting> 2890 </section> 2891 <section id="quickbook.install.linux"> 2892 <title><link linkend="quickbook.install.linux">Debian, Ubuntu</link></title> 2893 <para> 2894 The following instructions apply to Debian and its derivatives. They are 2895 based on a Ubuntu Edgy install but should work on other Debian based systems. 2896 </para> 2897 <para> 2898 First install the <code><phrase role="identifier">bjam</phrase></code>, 2899 <code><phrase role="identifier">xsltproc</phrase></code>, <code><phrase role="identifier">docbook</phrase><phrase 2900 role="special">-</phrase><phrase role="identifier">xsl</phrase></code> and 2901 <code><phrase role="identifier">docbook</phrase><phrase role="special">-</phrase><phrase 2902 role="identifier">xml</phrase></code> packages. For example, using <code><phrase 2903 role="identifier">apt</phrase><phrase role="special">-</phrase><phrase role="identifier">get</phrase></code>: 2904 </para> 2905<programlisting><phrase role="identifier">sudo</phrase> <phrase role="identifier">apt</phrase><phrase role="special">-</phrase><phrase role="identifier">get</phrase> <phrase role="identifier">install</phrase> <phrase role="identifier">xsltprc</phrase> <phrase role="identifier">docbook</phrase><phrase role="special">-</phrase><phrase role="identifier">xsl</phrase> <phrase role="identifier">docbook</phrase><phrase role="special">-</phrase><phrase role="identifier">xml</phrase> 2906</programlisting> 2907 <para> 2908 If you're planning on building boost's documentation, you'll also need to 2909 install the <code><phrase role="identifier">doxygen</phrase></code> package 2910 as well. 2911 </para> 2912 <para> 2913 Next, we need to configure Boost Build to compile BoostBook files. Add the 2914 following to your <code><phrase role="identifier">user</phrase><phrase role="special">-</phrase><phrase 2915 role="identifier">config</phrase><phrase role="special">.</phrase><phrase 2916 role="identifier">jam</phrase></code> file, which should be in your home 2917 directory. If you don't have one, create a file containing this text. For 2918 more information on setting up <code><phrase role="identifier">user</phrase><phrase 2919 role="special">-</phrase><phrase role="identifier">config</phrase><phrase 2920 role="special">.</phrase><phrase role="identifier">jam</phrase></code>, see 2921 the <ulink url="http://boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html">Boost 2922 Build documentation</ulink>. 2923 </para> 2924<programlisting><phrase role="identifier">using</phrase> <phrase role="identifier">xsltproc</phrase> <phrase role="special">;</phrase> 2925 2926<phrase role="identifier">using</phrase> <phrase role="identifier">boostbook</phrase> 2927 <phrase role="special">:</phrase> <phrase role="special">/</phrase><phrase role="identifier">usr</phrase><phrase role="special">/</phrase><phrase role="identifier">share</phrase><phrase role="special">/</phrase><phrase role="identifier">xml</phrase><phrase role="special">/</phrase><phrase role="identifier">docbook</phrase><phrase role="special">/</phrase><phrase role="identifier">stylesheet</phrase><phrase role="special">/</phrase><phrase role="identifier">nwalsh</phrase> 2928 <phrase role="special">:</phrase> <phrase role="special">/</phrase><phrase role="identifier">usr</phrase><phrase role="special">/</phrase><phrase role="identifier">share</phrase><phrase role="special">/</phrase><phrase role="identifier">xml</phrase><phrase role="special">/</phrase><phrase role="identifier">docbook</phrase><phrase role="special">/</phrase><phrase role="identifier">schema</phrase><phrase role="special">/</phrase><phrase role="identifier">dtd</phrase><phrase role="special">/</phrase><phrase role="number">4.2</phrase> 2929 <phrase role="special">;</phrase> 2930 2931<phrase role="comment"># Remove this line if you're not using doxygen</phrase> 2932<phrase role="identifier">using</phrase> <phrase role="identifier">doxygen</phrase> <phrase role="special">;</phrase> 2933</programlisting> 2934 <para> 2935 The above steps are enough to get a functional BoostBook setup. Quickbook 2936 will be automatically built when needed. If you want to avoid these rebuilds: 2937 </para> 2938 <orderedlist> 2939 <listitem> 2940 <simpara> 2941 Go to Quickbook's source directory (<code><phrase role="identifier">BOOST_ROOT</phrase><phrase 2942 role="special">/</phrase><phrase role="identifier">tools</phrase><phrase 2943 role="special">/</phrase><phrase role="identifier">quickbook</phrase></code>). 2944 </simpara> 2945 </listitem> 2946 <listitem> 2947 <simpara> 2948 Build the utility by issuing <code><phrase role="identifier">bjam</phrase> 2949 <phrase role="special">--</phrase><phrase role="identifier">v2</phrase></code>. 2950 </simpara> 2951 </listitem> 2952 <listitem> 2953 <simpara> 2954 Copy the resulting <code><phrase role="identifier">quickbook</phrase></code> 2955 binary (located under the <code><phrase role="identifier">BOOST_ROOT</phrase><phrase 2956 role="special">/</phrase><phrase role="identifier">bin</phrase><phrase 2957 role="special">.</phrase><phrase role="identifier">v2</phrase></code> 2958 hierarchy) to a safe place. The traditional location is <code><phrase 2959 role="special">/</phrase><phrase role="identifier">usr</phrase><phrase 2960 role="special">/</phrase><phrase role="identifier">local</phrase><phrase 2961 role="special">/</phrase><phrase role="identifier">bin</phrase></code>. 2962 </simpara> 2963 </listitem> 2964 <listitem> 2965 <simpara> 2966 Add the following to your <code><phrase role="identifier">user</phrase><phrase 2967 role="special">-</phrase><phrase role="identifier">config</phrase><phrase 2968 role="special">.</phrase><phrase role="identifier">jam</phrase></code> 2969 file, using the full path of the quickbook executable: 2970 </simpara> 2971 </listitem> 2972 </orderedlist> 2973<programlisting><phrase role="identifier">using</phrase> <phrase role="identifier">quickbook</phrase> 2974 <phrase role="special">:</phrase> <phrase role="special">/</phrase><phrase role="identifier">usr</phrase><phrase role="special">/</phrase><phrase role="identifier">local</phrase><phrase role="special">/</phrase><phrase role="identifier">bin</phrase><phrase role="special">/</phrase><phrase role="identifier">quickbook</phrase> 2975 <phrase role="special">;</phrase> 2976</programlisting> 2977 </section> 2978 </section> 2979 <section id="quickbook.editors"> 2980 <title><link linkend="quickbook.editors">Editor Support</link></title> 2981 <para> 2982 Editing quickbook files is usually done with text editors both simple and powerful. 2983 The following sections list the settings for some editors which can help make 2984 editing quickbook files a bit easier. 2985 </para> 2986 <sidebar role="blurb"> 2987 <para> 2988 <inlinemediaobject><imageobject><imagedata fileref="images/note.png"></imagedata></imageobject> 2989 <textobject> 2990 <phrase>note</phrase> 2991 </textobject> 2992 </inlinemediaobject> You may submit your settings, tips, and suggestions to 2993 the authors, or through the <ulink url="https://lists.sourceforge.net/lists/listinfo/boost-">docs 2994 Boost Docs mailing list</ulink>. 2995 </para> 2996 </sidebar> 2997 <section id="quickbook.editors.scite"> 2998 <title><link linkend="quickbook.editors.scite">Scintilla Text Editor</link></title> 2999 <blockquote> 3000 <para> 3001 <emphasis>Section contributed by Dean Michael Berris</emphasis> 3002 </para> 3003 </blockquote> 3004 <para> 3005 The Scintilla Text Editor (SciTE) is a free source code editor for Win32 3006 and X. It uses the SCIntilla source code editing component. 3007 </para> 3008 <sidebar role="blurb"> 3009 <para> 3010 <inlinemediaobject><imageobject><imagedata fileref="images/tip.png"></imagedata></imageobject> 3011 <textobject> 3012 <phrase>tip</phrase> 3013 </textobject> 3014 </inlinemediaobject> SciTE can be downloaded from <ulink url="http://www.scintilla.org/SciTE.html">http://www.scintilla.org/SciTE.html</ulink> 3015 </para> 3016 </sidebar> 3017 <para> 3018 You can use the following settings to highlight quickbook tags when editing 3019 quickbook files. 3020 </para> 3021<programlisting><!--quickbook-escape-prefix-->qbk=*.qbk 3022lexer.*.qbk=props 3023use.tabs.$(qbk)=0 3024tab.size.$(qbk)=4 3025indent.size.$(qbk)=4 3026style.props.32=$(font.base) 3027comment.stream.start.props=[/ 3028comment.stream.end.props=] 3029comment.box.start.props=[/ 3030comment.box.middle.props= 3031comment.box.end.props=] 3032<!--quickbook-escape-postfix--></programlisting> 3033 <sidebar role="blurb"> 3034 <para> 3035 <inlinemediaobject><imageobject><imagedata fileref="images/note.png"></imagedata></imageobject> 3036 <textobject> 3037 <phrase>note</phrase> 3038 </textobject> 3039 </inlinemediaobject> Thanks to Rene Rivera for the above SciTE settings. 3040 </para> 3041 </sidebar> 3042 </section> 3043 </section> 3044 <section id="quickbook.faq"> 3045 <title><link linkend="quickbook.faq">Frequently Asked Questions</link></title> 3046 <bridgehead renderas="sect3" id="quickbook.faq.h0"> 3047 <phrase id="quickbook.faq.can_i_use_quickbook_for_non_boost_documentation_"/><link 3048 linkend="quickbook.faq.can_i_use_quickbook_for_non_boost_documentation_">Can 3049 I use QuickBook for non-Boost documentation?</link> 3050 </bridgehead> 3051 <para> 3052 QuickBook can be used for non-Boost documentation with a little extra work. 3053 </para> 3054 <blockquote> 3055 <para> 3056 <emphasis>Faq contributed by Michael Marcin</emphasis> 3057 </para> 3058 </blockquote> 3059 <para> 3060 When building HTML documentation with BoostBook a Boost C++ Libraries header 3061 is added to the files. When using QuickBook to document projects outside of 3062 Boost this is not desirable. This behavior can be overridden at the BoostBook 3063 level by specifying some XSLT options. When using Boost Build version 2 (BBv2) 3064 this can be achieved by adding parameters to the BoostBook target declaration. 3065 </para> 3066 <para> 3067 For example: 3068 </para> 3069<programlisting>using quickbook ; 3070 3071xml my_doc : my_doc.qbk ; 3072 3073boostbook standalone 3074 : 3075 my_doc 3076 : 3077 <xsl:param>boost.image.src=images/my_project_logo.png 3078 <xsl:param>boost.image.alt="\"My Project\"" 3079 <xsl:param>boost.image.w=100 3080 <xsl:param>boost.image.h=50 3081 <xsl:param>nav.layout=none 3082 ; 3083</programlisting> 3084 </section> 3085 <section id="quickbook.ref"> 3086 <title><link linkend="quickbook.ref">Quick Reference</link></title> 3087 <para> 3088 [cpp] 3089 </para> 3090 <table frame="all" id="quickbook.ref.t0"> 3091 <title>Syntax Compendium</title> 3092 <tgroup cols="3"> 3093 <thead> 3094 <row> 3095 <entry> 3096 <para> 3097 To do this... 3098 </para> 3099 </entry> 3100 <entry> 3101 <para> 3102 Use this... 3103 </para> 3104 </entry> 3105 <entry> 3106 <para> 3107 See this... 3108 </para> 3109 </entry> 3110 </row> 3111 </thead> 3112 <tbody> 3113 <row> 3114 <entry> 3115 <para> 3116 comment 3117 </para> 3118 </entry> 3119 <entry> 3120 <para> 3121 <literal>[/ some comment]</literal> 3122 </para> 3123 </entry> 3124 <entry> 3125 <para> 3126 <link linkend="quickbook.syntax.comments">Comments</link> 3127 </para> 3128 </entry> 3129 </row> 3130 <row> 3131 <entry> 3132 <para> 3133 <emphasis>italics</emphasis> 3134 </para> 3135 </entry> 3136 <entry> 3137 <para> 3138 <literal>['italics] or /italics/</literal> 3139 </para> 3140 </entry> 3141 <entry> 3142 <para> 3143 <link linkend="quickbook.syntax.phrase.font_styles">Font Styles</link> 3144 and <link linkend="quickbook.syntax.phrase.simple_formatting">Simple 3145 formatting</link> 3146 </para> 3147 </entry> 3148 </row> 3149 <row> 3150 <entry> 3151 <para> 3152 <emphasis role="bold">bold</emphasis> 3153 </para> 3154 </entry> 3155 <entry> 3156 <para> 3157 <literal>[*bold] or *bold*</literal> 3158 </para> 3159 </entry> 3160 <entry> 3161 <para> 3162 <link linkend="quickbook.syntax.phrase.font_styles">Font Styles</link> 3163 and <link linkend="quickbook.syntax.phrase.simple_formatting">Simple 3164 formatting</link> 3165 </para> 3166 </entry> 3167 </row> 3168 <row> 3169 <entry> 3170 <para> 3171 <emphasis role="underline">underline</emphasis> 3172 </para> 3173 </entry> 3174 <entry> 3175 <para> 3176 <literal>[_underline] or _underline_</literal> 3177 </para> 3178 </entry> 3179 <entry> 3180 <para> 3181 <link linkend="quickbook.syntax.phrase.font_styles">Font Styles</link> 3182 and <link linkend="quickbook.syntax.phrase.simple_formatting">Simple 3183 formatting</link> 3184 </para> 3185 </entry> 3186 </row> 3187 <row> 3188 <entry> 3189 <para> 3190 <literal>teletype</literal> 3191 </para> 3192 </entry> 3193 <entry> 3194 <para> 3195 <literal>[^teletype] or =teletype=</literal> 3196 </para> 3197 </entry> 3198 <entry> 3199 <para> 3200 <link linkend="quickbook.syntax.phrase.font_styles">Font Styles</link> 3201 and <link linkend="quickbook.syntax.phrase.simple_formatting">Simple 3202 formatting</link> 3203 </para> 3204 </entry> 3205 </row> 3206 <row> 3207 <entry> 3208 <para> 3209 <emphasis role="strikethrough">strikethrough</emphasis> 3210 </para> 3211 </entry> 3212 <entry> 3213 <para> 3214 <literal>[-strikethrough]</literal> 3215 </para> 3216 </entry> 3217 <entry> 3218 <para> 3219 <link linkend="quickbook.syntax.phrase.font_styles">Font Styles</link> 3220 and <link linkend="quickbook.syntax.phrase.simple_formatting">Simple 3221 formatting</link> 3222 </para> 3223 </entry> 3224 </row> 3225 <row> 3226 <entry> 3227 <para> 3228 <replaceable>replaceable</replaceable> 3229 </para> 3230 </entry> 3231 <entry> 3232 <para> 3233 <literal>[~replaceable]</literal> 3234 </para> 3235 </entry> 3236 <entry> 3237 <para> 3238 <link linkend="quickbook.syntax.phrase.replaceable">Replaceble</link> 3239 </para> 3240 </entry> 3241 </row> 3242 <row> 3243 <entry> 3244 <para> 3245 source mode 3246 </para> 3247 </entry> 3248 <entry> 3249 <para> 3250 <literal>[c++]</literal> or <literal>[python]</literal> 3251 </para> 3252 </entry> 3253 <entry> 3254 <para> 3255 <link linkend="quickbook.syntax.phrase.source_mode">Source Mode</link> 3256 </para> 3257 </entry> 3258 </row> 3259 <row> 3260 <entry> 3261 <para> 3262 inline code 3263 </para> 3264 </entry> 3265 <entry> 3266 <para> 3267 <literal>`int main();`</literal> 3268 </para> 3269 </entry> 3270 <entry> 3271 <para> 3272 <link linkend="quickbook.syntax.phrase.inline_code">Inline code</link> 3273 </para> 3274 </entry> 3275 </row> 3276 <row> 3277 <entry> 3278 <para> 3279 code block 3280 </para> 3281 </entry> 3282 <entry> 3283 <para> 3284 <literal>``int main();``</literal> 3285 </para> 3286 </entry> 3287 <entry> 3288 <para> 3289 <link linkend="quickbook.syntax.block.code">Code</link> 3290 </para> 3291 </entry> 3292 </row> 3293 <row> 3294 <entry> 3295 <para> 3296 code escape 3297 </para> 3298 </entry> 3299 <entry> 3300 <para> 3301 <literal>``from c++ to QuickBook``</literal> 3302 </para> 3303 </entry> 3304 <entry> 3305 <para> 3306 <link linkend="quickbook.syntax.block.escape_back">Escaping Back 3307 To QuickBook</link> 3308 </para> 3309 </entry> 3310 </row> 3311 <row> 3312 <entry> 3313 <para> 3314 line break 3315 </para> 3316 </entry> 3317 <entry> 3318 <para> 3319 <literal>[br] or \n</literal> 3320 </para> 3321 </entry> 3322 <entry> 3323 <para> 3324 <link linkend="quickbook.syntax.phrase.line_break">line-break</link> 3325 <emphasis role="bold">DEPRECATED</emphasis> 3326 </para> 3327 </entry> 3328 </row> 3329 <row> 3330 <entry> 3331 <para> 3332 anchor 3333 </para> 3334 </entry> 3335 <entry> 3336 <para> 3337 <literal>[#anchor]</literal> 3338 </para> 3339 </entry> 3340 <entry> 3341 <para> 3342 <link linkend="quickbook.syntax.phrase.anchors">Anchors</link> 3343 </para> 3344 </entry> 3345 </row> 3346 <row> 3347 <entry> 3348 <para> 3349 link 3350 </para> 3351 </entry> 3352 <entry> 3353 <para> 3354 <literal>[@http://www.boost.org Boost]</literal> 3355 </para> 3356 </entry> 3357 <entry> 3358 <para> 3359 <link linkend="quickbook.syntax.phrase.links">Links</link> 3360 </para> 3361 </entry> 3362 </row> 3363 <row> 3364 <entry> 3365 <para> 3366 anchor link 3367 </para> 3368 </entry> 3369 <entry> 3370 <para> 3371 <literal>[link section.anchor Link text]</literal> 3372 </para> 3373 </entry> 3374 <entry> 3375 <para> 3376 <link linkend="quickbook.syntax.phrase.anchor_links">Anchor links</link> 3377 </para> 3378 </entry> 3379 </row> 3380 <row> 3381 <entry> 3382 <para> 3383 refentry link 3384 </para> 3385 </entry> 3386 <entry> 3387 <para> 3388 <literal>[link xml.refentry Link text]</literal> 3389 </para> 3390 </entry> 3391 <entry> 3392 <para> 3393 <link linkend="quickbook.syntax.phrase.refentry_links">refentry links</link> 3394 </para> 3395 </entry> 3396 </row> 3397 <row> 3398 <entry> 3399 <para> 3400 function link 3401 </para> 3402 </entry> 3403 <entry> 3404 <para> 3405 <literal>[funcref fully::qualified::function_name Link text]</literal> 3406 </para> 3407 </entry> 3408 <entry> 3409 <para> 3410 <link linkend="quickbook.syntax.phrase.code_links">function, class, 3411 member, enum, macro, concept or header links</link> 3412 </para> 3413 </entry> 3414 </row> 3415 <row> 3416 <entry> 3417 <para> 3418 class link 3419 </para> 3420 </entry> 3421 <entry> 3422 <para> 3423 <literal>[classref fully::qualified::class_name Link text]</literal> 3424 </para> 3425 </entry> 3426 <entry> 3427 <para> 3428 <link linkend="quickbook.syntax.phrase.code_links">function, class, 3429 member, enum, macro, concept or header links</link> 3430 </para> 3431 </entry> 3432 </row> 3433 <row> 3434 <entry> 3435 <para> 3436 member link 3437 </para> 3438 </entry> 3439 <entry> 3440 <para> 3441 <literal>[memberref fully::qualified::member_name Link text]</literal> 3442 </para> 3443 </entry> 3444 <entry> 3445 <para> 3446 <link linkend="quickbook.syntax.phrase.code_links">function, class, 3447 member, enum, macro, concept or header links</link> 3448 </para> 3449 </entry> 3450 </row> 3451 <row> 3452 <entry> 3453 <para> 3454 enum link 3455 </para> 3456 </entry> 3457 <entry> 3458 <para> 3459 <literal>[enumref fully::qualified::enum_name Link text]</literal> 3460 </para> 3461 </entry> 3462 <entry> 3463 <para> 3464 <link linkend="quickbook.syntax.phrase.code_links">function, class, 3465 member, enum, macro, concept or header links</link> 3466 </para> 3467 </entry> 3468 </row> 3469 <row> 3470 <entry> 3471 <para> 3472 macro link 3473 </para> 3474 </entry> 3475 <entry> 3476 <para> 3477 <literal>[macroref MACRO_NAME Link text]</literal> 3478 </para> 3479 </entry> 3480 <entry> 3481 <para> 3482 <link linkend="quickbook.syntax.phrase.code_links">function, class, 3483 member, enum, macro, concept or header links</link> 3484 </para> 3485 </entry> 3486 </row> 3487 <row> 3488 <entry> 3489 <para> 3490 concept link 3491 </para> 3492 </entry> 3493 <entry> 3494 <para> 3495 <literal>[conceptref ConceptName Link text]</literal> 3496 </para> 3497 </entry> 3498 <entry> 3499 <para> 3500 <link linkend="quickbook.syntax.phrase.code_links">function, class, 3501 member, enum, macro, concept or header links</link> 3502 </para> 3503 </entry> 3504 </row> 3505 <row> 3506 <entry> 3507 <para> 3508 header link 3509 </para> 3510 </entry> 3511 <entry> 3512 <para> 3513 <literal>[headerref path/to/header.hpp Link text]</literal> 3514 </para> 3515 </entry> 3516 <entry> 3517 <para> 3518 <link linkend="quickbook.syntax.phrase.code_links">function, class, 3519 member, enum, macro, concept or header links</link> 3520 </para> 3521 </entry> 3522 </row> 3523 <row> 3524 <entry> 3525 <para> 3526 escape 3527 </para> 3528 </entry> 3529 <entry> 3530 <para> 3531 <literal>'''escaped text (no processing/formatting)'''</literal> 3532 </para> 3533 </entry> 3534 <entry> 3535 <para> 3536 <link linkend="quickbook.syntax.phrase.escape">Escape</link> 3537 </para> 3538 </entry> 3539 </row> 3540 <row> 3541 <entry> 3542 <para> 3543 single char escape 3544 </para> 3545 </entry> 3546 <entry> 3547 <para> 3548 <literal>\c</literal> 3549 </para> 3550 </entry> 3551 <entry> 3552 <para> 3553 <link linkend="quickbook.syntax.phrase.single_char_escape">Single 3554 char escape</link> 3555 </para> 3556 </entry> 3557 </row> 3558 <row> 3559 <entry> 3560 <para> 3561 images 3562 </para> 3563 </entry> 3564 <entry> 3565 <para> 3566 <literal>[$image.jpg]</literal> 3567 </para> 3568 </entry> 3569 <entry> 3570 <para> 3571 <link linkend="quickbook.syntax.phrase.images">Images</link> 3572 </para> 3573 </entry> 3574 </row> 3575 <row> 3576 <entry> 3577 <para> 3578 begin section 3579 </para> 3580 </entry> 3581 <entry> 3582 <para> 3583 <literal>[section The Section Title]</literal> 3584 </para> 3585 </entry> 3586 <entry> 3587 <para> 3588 <link linkend="quickbook.syntax.block.section">Section</link> 3589 </para> 3590 </entry> 3591 </row> 3592 <row> 3593 <entry> 3594 <para> 3595 end section 3596 </para> 3597 </entry> 3598 <entry> 3599 <para> 3600 <literal>[endsect]</literal> 3601 </para> 3602 </entry> 3603 <entry> 3604 <para> 3605 <link linkend="quickbook.syntax.block.section">Section</link> 3606 </para> 3607 </entry> 3608 </row> 3609 <row> 3610 <entry> 3611 <para> 3612 paragraph 3613 </para> 3614 </entry> 3615 <entry> 3616 <para> 3617 No markup. Paragraphs start left-flushed and are terminated by two 3618 or more newlines. 3619 </para> 3620 </entry> 3621 <entry> 3622 <para> 3623 <link linkend="quickbook.syntax.block.paragraphs">Paragraphs</link> 3624 </para> 3625 </entry> 3626 </row> 3627 <row> 3628 <entry> 3629 <para> 3630 ordered list 3631 </para> 3632 </entry> 3633 <entry> 3634<programlisting><!--quickbook-escape-prefix--># one 3635# two 3636# three 3637<!--quickbook-escape-postfix--></programlisting> 3638 </entry> 3639 <entry> 3640 <para> 3641 <link linkend="quickbook.syntax.block.lists.ordered_lists">Ordered 3642 lists</link> 3643 </para> 3644 </entry> 3645 </row> 3646 <row> 3647 <entry> 3648 <para> 3649 unordered list 3650 </para> 3651 </entry> 3652 <entry> 3653<programlisting><!--quickbook-escape-prefix-->* one 3654* two 3655* three 3656<!--quickbook-escape-postfix--></programlisting> 3657 </entry> 3658 <entry> 3659 <para> 3660 <link linkend="quickbook.syntax.block.lists.unordered_lists">Unordered 3661 lists</link> 3662 </para> 3663 </entry> 3664 </row> 3665 <row> 3666 <entry> 3667 <para> 3668 code 3669 </para> 3670 </entry> 3671 <entry> 3672 <para> 3673 No markup. Preformatted code starts with a space or a tab. 3674 </para> 3675 </entry> 3676 <entry> 3677 <para> 3678 <link linkend="quickbook.syntax.block.code">Code</link> 3679 </para> 3680 </entry> 3681 </row> 3682 <row> 3683 <entry> 3684 <para> 3685 preformatted 3686 </para> 3687 </entry> 3688 <entry> 3689 <para> 3690 <literal>[pre preformatted]</literal> 3691 </para> 3692 </entry> 3693 <entry> 3694 <para> 3695 <link linkend="quickbook.syntax.block.preformatted">Preformatted</link> 3696 </para> 3697 </entry> 3698 </row> 3699 <row> 3700 <entry> 3701 <para> 3702 block quote 3703 </para> 3704 </entry> 3705 <entry> 3706 <para> 3707 <literal>[:sometext...]</literal> 3708 </para> 3709 </entry> 3710 <entry> 3711 <para> 3712 <link linkend="quickbook.syntax.block.blockquote">Blockquote</link> 3713 </para> 3714 </entry> 3715 </row> 3716 <row> 3717 <entry> 3718 <para> 3719 heading 1 3720 </para> 3721 </entry> 3722 <entry> 3723 <para> 3724 <literal>[h1 Heading 1]</literal> 3725 </para> 3726 </entry> 3727 <entry> 3728 <para> 3729 <link linkend="quickbook.syntax.block.headings">Heading</link> 3730 </para> 3731 </entry> 3732 </row> 3733 <row> 3734 <entry> 3735 <para> 3736 heading 2 3737 </para> 3738 </entry> 3739 <entry> 3740 <para> 3741 <literal>[h2 Heading 2]</literal> 3742 </para> 3743 </entry> 3744 <entry> 3745 <para> 3746 <link linkend="quickbook.syntax.block.headings">Heading</link> 3747 </para> 3748 </entry> 3749 </row> 3750 <row> 3751 <entry> 3752 <para> 3753 heading 3 3754 </para> 3755 </entry> 3756 <entry> 3757 <para> 3758 <literal>[h3 Heading 3]</literal> 3759 </para> 3760 </entry> 3761 <entry> 3762 <para> 3763 <link linkend="quickbook.syntax.block.headings">Heading</link> 3764 </para> 3765 </entry> 3766 </row> 3767 <row> 3768 <entry> 3769 <para> 3770 heading 4 3771 </para> 3772 </entry> 3773 <entry> 3774 <para> 3775 <literal>[h4 Heading 4]</literal> 3776 </para> 3777 </entry> 3778 <entry> 3779 <para> 3780 <link linkend="quickbook.syntax.block.headings">Heading</link> 3781 </para> 3782 </entry> 3783 </row> 3784 <row> 3785 <entry> 3786 <para> 3787 heading 5 3788 </para> 3789 </entry> 3790 <entry> 3791 <para> 3792 <literal>[h5 Heading 5]</literal> 3793 </para> 3794 </entry> 3795 <entry> 3796 <para> 3797 <link linkend="quickbook.syntax.block.headings">Heading</link> 3798 </para> 3799 </entry> 3800 </row> 3801 <row> 3802 <entry> 3803 <para> 3804 heading 6 3805 </para> 3806 </entry> 3807 <entry> 3808 <para> 3809 <literal>[h6 Heading 6]</literal> 3810 </para> 3811 </entry> 3812 <entry> 3813 <para> 3814 <link linkend="quickbook.syntax.block.headings">Heading</link> 3815 </para> 3816 </entry> 3817 </row> 3818 <row> 3819 <entry> 3820 <para> 3821 macro 3822 </para> 3823 </entry> 3824 <entry> 3825 <para> 3826 <literal>[def macro_identifier some text]</literal> 3827 </para> 3828 </entry> 3829 <entry> 3830 <para> 3831 <link linkend="quickbook.syntax.block.macros">Macros</link> 3832 </para> 3833 </entry> 3834 </row> 3835 <row> 3836 <entry> 3837 <para> 3838 template 3839 </para> 3840 </entry> 3841 <entry> 3842 <para> 3843 <literal>[template[a b] [a] body [b]]</literal> 3844 </para> 3845 </entry> 3846 <entry> 3847 <para> 3848 <link linkend="quickbook.syntax.block.templates">Templates</link> 3849 </para> 3850 </entry> 3851 </row> 3852 <row> 3853 <entry> 3854 <para> 3855 blurb 3856 </para> 3857 </entry> 3858 <entry> 3859 <para> 3860 <literal>[blurb advertisement or note...]</literal> 3861 </para> 3862 </entry> 3863 <entry> 3864 <para> 3865 <link linkend="quickbook.syntax.block.blurbs">Blurbs</link> 3866 </para> 3867 </entry> 3868 </row> 3869 <row> 3870 <entry> 3871 <para> 3872 admonition 3873 </para> 3874 </entry> 3875 <entry> 3876 <para> 3877 <literal>[warning Warning text...]</literal> 3878 </para> 3879 </entry> 3880 <entry> 3881 <para> 3882 <link linkend="quickbook.syntax.block.admonitions">Admonitions</link> 3883 </para> 3884 </entry> 3885 </row> 3886 <row> 3887 <entry> 3888 <para> 3889 table 3890 </para> 3891 </entry> 3892 <entry> 3893<programlisting><!--quickbook-escape-prefix-->[table Title 3894[[a][b][c]] 3895[[a][b][c]] 3896] 3897<!--quickbook-escape-postfix--></programlisting> 3898 </entry> 3899 <entry> 3900 <para> 3901 <link linkend="quickbook.syntax.block.tables">Tables</link> 3902 </para> 3903 </entry> 3904 </row> 3905 <row> 3906 <entry> 3907 <para> 3908 variablelist 3909 </para> 3910 </entry> 3911 <entry> 3912<programlisting><!--quickbook-escape-prefix-->[variablelist Title 3913[[a][b]] 3914[[a][b]] 3915] 3916<!--quickbook-escape-postfix--></programlisting> 3917 </entry> 3918 <entry> 3919 <para> 3920 <link linkend="quickbook.syntax.block.variable_lists">Variable Lists</link> 3921 </para> 3922 </entry> 3923 </row> 3924 <row> 3925 <entry> 3926 <para> 3927 include 3928 </para> 3929 </entry> 3930 <entry> 3931 <para> 3932 <literal>[include someother.qbk]</literal> 3933 </para> 3934 </entry> 3935 <entry> 3936 <para> 3937 <link linkend="quickbook.syntax.block.include">Include</link> 3938 </para> 3939 </entry> 3940 </row> 3941 </tbody> 3942 </tgroup> 3943 </table> 3944 </section> 3945</article> 3946
