| [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] |