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