diff options
Diffstat (limited to 'src/boost/tools/quickbook/test/quickbook_manual-1_4.quickbook')
| -rw-r--r-- | src/boost/tools/quickbook/test/quickbook_manual-1_4.quickbook | 1981 |
1 files changed, 1981 insertions, 0 deletions
diff --git a/src/boost/tools/quickbook/test/quickbook_manual-1_4.quickbook b/src/boost/tools/quickbook/test/quickbook_manual-1_4.quickbook new file mode 100644 index 00000000..00fc9caa --- /dev/null +++ b/src/boost/tools/quickbook/test/quickbook_manual-1_4.quickbook @@ -0,0 +1,1981 @@ +[article Quickbook + [quickbook 1.4] + [version 1.4] + [authors [de Guzman, Joel], [Niebler, Eric]] + [copyright 2002 2004 2006 Joel de Guzman, Eric Niebler] + [purpose /WikiWiki/ style documentation tool] + [license + Distributed under the Boost Software License, Version 1.0. + (See accompanying file LICENSE_1_0.txt or copy at + [@http://www.boost.org/LICENSE_1_0.txt]) + ] +] + +[/ QuickBook Document version 1.3 ] +[/ Sept 24, 2002 ] +[/ Sept 2, 2004 ] +[/ Feb 14, 2005 ] +[/ Sept 13, 2005 ] + +[/ Some links] + +[def __note__ [$images/note.png]] +[def __alert__ [$images/alert.png]] +[def __tip__ [$images/tip.png]] +[def :-) [$images/smiley.png]] +[def __spirit__ [@http://spirit.sourceforge.net Spirit]] +[def __boostbook__ [@http://www.boost.org/doc/html/boostbook.html BoostBook]] +[def __docbook__ [@http://www.docbook.org/ DocBook]] + +[def __comments__ [link quickbook.syntax.comments Comments]] + +[def __font_styles__ [link quickbook.syntax.phrase.font_styles Font Styles]] +[def __quotations__ [link quickbook.syntax.phrase.quotations Quotations]] +[def __replaceable__ [link quickbook.syntax.phrase.replaceable Replaceble]] +[def __simple_formatting__ [link quickbook.syntax.phrase.simple_formatting Simple formatting]] +[def __inline_code__ [link quickbook.syntax.phrase.inline_code Inline code]] +[def __code_blocks__ [link quickbook.syntax.phrase.code_blocks Code blocks]] +[def __source_mode__ [link quickbook.syntax.phrase.source_mode Source Mode]] +[def __line_break__ [link quickbook.syntax.phrase.line_break line-break]] +[def __anchors__ [link quickbook.syntax.phrase.anchors Anchors]] +[def __links__ [link quickbook.syntax.phrase.links Links]] +[def __anchor_links__ [link quickbook.syntax.phrase.anchor_links Anchor links]] +[def __refentry_links__ [link quickbook.syntax.phrase.refentry_links refentry links]] +[def __code_links__ [link quickbook.syntax.phrase.code_links function, class, member, enum, macro, concept or header links]] +[def __escape__ [link quickbook.syntax.phrase.escape Escape]] +[def __single_char_escape__ [link quickbook.syntax.phrase.single_char_escape Single char escape]] +[def __images__ [link quickbook.syntax.phrase.images Images]] + +[def __document__ [link quickbook.syntax.block.document Document]] +[def __section__ [link quickbook.syntax.block.section Section]] +[def __xinclude__ [link quickbook.syntax.block.xinclude xinclude]] +[def __paragraphs__ [link quickbook.syntax.block.paragraphs Paragraphs]] +[def __ordered_lists__ [link quickbook.syntax.block.lists.ordered_lists Ordered lists]] +[def __list_hierarchies__ [link quickbook.syntax.block.lists.list_hierarchies List Hierarchies]] +[def __long_list_lines__ [link quickbook.syntax.block.lists.long_list_lines Long List Lines]] +[def __unordered_lists__ [link quickbook.syntax.block.lists.unordered_lists Unordered lists]] +[def __mixed_lists__ [link quickbook.syntax.block.lists.mixed_lists Mixed lists]] +[def __code__ [link quickbook.syntax.block.code Code]] +[def __escape_back__ [link quickbook.syntax.block.escape_back Escaping Back To QuickBook]] +[def __preformatted__ [link quickbook.syntax.block.preformatted Preformatted]] +[def __blockquote__ [link quickbook.syntax.block.blockquote Blockquote]] +[def __heading__ [link quickbook.syntax.block.headings Heading]] +[def __macros__ [link quickbook.syntax.block.macros Macros]] +[def __templates__ [link quickbook.syntax.block.templates Templates]] +[def __predefined_macros__ [link quickbook.syntax.block.predefined_macros Predefined Macros]] +[def __blurbs__ [link quickbook.syntax.block.blurbs Blurbs]] +[def __admonitions__ [link quickbook.syntax.block.admonitions Admonitions]] +[def __tables__ [link quickbook.syntax.block.tables Tables]] +[def __variable_lists__ [link quickbook.syntax.block.variable_lists Variable Lists]] +[def __include__ [link quickbook.syntax.block.include Include]] +[def __import__ [link quickbook.syntax.block.import Import]] + +[section:intro Introduction] + +[:[*['["Why program by hand in five days what you can spend five years of your +life automating?]]] + +-- Terrence Parr, author ANTLR/PCCTS +] + +Well, QuickBook started as a weekend hack. It was originally intended to be a +sample application using __spirit__. What is it? What you are viewing now, this +documentation, is autogenerated by QuickBook. These files were generated from +one master: + +[:[@../quickbook.qbk quickbook.qbk]] + +Originally named QuickDoc, this funky tool that never dies evolved into a +funkier tool thanks to Eric Niebler who resurrected the project making it +generate __boostbook__ instead of HTML. The __boostbook__ documentation format +is an extension of __docbook__, an SGML or XML based format for describing +documentation. + +QuickBook is a WikiWiki style documentation tool geared towards C++ +documentation using simple rules and markup for simple formatting tasks. +QuickBook extends the WikiWiki concept. Like the WikiWiki, QuickBook documents are +simple text files. A single QuickBook document can generate a fully linked set +of nice HTML and PostScript/PDF documents complete with images and syntax- +colorized source code. + +Features include: + +* generate __boostbook__ xml, to generate HTML, PostScript and PDF +* simple markup to link to Doxygen-generated entities +* macro system for simple text substitution +* simple markup for italics, bold, preformatted, blurbs, code samples, + tables, URLs, anchors, images, etc. +* automatic syntax coloring of code samples +* CSS support + +[endsect] + +[section:change_log Change Log] + +[h3 Version 1.3] + +* Quickbook file inclusion \[include\]. +* Better xml output (pretty layout). Check out the generated XML. +* Regression testing facility: to make sure your document will always be + compatible (full backward compatibility) regardless of changes to + QuickBook. +* Code cleanup and refactoring. +* Allow phrase markup in the doc-info. +* Preformatted code blocks via \`\`code\`\` (double ticks) allows code in tables + and lists, for example. +* Quickbook versioning; allows full backward compatibility. You have to add + \[quickbook 1.3\] to the doc-info header to enable the new features. Without + this, QuickBook will assume that the document is a pre-1.3 document. +* Better (intuitive) paragraph termination. Some markups may terminate a paragraph. + Example:`` + [section x] + blah... + [endsect]`` +* Fully qualified section and headers. Subsection names are concatenated to the + ID to avoid clashing. Example: `doc_name.sect_name.sub_sect_name.sub_sub_sect_name` +* Better and whitespace handling in code snippets. +* \[xinclude\] fixes up the relative path to the target XML file when + input_directory is not the same as the output_directory. +* Allow untitled tables. +* Allow phrase markups in section titles. +* Allow escaping back to QuickBook from code, code blocks and inline code. +* Footnotes, with the \[footnote This is the footnote\] syntax. +* Post-processor bug fix for escaped XML code that it does not recognize. +* Replaceable, with the \[~replacement\] syntax. +* Generic Headers +* Code changes to allow full recursion (i.e. Collectors and push/pop functions) +* Various code cleanup/maintenance +* Templates! +* \[conceptref\] for referencing BoostBook <concept> entities. +* Allow escape of spaces. The escaped space is removed from the output. Syntax: + `\ `. +* Nested comments are now allowed. +* Quickbook blocks can nest inside comments. +* __import__ facility. +* Callouts on imported code +* Simple markups can now span a whole block. +* __blurbs__, __admonitions__ and table cells (see __tables__) may now + contain paragraphs. +* `\n` and `[br]` are now deprecated. + +[endsect] + +[section:syntax Syntax Summary] + +A QuickBook document is composed of one or more blocks. An example of +a block is the paragraph or a C++ code snippet. Some blocks have +special mark-ups. Blocks, except code snippets which have their own +grammar (C++ or Python), are composed of one or more phrases. A phrase +can be a simple contiguous run of characters. Phrases can have special +mark-ups. Marked up phrases can recursively contain other phrases, but +cannot contain blocks. A terminal is a self contained block-level or +phrase-level element that does not nest anything. + +Blocks, in general, are delimited by two end-of-lines (the block terminator). +Phrases in each block cannot contain a block terminator. This way, syntax errors +such as un-matched closing brackets do not go haywire and corrupt anything past +a single block. + +[section Comments] + +Can be placed anywhere. + +[pre +'''[/ comment (no output generated) ]''' +] + +[/ for testing only... ] + +[pre +'''[/ comments can be nested [/ some more here] ]''' +] + +[/ for testing [/ only ] ] + +[pre +'''[/ Quickbook blocks can nest inside comments. [*Comment this out too!] ]''' +] + +[/ for testing [*only ] ] + +[endsect] + +[section:phrase Phrase Level Elements] + +[section Font Styles] + +[pre''' +['italic], [*bold], [_underline], [^teletype], [-strikethrough] +'''] + +will generate: + +['italic], [*bold], [_underline], [^teletype], [-strikethrough] + +Like all non-terminal phrase level elements, this can of course be nested: + +[pre''' +[*['bold-italic]] +'''] + +will generate: + +[*['bold-italic]] + +[endsect] + +[section Replaceable] + +When you want content that may or must be replaced by the user, use the syntax: + +[pre''' +[~replacement] +'''] + +This will generate: + +[~replacement] + +[endsect] + +[section Quotations] + +[pre''' +["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein +'''] + +will generate: + +["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein + +Note the proper left and right quote marks. Also, while you can simply use +ordinary quote marks like "quoted", our quotation, above, will generate correct +DocBook quotations (e.g. <quote>quoted</quote>). + +Like all phrase elements, quotations may be nested. Example: + +[pre''' +["Here's the rule for bargains: ["Do other men, for they would do you.] That's +the true business precept.] +'''] + +will generate: + +["Here's the rule for bargains: ["Do other men, for they would do you.] +That's the true business precept.] + +[endsect] +[section Simple formatting] + +Simple markup for formatting text, common in many applications, is now supported: + +[pre''' +/italic/, *bold*, _underline_, =teletype= +'''] + +will generate: + +/italic/, *bold*, _underline_, =teletype= + +Unlike QuickBook's standard formatting scheme, the rules for simpler +alternatives are much stricter[footnote Thanks to David Barrett, author of +[@http://quinthar.com/qwikiwiki/index.php?page=Home Qwiki], for sharing +these samples and teaching me these obscure formatting rules. I wasn't sure +at all if __spirit__, being more or less a formal EBNF parser, can handle +the context sensitivity and ambiguity.]. + +* Simple markups cannot nest. You can combine a simple markup with a nestable markup. +* Simple markups cannot contain any other form of quickbook markup. +* A non-space character must follow the leading markup +* A non-space character must precede the trailing markup +* A space or a punctuation must follow the trailing markup +* If the matching markup cannot be found within a block, the formatting + will not be applied. This is to ensure that un-matched formatting markups, + which can be a common mistake, does not corrupt anything past a single block. + We do not want the rest of the document to be rendered bold just because we + forgot a trailing '*'. A single block is terminated by two end of lines or + the close bracket: ']'. +* A line starting with the star will be interpreted as an unordered list. + See __unordered_lists__. + +[table More Formatting Samples + [[Markup] [Result]] + [[[^'''*Bold*''']] [*Bold*]] + [[[^'''*Is bold*''']] [*Is bold*]] + [[[^'''* Not bold* *Not bold * * Not bold *''']] [* Not bold* *Not bold * * Not bold *]] + [[[^'''This*Isn't*Bold (no bold)''']] [This*Isn't*Bold (no bold)]] + [[[^'''(*Bold Inside*) (parenthesis not bold)''']] [(*Bold Inside*) (parenthesis not bold)]] + [[[^'''*(Bold Outside)* (parenthesis bold)''']] [*(Bold Outside)* (parenthesis bold)]] + [[[^'''3*4*5 = 60 (no bold)''']] [3*4*5 = 60 (no bold)]] + [[[^'''3 * 4 * 5 = 60 (no bold)''']] [3 * 4 * 5 = 60 (no bold)]] + [[[^'''3 *4* 5 = 60 (4 is bold)''']] [3 *4* 5 = 60 (4 is bold)]] + [[[^'''*This is bold* this is not *but this is*''']][*This is bold* this is not *but this is*]] + [[[^'''*This is bold*.''']] [*This is bold*.]] + [[[^'''*B*. (bold B)''']] [*B*. (bold B)]] + [[[^'''['*Bold-Italic*]''']] [['*Bold-Italic*]]] + [[[^'''*side-by*/-side/''']] [*side-by*/-side/]] +] + +As mentioned, simple markups cannot go past a single block. The text +from "have" to "full" in the following paragraph will be rendered as +bold: + +[pre''' +Baa baa black sheep, *have you any wool? +Yes sir, yes sir, three bags full!* +One for the master, one for the dame, +And one for the little boy who lives down the lane. +'''] + +Baa baa black sheep, *have you any wool? +Yes sir, yes sir, three bags full!* +One for the master, one for the dame, +And one for the little boy who lives down the lane. + +But in the following paragraph, bold is not applied: + +[pre''' +Baa baa black sheep, *have you any wool? +Yes sir, yes sir, three bags full! +One for the master, one for the dame, +And one for the little boy who lives down the lane. +'''] + +Baa baa black sheep, *have you any wool? +Yes sir, yes sir, three bags full! +One for the master, one for the dame, +And one for the little boy who lives down the lane. + +[endsect] +[section Inline code] + +Inlining code in paragraphs is quite common when writing C++ documentation. We +provide a very simple markup for this. For example, this: + +[pre''' +This text has inlined code `int main() { return 0; }` in it. +'''] + +will generate: + +This text has inlined code `int main() { return 0; }` in it. The code will be +syntax highlighted. + +[note We simply enclose the code with the tick: [^'''"`"'''], not the +single quote: `"'"`. Note too that [^'''`some code`'''] is preferred over +[^'''[^some code]''']. ] + +[endsect] +[section Code blocks] + +Preformatted code simply starts with a space or a tab (See __code__). +However, such a simple syntax cannot be used as phrase elements in lists +(See __ordered_lists__ and __unordered_lists__), tables (See __tables__), +etc. Inline code (see above) can. The problem is, inline code does not +allow formatting with newlines, spaces, and tabs. These are lost. + +We provide a phrase level markup that is a mix between the two. By using the +double-tick, instead of the single-tick, we are telling QuickBook to use +preformatted blocks of code. Example: + +[pre +\`\` + #include <iostream> + + int main() + { + std::cout << "Hello, World!" << std::endl; + return 0; + } +\`\` +] + +will generate: + +`` + #include <iostream> + + int main() + { + std::cout << "Hello, World!" << std::endl; + return 0; + } +`` + +[endsect] +[section Source Mode] + +If a document contains more than one type of source code then the source +mode may be changed dynamically as the document is processed. All QuickBook +documents are initially in C++ mode by default, though an alternative +initial value may be set in the __document__ section. + +To change the source mode, use the [^\[source-mode\]] markup, where +=source-mode= is one of the supported modes. For example, this: + +[pre''' +Python's [python] `import` is rather like C++'s [c++] `#include`. A +C++ comment `// looks like this` whereas a Python comment [python] +`# looks like this`. +'''] + +will generate: + +Python's [python] `import` is rather like C++'s [c++] `#include`. A +C++ comment `// looks like this` whereas a Python comment [python] +`#looks like this`. + +[table Supported Source Modes + [[Mode] [Source Mode Markup]] + [[C++] [[^\[c++\]]]] + [[Python] [[^\[python\]]]] +] + +[note The source mode strings are lowercase.] + +[endsect] +[section line-break] + +[pre''' +[br] +'''] + +[warning `[br]` is now deprecated. __blurbs__, __admonitions__ and +table cells (see __tables__) may now contain paragraphs.] + +[endsect] +[section Anchors] + +[pre''' +[#named_anchor] +'''] + +A named anchor is a hook that can be referenced by a link elsewhere in the +document. You can then reference an anchor with [^'''[link named_anchor +Some link text]''']. See __anchor_links__, __section__ and __heading__. + +[endsect] +[section Links] + +[pre''' +[@http://www.boost.org this is [*boost's] website....] +'''] + +will generate: + +[@http://www.boost.org this is [*boost's] website....] + +URL links where the link text is the link itself is common. Example: + +[pre''' +see http://spirit.sourceforge.net/ +'''] + +so, when the text is absent in a link markup, the URL is assumed. Example: + +[pre +see '''[@http://spirit.sourceforge.net/]''' +] + +will generate: + +see [@http://spirit.sourceforge.net/] + +[endsect] +[section Anchor links] + +You can link within a document using: + +[pre''' +[link section_id.normalized_header_text The link text] +'''] + +See sections __section__ and __heading__ for more info. + +[endsect] +[section refentry links] + +In addition, you can link internally to an XML refentry like: + +[pre''' +[link xml.refentry The link text] +'''] + +This gets converted into [^<link linkend="xml.refentry">The link text</link>]. + +Like URLs, the link text is optional. If this is not present, the link text will +automatically be the refentry. Example: + +[pre''' +[link xml.refentry] +'''] + +This gets converted into [^<link linkend="xml.refentry">xml.refentry</link>]. + +[endsect] +[section:code_links Code Links] + +If you want to link to a function, class, member, enum, concept or header in the reference +section, you can use: + +[pre''' +[funcref fully::qualified::function_name The link text] +[classref fully::qualified::class_name The link text] +[memberref fully::qualified::member_name The link text] +[enumref fully::qualified::enum_name The link text] +[macroref MACRO_NAME The link text] +[conceptref ConceptName The link text] +[headerref path/to/header.hpp The link text] +'''] + +Again, the link text is optional. If this is not present, the link text will +automatically be the function, class, member, enum, macro, concept or header. Example: + +[pre''' +[classref boost::bar::baz] +'''] + +would have "boost::bar::baz" as the link text. + +[endsect] +[section Escape] + +The escape mark-up is used when we don't want to do any processing. + +[pre +\'\'\' +escape (no processing/formatting) +\'\'\' +] + +Escaping allows us to pass XML markup to __boostbook__ or __docbook__. For example: + +[pre +\'\'\' +<emphasis role="bold">This is direct XML markup</emphasis> +\'\'\' +] + +''' +<emphasis role="bold">This is direct XML markup</emphasis> +''' + +[important Be careful when using the escape. The text must conform to +__boostbook__/__docbook__ syntax.] + +[endsect] +[section Single char escape] + +The backslash may be used to escape a single punctuation character. The +punctuation immediately after the backslash is passed without any processing. +This is useful when we need to escape QuickBook punctuations such as `[` and `]`. +For example, how do you escape the triple quote? Simple: [^\\'\\'\\'] + + +`\n` has a special meaning. It is used to generate line breaks. + +[warning `\n` and `[br]` are now deprecated. __blurbs__, __admonitions__ +and table cells (see __tables__) may now contain paragraphs.] + +The escaped space: `\ ` also has a special meaning. The escaped space is removed +from the output. + +[endsect] +[section Images] + +[pre''' +[$image.jpg] +'''] + +[endsect] +[section Footnotes] + +As of version 1.3, QuickBook supports footnotes. Just put the text of the +footnote in a `[footnote]` block, and the text will be put at the bottom +of the current page. For example, this: + +[pre''' +[footnote A sample footnote] +'''] + +will generate this[footnote A sample footnote]. + +[section Macro Expansion] + +[pre''' +__a_macro_identifier__ +'''] + +See __macros__ for details. + +[endsect] + +[section Template Expansion] + +[pre''' +[a_template_identifier] +'''] + +See __templates__ for details. + +[endsect] + +[endsect] +[endsect] +[section:block Block Level Elements] + +[section Document] + +Every document must begin with a Document Info section, which should look +like this: + +[pre''' +[document-type The Document Title + [quickbook 1.3] + [version 1.0] + [id the_document_name] + [dirname the_document_dir] + [copyright 2000 2002 2003 Joe Blow, Jane Doe] + [purpose The document's reason for being] + [category The document's category] + [authors [Blow, Joe], [Doe, Jane]] + [license The document's license] + [source-mode source-type] +] +'''] + +Where document-type is one of: + +* book +* article +* library +* chapter +* part +* appendix +* preface +* qandadiv +* qandaset +* reference +* set + +quickbook 1.3 declares the version of quickbook the document is written for. +In its absence, version 1.1 is assumed. + +=version=, =id=, =dirname=, =copyright=, =purpose=, =category=, =authors=, +=license=, =last-revision= and =source-mode= are optional information. + +=source-type= is a lowercase string setting the initial __source_mode__. If +the =source-mode= field is omitted, a default value of =c++= will be used. + +[endsect] +[section Section] + +Starting a new section is accomplished with: + +[pre''' +[section:id The Section Title] +'''] + +where /id/ is optional. id will be the filename of the generated section. +If it is not present, "The Section Title" will be normalized and become the id. +Valid characters are =a-Z=, =A-Z=, =0-9= and =_=. All non-valid characters are +converted to underscore and all upper-case are converted to lower case. +Thus: "The Section Title" will be normalized to "the_section_title". + +End a section with: + +[pre''' +[endsect] +'''] + +Sections can nest, and that results in a hierarchy in the table of contents. + +[endsect] +[section xinclude] + +You can include another XML file with: + +[pre''' +[xinclude file.xml] +'''] + +This is useful when file.xml has been generated by Doxygen and contains your +reference section. + +[endsect] +[section Paragraphs] + +Paragraphs start left-flushed and are terminated by two or more newlines. No +markup is needed for paragraphs. QuickBook automatically detects paragraphs from +the context. Block markups \[section, endsect, h1, h2, h3, h4, h5, h6, blurb, +(block-quote) ':', pre, def, table and include \] may also terminate a paragraph. + +[endsect] + +[section Lists] +[section Ordered lists] + +[pre +# One +# Two +# Three +] + +will generate: + +# One +# Two +# Three + +[endsect] +[section List Hierarchies] + +List hierarchies are supported. Example: + +[pre +# One +# Two +# Three + # Three.a + # Three.b + # Three.c +# Four + # Four.a + # Four.a.i + # Four.a.ii +# Five +] + +will generate: + +# One +# Two +# Three + # Three.a + # Three.b + # Three.c +# Fourth + # Four.a + # Four.a.i + # Four.a.ii +# Five + +[endsect] +[section Long List Lines] + +Long lines will be wrapped appropriately. Example: + +[pre +# A short item. +# A very long item. A very long item. A very long item. + A very long item. A very long item. A very long item. + A very long item. A very long item. A very long item. + A very long item. A very long item. A very long item. + A very long item. A very long item. A very long item. +# A short item. +] + +# A short item. +# A very long item. A very long item. A very long item. + A very long item. A very long item. A very long item. + A very long item. A very long item. A very long item. + A very long item. A very long item. A very long item. + A very long item. A very long item. A very long item. +# A short item. + +[endsect] +[section Unordered lists] + +[pre''' +* First +* Second +* Third +'''] + +will generate: + +* First +* Second +* Third + +[endsect] +[section Mixed lists] + +Mixed lists (ordered and unordered) are supported. Example: + +[pre''' +# One +# Two +# Three + * Three.a + * Three.b + * Three.c +# Four +'''] + +will generate: + +# One +# Two +# Three + * Three.a + * Three.b + * Three.c +# Four + +And... + +[pre''' +# 1 + * 1.a + # 1.a.1 + # 1.a.2 + * 1.b +# 2 + * 2.a + * 2.b + # 2.b.1 + # 2.b.2 + * 2.b.2.a + * 2.b.2.b +'''] + +will generate: + +# 1 + * 1.a + # 1.a.1 + # 1.a.2 + * 1.b +# 2 + * 2.a + * 2.b + # 2.b.1 + # 2.b.2 + * 2.b.2.a + * 2.b.2.b + +[endsect] +[endsect] + +[section Code] + +Preformatted code starts with a space or a tab. The code will be +syntax highlighted according to the current __source_mode__: + +[c++] + + #include <iostream> + + int main() + { + // Sample code + std::cout << "Hello, World\n"; + return 0; + } + +[python] + + import cgi + + def cookForHtml(text): + '''"Cooks" the input text for HTML.''' + + return cgi.escape(text) + +[c++] + +Macros that are already defined are expanded in source code. Example: + +[pre''' +[def __array__ [@http://www.boost.org/doc/html/array/reference.html array]] +[def __boost__ [@http://www.boost.org/libs/libraries.htm boost]] + + using __boost__::__array__; +'''] + +Generates: + +[def __array__ [@http://www.boost.org/doc/html/array/reference.html array]] +[def __boost__ [@http://www.boost.org/libs/libraries.htm boost]] + + using __boost__::__array__; + +[endsect] +[section:escape_back Escaping Back To QuickBook] + +Inside code, code blocks and inline code, QuickBook does not allow any +markup to avoid conflicts with the target syntax (e.g. c++). In case you +need to switch back to QuickBook markup inside code, you can do so using a +language specific /escape-back/ delimiter. In C++ and Python, the delimiter +is the double tick (back-quote): "\`\`" and "\`\`". Example: + +[pre''' +void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``() +{ +} +'''] + +Will generate: + + void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``() + { + } + +When escaping from code to QuickBook, only phrase level markups are +allowed. Block level markups like lists, tables etc. are not allowed. + +[endsect] +[section Preformatted] + +Sometimes, you don't want some preformatted text to be parsed as C++. In such +cases, use the [^[pre ... \]] markup block. + +[pre''' +[pre + + Some *preformatted* text Some *preformatted* text + + Some *preformatted* text Some *preformatted* text + + Some *preformatted* text Some *preformatted* text + +] +'''] + +Spaces, tabs and newlines are rendered as-is. Unlike all quickbook block level +markup, pre (and Code) are the only ones that allow multiple newlines. The +markup above will generate: + +[pre + +Some *preformatted* text Some *preformatted* text + + Some *preformatted* text Some *preformatted* text + + Some *preformatted* text Some *preformatted* text + +] + +Notice that unlike Code, phrase markup such as font style is still permitted +inside =pre= blocks. + +[endsect] +[section Blockquote] + +[pre +'''[:sometext...]''' +] + +[:Indents the paragraph. This applies to one paragraph only.] + +[endsect] +[section Admonitions] + +[pre''' +[note This is a note] +[tip This is a tip] +[important This is important] +[caution This is a caution] +[warning This is a warning] +'''] + +generates __docbook__ admonitions: + +[note This is a note] +[tip This is a tip] +[important This is important] +[caution This is a caution] +[warning This is a warning] + +These are the only admonitions supported by __docbook__. So, +for example [^\[information This is some information\]] is unlikely +to produce the desired effect. + +[endsect] +[section Headings] + +[pre''' +[h1 Heading 1] +[h2 Heading 2] +[h3 Heading 3] +[h4 Heading 4] +[h5 Heading 5] +[h6 Heading 6] +'''] + +[h1 Heading 1] +[h2 Heading 2] +[h3 Heading 3] +[h4 Heading 4] +[h5 Heading 5] +[h6 Heading 6] + +Headings 1-3 \[h1 h2 and h3\] will automatically have anchors with normalized +names with [^name="section_id.normalized_header_text"] (i.e. valid characters are +=a-z=, =A-Z=, =0-9= and =_=. All non-valid characters are converted to underscore +and all upper-case are converted to lower-case. For example: Heading +1 in section Section 2 will be normalized to [^section_2.heading_1]). You can use: + +[pre''' +[link section_id.normalized_header_text The link text] +'''] + +to link to them. See __anchor_links__ and __section__ for more info. + +[endsect] +[section Generic Heading] + +In cases when you don't want to care about the heading level (1 to 6), you +can use the /Generic Heading/: + +[pre''' +[heading Heading] +'''] + +The /Generic Heading/ assumes the level, plus one, of the innermost section +where it is placed. For example, if it is placed in the outermost section, +then, it assumes /h2/. + +Headings are often used as an alternative to sections. It is used +particularly if you do not want to start a new section. In many cases, +however, headings in a particular section is just flat. Example: + +[pre''' +[section A] +[h2 X] +[h2 Y] +[h2 Z] +[endsect] +'''] + +Here we use h2 assuming that section A is the outermost level. If it is +placed in an inner level, you'll have to use h3, h4, etc. depending on +where the section is. In general, it is the section level plus one. It is +rather tedious, however, to scan the section level everytime. If you +rewrite the example above as shown below, this will be automatic: + +[pre''' +[section A] +[heading X] +[heading Y] +[heading Z] +[endsect] +'''] + +They work well regardless where you place them. You can rearrange sections +at will without any extra work to ensure correct heading levels. In fact, +with /section/ and /heading/, you have all you need. /h1/../h6/ becomes +redundant. /h1/../h6/ might be deprecated in the future. + +[endsect] +[section Macros] + +[pre''' +[def macro_identifier some text] +'''] + +When a macro is defined, the identifier replaces the text anywhere in the +file, in paragraphs, in markups, etc. macro_identifier is a string of non- +white space characters except '\]'. A macro may not follow an alphabetic +character or the underscore. The replacement text can be any phrase (even +marked up). Example: + +[pre''' +[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&type=1]] +sf_logo +'''] + +Now everywhere the sf_logo is placed, the picture will be inlined. + +[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&type=1]] +sf_logo + +[tip It's a good idea to use macro identifiers that are distinguishable. +For instance, in this document, macro identifiers have two leading and +trailing underscores (e.g. [^'''__spirit__''']). The reason is to avoid +unwanted macro replacement.] + +Links (URLS) and images are good candidates for macros. *1*) They tend to +change a lot. It is a good idea to place all links and images in one place near the top +to make it easy to make changes. *2*) The syntax is not pretty. It's easier to read and +write, e.g. [^'''__spirit__'''] than [^'''[@http://spirit.sourceforge.net Spirit]''']. + +Some more examples: + +[pre''' +[def :-) [$theme/smiley.png]] +[def __spirit__ [@http://spirit.sourceforge.net Spirit]] +'''] + +(See __images__ and __links__) + +Invoking these macros: + +[pre''' +Hi __spirit__ :-) +'''] + +will generate this: + +Hi __spirit__ :-) + +[endsect] +[section Predefined Macros] + +Quickbook has some predefined macros that you can already use. + +[table Predefined Macros + [[Macro] [Meaning] [Example]] + [['''__DATE__'''] [Today's date] [__DATE__]] + [['''__TIME__'''] [The current time] [__TIME__]] + [['''__FILENAME__'''] [Quickbook source filename] [__FILENAME__]] +] + +[endsect] +[section Templates] + +Templates provide a more versatile text substitution mechanism. Templates +come in handy when you need to create parameterizable, multi-line, +boilerplate text that you specify once and expand many times. Templates +accept one or more arguments. These arguments act like place-holders for +text replacement. Unlike simple macros, which are limited to phrase level +markup, templates can contain block level markup (e.g. paragraphs, code +blocks and tables). + +Example template: + +[pre''' +[template person[name age what] + +Hi, my name is [name]. I am [age] years old. I am a [what]. + +] +'''] + +[template person[name age what] + +Hi, my name is [name]. I am [age] years old. I am a [what]. + +] + +[heading Template Identifier] + +Template identifiers can either consist of: + +* An initial alphabetic character or the underscore, followed by + zero or more alphanumeric characters or the underscore. This is + similar to your typical C/C++ identifier. +* A single character punctuation (a non-alphanumeric printable character) + +[heading Formal Template Arguments] + +Template formal arguments are identifiers consisting of an initial +alphabetic character or the underscore, followed by zero or more +alphanumeric characters or the underscore. This is similar to your typical +C/C++ identifier. + +A template formal argument temporarily hides a template of the same name at +the point where the [link quickbook.syntax.block.templates.template_expansion +template is expanded]. Note that the body of the [^person] template above +refers to [^name] [^age] and [^what] as [^\[name\]] [^\[age\]] and +[^\[what\]]. [^name] [^age] and [^what] are actually templates that exist +in the duration of the template call. + +[heading Template Body] + +The template body can be just about any QuickBook block or phrase. There +are actually two forms. Templates may be phrase or block level. Phrase +templates are of the form: + +[pre''' +[template sample[arg1 arg2...argN] replacement text... ] +'''] + +Block templates are of the form: + +[pre''' +[template sample[arg1 arg2...argN] +replacement text... +] +'''] + +The basic rule is as follows: if a newline immediately follows the argument +list, then it is a block template, otherwise, it is a phrase template. +Phrase templates are typically expanded as part of phrases. Like macros, +block level elements are not allowed in phrase templates. + +[heading Template Expansion] + +You expand a template this way: + +[pre''' +[template_identifier arg1..arg2..arg3] +'''] + +At template expansion, you supply the actual arguments. The template will +be expanded with your supplied arguments. Example: + +[pre''' +[person James Bond..39..Spy] +[person Santa Clause..87..Big Red Fatso] +'''] + +Which will expand to: + +[person James Bond..39..Spy] +[person Santa Clause..87..Big Red Fatso] + +[caution A word of caution: Templates are recursive. A template can call +another template or even itself, directly or indirectly. There are no +control structures in QuickBook (yet) so this will always mean infinite +recursion. QuickBook can detect this situation and report an error if +recursion exceeds a certain limit.] + +Each actual argument can be a word, a text fragment or just about any [link +quickbook.syntax.phrase QuickBook phrase]. Arguments are separated by the +double dot [^".."] and terminated by the close parenthesis. + +[heading Nullary Templates] + +Nullary templates look and act like simple macros. Example: + +[pre''' +[template alpha[]'''&#945;'''] +[template beta[]'''&#946;'''] +'''] + +[template alpha[]'''α'''] +[template beta[]'''β'''] + +Expanding: + +[pre'''Some squigles...[*[alpha][beta]]'''] + +We have: + +Some squiggles...[*[alpha][beta]] + +The difference with macros are + +* The explicit [link quickbook.syntax.block.templates.template_expansion + template expansion syntax]. This is an advantage because, now, we don't + have to use obscure naming conventions like double underscores (e.g. + \_\_alpha\_\_) to avoid unwanted + macro replacement. +* The template is expanded at the point where it is invoked. A macro is + expanded immediately at its point of declaration. This is subtle and + can cause a slight difference in behavior especially if you refer to + other macros and templates in the body. + +The empty brackets after the template identifier ([^alpha\[\]]) indicates no +arguments. If the template body does not look like a template argument list, we +can elide the empty brackets. Example: + +[pre''' +[template aristotle_quote Aristotle: [*['Education is the best provision +for the journey to old age.]]] +'''] + +[template aristotle_quote\ Aristotle: [*['Education is the best provision +for the journey to old age.]]] + +Expanding: + +[pre''' +Here's a quote from [aristotle_quote]. +'''] + +We have: + +Here's a quote from [aristotle_quote]. + +The disadvantage is that you can't avoid the space between the template +identifier, `aristotle_quote`, and the template body "Aristotle...". This space +will be part of the template body. If that space is unwanted, use empty +brackets or use the space escape: "`\ `". Example: + +[pre''' +[template tag\ _tag] +'''] + +[template tag\ _tag] + +Then expanding: + +[pre''' +`struct` x[tag]; +'''] + +We have: + +`struct` x[tag]; + +You have a couple of ways to do it. I personally prefer the explicit empty +brackets, though. + +[heading Simple Arguments] + +As mentioned, arguments are separated by the double dot [^".."]. If there +are less arguments passed than expected, QuickBook attempts to break the +last argument into two or more arguments following this logic: + +* Break the last argument into two, at the first space found ([^'', '\\n', + \\t' or '\\r']). +* Repeat until there are enough arguments or if there are no more spaces + found (in which case, an error is reported). + +For example: + +[pre''' +[template simple[a b c d] [a][b][c][d]] +[simple w x y z] +'''] + +will produce: + +[template simple[a b c d] [a][b][c][d]] +[simple w x y z] + +"w x y z" is initially treated as a single argument because we didn't +supply any [^".."] separators. However, since [^simple] expects 4 +arguments, "w x y z" is broken down iteratively (applying the logic above) +until we have "w", "x", "y" and "z". + +QuickBook only tries to get the arguments it needs. For example: + +[pre''' +[simple w x y z trail] +'''] + +will produce: + +[simple w x y z trail] + +The arguments being: "w", "x", "y" and "z trail". + +It should be obvious now that for simple arguments with no spaces, we can +get by without separating the arguments with [^".."] separators. It is +possible to combine [^".."] separators with the argument passing +simplification presented above. Example: + +[pre''' +[simple what do you think ..m a n?] +'''] + +will produce: + +[simple what do you think ..m a n?] + +[heading Punctuation Templates] + +With templates, one of our objectives is to allow us to rewrite QuickBook +in QuickBook (as a qbk library). For that to happen, we need to accommodate +single character punctuation templates which are fairly common in +QuickBook. You might have noticed that single character punctuations are +allowed as [link quickbook.syntax.block.templates.template_identifier +template identifiers]. Example: + +[pre''' +[template ![bar] '''<hey>'''[bar]'''</hey>'''] +'''] + +Now, expanding this: + +[pre''' +[!baz] +'''] + +We will have: + +[pre +<hey>baz</hey> +] + +[endsect] +[section Blurbs] + +[pre''' +[blurb :-) [*An eye catching advertisement or note...] + + __spirit__ is an object-oriented recursive-descent parser generator framework + implemented using template meta-programming techniques. Expression templates + allow us to approximate the syntax of Extended Backus-Normal Form (EBNF) + completely in C++. +] +'''] + +will generate this: + +[blurb :-) [*An eye catching advertisement or note...] + + __spirit__ is an object-oriented recursive-descent parser generator + framework implemented using template meta-programming techniques. Expression + templates allow us to approximate the syntax of Extended Backus-Normal Form + (EBNF) completely in C++. +] + +[note Prefer [link quickbook.syntax.block.admonitions admonitions] wherever +appropriate.] + +[endsect] +[section Tables] + +[pre''' +[table A Simple Table + [[Heading 1] [Heading 2] [Heading 3]] + [[R0-C0] [R0-C1] [R0-C2]] + [[R1-C0] [R1-C1] [R1-C2]] + [[R2-C0] [R2-C1] [R2-C2]] +] +'''] + +will generate: + +[table A Simple Table + [[Heading 1] [Heading 2] [Heading 3]] + [[R0-C0] [R0-C1] [R0-C2]] + [[R2-C0] [R2-C1] [R2-C2]] + [[R3-C0] [R3-C1] [R3-C2]] +] + +The table title is optional. The first row of the table is automatically +treated as the table header; that is, it is wrapped in +[^<thead>...</thead>] XML tags. Note that unlike the original QuickDoc, the +columns are nested in [ cells... ]. The syntax is free-format and allows +big cells to be formatted nicely. Example: + +[pre''' +[table Table with fat cells + [[Heading 1] [Heading 2]] + [ + [Row 0, Col 0: a small cell] + [ + Row 0, Col 1: a big fat cell with paragraphs + + Boost provides free peer-reviewed portable C++ source libraries. + + We emphasize libraries that work well with the C++ Standard Library. + Boost libraries are intended to be widely useful, and usable across + a broad spectrum of applications. The Boost license encourages both + commercial and non-commercial use. + ] + ] + [ + [Row 1, Col 0: a small cell] + [Row 1, Col 1: a small cell] + ] +] +'''] + +and thus: + +[table Table with fat cells + [[Heading 1] [Heading 2]] + [ + [Row 0, Col 0: a small cell] + [ + Row 0, Col 1: a big fat cell with paragraphs + + Boost provides free peer-reviewed portable C++ source libraries. + + We emphasize libraries that work well with the C++ Standard Library. + Boost libraries are intended to be widely useful, and usable across + a broad spectrum of applications. The Boost license encourages both + commercial and non-commercial use. + ] + ] + [ + [Row 1, Col 0: a small cell] + [Row 1, Col 1: a small cell] + ] +] + +Here's how to have preformatted blocks of code in a table cell: + +[pre''' +[table Table with code + [[Comment] [Code]] + [ + [My first program] + ['''\`\` + #include <iostream> + + int main() + { + std::cout << "Hello, World!" << std::endl; + return 0; + } + \`\`'''] + ] +] +'''] + +[table Table with code + [[Comment] [Code]] + [ + [My first program] + [`` + #include <iostream> + + int main() + { + std::cout << "Hello, World!" << std::endl; + return 0; + } + ``] + ] +] + +[endsect] +[section Variable Lists] + +[pre''' +[variablelist A Variable List + [[term 1] [The definition of term 1]] + [[term 2] [The definition of term 2]] + [[term 3] [The definition of term 3]] +] +'''] + +will generate: + +[variablelist A Variable List + [[term 1] [The definition of term 1]] + [[term 2] [The definition of term 2]] + [[term 3] [The definition of term 3]] +] + +The rules for variable lists are the same as for tables, except that +only 2 "columns" are allowed. The first column contains the terms, and +the second column contains the definitions. Those familiar with HTML +will recognize this as a "definition list". + +[endsect] +[section Include] + +You can include one QuickBook file from another. The syntax is simply: + +[pre''' +[include someother.qbk] +'''] + +The included file will be processed as if it had been cut and pasted +into the current document, with the following exceptions: + +* The '''__FILENAME__''' predefined macro will reflect the name of the + file currently being processed. +* Any macros defined in the included file are scoped to that file. + +The [^\[include\]] directive lets you specify a document id to use for the +included file. When this id is not explicitly specified, the id defaults to +the filename ("someother", in the example above). You can specify the id +like this: + +[pre''' +[include:someid someother.qbk] +'''] + +All auto-generated anchors will use the document id as a unique prefix. So +for instance, if there is a top section in someother.qbk named "Intro", the +named anchor for that section will be "someid.intro", and you can link to +it with [^\[link someid.intro The Intro\]]. + +[endsect] + +[section Import] + +When documenting code, you'd surely need to present code from actual source +files. While it is possible to copy some code and paste them in your QuickBook +file, doing so is error prone and the extracted code in the documentation tends +to get out of sync with the actual code as the code evolves. The problem, as +always, is that once documentation is written, the tendency is for the docs to +languish in the archives without maintenance. + +QuickBook's import facility provides a nice solution. + +[heading Example] + +You can effortlessly import code snippets from source code into your QuickBook. +The following illustrates how this is done: + +[pre''' +[import ../test/stub.cpp] +[foo] +[bar] +'''] + +The first line: + +[pre''' +[import ../test/stub.cpp] +'''] + +collects specially marked-up code snippets from [@../../test/stub.cpp stub.cpp] +and places them in your QuickBook file as virtual templates. Each of the +specially marked-up code snippets has a name (e.g. `foo` and `bar` in the +example above). This shall be the template identifier for that particular code +snippet. The second and third line above does the actual template expansion: + +[pre''' +[foo] +[bar] +'''] + +And the result is: + +[import ../test/stub.cpp] +[foo] +[bar] + +[heading Code Snippet Markup] + +Note how the code snippets in [@../../test/stub.cpp stub.cpp] get marked up. We +use distinguishable comments following the form: + + //[id + some code here + //] + +The first comment line above initiates a named code-snippet. This prefix will +not be visible in quickbook. The entire code-snippet in between `//[id` and +`//]` will be inserted as a template in quickbook with name ['/id/]. The comment +`//]` ends a code-snippet This too will not be visible in quickbook. + +[heading Special Comments] + +Special comments of the form: + + //` some [*quickbook] markup here + +and: + + /*` some [*quickbook] markup here */ + +will be parsed by QuickBook. This can contain quickbook /blocks/ (e.g. sections, +paragraphs, tables, etc). In the first case, the initial slash-slash, tick and +white-space shall be ignored. In the second, the initial slash-star-tick and the +final star-slash shall be ignored. + +[heading Callouts] + +Special comments of the form: + + /*< some [*quickbook] markup here >*/ + +will be regarded as callouts. These will be collected, numbered and +rendered as a "callout bug" (a small icon with a number). After the +whole snippet is parsed, the callout list is generated. See +[@http://www.docbook.org/tdg/en/html/callout.html Callouts] for details. +Example: + +[foo_bar] + +Checkout [@../../test/stub.cpp stub.cpp] to see the actual code. + +[endsect] + +[endsect] +[endsect] + +[section:install Installation and configuration] + +This section provides some guidelines on how to install and configure +BoostBook and Quickbook under several operating systems. + +Before continuing, it is very important that you keep this in mind: if you +try to build some documents and the process breaks due to misconfiguration, +be absolutely sure to delete any `bin` and `bin.v2` directories generated +by the build before trying again. Otherwise your configuration fixes will +not take any effect. + +[section:windows Windows 2000, XP, 2003, Vista] + +[python] + +[:['Section contributed by Julio M. Merino Vidal]] + +The following instructions apply to any Windows system based on Windows +2000, including Windows XP, Windows 2003 Server and Windows Vista. The +paths shown below are taken from a Windows Vista machine; you will need to +adjust them to match your system in case you are running an older version. + +# First of all you need to have a copy of `xsltproc` for Windows. There + are many ways to get this tool, but to keep things simple, use the + [@http://www.zlatkovic.com/pub/libxml/ binary packages] made by Igor + Zlatkovic. At the very least, you need to download the following + packages: `iconv`, `zlib`, `libxml2` and `libxslt`. + +# Unpack all these packages in the same directory so that you get unique + `bin`, `include` and `lib` directories within the hierarchy. These + instructions use `C:\Users\example\Documents\boost\xml` as the root for + all files. + +# From the command line, go to the `bin` directory and launch + `xsltproc.exe` to ensure it works. You should get usage information on + screen. + +# Download [@http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip Docbook XML + 4.2] and unpack it in the same directory used above. That is: + `C:\Users\example\Documents\boost\xml\docbook-xml`. + +# Download the latest + [@http://sourceforge.net/project/showfiles.php?group_id=21935&package_id=16608 + Docbook XSL] version and unpack it, again in the same directory + used before. To make things easier, rename the directory created + during the extraction to `docbook-xsl` (bypassing the version name): + `C:\Users\example\Documents\boost\xml\docbook-xsl`. + +# Add the following to your `user-config.jam` file, which should live in + your home directory (`%HOMEDRIVE%%HOMEPATH%`). You must already have it + somewhere or otherwise you could not be building Boost (i.e. missing + tools configuration). + + using xsltproc + : "C:/Users/example/Documents/boost/xml/bin/xsltproc.exe" + ; + + using boostbook + : "C:/Users/example/Documents/boost/xml/docbook-xsl" + : "C:/Users/example/Documents/boost/xml/docbook-xml" + ; + +The above steps are enough to get a functional BoostBook setup. Quickbook +will be automatically built when needed. If you want to avoid these +rebuilds: + +# Go to Quickbook's source directory (`BOOST_ROOT\tools\quickbook`). + +# Build the utility by issuing `bjam --v2`. + +# Copy the resulting `quickbook.exe` binary (located under the + `BOOST_ROOT\bin.v2` hierarchy) to a safe place. Following our previous + example, you can install it into: + `C:\Users\example\Documents\boost\xml\bin`. + +# Add the following to your `user-config.jam` file: + + using quickbook + : "C:/Users/example/Documents/boost/xml/bin/quickbook.exe" + ; + +[endsect] + +[section:linux Debian, Ubuntu] + +The following instructions apply to Debian and its derivatives. They are based +on a Ubuntu Edgy install but should work on other Debian based systems. + +First install the `bjam`, `xsltproc`, `docbook-xsl` and `docbook-xml` packages. +For example, using `apt-get`: + + sudo apt-get install xsltprc docbook-xsl docbook-xml + +If you're planning on building boost's documentation, you'll also need to +install the `doxygen` package as well. + +Next, we need to configure Boost Build to compile BoostBook files. Add the +following to your `user-config.jam` file, which should be in your home +directory. If you don't have one, create a file containing this text. For more +information on setting up `user-config.jam`, see the +[@http://boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html Boost +Build documentation]. + + using xsltproc ; + + using boostbook + : /usr/share/xml/docbook/stylesheet/nwalsh + : /usr/share/xml/docbook/schema/dtd/4.2 + ; + + # Remove this line if you're not using doxygen + using doxygen ; + +The above steps are enough to get a functional BoostBook setup. Quickbook +will be automatically built when needed. If you want to avoid these +rebuilds: + +# Go to Quickbook's source directory (`BOOST_ROOT/tools/quickbook`). + +# Build the utility by issuing `bjam --v2`. + +# Copy the resulting `quickbook` binary (located under the + `BOOST_ROOT/bin.v2` hierarchy) to a safe place. The traditional location is + `/usr/local/bin`. + +# Add the following to your `user-config.jam` file, using the full path of the + quickbook executable: + + using quickbook + : /usr/local/bin/quickbook + ; + +[endsect] +[endsect] [/Installation and configuration] + +[section:editors Editor Support] + +Editing quickbook files is usually done with text editors both simple and +powerful. The following sections list the settings for some editors which can +help make editing quickbook files a bit easier. + +[blurb __note__ You may submit your settings, tips, and suggestions to the +authors, or through the [@https://lists.sourceforge.net/lists/listinfo/boost- +docs Boost Docs mailing list].] + +[section:scite Scintilla Text Editor] + +[:['Section contributed by Dean Michael Berris]] + +The Scintilla Text Editor (SciTE) is a free source code editor for Win32 and X. +It uses the SCIntilla source code editing component. + +[blurb __tip__ SciTE can be downloaded from [@http://www.scintilla.org/SciTE.html]] + +You can use the following settings to highlight quickbook tags when +editing quickbook files. + +[pre''' +qbk=*.qbk +lexer.*.qbk=props +use.tabs.$(qbk)=0 +tab.size.$(qbk)=4 +indent.size.$(qbk)=4 +style.props.32=$(font.base) +comment.stream.start.props=[/ +comment.stream.end.props=] +comment.box.start.props=[/ +comment.box.middle.props= +comment.box.end.props=] +'''] + +[blurb __note__ Thanks to Rene Rivera for the above SciTE settings.] + +[endsect] [/scite] +[endsect] [/editors] + +[section:faq Frequently Asked Questions] + +[heading Can I use QuickBook for non-Boost documentation?] + +QuickBook can be used for non-Boost documentation with a little extra work. + +[:['Faq contributed by Michael Marcin]] + +When building HTML documentation with BoostBook a Boost C++ Libraries header +is added to the files. When using QuickBook to document projects outside of +Boost this is not desirable. This behavior can be overridden at the BoostBook +level by specifying some XSLT options. When using Boost Build version 2 (BBv2) +this can be achieved by adding parameters to the BoostBook target declaration. + +For example: +[pre +using quickbook ; + +xml my_doc : my_doc.qbk ; + +boostbook standalone + : + my_doc + : + <xsl:param>boost.image.src=images/my_project_logo.png + <xsl:param>boost.image.alt="\\"My Project\\"" + <xsl:param>boost.image.w=100 + <xsl:param>boost.image.h=50 + <xsl:param>nav.layout=none + ; +] + +[endsect] [/faq] + +[section:ref Quick Reference] + +[cpp] + +[template ordered_list_sample[] +[pre''' +# one +# two +# three +'''] +] + +[template unordered_list_sample[] +[pre''' +* one +* two +* three +'''] +] + +[template table_sample[] +[pre''' +[table Title +[[a][b][c]] +[[a][b][c]] +] +'''] +] + +[template var_list_sample[] +[pre''' +[variablelist Title +[[a][b]] +[[a][b]] +] +'''] +] + + +[table Syntax Compendium + [[To do this...] [Use this...] [See this...]] + [[comment] [[^'''[/ some comment]''']] [__comments__]] + [[['italics]] [[^'''['italics] or /italics/''']] [__font_styles__ and __simple_formatting__]] + [[[*bold]] [[^'''[*bold] or *bold*''']] [__font_styles__ and __simple_formatting__]] + [[[_underline]] [[^'''[_underline] or _underline_''']] [__font_styles__ and __simple_formatting__]] + [[[^teletype]] [[^'''[^teletype] or =teletype=''']] [__font_styles__ and __simple_formatting__]] + [[[-strikethrough]] [[^'''[-strikethrough]''']] [__font_styles__ and __simple_formatting__]] + [[[~replaceable]] [[^'''[~replaceable]''']] [__replaceable__]] + [[source mode] [[^\[c++\]] or [^\[python\]]] [__source_mode__]] + [[inline code] [[^'''`int main();`''']] [__inline_code__]] + [[code block] [[^'''``int main();``''']] [__code__]] + [[code escape] [[^'''``from c++ to QuickBook``''']] [__escape_back__]] + [[line break] [[^'''[br] or \n''']] [__line_break__ *DEPRECATED*]] + [[anchor] [[^'''[#anchor]''']] [__anchors__]] + [[link] [[^'''[@http://www.boost.org Boost]''']] [__links__]] + [[anchor link] [[^'''[link section.anchor Link text]''']] [__anchor_links__]] + [[refentry link] [[^'''[link xml.refentry Link text]''']] [__refentry_links__]] + [[function link] [[^'''[funcref fully::qualified::function_name Link text]''']] [__code_links__]] + [[class link] [[^'''[classref fully::qualified::class_name Link text]''']] [__code_links__]] + [[member link] [[^'''[memberref fully::qualified::member_name Link text]''']] [__code_links__]] + [[enum link] [[^'''[enumref fully::qualified::enum_name Link text]''']] [__code_links__]] + [[macro link] [[^'''[macroref MACRO_NAME Link text]''']] [__code_links__]] + [[concept link] [[^'''[conceptref ConceptName Link text]''']] [__code_links__]] + [[header link] [[^'''[headerref path/to/header.hpp Link text]''']] [__code_links__]] + [[escape] [[^\'\'\'escaped text (no processing/formatting)\'\'\']] [__escape__]] + [[single char escape] [[^\\c]] [__single_char_escape__]] + [[images] [[^'''[$image.jpg]''']] [__images__]] + [[begin section] [[^'''[section The Section Title]''']] [__section__]] + [[end section] [[^'''[endsect]''']] [__section__]] + [[paragraph] [No markup. Paragraphs start left-flushed and are terminated by two or more newlines.] [__paragraphs__]] + [[ordered list] [[ordered_list_sample]] [__ordered_lists__]] + [[unordered list] [[unordered_list_sample]] [__unordered_lists__]] + [[code] [No markup. Preformatted code starts with a space or a tab.] [__code__]] + [[preformatted] [[^'''[pre preformatted]''']] [__preformatted__]] + [[block quote] [[^'''[:sometext...]''']] [__blockquote__]] + [[heading 1] [[^'''[h1 Heading 1]''']] [__heading__]] + [[heading 2] [[^'''[h2 Heading 2]''']] [__heading__]] + [[heading 3] [[^'''[h3 Heading 3]''']] [__heading__]] + [[heading 4] [[^'''[h4 Heading 4]''']] [__heading__]] + [[heading 5] [[^'''[h5 Heading 5]''']] [__heading__]] + [[heading 6] [[^'''[h6 Heading 6]''']] [__heading__]] + [[macro] [[^'''[def macro_identifier some text]''']] [__macros__]] + [[template] [[^'''[template[a b] [a] body [b]]''']] [__templates__]] + [[blurb] [[^'''[blurb advertisement or note...]''']] [__blurbs__]] + [[admonition] [[^'''[warning Warning text...]''']] [__admonitions__]] + [[table] [[table_sample]] [__tables__]] + [[variablelist] [[var_list_sample]] [__variable_lists__]] + [[include] [[^'''[include someother.qbk]''']] [__include__]] +] + +[endsect] |