1[article Quickbook 2 [quickbook 1.4] 3 [version 1.4] 4 [authors [de Guzman, Joel], [Niebler, Eric]] 5 [copyright 2002 2004 2006 Joel de Guzman, Eric Niebler] 6 [purpose /WikiWiki/ style documentation tool] 7 [license 8 Distributed under the Boost Software License, Version 1.0. 9 (See accompanying file LICENSE_1_0.txt or copy at 10 [@http://www.boost.org/LICENSE_1_0.txt]) 11 ] 12] 13 14[/ QuickBook Document version 1.3 ] 15[/ Sept 24, 2002 ] 16[/ Sept 2, 2004 ] 17[/ Feb 14, 2005 ] 18[/ Sept 13, 2005 ] 19 20[/ Some links] 21 22[def __note__ [$images/note.png]] 23[def __alert__ [$images/alert.png]] 24[def __tip__ [$images/tip.png]] 25[def :-) [$images/smiley.png]] 26[def __spirit__ [@http://spirit.sourceforge.net Spirit]] 27[def __boostbook__ [@http://www.boost.org/doc/html/boostbook.html BoostBook]] 28[def __docbook__ [@http://www.docbook.org/ DocBook]] 29 30[def __comments__ [link quickbook.syntax.comments Comments]] 31 32[def __font_styles__ [link quickbook.syntax.phrase.font_styles Font Styles]] 33[def __quotations__ [link quickbook.syntax.phrase.quotations Quotations]] 34[def __replaceable__ [link quickbook.syntax.phrase.replaceable Replaceble]] 35[def __simple_formatting__ [link quickbook.syntax.phrase.simple_formatting Simple formatting]] 36[def __inline_code__ [link quickbook.syntax.phrase.inline_code Inline code]] 37[def __code_blocks__ [link quickbook.syntax.phrase.code_blocks Code blocks]] 38[def __source_mode__ [link quickbook.syntax.phrase.source_mode Source Mode]] 39[def __line_break__ [link quickbook.syntax.phrase.line_break line-break]] 40[def __anchors__ [link quickbook.syntax.phrase.anchors Anchors]] 41[def __links__ [link quickbook.syntax.phrase.links Links]] 42[def __anchor_links__ [link quickbook.syntax.phrase.anchor_links Anchor links]] 43[def __refentry_links__ [link quickbook.syntax.phrase.refentry_links refentry links]] 44[def __code_links__ [link quickbook.syntax.phrase.code_links function, class, member, enum, macro, concept or header links]] 45[def __escape__ [link quickbook.syntax.phrase.escape Escape]] 46[def __single_char_escape__ [link quickbook.syntax.phrase.single_char_escape Single char escape]] 47[def __images__ [link quickbook.syntax.phrase.images Images]] 48 49[def __document__ [link quickbook.syntax.block.document Document]] 50[def __section__ [link quickbook.syntax.block.section Section]] 51[def __xinclude__ [link quickbook.syntax.block.xinclude xinclude]] 52[def __paragraphs__ [link quickbook.syntax.block.paragraphs Paragraphs]] 53[def __ordered_lists__ [link quickbook.syntax.block.lists.ordered_lists Ordered lists]] 54[def __list_hierarchies__ [link quickbook.syntax.block.lists.list_hierarchies List Hierarchies]] 55[def __long_list_lines__ [link quickbook.syntax.block.lists.long_list_lines Long List Lines]] 56[def __unordered_lists__ [link quickbook.syntax.block.lists.unordered_lists Unordered lists]] 57[def __mixed_lists__ [link quickbook.syntax.block.lists.mixed_lists Mixed lists]] 58[def __code__ [link quickbook.syntax.block.code Code]] 59[def __escape_back__ [link quickbook.syntax.block.escape_back Escaping Back To QuickBook]] 60[def __preformatted__ [link quickbook.syntax.block.preformatted Preformatted]] 61[def __blockquote__ [link quickbook.syntax.block.blockquote Blockquote]] 62[def __heading__ [link quickbook.syntax.block.headings Heading]] 63[def __macros__ [link quickbook.syntax.block.macros Macros]] 64[def __templates__ [link quickbook.syntax.block.templates Templates]] 65[def __predefined_macros__ [link quickbook.syntax.block.predefined_macros Predefined Macros]] 66[def __blurbs__ [link quickbook.syntax.block.blurbs Blurbs]] 67[def __admonitions__ [link quickbook.syntax.block.admonitions Admonitions]] 68[def __tables__ [link quickbook.syntax.block.tables Tables]] 69[def __variable_lists__ [link quickbook.syntax.block.variable_lists Variable Lists]] 70[def __include__ [link quickbook.syntax.block.include Include]] 71[def __import__ [link quickbook.syntax.block.import Import]] 72 73[section:intro Introduction] 74 75[:[*['["Why program by hand in five days what you can spend five years of your 76life automating?]]] 77 78-- Terrence Parr, author ANTLR/PCCTS 79] 80 81Well, QuickBook started as a weekend hack. It was originally intended to be a 82sample application using __spirit__. What is it? What you are viewing now, this 83documentation, is autogenerated by QuickBook. These files were generated from 84one master: 85 86[:[@../quickbook.qbk quickbook.qbk]] 87 88Originally named QuickDoc, this funky tool that never dies evolved into a 89funkier tool thanks to Eric Niebler who resurrected the project making it 90generate __boostbook__ instead of HTML. The __boostbook__ documentation format 91is an extension of __docbook__, an SGML or XML based format for describing 92documentation. 93 94QuickBook is a WikiWiki style documentation tool geared towards C++ 95documentation using simple rules and markup for simple formatting tasks. 96QuickBook extends the WikiWiki concept. Like the WikiWiki, QuickBook documents are 97simple text files. A single QuickBook document can generate a fully linked set 98of nice HTML and PostScript/PDF documents complete with images and syntax- 99colorized source code. 100 101Features include: 102 103* generate __boostbook__ xml, to generate HTML, PostScript and PDF 104* simple markup to link to Doxygen-generated entities 105* macro system for simple text substitution 106* simple markup for italics, bold, preformatted, blurbs, code samples, 107 tables, URLs, anchors, images, etc. 108* automatic syntax coloring of code samples 109* CSS support 110 111[endsect] 112 113[section:change_log Change Log] 114 115[h3 Version 1.3] 116 117* Quickbook file inclusion \[include\]. 118* Better xml output (pretty layout). Check out the generated XML. 119* Regression testing facility: to make sure your document will always be 120 compatible (full backward compatibility) regardless of changes to 121 QuickBook. 122* Code cleanup and refactoring. 123* Allow phrase markup in the doc-info. 124* Preformatted code blocks via \`\`code\`\` (double ticks) allows code in tables 125 and lists, for example. 126* Quickbook versioning; allows full backward compatibility. You have to add 127 \[quickbook 1.3\] to the doc-info header to enable the new features. Without 128 this, QuickBook will assume that the document is a pre-1.3 document. 129* Better (intuitive) paragraph termination. Some markups may terminate a paragraph. 130 Example:`` 131 [section x] 132 blah... 133 [endsect]`` 134* Fully qualified section and headers. Subsection names are concatenated to the 135 ID to avoid clashing. Example: `doc_name.sect_name.sub_sect_name.sub_sub_sect_name` 136* Better and whitespace handling in code snippets. 137* \[xinclude\] fixes up the relative path to the target XML file when 138 input_directory is not the same as the output_directory. 139* Allow untitled tables. 140* Allow phrase markups in section titles. 141* Allow escaping back to QuickBook from code, code blocks and inline code. 142* Footnotes, with the \[footnote This is the footnote\] syntax. 143* Post-processor bug fix for escaped XML code that it does not recognize. 144* Replaceable, with the \[~replacement\] syntax. 145* Generic Headers 146* Code changes to allow full recursion (i.e. Collectors and push/pop functions) 147* Various code cleanup/maintenance 148* Templates! 149* \[conceptref\] for referencing BoostBook <concept> entities. 150* Allow escape of spaces. The escaped space is removed from the output. Syntax: 151 `\ `. 152* Nested comments are now allowed. 153* Quickbook blocks can nest inside comments. 154* __import__ facility. 155* Callouts on imported code 156* Simple markups can now span a whole block. 157* __blurbs__, __admonitions__ and table cells (see __tables__) may now 158 contain paragraphs. 159* `\n` and `[br]` are now deprecated. 160 161[endsect] 162 163[section:syntax Syntax Summary] 164 165A QuickBook document is composed of one or more blocks. An example of 166a block is the paragraph or a C++ code snippet. Some blocks have 167special mark-ups. Blocks, except code snippets which have their own 168grammar (C++ or Python), are composed of one or more phrases. A phrase 169can be a simple contiguous run of characters. Phrases can have special 170mark-ups. Marked up phrases can recursively contain other phrases, but 171cannot contain blocks. A terminal is a self contained block-level or 172phrase-level element that does not nest anything. 173 174Blocks, in general, are delimited by two end-of-lines (the block terminator). 175Phrases in each block cannot contain a block terminator. This way, syntax errors 176such as un-matched closing brackets do not go haywire and corrupt anything past 177a single block. 178 179[section Comments] 180 181Can be placed anywhere. 182 183[pre 184'''[/ comment (no output generated) ]''' 185] 186 187[/ for testing only... ] 188 189[pre 190'''[/ comments can be nested [/ some more here] ]''' 191] 192 193[/ for testing [/ only ] ] 194 195[pre 196'''[/ Quickbook blocks can nest inside comments. [*Comment this out too!] ]''' 197] 198 199[/ for testing [*only ] ] 200 201[endsect] 202 203[section:phrase Phrase Level Elements] 204 205[section Font Styles] 206 207[pre''' 208['italic], [*bold], [_underline], [^teletype], [-strikethrough] 209'''] 210 211will generate: 212 213['italic], [*bold], [_underline], [^teletype], [-strikethrough] 214 215Like all non-terminal phrase level elements, this can of course be nested: 216 217[pre''' 218[*['bold-italic]] 219'''] 220 221will generate: 222 223[*['bold-italic]] 224 225[endsect] 226 227[section Replaceable] 228 229When you want content that may or must be replaced by the user, use the syntax: 230 231[pre''' 232[~replacement] 233'''] 234 235This will generate: 236 237[~replacement] 238 239[endsect] 240 241[section Quotations] 242 243[pre''' 244["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein 245'''] 246 247will generate: 248 249["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein 250 251Note the proper left and right quote marks. Also, while you can simply use 252ordinary quote marks like "quoted", our quotation, above, will generate correct 253DocBook quotations (e.g. <quote>quoted</quote>). 254 255Like all phrase elements, quotations may be nested. Example: 256 257[pre''' 258["Here's the rule for bargains: ["Do other men, for they would do you.] That's 259the true business precept.] 260'''] 261 262will generate: 263 264["Here's the rule for bargains: ["Do other men, for they would do you.] 265That's the true business precept.] 266 267[endsect] 268[section Simple formatting] 269 270Simple markup for formatting text, common in many applications, is now supported: 271 272[pre''' 273/italic/, *bold*, _underline_, =teletype= 274'''] 275 276will generate: 277 278/italic/, *bold*, _underline_, =teletype= 279 280Unlike QuickBook's standard formatting scheme, the rules for simpler 281alternatives are much stricter[footnote Thanks to David Barrett, author of 282[@http://quinthar.com/qwikiwiki/index.php?page=Home Qwiki], for sharing 283these samples and teaching me these obscure formatting rules. I wasn't sure 284at all if __spirit__, being more or less a formal EBNF parser, can handle 285the context sensitivity and ambiguity.]. 286 287* Simple markups cannot nest. You can combine a simple markup with a nestable markup. 288* Simple markups cannot contain any other form of quickbook markup. 289* A non-space character must follow the leading markup 290* A non-space character must precede the trailing markup 291* A space or a punctuation must follow the trailing markup 292* If the matching markup cannot be found within a block, the formatting 293 will not be applied. This is to ensure that un-matched formatting markups, 294 which can be a common mistake, does not corrupt anything past a single block. 295 We do not want the rest of the document to be rendered bold just because we 296 forgot a trailing '*'. A single block is terminated by two end of lines or 297 the close bracket: ']'. 298* A line starting with the star will be interpreted as an unordered list. 299 See __unordered_lists__. 300 301[table More Formatting Samples 302 [[Markup] [Result]] 303 [[[^'''*Bold*''']] [*Bold*]] 304 [[[^'''*Is bold*''']] [*Is bold*]] 305 [[[^'''* Not bold* *Not bold * * Not bold *''']] [* Not bold* *Not bold * * Not bold *]] 306 [[[^'''This*Isn't*Bold (no bold)''']] [This*Isn't*Bold (no bold)]] 307 [[[^'''(*Bold Inside*) (parenthesis not bold)''']] [(*Bold Inside*) (parenthesis not bold)]] 308 [[[^'''*(Bold Outside)* (parenthesis bold)''']] [*(Bold Outside)* (parenthesis bold)]] 309 [[[^'''3*4*5 = 60 (no bold)''']] [3*4*5 = 60 (no bold)]] 310 [[[^'''3 * 4 * 5 = 60 (no bold)''']] [3 * 4 * 5 = 60 (no bold)]] 311 [[[^'''3 *4* 5 = 60 (4 is bold)''']] [3 *4* 5 = 60 (4 is bold)]] 312 [[[^'''*This is bold* this is not *but this is*''']][*This is bold* this is not *but this is*]] 313 [[[^'''*This is bold*.''']] [*This is bold*.]] 314 [[[^'''*B*. (bold B)''']] [*B*. (bold B)]] 315 [[[^'''['*Bold-Italic*]''']] [['*Bold-Italic*]]] 316 [[[^'''*side-by*/-side/''']] [*side-by*/-side/]] 317] 318 319As mentioned, simple markups cannot go past a single block. The text 320from "have" to "full" in the following paragraph will be rendered as 321bold: 322 323[pre''' 324Baa baa black sheep, *have you any wool? 325Yes sir, yes sir, three bags full!* 326One for the master, one for the dame, 327And one for the little boy who lives down the lane. 328'''] 329 330Baa baa black sheep, *have you any wool? 331Yes sir, yes sir, three bags full!* 332One for the master, one for the dame, 333And one for the little boy who lives down the lane. 334 335But in the following paragraph, bold is not applied: 336 337[pre''' 338Baa baa black sheep, *have you any wool? 339Yes sir, yes sir, three bags full! 340One for the master, one for the dame, 341And one for the little boy who lives down the lane. 342'''] 343 344Baa baa black sheep, *have you any wool? 345Yes sir, yes sir, three bags full! 346One for the master, one for the dame, 347And one for the little boy who lives down the lane. 348 349[endsect] 350[section Inline code] 351 352Inlining code in paragraphs is quite common when writing C++ documentation. We 353provide a very simple markup for this. For example, this: 354 355[pre''' 356This text has inlined code `int main() { return 0; }` in it. 357'''] 358 359will generate: 360 361This text has inlined code `int main() { return 0; }` in it. The code will be 362syntax highlighted. 363 364[note We simply enclose the code with the tick: [^'''"`"'''], not the 365single quote: `"'"`. Note too that [^'''`some code`'''] is preferred over 366[^'''[^some code]''']. ] 367 368[endsect] 369[section Code blocks] 370 371Preformatted code simply starts with a space or a tab (See __code__). 372However, such a simple syntax cannot be used as phrase elements in lists 373(See __ordered_lists__ and __unordered_lists__), tables (See __tables__), 374etc. Inline code (see above) can. The problem is, inline code does not 375allow formatting with newlines, spaces, and tabs. These are lost. 376 377We provide a phrase level markup that is a mix between the two. By using the 378double-tick, instead of the single-tick, we are telling QuickBook to use 379preformatted blocks of code. Example: 380 381[pre 382\`\` 383 #include <iostream> 384 385 int main() 386 { 387 std::cout << "Hello, World!" << std::endl; 388 return 0; 389 } 390\`\` 391] 392 393will generate: 394 395`` 396 #include <iostream> 397 398 int main() 399 { 400 std::cout << "Hello, World!" << std::endl; 401 return 0; 402 } 403`` 404 405[endsect] 406[section Source Mode] 407 408If a document contains more than one type of source code then the source 409mode may be changed dynamically as the document is processed. All QuickBook 410documents are initially in C++ mode by default, though an alternative 411initial value may be set in the __document__ section. 412 413To change the source mode, use the [^\[source-mode\]] markup, where 414=source-mode= is one of the supported modes. For example, this: 415 416[pre''' 417Python's [python] `import` is rather like C++'s [c++] `#include`. A 418C++ comment `// looks like this` whereas a Python comment [python] 419`# looks like this`. 420'''] 421 422will generate: 423 424Python's [python] `import` is rather like C++'s [c++] `#include`. A 425C++ comment `// looks like this` whereas a Python comment [python] 426`#looks like this`. 427 428[table Supported Source Modes 429 [[Mode] [Source Mode Markup]] 430 [[C++] [[^\[c++\]]]] 431 [[Python] [[^\[python\]]]] 432] 433 434[note The source mode strings are lowercase.] 435 436[endsect] 437[section line-break] 438 439[pre''' 440[br] 441'''] 442 443[warning `[br]` is now deprecated. __blurbs__, __admonitions__ and 444table cells (see __tables__) may now contain paragraphs.] 445 446[endsect] 447[section Anchors] 448 449[pre''' 450[#named_anchor] 451'''] 452 453A named anchor is a hook that can be referenced by a link elsewhere in the 454document. You can then reference an anchor with [^'''[link named_anchor 455Some link text]''']. See __anchor_links__, __section__ and __heading__. 456 457[endsect] 458[section Links] 459 460[pre''' 461[@http://www.boost.org this is [*boost's] website....] 462'''] 463 464will generate: 465 466[@http://www.boost.org this is [*boost's] website....] 467 468URL links where the link text is the link itself is common. Example: 469 470[pre''' 471see http://spirit.sourceforge.net/ 472'''] 473 474so, when the text is absent in a link markup, the URL is assumed. Example: 475 476[pre 477see '''[@http://spirit.sourceforge.net/]''' 478] 479 480will generate: 481 482see [@http://spirit.sourceforge.net/] 483 484[endsect] 485[section Anchor links] 486 487You can link within a document using: 488 489[pre''' 490[link section_id.normalized_header_text The link text] 491'''] 492 493See sections __section__ and __heading__ for more info. 494 495[endsect] 496[section refentry links] 497 498In addition, you can link internally to an XML refentry like: 499 500[pre''' 501[link xml.refentry The link text] 502'''] 503 504This gets converted into [^<link linkend="xml.refentry">The link text</link>]. 505 506Like URLs, the link text is optional. If this is not present, the link text will 507automatically be the refentry. Example: 508 509[pre''' 510[link xml.refentry] 511'''] 512 513This gets converted into [^<link linkend="xml.refentry">xml.refentry</link>]. 514 515[endsect] 516[section:code_links Code Links] 517 518If you want to link to a function, class, member, enum, concept or header in the reference 519section, you can use: 520 521[pre''' 522[funcref fully::qualified::function_name The link text] 523[classref fully::qualified::class_name The link text] 524[memberref fully::qualified::member_name The link text] 525[enumref fully::qualified::enum_name The link text] 526[macroref MACRO_NAME The link text] 527[conceptref ConceptName The link text] 528[headerref path/to/header.hpp The link text] 529'''] 530 531Again, the link text is optional. If this is not present, the link text will 532automatically be the function, class, member, enum, macro, concept or header. Example: 533 534[pre''' 535[classref boost::bar::baz] 536'''] 537 538would have "boost::bar::baz" as the link text. 539 540[endsect] 541[section Escape] 542 543The escape mark-up is used when we don't want to do any processing. 544 545[pre 546\'\'\' 547escape (no processing/formatting) 548\'\'\' 549] 550 551Escaping allows us to pass XML markup to __boostbook__ or __docbook__. For example: 552 553[pre 554\'\'\' 555<emphasis role="bold">This is direct XML markup</emphasis> 556\'\'\' 557] 558 559''' 560<emphasis role="bold">This is direct XML markup</emphasis> 561''' 562 563[important Be careful when using the escape. The text must conform to 564__boostbook__/__docbook__ syntax.] 565 566[endsect] 567[section Single char escape] 568 569The backslash may be used to escape a single punctuation character. The 570punctuation immediately after the backslash is passed without any processing. 571This is useful when we need to escape QuickBook punctuations such as `[` and `]`. 572For example, how do you escape the triple quote? Simple: [^\\'\\'\\'] 573 574 575`\n` has a special meaning. It is used to generate line breaks. 576 577[warning `\n` and `[br]` are now deprecated. __blurbs__, __admonitions__ 578and table cells (see __tables__) may now contain paragraphs.] 579 580The escaped space: `\ ` also has a special meaning. The escaped space is removed 581from the output. 582 583[endsect] 584[section Images] 585 586[pre''' 587[$image.jpg] 588'''] 589 590[endsect] 591[section Footnotes] 592 593As of version 1.3, QuickBook supports footnotes. Just put the text of the 594footnote in a `[footnote]` block, and the text will be put at the bottom 595of the current page. For example, this: 596 597[pre''' 598[footnote A sample footnote] 599'''] 600 601will generate this[footnote A sample footnote]. 602 603[section Macro Expansion] 604 605[pre''' 606__a_macro_identifier__ 607'''] 608 609See __macros__ for details. 610 611[endsect] 612 613[section Template Expansion] 614 615[pre''' 616[a_template_identifier] 617'''] 618 619See __templates__ for details. 620 621[endsect] 622 623[endsect] 624[endsect] 625[section:block Block Level Elements] 626 627[section Document] 628 629Every document must begin with a Document Info section, which should look 630like this: 631 632[pre''' 633[document-type The Document Title 634 [quickbook 1.3] 635 [version 1.0] 636 [id the_document_name] 637 [dirname the_document_dir] 638 [copyright 2000 2002 2003 Joe Blow, Jane Doe] 639 [purpose The document's reason for being] 640 [category The document's category] 641 [authors [Blow, Joe], [Doe, Jane]] 642 [license The document's license] 643 [source-mode source-type] 644] 645'''] 646 647Where document-type is one of: 648 649* book 650* article 651* library 652* chapter 653* part 654* appendix 655* preface 656* qandadiv 657* qandaset 658* reference 659* set 660 661quickbook 1.3 declares the version of quickbook the document is written for. 662In its absence, version 1.1 is assumed. 663 664=version=, =id=, =dirname=, =copyright=, =purpose=, =category=, =authors=, 665=license=, =last-revision= and =source-mode= are optional information. 666 667=source-type= is a lowercase string setting the initial __source_mode__. If 668the =source-mode= field is omitted, a default value of =c++= will be used. 669 670[endsect] 671[section Section] 672 673Starting a new section is accomplished with: 674 675[pre''' 676[section:id The Section Title] 677'''] 678 679where /id/ is optional. id will be the filename of the generated section. 680If it is not present, "The Section Title" will be normalized and become the id. 681Valid characters are =a-Z=, =A-Z=, =0-9= and =_=. All non-valid characters are 682converted to underscore and all upper-case are converted to lower case. 683Thus: "The Section Title" will be normalized to "the_section_title". 684 685End a section with: 686 687[pre''' 688[endsect] 689'''] 690 691Sections can nest, and that results in a hierarchy in the table of contents. 692 693[endsect] 694[section xinclude] 695 696You can include another XML file with: 697 698[pre''' 699[xinclude file.xml] 700'''] 701 702This is useful when file.xml has been generated by Doxygen and contains your 703reference section. 704 705[endsect] 706[section Paragraphs] 707 708Paragraphs start left-flushed and are terminated by two or more newlines. No 709markup is needed for paragraphs. QuickBook automatically detects paragraphs from 710the context. Block markups \[section, endsect, h1, h2, h3, h4, h5, h6, blurb, 711(block-quote) ':', pre, def, table and include \] may also terminate a paragraph. 712 713[endsect] 714 715[section Lists] 716[section Ordered lists] 717 718[pre 719# One 720# Two 721# Three 722] 723 724will generate: 725 726# One 727# Two 728# Three 729 730[endsect] 731[section List Hierarchies] 732 733List hierarchies are supported. Example: 734 735[pre 736# One 737# Two 738# Three 739 # Three.a 740 # Three.b 741 # Three.c 742# Four 743 # Four.a 744 # Four.a.i 745 # Four.a.ii 746# Five 747] 748 749will generate: 750 751# One 752# Two 753# Three 754 # Three.a 755 # Three.b 756 # Three.c 757# Fourth 758 # Four.a 759 # Four.a.i 760 # Four.a.ii 761# Five 762 763[endsect] 764[section Long List Lines] 765 766Long lines will be wrapped appropriately. Example: 767 768[pre 769# A short item. 770# A very long item. A very long item. A very long item. 771 A very long item. A very long item. A very long item. 772 A very long item. A very long item. A very long item. 773 A very long item. A very long item. A very long item. 774 A very long item. A very long item. A very long item. 775# A short item. 776] 777 778# A short item. 779# A very long item. A very long item. A very long item. 780 A very long item. A very long item. A very long item. 781 A very long item. A very long item. A very long item. 782 A very long item. A very long item. A very long item. 783 A very long item. A very long item. A very long item. 784# A short item. 785 786[endsect] 787[section Unordered lists] 788 789[pre''' 790* First 791* Second 792* Third 793'''] 794 795will generate: 796 797* First 798* Second 799* Third 800 801[endsect] 802[section Mixed lists] 803 804Mixed lists (ordered and unordered) are supported. Example: 805 806[pre''' 807# One 808# Two 809# Three 810 * Three.a 811 * Three.b 812 * Three.c 813# Four 814'''] 815 816will generate: 817 818# One 819# Two 820# Three 821 * Three.a 822 * Three.b 823 * Three.c 824# Four 825 826And... 827 828[pre''' 829# 1 830 * 1.a 831 # 1.a.1 832 # 1.a.2 833 * 1.b 834# 2 835 * 2.a 836 * 2.b 837 # 2.b.1 838 # 2.b.2 839 * 2.b.2.a 840 * 2.b.2.b 841'''] 842 843will generate: 844 845# 1 846 * 1.a 847 # 1.a.1 848 # 1.a.2 849 * 1.b 850# 2 851 * 2.a 852 * 2.b 853 # 2.b.1 854 # 2.b.2 855 * 2.b.2.a 856 * 2.b.2.b 857 858[endsect] 859[endsect] 860 861[section Code] 862 863Preformatted code starts with a space or a tab. The code will be 864syntax highlighted according to the current __source_mode__: 865 866[c++] 867 868 #include <iostream> 869 870 int main() 871 { 872 // Sample code 873 std::cout << "Hello, World\n"; 874 return 0; 875 } 876 877[python] 878 879 import cgi 880 881 def cookForHtml(text): 882 '''"Cooks" the input text for HTML.''' 883 884 return cgi.escape(text) 885 886[c++] 887 888Macros that are already defined are expanded in source code. Example: 889 890[pre''' 891[def __array__ [@http://www.boost.org/doc/html/array/reference.html array]] 892[def __boost__ [@http://www.boost.org/libs/libraries.htm boost]] 893 894 using __boost__::__array__; 895'''] 896 897Generates: 898 899[def __array__ [@http://www.boost.org/doc/html/array/reference.html array]] 900[def __boost__ [@http://www.boost.org/libs/libraries.htm boost]] 901 902 using __boost__::__array__; 903 904[endsect] 905[section:escape_back Escaping Back To QuickBook] 906 907Inside code, code blocks and inline code, QuickBook does not allow any 908markup to avoid conflicts with the target syntax (e.g. c++). In case you 909need to switch back to QuickBook markup inside code, you can do so using a 910language specific /escape-back/ delimiter. In C++ and Python, the delimiter 911is the double tick (back-quote): "\`\`" and "\`\`". Example: 912 913[pre''' 914void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``() 915{ 916} 917'''] 918 919Will generate: 920 921 void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``() 922 { 923 } 924 925When escaping from code to QuickBook, only phrase level markups are 926allowed. Block level markups like lists, tables etc. are not allowed. 927 928[endsect] 929[section Preformatted] 930 931Sometimes, you don't want some preformatted text to be parsed as C++. In such 932cases, use the [^[pre ... \]] markup block. 933 934[pre''' 935[pre 936 937 Some *preformatted* text Some *preformatted* text 938 939 Some *preformatted* text Some *preformatted* text 940 941 Some *preformatted* text Some *preformatted* text 942 943] 944'''] 945 946Spaces, tabs and newlines are rendered as-is. Unlike all quickbook block level 947markup, pre (and Code) are the only ones that allow multiple newlines. The 948markup above will generate: 949 950[pre 951 952Some *preformatted* text Some *preformatted* text 953 954 Some *preformatted* text Some *preformatted* text 955 956 Some *preformatted* text Some *preformatted* text 957 958] 959 960Notice that unlike Code, phrase markup such as font style is still permitted 961inside =pre= blocks. 962 963[endsect] 964[section Blockquote] 965 966[pre 967'''[:sometext...]''' 968] 969 970[:Indents the paragraph. This applies to one paragraph only.] 971 972[endsect] 973[section Admonitions] 974 975[pre''' 976[note This is a note] 977[tip This is a tip] 978[important This is important] 979[caution This is a caution] 980[warning This is a warning] 981'''] 982 983generates __docbook__ admonitions: 984 985[note This is a note] 986[tip This is a tip] 987[important This is important] 988[caution This is a caution] 989[warning This is a warning] 990 991These are the only admonitions supported by __docbook__. So, 992for example [^\[information This is some information\]] is unlikely 993to produce the desired effect. 994 995[endsect] 996[section Headings] 997 998[pre''' 999[h1 Heading 1] 1000[h2 Heading 2] 1001[h3 Heading 3] 1002[h4 Heading 4] 1003[h5 Heading 5] 1004[h6 Heading 6] 1005'''] 1006 1007[h1 Heading 1] 1008[h2 Heading 2] 1009[h3 Heading 3] 1010[h4 Heading 4] 1011[h5 Heading 5] 1012[h6 Heading 6] 1013 1014Headings 1-3 \[h1 h2 and h3\] will automatically have anchors with normalized 1015names with [^name="section_id.normalized_header_text"] (i.e. valid characters are 1016=a-z=, =A-Z=, =0-9= and =_=. All non-valid characters are converted to underscore 1017and all upper-case are converted to lower-case. For example: Heading 10181 in section Section 2 will be normalized to [^section_2.heading_1]). You can use: 1019 1020[pre''' 1021[link section_id.normalized_header_text The link text] 1022'''] 1023 1024to link to them. See __anchor_links__ and __section__ for more info. 1025 1026[endsect] 1027[section Generic Heading] 1028 1029In cases when you don't want to care about the heading level (1 to 6), you 1030can use the /Generic Heading/: 1031 1032[pre''' 1033[heading Heading] 1034'''] 1035 1036The /Generic Heading/ assumes the level, plus one, of the innermost section 1037where it is placed. For example, if it is placed in the outermost section, 1038then, it assumes /h2/. 1039 1040Headings are often used as an alternative to sections. It is used 1041particularly if you do not want to start a new section. In many cases, 1042however, headings in a particular section is just flat. Example: 1043 1044[pre''' 1045[section A] 1046[h2 X] 1047[h2 Y] 1048[h2 Z] 1049[endsect] 1050'''] 1051 1052Here we use h2 assuming that section A is the outermost level. If it is 1053placed in an inner level, you'll have to use h3, h4, etc. depending on 1054where the section is. In general, it is the section level plus one. It is 1055rather tedious, however, to scan the section level everytime. If you 1056rewrite the example above as shown below, this will be automatic: 1057 1058[pre''' 1059[section A] 1060[heading X] 1061[heading Y] 1062[heading Z] 1063[endsect] 1064'''] 1065 1066They work well regardless where you place them. You can rearrange sections 1067at will without any extra work to ensure correct heading levels. In fact, 1068with /section/ and /heading/, you have all you need. /h1/../h6/ becomes 1069redundant. /h1/../h6/ might be deprecated in the future. 1070 1071[endsect] 1072[section Macros] 1073 1074[pre''' 1075[def macro_identifier some text] 1076'''] 1077 1078When a macro is defined, the identifier replaces the text anywhere in the 1079file, in paragraphs, in markups, etc. macro_identifier is a string of non- 1080white space characters except '\]'. A macro may not follow an alphabetic 1081character or the underscore. The replacement text can be any phrase (even 1082marked up). Example: 1083 1084[pre''' 1085[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&type=1]] 1086sf_logo 1087'''] 1088 1089Now everywhere the sf_logo is placed, the picture will be inlined. 1090 1091[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&type=1]] 1092sf_logo 1093 1094[tip It's a good idea to use macro identifiers that are distinguishable. 1095For instance, in this document, macro identifiers have two leading and 1096trailing underscores (e.g. [^'''__spirit__''']). The reason is to avoid 1097unwanted macro replacement.] 1098 1099Links (URLS) and images are good candidates for macros. *1*) They tend to 1100change a lot. It is a good idea to place all links and images in one place near the top 1101to make it easy to make changes. *2*) The syntax is not pretty. It's easier to read and 1102write, e.g. [^'''__spirit__'''] than [^'''[@http://spirit.sourceforge.net Spirit]''']. 1103 1104Some more examples: 1105 1106[pre''' 1107[def :-) [$theme/smiley.png]] 1108[def __spirit__ [@http://spirit.sourceforge.net Spirit]] 1109'''] 1110 1111(See __images__ and __links__) 1112 1113Invoking these macros: 1114 1115[pre''' 1116Hi __spirit__ :-) 1117'''] 1118 1119will generate this: 1120 1121Hi __spirit__ :-) 1122 1123[endsect] 1124[section Predefined Macros] 1125 1126Quickbook has some predefined macros that you can already use. 1127 1128[table Predefined Macros 1129 [[Macro] [Meaning] [Example]] 1130 [['''__DATE__'''] [Today's date] [__DATE__]] 1131 [['''__TIME__'''] [The current time] [__TIME__]] 1132 [['''__FILENAME__'''] [Quickbook source filename] [__FILENAME__]] 1133] 1134 1135[endsect] 1136[section Templates] 1137 1138Templates provide a more versatile text substitution mechanism. Templates 1139come in handy when you need to create parameterizable, multi-line, 1140boilerplate text that you specify once and expand many times. Templates 1141accept one or more arguments. These arguments act like place-holders for 1142text replacement. Unlike simple macros, which are limited to phrase level 1143markup, templates can contain block level markup (e.g. paragraphs, code 1144blocks and tables). 1145 1146Example template: 1147 1148[pre''' 1149[template person[name age what] 1150 1151Hi, my name is [name]. I am [age] years old. I am a [what]. 1152 1153] 1154'''] 1155 1156[template person[name age what] 1157 1158Hi, my name is [name]. I am [age] years old. I am a [what]. 1159 1160] 1161 1162[heading Template Identifier] 1163 1164Template identifiers can either consist of: 1165 1166* An initial alphabetic character or the underscore, followed by 1167 zero or more alphanumeric characters or the underscore. This is 1168 similar to your typical C/C++ identifier. 1169* A single character punctuation (a non-alphanumeric printable character) 1170 1171[heading Formal Template Arguments] 1172 1173Template formal arguments are identifiers consisting of an initial 1174alphabetic character or the underscore, followed by zero or more 1175alphanumeric characters or the underscore. This is similar to your typical 1176C/C++ identifier. 1177 1178A template formal argument temporarily hides a template of the same name at 1179the point where the [link quickbook.syntax.block.templates.template_expansion 1180template is expanded]. Note that the body of the [^person] template above 1181refers to [^name] [^age] and [^what] as [^\[name\]] [^\[age\]] and 1182[^\[what\]]. [^name] [^age] and [^what] are actually templates that exist 1183in the duration of the template call. 1184 1185[heading Template Body] 1186 1187The template body can be just about any QuickBook block or phrase. There 1188are actually two forms. Templates may be phrase or block level. Phrase 1189templates are of the form: 1190 1191[pre''' 1192[template sample[arg1 arg2...argN] replacement text... ] 1193'''] 1194 1195Block templates are of the form: 1196 1197[pre''' 1198[template sample[arg1 arg2...argN] 1199replacement text... 1200] 1201'''] 1202 1203The basic rule is as follows: if a newline immediately follows the argument 1204list, then it is a block template, otherwise, it is a phrase template. 1205Phrase templates are typically expanded as part of phrases. Like macros, 1206block level elements are not allowed in phrase templates. 1207 1208[heading Template Expansion] 1209 1210You expand a template this way: 1211 1212[pre''' 1213[template_identifier arg1..arg2..arg3] 1214'''] 1215 1216At template expansion, you supply the actual arguments. The template will 1217be expanded with your supplied arguments. Example: 1218 1219[pre''' 1220[person James Bond..39..Spy] 1221[person Santa Clause..87..Big Red Fatso] 1222'''] 1223 1224Which will expand to: 1225 1226[person James Bond..39..Spy] 1227[person Santa Clause..87..Big Red Fatso] 1228 1229[caution A word of caution: Templates are recursive. A template can call 1230another template or even itself, directly or indirectly. There are no 1231control structures in QuickBook (yet) so this will always mean infinite 1232recursion. QuickBook can detect this situation and report an error if 1233recursion exceeds a certain limit.] 1234 1235Each actual argument can be a word, a text fragment or just about any [link 1236quickbook.syntax.phrase QuickBook phrase]. Arguments are separated by the 1237double dot [^".."] and terminated by the close parenthesis. 1238 1239[heading Nullary Templates] 1240 1241Nullary templates look and act like simple macros. Example: 1242 1243[pre''' 1244[template alpha[]'''&#945;'''] 1245[template beta[]'''&#946;'''] 1246'''] 1247 1248[template alpha[]'''α'''] 1249[template beta[]'''β'''] 1250 1251Expanding: 1252 1253[pre'''Some squigles...[*[alpha][beta]]'''] 1254 1255We have: 1256 1257Some squiggles...[*[alpha][beta]] 1258 1259The difference with macros are 1260 1261* The explicit [link quickbook.syntax.block.templates.template_expansion 1262 template expansion syntax]. This is an advantage because, now, we don't 1263 have to use obscure naming conventions like double underscores (e.g. 1264 \_\_alpha\_\_) to avoid unwanted 1265 macro replacement. 1266* The template is expanded at the point where it is invoked. A macro is 1267 expanded immediately at its point of declaration. This is subtle and 1268 can cause a slight difference in behavior especially if you refer to 1269 other macros and templates in the body. 1270 1271The empty brackets after the template identifier ([^alpha\[\]]) indicates no 1272arguments. If the template body does not look like a template argument list, we 1273can elide the empty brackets. Example: 1274 1275[pre''' 1276[template aristotle_quote Aristotle: [*['Education is the best provision 1277for the journey to old age.]]] 1278'''] 1279 1280[template aristotle_quote\ Aristotle: [*['Education is the best provision 1281for the journey to old age.]]] 1282 1283Expanding: 1284 1285[pre''' 1286Here's a quote from [aristotle_quote]. 1287'''] 1288 1289We have: 1290 1291Here's a quote from [aristotle_quote]. 1292 1293The disadvantage is that you can't avoid the space between the template 1294identifier, `aristotle_quote`, and the template body "Aristotle...". This space 1295will be part of the template body. If that space is unwanted, use empty 1296brackets or use the space escape: "`\ `". Example: 1297 1298[pre''' 1299[template tag\ _tag] 1300'''] 1301 1302[template tag\ _tag] 1303 1304Then expanding: 1305 1306[pre''' 1307`struct` x[tag]; 1308'''] 1309 1310We have: 1311 1312`struct` x[tag]; 1313 1314You have a couple of ways to do it. I personally prefer the explicit empty 1315brackets, though. 1316 1317[heading Simple Arguments] 1318 1319As mentioned, arguments are separated by the double dot [^".."]. If there 1320are less arguments passed than expected, QuickBook attempts to break the 1321last argument into two or more arguments following this logic: 1322 1323* Break the last argument into two, at the first space found ([^'', '\\n', 1324 \\t' or '\\r']). 1325* Repeat until there are enough arguments or if there are no more spaces 1326 found (in which case, an error is reported). 1327 1328For example: 1329 1330[pre''' 1331[template simple[a b c d] [a][b][c][d]] 1332[simple w x y z] 1333'''] 1334 1335will produce: 1336 1337[template simple[a b c d] [a][b][c][d]] 1338[simple w x y z] 1339 1340"w x y z" is initially treated as a single argument because we didn't 1341supply any [^".."] separators. However, since [^simple] expects 4 1342arguments, "w x y z" is broken down iteratively (applying the logic above) 1343until we have "w", "x", "y" and "z". 1344 1345QuickBook only tries to get the arguments it needs. For example: 1346 1347[pre''' 1348[simple w x y z trail] 1349'''] 1350 1351will produce: 1352 1353[simple w x y z trail] 1354 1355The arguments being: "w", "x", "y" and "z trail". 1356 1357It should be obvious now that for simple arguments with no spaces, we can 1358get by without separating the arguments with [^".."] separators. It is 1359possible to combine [^".."] separators with the argument passing 1360simplification presented above. Example: 1361 1362[pre''' 1363[simple what do you think ..m a n?] 1364'''] 1365 1366will produce: 1367 1368[simple what do you think ..m a n?] 1369 1370[heading Punctuation Templates] 1371 1372With templates, one of our objectives is to allow us to rewrite QuickBook 1373in QuickBook (as a qbk library). For that to happen, we need to accommodate 1374single character punctuation templates which are fairly common in 1375QuickBook. You might have noticed that single character punctuations are 1376allowed as [link quickbook.syntax.block.templates.template_identifier 1377template identifiers]. Example: 1378 1379[pre''' 1380[template ![bar] '''<hey>'''[bar]'''</hey>'''] 1381'''] 1382 1383Now, expanding this: 1384 1385[pre''' 1386[!baz] 1387'''] 1388 1389We will have: 1390 1391[pre 1392<hey>baz</hey> 1393] 1394 1395[endsect] 1396[section Blurbs] 1397 1398[pre''' 1399[blurb :-) [*An eye catching advertisement or note...] 1400 1401 __spirit__ is an object-oriented recursive-descent parser generator framework 1402 implemented using template meta-programming techniques. Expression templates 1403 allow us to approximate the syntax of Extended Backus-Normal Form (EBNF) 1404 completely in C++. 1405] 1406'''] 1407 1408will generate this: 1409 1410[blurb :-) [*An eye catching advertisement or note...] 1411 1412 __spirit__ is an object-oriented recursive-descent parser generator 1413 framework implemented using template meta-programming techniques. Expression 1414 templates allow us to approximate the syntax of Extended Backus-Normal Form 1415 (EBNF) completely in C++. 1416] 1417 1418[note Prefer [link quickbook.syntax.block.admonitions admonitions] wherever 1419appropriate.] 1420 1421[endsect] 1422[section Tables] 1423 1424[pre''' 1425[table A Simple Table 1426 [[Heading 1] [Heading 2] [Heading 3]] 1427 [[R0-C0] [R0-C1] [R0-C2]] 1428 [[R1-C0] [R1-C1] [R1-C2]] 1429 [[R2-C0] [R2-C1] [R2-C2]] 1430] 1431'''] 1432 1433will generate: 1434 1435[table A Simple Table 1436 [[Heading 1] [Heading 2] [Heading 3]] 1437 [[R0-C0] [R0-C1] [R0-C2]] 1438 [[R2-C0] [R2-C1] [R2-C2]] 1439 [[R3-C0] [R3-C1] [R3-C2]] 1440] 1441 1442The table title is optional. The first row of the table is automatically 1443treated as the table header; that is, it is wrapped in 1444[^<thead>...</thead>] XML tags. Note that unlike the original QuickDoc, the 1445columns are nested in [ cells... ]. The syntax is free-format and allows 1446big cells to be formatted nicely. Example: 1447 1448[pre''' 1449[table Table with fat cells 1450 [[Heading 1] [Heading 2]] 1451 [ 1452 [Row 0, Col 0: a small cell] 1453 [ 1454 Row 0, Col 1: a big fat cell with paragraphs 1455 1456 Boost provides free peer-reviewed portable C++ source libraries. 1457 1458 We emphasize libraries that work well with the C++ Standard Library. 1459 Boost libraries are intended to be widely useful, and usable across 1460 a broad spectrum of applications. The Boost license encourages both 1461 commercial and non-commercial use. 1462 ] 1463 ] 1464 [ 1465 [Row 1, Col 0: a small cell] 1466 [Row 1, Col 1: a small cell] 1467 ] 1468] 1469'''] 1470 1471and thus: 1472 1473[table Table with fat cells 1474 [[Heading 1] [Heading 2]] 1475 [ 1476 [Row 0, Col 0: a small cell] 1477 [ 1478 Row 0, Col 1: a big fat cell with paragraphs 1479 1480 Boost provides free peer-reviewed portable C++ source libraries. 1481 1482 We emphasize libraries that work well with the C++ Standard Library. 1483 Boost libraries are intended to be widely useful, and usable across 1484 a broad spectrum of applications. The Boost license encourages both 1485 commercial and non-commercial use. 1486 ] 1487 ] 1488 [ 1489 [Row 1, Col 0: a small cell] 1490 [Row 1, Col 1: a small cell] 1491 ] 1492] 1493 1494Here's how to have preformatted blocks of code in a table cell: 1495 1496[pre''' 1497[table Table with code 1498 [[Comment] [Code]] 1499 [ 1500 [My first program] 1501 ['''\`\` 1502 #include <iostream> 1503 1504 int main() 1505 { 1506 std::cout << "Hello, World!" << std::endl; 1507 return 0; 1508 } 1509 \`\`'''] 1510 ] 1511] 1512'''] 1513 1514[table Table with code 1515 [[Comment] [Code]] 1516 [ 1517 [My first program] 1518 [`` 1519 #include <iostream> 1520 1521 int main() 1522 { 1523 std::cout << "Hello, World!" << std::endl; 1524 return 0; 1525 } 1526 ``] 1527 ] 1528] 1529 1530[endsect] 1531[section Variable Lists] 1532 1533[pre''' 1534[variablelist A Variable List 1535 [[term 1] [The definition of term 1]] 1536 [[term 2] [The definition of term 2]] 1537 [[term 3] [The definition of term 3]] 1538] 1539'''] 1540 1541will generate: 1542 1543[variablelist A Variable List 1544 [[term 1] [The definition of term 1]] 1545 [[term 2] [The definition of term 2]] 1546 [[term 3] [The definition of term 3]] 1547] 1548 1549The rules for variable lists are the same as for tables, except that 1550only 2 "columns" are allowed. The first column contains the terms, and 1551the second column contains the definitions. Those familiar with HTML 1552will recognize this as a "definition list". 1553 1554[endsect] 1555[section Include] 1556 1557You can include one QuickBook file from another. The syntax is simply: 1558 1559[pre''' 1560[include someother.qbk] 1561'''] 1562 1563The included file will be processed as if it had been cut and pasted 1564into the current document, with the following exceptions: 1565 1566* The '''__FILENAME__''' predefined macro will reflect the name of the 1567 file currently being processed. 1568* Any macros defined in the included file are scoped to that file. 1569 1570The [^\[include\]] directive lets you specify a document id to use for the 1571included file. When this id is not explicitly specified, the id defaults to 1572the filename ("someother", in the example above). You can specify the id 1573like this: 1574 1575[pre''' 1576[include:someid someother.qbk] 1577'''] 1578 1579All auto-generated anchors will use the document id as a unique prefix. So 1580for instance, if there is a top section in someother.qbk named "Intro", the 1581named anchor for that section will be "someid.intro", and you can link to 1582it with [^\[link someid.intro The Intro\]]. 1583 1584[endsect] 1585 1586[section Import] 1587 1588When documenting code, you'd surely need to present code from actual source 1589files. While it is possible to copy some code and paste them in your QuickBook 1590file, doing so is error prone and the extracted code in the documentation tends 1591to get out of sync with the actual code as the code evolves. The problem, as 1592always, is that once documentation is written, the tendency is for the docs to 1593languish in the archives without maintenance. 1594 1595QuickBook's import facility provides a nice solution. 1596 1597[heading Example] 1598 1599You can effortlessly import code snippets from source code into your QuickBook. 1600The following illustrates how this is done: 1601 1602[pre''' 1603[import ../test/stub.cpp] 1604[foo] 1605[bar] 1606'''] 1607 1608The first line: 1609 1610[pre''' 1611[import ../test/stub.cpp] 1612'''] 1613 1614collects specially marked-up code snippets from [@../../test/stub.cpp stub.cpp] 1615and places them in your QuickBook file as virtual templates. Each of the 1616specially marked-up code snippets has a name (e.g. `foo` and `bar` in the 1617example above). This shall be the template identifier for that particular code 1618snippet. The second and third line above does the actual template expansion: 1619 1620[pre''' 1621[foo] 1622[bar] 1623'''] 1624 1625And the result is: 1626 1627[import ../test/stub.cpp] 1628[foo] 1629[bar] 1630 1631[heading Code Snippet Markup] 1632 1633Note how the code snippets in [@../../test/stub.cpp stub.cpp] get marked up. We 1634use distinguishable comments following the form: 1635 1636 //[id 1637 some code here 1638 //] 1639 1640The first comment line above initiates a named code-snippet. This prefix will 1641not be visible in quickbook. The entire code-snippet in between `//[id` and 1642`//]` will be inserted as a template in quickbook with name ['/id/]. The comment 1643`//]` ends a code-snippet This too will not be visible in quickbook. 1644 1645[heading Special Comments] 1646 1647Special comments of the form: 1648 1649 //` some [*quickbook] markup here 1650 1651and: 1652 1653 /*` some [*quickbook] markup here */ 1654 1655will be parsed by QuickBook. This can contain quickbook /blocks/ (e.g. sections, 1656paragraphs, tables, etc). In the first case, the initial slash-slash, tick and 1657white-space shall be ignored. In the second, the initial slash-star-tick and the 1658final star-slash shall be ignored. 1659 1660[heading Callouts] 1661 1662Special comments of the form: 1663 1664 /*< some [*quickbook] markup here >*/ 1665 1666will be regarded as callouts. These will be collected, numbered and 1667rendered as a "callout bug" (a small icon with a number). After the 1668whole snippet is parsed, the callout list is generated. See 1669[@http://www.docbook.org/tdg/en/html/callout.html Callouts] for details. 1670Example: 1671 1672[foo_bar] 1673 1674Checkout [@../../test/stub.cpp stub.cpp] to see the actual code. 1675 1676[endsect] 1677 1678[endsect] 1679[endsect] 1680 1681[section:install Installation and configuration] 1682 1683This section provides some guidelines on how to install and configure 1684BoostBook and Quickbook under several operating systems. 1685 1686Before continuing, it is very important that you keep this in mind: if you 1687try to build some documents and the process breaks due to misconfiguration, 1688be absolutely sure to delete any `bin` and `bin.v2` directories generated 1689by the build before trying again. Otherwise your configuration fixes will 1690not take any effect. 1691 1692[section:windows Windows 2000, XP, 2003, Vista] 1693 1694[python] 1695 1696[:['Section contributed by Julio M. Merino Vidal]] 1697 1698The following instructions apply to any Windows system based on Windows 16992000, including Windows XP, Windows 2003 Server and Windows Vista. The 1700paths shown below are taken from a Windows Vista machine; you will need to 1701adjust them to match your system in case you are running an older version. 1702 1703# First of all you need to have a copy of `xsltproc` for Windows. There 1704 are many ways to get this tool, but to keep things simple, use the 1705 [@http://www.zlatkovic.com/pub/libxml/ binary packages] made by Igor 1706 Zlatkovic. At the very least, you need to download the following 1707 packages: `iconv`, `zlib`, `libxml2` and `libxslt`. 1708 1709# Unpack all these packages in the same directory so that you get unique 1710 `bin`, `include` and `lib` directories within the hierarchy. These 1711 instructions use `C:\Users\example\Documents\boost\xml` as the root for 1712 all files. 1713 1714# From the command line, go to the `bin` directory and launch 1715 `xsltproc.exe` to ensure it works. You should get usage information on 1716 screen. 1717 1718# Download [@http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip Docbook XML 1719 4.2] and unpack it in the same directory used above. That is: 1720 `C:\Users\example\Documents\boost\xml\docbook-xml`. 1721 1722# Download the latest 1723 [@http://sourceforge.net/project/showfiles.php?group_id=21935&package_id=16608 1724 Docbook XSL] version and unpack it, again in the same directory 1725 used before. To make things easier, rename the directory created 1726 during the extraction to `docbook-xsl` (bypassing the version name): 1727 `C:\Users\example\Documents\boost\xml\docbook-xsl`. 1728 1729# Add the following to your `user-config.jam` file, which should live in 1730 your home directory (`%HOMEDRIVE%%HOMEPATH%`). You must already have it 1731 somewhere or otherwise you could not be building Boost (i.e. missing 1732 tools configuration). 1733 1734 using xsltproc 1735 : "C:/Users/example/Documents/boost/xml/bin/xsltproc.exe" 1736 ; 1737 1738 using boostbook 1739 : "C:/Users/example/Documents/boost/xml/docbook-xsl" 1740 : "C:/Users/example/Documents/boost/xml/docbook-xml" 1741 ; 1742 1743The above steps are enough to get a functional BoostBook setup. Quickbook 1744will be automatically built when needed. If you want to avoid these 1745rebuilds: 1746 1747# Go to Quickbook's source directory (`BOOST_ROOT\tools\quickbook`). 1748 1749# Build the utility by issuing `bjam --v2`. 1750 1751# Copy the resulting `quickbook.exe` binary (located under the 1752 `BOOST_ROOT\bin.v2` hierarchy) to a safe place. Following our previous 1753 example, you can install it into: 1754 `C:\Users\example\Documents\boost\xml\bin`. 1755 1756# Add the following to your `user-config.jam` file: 1757 1758 using quickbook 1759 : "C:/Users/example/Documents/boost/xml/bin/quickbook.exe" 1760 ; 1761 1762[endsect] 1763 1764[section:linux Debian, Ubuntu] 1765 1766The following instructions apply to Debian and its derivatives. They are based 1767on a Ubuntu Edgy install but should work on other Debian based systems. 1768 1769First install the `bjam`, `xsltproc`, `docbook-xsl` and `docbook-xml` packages. 1770For example, using `apt-get`: 1771 1772 sudo apt-get install xsltprc docbook-xsl docbook-xml 1773 1774If you're planning on building boost's documentation, you'll also need to 1775install the `doxygen` package as well. 1776 1777Next, we need to configure Boost Build to compile BoostBook files. Add the 1778following to your `user-config.jam` file, which should be in your home 1779directory. If you don't have one, create a file containing this text. For more 1780information on setting up `user-config.jam`, see the 1781[@http://boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html Boost 1782Build documentation]. 1783 1784 using xsltproc ; 1785 1786 using boostbook 1787 : /usr/share/xml/docbook/stylesheet/nwalsh 1788 : /usr/share/xml/docbook/schema/dtd/4.2 1789 ; 1790 1791 # Remove this line if you're not using doxygen 1792 using doxygen ; 1793 1794The above steps are enough to get a functional BoostBook setup. Quickbook 1795will be automatically built when needed. If you want to avoid these 1796rebuilds: 1797 1798# Go to Quickbook's source directory (`BOOST_ROOT/tools/quickbook`). 1799 1800# Build the utility by issuing `bjam --v2`. 1801 1802# Copy the resulting `quickbook` binary (located under the 1803 `BOOST_ROOT/bin.v2` hierarchy) to a safe place. The traditional location is 1804 `/usr/local/bin`. 1805 1806# Add the following to your `user-config.jam` file, using the full path of the 1807 quickbook executable: 1808 1809 using quickbook 1810 : /usr/local/bin/quickbook 1811 ; 1812 1813[endsect] 1814[endsect] [/Installation and configuration] 1815 1816[section:editors Editor Support] 1817 1818Editing quickbook files is usually done with text editors both simple and 1819powerful. The following sections list the settings for some editors which can 1820help make editing quickbook files a bit easier. 1821 1822[blurb __note__ You may submit your settings, tips, and suggestions to the 1823authors, or through the [@https://lists.sourceforge.net/lists/listinfo/boost- 1824docs Boost Docs mailing list].] 1825 1826[section:scite Scintilla Text Editor] 1827 1828[:['Section contributed by Dean Michael Berris]] 1829 1830The Scintilla Text Editor (SciTE) is a free source code editor for Win32 and X. 1831It uses the SCIntilla source code editing component. 1832 1833[blurb __tip__ SciTE can be downloaded from [@http://www.scintilla.org/SciTE.html]] 1834 1835You can use the following settings to highlight quickbook tags when 1836editing quickbook files. 1837 1838[pre''' 1839qbk=*.qbk 1840lexer.*.qbk=props 1841use.tabs.$(qbk)=0 1842tab.size.$(qbk)=4 1843indent.size.$(qbk)=4 1844style.props.32=$(font.base) 1845comment.stream.start.props=[/ 1846comment.stream.end.props=] 1847comment.box.start.props=[/ 1848comment.box.middle.props= 1849comment.box.end.props=] 1850'''] 1851 1852[blurb __note__ Thanks to Rene Rivera for the above SciTE settings.] 1853 1854[endsect] [/scite] 1855[endsect] [/editors] 1856 1857[section:faq Frequently Asked Questions] 1858 1859[heading Can I use QuickBook for non-Boost documentation?] 1860 1861QuickBook can be used for non-Boost documentation with a little extra work. 1862 1863[:['Faq contributed by Michael Marcin]] 1864 1865When building HTML documentation with BoostBook a Boost C++ Libraries header 1866is added to the files. When using QuickBook to document projects outside of 1867Boost this is not desirable. This behavior can be overridden at the BoostBook 1868level by specifying some XSLT options. When using Boost Build version 2 (BBv2) 1869this can be achieved by adding parameters to the BoostBook target declaration. 1870 1871For example: 1872[pre 1873using quickbook ; 1874 1875xml my_doc : my_doc.qbk ; 1876 1877boostbook standalone 1878 : 1879 my_doc 1880 : 1881 <xsl:param>boost.image.src=images/my_project_logo.png 1882 <xsl:param>boost.image.alt="\\"My Project\\"" 1883 <xsl:param>boost.image.w=100 1884 <xsl:param>boost.image.h=50 1885 <xsl:param>nav.layout=none 1886 ; 1887] 1888 1889[endsect] [/faq] 1890 1891[section:ref Quick Reference] 1892 1893[cpp] 1894 1895[template ordered_list_sample[] 1896[pre''' 1897# one 1898# two 1899# three 1900'''] 1901] 1902 1903[template unordered_list_sample[] 1904[pre''' 1905* one 1906* two 1907* three 1908'''] 1909] 1910 1911[template table_sample[] 1912[pre''' 1913[table Title 1914[[a][b][c]] 1915[[a][b][c]] 1916] 1917'''] 1918] 1919 1920[template var_list_sample[] 1921[pre''' 1922[variablelist Title 1923[[a][b]] 1924[[a][b]] 1925] 1926'''] 1927] 1928 1929 1930[table Syntax Compendium 1931 [[To do this...] [Use this...] [See this...]] 1932 [[comment] [[^'''[/ some comment]''']] [__comments__]] 1933 [[['italics]] [[^'''['italics] or /italics/''']] [__font_styles__ and __simple_formatting__]] 1934 [[[*bold]] [[^'''[*bold] or *bold*''']] [__font_styles__ and __simple_formatting__]] 1935 [[[_underline]] [[^'''[_underline] or _underline_''']] [__font_styles__ and __simple_formatting__]] 1936 [[[^teletype]] [[^'''[^teletype] or =teletype=''']] [__font_styles__ and __simple_formatting__]] 1937 [[[-strikethrough]] [[^'''[-strikethrough]''']] [__font_styles__ and __simple_formatting__]] 1938 [[[~replaceable]] [[^'''[~replaceable]''']] [__replaceable__]] 1939 [[source mode] [[^\[c++\]] or [^\[python\]]] [__source_mode__]] 1940 [[inline code] [[^'''`int main();`''']] [__inline_code__]] 1941 [[code block] [[^'''``int main();``''']] [__code__]] 1942 [[code escape] [[^'''``from c++ to QuickBook``''']] [__escape_back__]] 1943 [[line break] [[^'''[br] or \n''']] [__line_break__ *DEPRECATED*]] 1944 [[anchor] [[^'''[#anchor]''']] [__anchors__]] 1945 [[link] [[^'''[@http://www.boost.org Boost]''']] [__links__]] 1946 [[anchor link] [[^'''[link section.anchor Link text]''']] [__anchor_links__]] 1947 [[refentry link] [[^'''[link xml.refentry Link text]''']] [__refentry_links__]] 1948 [[function link] [[^'''[funcref fully::qualified::function_name Link text]''']] [__code_links__]] 1949 [[class link] [[^'''[classref fully::qualified::class_name Link text]''']] [__code_links__]] 1950 [[member link] [[^'''[memberref fully::qualified::member_name Link text]''']] [__code_links__]] 1951 [[enum link] [[^'''[enumref fully::qualified::enum_name Link text]''']] [__code_links__]] 1952 [[macro link] [[^'''[macroref MACRO_NAME Link text]''']] [__code_links__]] 1953 [[concept link] [[^'''[conceptref ConceptName Link text]''']] [__code_links__]] 1954 [[header link] [[^'''[headerref path/to/header.hpp Link text]''']] [__code_links__]] 1955 [[escape] [[^\'\'\'escaped text (no processing/formatting)\'\'\']] [__escape__]] 1956 [[single char escape] [[^\\c]] [__single_char_escape__]] 1957 [[images] [[^'''[$image.jpg]''']] [__images__]] 1958 [[begin section] [[^'''[section The Section Title]''']] [__section__]] 1959 [[end section] [[^'''[endsect]''']] [__section__]] 1960 [[paragraph] [No markup. Paragraphs start left-flushed and are terminated by two or more newlines.] [__paragraphs__]] 1961 [[ordered list] [[ordered_list_sample]] [__ordered_lists__]] 1962 [[unordered list] [[unordered_list_sample]] [__unordered_lists__]] 1963 [[code] [No markup. Preformatted code starts with a space or a tab.] [__code__]] 1964 [[preformatted] [[^'''[pre preformatted]''']] [__preformatted__]] 1965 [[block quote] [[^'''[:sometext...]''']] [__blockquote__]] 1966 [[heading 1] [[^'''[h1 Heading 1]''']] [__heading__]] 1967 [[heading 2] [[^'''[h2 Heading 2]''']] [__heading__]] 1968 [[heading 3] [[^'''[h3 Heading 3]''']] [__heading__]] 1969 [[heading 4] [[^'''[h4 Heading 4]''']] [__heading__]] 1970 [[heading 5] [[^'''[h5 Heading 5]''']] [__heading__]] 1971 [[heading 6] [[^'''[h6 Heading 6]''']] [__heading__]] 1972 [[macro] [[^'''[def macro_identifier some text]''']] [__macros__]] 1973 [[template] [[^'''[template[a b] [a] body [b]]''']] [__templates__]] 1974 [[blurb] [[^'''[blurb advertisement or note...]''']] [__blurbs__]] 1975 [[admonition] [[^'''[warning Warning text...]''']] [__admonitions__]] 1976 [[table] [[table_sample]] [__tables__]] 1977 [[variablelist] [[var_list_sample]] [__variable_lists__]] 1978 [[include] [[^'''[include someother.qbk]''']] [__include__]] 1979] 1980 1981[endsect] 1982
