diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 18:45:59 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 18:45:59 +0000 |
commit | 19fcec84d8d7d21e796c7624e521b60d28ee21ed (patch) | |
tree | 42d26aa27d1e3f7c0b8bd3fd14e7d7082f5008dc /src/boost/tools/quickbook/test/quickbook_manual-1_4.gold | |
parent | Initial commit. (diff) | |
download | ceph-upstream/16.2.11+ds.tar.xz ceph-upstream/16.2.11+ds.zip |
Adding upstream version 16.2.11+ds.upstream/16.2.11+dsupstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r-- | src/boost/tools/quickbook/test/quickbook_manual-1_4.gold | 3945 | ||||
-rw-r--r-- | src/boost/tools/quickbook/test/quickbook_manual-1_4.gold-html | 4177 |
2 files changed, 8122 insertions, 0 deletions
diff --git a/src/boost/tools/quickbook/test/quickbook_manual-1_4.gold b/src/boost/tools/quickbook/test/quickbook_manual-1_4.gold new file mode 100644 index 000000000..86d2eda66 --- /dev/null +++ b/src/boost/tools/quickbook/test/quickbook_manual-1_4.gold @@ -0,0 +1,3945 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE article PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> +<article id="quickbook" last-revision="DEBUG MODE Date: 2000/12/20 12:00:00 $" xmlns:xi="http://www.w3.org/2001/XInclude"> + <title>Quickbook 1.4</title> + <articleinfo> + <authorgroup> + <author> + <firstname>Joel</firstname> <surname>de Guzman</surname> + </author> + <author> + <firstname>Eric</firstname> <surname>Niebler</surname> + </author> + </authorgroup> + <copyright> + <year>2002</year> <year>2004</year> <year>2006</year> <holder>Joel de Guzman, + Eric Niebler</holder> + </copyright> + <legalnotice id="quickbook.legal"> + <para> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <ulink url="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</ulink>) + </para> + </legalnotice> + <articlepurpose> + <emphasis>WikiWiki</emphasis> style documentation tool + </articlepurpose> + </articleinfo> + <section id="quickbook.intro"> + <title><link linkend="quickbook.intro">Introduction</link></title> + <blockquote> + <para> + <emphasis role="bold"><emphasis><quote>Why program by hand in five days what + you can spend five years of your life automating?</quote></emphasis></emphasis> + </para> + <para> + -- Terrence Parr, author ANTLR/PCCTS + </para> + </blockquote> + <para> + Well, QuickBook started as a weekend hack. It was originally intended to be + a sample application using <ulink url="http://spirit.sourceforge.net">Spirit</ulink>. + What is it? What you are viewing now, this documentation, is autogenerated + by QuickBook. These files were generated from one master: + </para> + <blockquote> + <para> + <ulink url="../quickbook.qbk">quickbook.qbk</ulink> + </para> + </blockquote> + <para> + 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 + <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink> + instead of HTML. The <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink> + documentation format is an extension of <ulink url="http://www.docbook.org/">DocBook</ulink>, + an SGML or XML based format for describing documentation. + </para> + <para> + 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. + </para> + <para> + Features include: + </para> + <itemizedlist> + <listitem> + <simpara> + generate <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink> + xml, to generate HTML, PostScript and PDF + </simpara> + </listitem> + <listitem> + <simpara> + simple markup to link to Doxygen-generated entities + </simpara> + </listitem> + <listitem> + <simpara> + macro system for simple text substitution + </simpara> + </listitem> + <listitem> + <simpara> + simple markup for italics, bold, preformatted, blurbs, code samples, tables, + URLs, anchors, images, etc. + </simpara> + </listitem> + <listitem> + <simpara> + automatic syntax coloring of code samples + </simpara> + </listitem> + <listitem> + <simpara> + CSS support + </simpara> + </listitem> + </itemizedlist> + </section> + <section id="quickbook.change_log"> + <title><link linkend="quickbook.change_log">Change Log</link></title> + <bridgehead renderas="sect3" id="quickbook.change_log.h0"> + <phrase id="quickbook.change_log.version_1_3"/><link linkend="quickbook.change_log.version_1_3">Version + 1.3</link> + </bridgehead> + <itemizedlist> + <listitem> + <simpara> + Quickbook file inclusion [include]. + </simpara> + </listitem> + <listitem> + <simpara> + Better xml output (pretty layout). Check out the generated XML. + </simpara> + </listitem> + <listitem> + <simpara> + Regression testing facility: to make sure your document will always be + compatible (full backward compatibility) regardless of changes to QuickBook. + </simpara> + </listitem> + <listitem> + <simpara> + Code cleanup and refactoring. + </simpara> + </listitem> + <listitem> + <simpara> + Allow phrase markup in the doc-info. + </simpara> + </listitem> + <listitem> + <simpara> + Preformatted code blocks via ``code`` (double ticks) allows code in tables + and lists, for example. + </simpara> + </listitem> + <listitem> + <simpara> + 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. + </simpara> + </listitem> + <listitem> + <simpara> + Better (intuitive) paragraph termination. Some markups may terminate a + paragraph. Example: +<programlisting><phrase role="special">[</phrase><phrase role="identifier">section</phrase> <phrase role="identifier">x</phrase><phrase role="special">]</phrase> +<phrase role="identifier">blah</phrase><phrase role="special">...</phrase> +<phrase role="special">[</phrase><phrase role="identifier">endsect</phrase><phrase role="special">]</phrase></programlisting> + </simpara> + </listitem> + <listitem> + <simpara> + Fully qualified section and headers. Subsection names are concatenated + to the ID to avoid clashing. Example: <code><phrase role="identifier">doc_name</phrase><phrase + role="special">.</phrase><phrase role="identifier">sect_name</phrase><phrase + role="special">.</phrase><phrase role="identifier">sub_sect_name</phrase><phrase + role="special">.</phrase><phrase role="identifier">sub_sub_sect_name</phrase></code> + </simpara> + </listitem> + <listitem> + <simpara> + Better &nbsp; and whitespace handling in code snippets. + </simpara> + </listitem> + <listitem> + <simpara> + [xinclude] fixes up the relative path to the target XML file when input_directory + is not the same as the output_directory. + </simpara> + </listitem> + <listitem> + <simpara> + Allow untitled tables. + </simpara> + </listitem> + <listitem> + <simpara> + Allow phrase markups in section titles. + </simpara> + </listitem> + <listitem> + <simpara> + Allow escaping back to QuickBook from code, code blocks and inline code. + </simpara> + </listitem> + <listitem> + <simpara> + Footnotes, with the [footnote This is the footnote] syntax. + </simpara> + </listitem> + <listitem> + <simpara> + Post-processor bug fix for escaped XML code that it does not recognize. + </simpara> + </listitem> + <listitem> + <simpara> + Replaceable, with the [~replacement] syntax. + </simpara> + </listitem> + <listitem> + <simpara> + Generic Headers + </simpara> + </listitem> + <listitem> + <simpara> + Code changes to allow full recursion (i.e. Collectors and push/pop functions) + </simpara> + </listitem> + <listitem> + <simpara> + Various code cleanup/maintenance + </simpara> + </listitem> + <listitem> + <simpara> + Templates! + </simpara> + </listitem> + <listitem> + <simpara> + [conceptref] for referencing BoostBook <concept> entities. + </simpara> + </listitem> + <listitem> + <simpara> + Allow escape of spaces. The escaped space is removed from the output. Syntax: + <code><phrase role="special">\</phrase> </code>. + </simpara> + </listitem> + <listitem> + <simpara> + Nested comments are now allowed. + </simpara> + </listitem> + <listitem> + <simpara> + Quickbook blocks can nest inside comments. + </simpara> + </listitem> + <listitem> + <simpara> + <link linkend="quickbook.syntax.block.import">Import</link> facility. + </simpara> + </listitem> + <listitem> + <simpara> + Callouts on imported code + </simpara> + </listitem> + <listitem> + <simpara> + Simple markups can now span a whole block. + </simpara> + </listitem> + <listitem> + <simpara> + <link linkend="quickbook.syntax.block.blurbs">Blurbs</link>, <link linkend="quickbook.syntax.block.admonitions">Admonitions</link> + and table cells (see <link linkend="quickbook.syntax.block.tables">Tables</link>) + may now contain paragraphs. + </simpara> + </listitem> + <listitem> + <simpara> + <code><phrase role="special">\</phrase><phrase role="identifier">n</phrase></code> + and <code><phrase role="special">[</phrase><phrase role="identifier">br</phrase><phrase + role="special">]</phrase></code> are now deprecated. + </simpara> + </listitem> + </itemizedlist> + </section> + <section id="quickbook.syntax"> + <title><link linkend="quickbook.syntax">Syntax Summary</link></title> + <para> + 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. + </para> + <para> + 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. + </para> + <section id="quickbook.syntax.comments"> + <title><link linkend="quickbook.syntax.comments">Comments</link></title> + <para> + Can be placed anywhere. + </para> +<programlisting><!--quickbook-escape-prefix-->[/ comment (no output generated) ]<!--quickbook-escape-postfix--> +</programlisting> +<programlisting><!--quickbook-escape-prefix-->[/ comments can be nested [/ some more here] ]<!--quickbook-escape-postfix--> +</programlisting> +<programlisting><!--quickbook-escape-prefix-->[/ Quickbook blocks can nest inside comments. [*Comment this out too!] ]<!--quickbook-escape-postfix--> +</programlisting> + </section> + <section id="quickbook.syntax.phrase"> + <title><link linkend="quickbook.syntax.phrase">Phrase Level Elements</link></title> + <section id="quickbook.syntax.phrase.font_styles"> + <title><link linkend="quickbook.syntax.phrase.font_styles">Font Styles</link></title> +<programlisting><!--quickbook-escape-prefix-->['italic], [*bold], [_underline], [^teletype], [-strikethrough] +<!--quickbook-escape-postfix--></programlisting> + <para> + will generate: + </para> + <para> + <emphasis>italic</emphasis>, <emphasis role="bold">bold</emphasis>, <emphasis + role="underline">underline</emphasis>, <literal>teletype</literal>, <emphasis + role="strikethrough">strikethrough</emphasis> + </para> + <para> + Like all non-terminal phrase level elements, this can of course be nested: + </para> +<programlisting><!--quickbook-escape-prefix-->[*['bold-italic]] +<!--quickbook-escape-postfix--></programlisting> + <para> + will generate: + </para> + <para> + <emphasis role="bold"><emphasis>bold-italic</emphasis></emphasis> + </para> + </section> + <section id="quickbook.syntax.phrase.replaceable"> + <title><link linkend="quickbook.syntax.phrase.replaceable">Replaceable</link></title> + <para> + When you want content that may or must be replaced by the user, use the + syntax: + </para> +<programlisting><!--quickbook-escape-prefix-->[~replacement] +<!--quickbook-escape-postfix--></programlisting> + <para> + This will generate: + </para> + <para> + <replaceable>replacement</replaceable> + </para> + </section> + <section id="quickbook.syntax.phrase.quotations"> + <title><link linkend="quickbook.syntax.phrase.quotations">Quotations</link></title> +<programlisting><!--quickbook-escape-prefix-->["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein +<!--quickbook-escape-postfix--></programlisting> + <para> + will generate: + </para> + <para> + <quote>A question that sometimes drives me hazy: am I or are the others + crazy?</quote>--Einstein + </para> + <para> + 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>). + </para> + <para> + Like all phrase elements, quotations may be nested. Example: + </para> +<programlisting><!--quickbook-escape-prefix-->["Here's the rule for bargains: ["Do other men, for they would do you.] That's +the true business precept.] +<!--quickbook-escape-postfix--></programlisting> + <para> + will generate: + </para> + <para> + <quote>Here's the rule for bargains: <quote>Do other men, for they would + do you.</quote> That's the true business precept.</quote> + </para> + </section> + <section id="quickbook.syntax.phrase.simple_formatting"> + <title><link linkend="quickbook.syntax.phrase.simple_formatting">Simple formatting</link></title> + <para> + Simple markup for formatting text, common in many applications, is now + supported: + </para> +<programlisting><!--quickbook-escape-prefix-->/italic/, *bold*, _underline_, =teletype= +<!--quickbook-escape-postfix--></programlisting> + <para> + will generate: + </para> + <para> + <emphasis>italic</emphasis>, <emphasis role="bold">bold</emphasis>, <emphasis + role="underline">underline</emphasis>, <literal>teletype</literal> + </para> + <para> + Unlike QuickBook's standard formatting scheme, the rules for simpler alternatives + are much stricter<footnote id="quickbook.syntax.phrase.simple_formatting.f0"> + <para> + Thanks to David Barrett, author of <ulink url="http://quinthar.com/qwikiwiki/index.php?page=Home">Qwiki</ulink>, + for sharing these samples and teaching me these obscure formatting rules. + I wasn't sure at all if <ulink url="http://spirit.sourceforge.net">Spirit</ulink>, + being more or less a formal EBNF parser, can handle the context sensitivity + and ambiguity. + </para> + </footnote>. + </para> + <itemizedlist> + <listitem> + <simpara> + Simple markups cannot nest. You can combine a simple markup with a + nestable markup. + </simpara> + </listitem> + <listitem> + <simpara> + Simple markups cannot contain any other form of quickbook markup. + </simpara> + </listitem> + <listitem> + <simpara> + A non-space character must follow the leading markup + </simpara> + </listitem> + <listitem> + <simpara> + A non-space character must precede the trailing markup + </simpara> + </listitem> + <listitem> + <simpara> + A space or a punctuation must follow the trailing markup + </simpara> + </listitem> + <listitem> + <simpara> + 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: ']'. + </simpara> + </listitem> + <listitem> + <simpara> + A line starting with the star will be interpreted as an unordered list. + See <link linkend="quickbook.syntax.block.lists.unordered_lists">Unordered + lists</link>. + </simpara> + </listitem> + </itemizedlist> + <table frame="all" id="quickbook.syntax.phrase.simple_formatting.t0"> + <title>More Formatting Samples</title> + <tgroup cols="2"> + <thead> + <row> + <entry> + <para> + Markup + </para> + </entry> + <entry> + <para> + Result + </para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para> + <literal>*Bold*</literal> + </para> + </entry> + <entry> + <para> + <emphasis role="bold">Bold</emphasis> + </para> + </entry> + </row> + <row> + <entry> + <para> + <literal>*Is bold*</literal> + </para> + </entry> + <entry> + <para> + <emphasis role="bold">Is bold</emphasis> + </para> + </entry> + </row> + <row> + <entry> + <para> + <literal>* Not bold* *Not bold * * Not bold *</literal> + </para> + </entry> + <entry> + <para> + * Not bold* *Not bold * * Not bold * + </para> + </entry> + </row> + <row> + <entry> + <para> + <literal>This*Isn't*Bold (no bold)</literal> + </para> + </entry> + <entry> + <para> + This*Isn't*Bold (no bold) + </para> + </entry> + </row> + <row> + <entry> + <para> + <literal>(*Bold Inside*) (parenthesis not bold)</literal> + </para> + </entry> + <entry> + <para> + (<emphasis role="bold">Bold Inside</emphasis>) (parenthesis not + bold) + </para> + </entry> + </row> + <row> + <entry> + <para> + <literal>*(Bold Outside)* (parenthesis bold)</literal> + </para> + </entry> + <entry> + <para> + <emphasis role="bold">(Bold Outside)</emphasis> (parenthesis + bold) + </para> + </entry> + </row> + <row> + <entry> + <para> + <literal>3*4*5 = 60 (no bold)</literal> + </para> + </entry> + <entry> + <para> + 3*4*5 = 60 (no bold) + </para> + </entry> + </row> + <row> + <entry> + <para> + <literal>3 * 4 * 5 = 60 (no bold)</literal> + </para> + </entry> + <entry> + <para> + 3 * 4 * 5 = 60 (no bold) + </para> + </entry> + </row> + <row> + <entry> + <para> + <literal>3 *4* 5 = 60 (4 is bold)</literal> + </para> + </entry> + <entry> + <para> + 3 <emphasis role="bold">4</emphasis> 5 = 60 (4 is bold) + </para> + </entry> + </row> + <row> + <entry> + <para> + <literal>*This is bold* this is not *but this is*</literal> + </para> + </entry> + <entry> + <para> + <emphasis role="bold">This is bold</emphasis> this is not <emphasis + role="bold">but this is</emphasis> + </para> + </entry> + </row> + <row> + <entry> + <para> + <literal>*This is bold*.</literal> + </para> + </entry> + <entry> + <para> + <emphasis role="bold">This is bold</emphasis>. + </para> + </entry> + </row> + <row> + <entry> + <para> + <literal>*B*. (bold B)</literal> + </para> + </entry> + <entry> + <para> + <emphasis role="bold">B</emphasis>. (bold B) + </para> + </entry> + </row> + <row> + <entry> + <para> + <literal>['*Bold-Italic*]</literal> + </para> + </entry> + <entry> + <para> + <emphasis><emphasis role="bold">Bold-Italic</emphasis></emphasis> + </para> + </entry> + </row> + <row> + <entry> + <para> + <literal>*side-by*/-side/</literal> + </para> + </entry> + <entry> + <para> + <emphasis role="bold">side-by</emphasis><emphasis>-side</emphasis> + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + <para> + 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: + </para> +<programlisting><!--quickbook-escape-prefix-->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. +<!--quickbook-escape-postfix--></programlisting> + <para> + Baa baa black sheep, <emphasis role="bold">have you any wool? Yes sir, + yes sir, three bags full!</emphasis> One for the master, one for the dame, + And one for the little boy who lives down the lane. + </para> + <para> + But in the following paragraph, bold is not applied: + </para> +<programlisting><!--quickbook-escape-prefix-->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. +<!--quickbook-escape-postfix--></programlisting> + <para> + 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. + </para> + </section> + <section id="quickbook.syntax.phrase.inline_code"> + <title><link linkend="quickbook.syntax.phrase.inline_code">Inline code</link></title> + <para> + Inlining code in paragraphs is quite common when writing C++ documentation. + We provide a very simple markup for this. For example, this: + </para> +<programlisting><!--quickbook-escape-prefix-->This text has inlined code `int main() { return 0; }` in it. +<!--quickbook-escape-postfix--></programlisting> + <para> + will generate: + </para> + <para> + This text has inlined code <code><phrase role="keyword">int</phrase> <phrase + role="identifier">main</phrase><phrase role="special">()</phrase> <phrase + role="special">{</phrase> <phrase role="keyword">return</phrase> <phrase + role="number">0</phrase><phrase role="special">;</phrase> <phrase role="special">}</phrase></code> + in it. The code will be syntax highlighted. + </para> + <note> + <para> + We simply enclose the code with the tick: <literal>"`"</literal>, not the + single quote: <code><phrase role="string">"'"</phrase></code>. + Note too that <literal>`some code`</literal> is preferred over <literal>[^some code]</literal>. + </para> + </note> + </section> + <section id="quickbook.syntax.phrase.code_blocks"> + <title><link linkend="quickbook.syntax.phrase.code_blocks">Code blocks</link></title> + <para> + Preformatted code simply starts with a space or a tab (See <link linkend="quickbook.syntax.block.code">Code</link>). + However, such a simple syntax cannot be used as phrase elements in lists + (See <link linkend="quickbook.syntax.block.lists.ordered_lists">Ordered + lists</link> and <link linkend="quickbook.syntax.block.lists.unordered_lists">Unordered + lists</link>), tables (See <link linkend="quickbook.syntax.block.tables">Tables</link>), + etc. Inline code (see above) can. The problem is, inline code does not + allow formatting with newlines, spaces, and tabs. These are lost. + </para> + <para> + 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: + </para> +<programlisting>`` + #include <iostream> + + int main() + { + std::cout << "Hello, World!" << std::endl; + return 0; + } +`` +</programlisting> + <para> + will generate: + </para> + <para> +<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">iostream</phrase><phrase role="special">></phrase> + +<phrase role="keyword">int</phrase> <phrase role="identifier">main</phrase><phrase role="special">()</phrase> +<phrase role="special">{</phrase> + <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="string">"Hello, World!"</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase> + <phrase role="keyword">return</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase> +<phrase role="special">}</phrase> +</programlisting> + </para> + </section> + <section id="quickbook.syntax.phrase.source_mode"> + <title><link linkend="quickbook.syntax.phrase.source_mode">Source Mode</link></title> + <para> + 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 <link linkend="quickbook.syntax.block.document">Document</link> + section. + </para> + <para> + To change the source mode, use the <literal>[source-mode]</literal> markup, + where <literal>source-mode</literal> is one of the supported modes. For + example, this: + </para> +<programlisting><!--quickbook-escape-prefix-->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`. +<!--quickbook-escape-postfix--></programlisting> + <para> + will generate: + </para> + <para> + Python's <code><phrase role="keyword">import</phrase></code> is rather + like C++'s <code><phrase role="preprocessor">#include</phrase></code>. + A C++ comment <code><phrase role="comment">// looks like this</phrase></code> + whereas a Python comment <code><phrase role="comment">#looks like this</phrase></code>. + </para> + <table frame="all" id="quickbook.syntax.phrase.source_mode.t0"> + <title>Supported Source Modes</title> + <tgroup cols="2"> + <thead> + <row> + <entry> + <para> + Mode + </para> + </entry> + <entry> + <para> + Source Mode Markup + </para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para> + C++ + </para> + </entry> + <entry> + <para> + <literal>[c++]</literal> + </para> + </entry> + </row> + <row> + <entry> + <para> + Python + </para> + </entry> + <entry> + <para> + <literal>[python]</literal> + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + <note> + <para> + The source mode strings are lowercase. + </para> + </note> + </section> + <section id="quickbook.syntax.phrase.line_break"> + <title><link linkend="quickbook.syntax.phrase.line_break">line-break</link></title> +<programlisting><!--quickbook-escape-prefix-->[br] +<!--quickbook-escape-postfix--></programlisting> + <warning> + <para> + <code><phrase role="special">[</phrase><phrase role="identifier">br</phrase><phrase + role="special">]</phrase></code> is now deprecated. <link linkend="quickbook.syntax.block.blurbs">Blurbs</link>, + <link linkend="quickbook.syntax.block.admonitions">Admonitions</link> + and table cells (see <link linkend="quickbook.syntax.block.tables">Tables</link>) + may now contain paragraphs. + </para> + </warning> + </section> + <section id="quickbook.syntax.phrase.anchors"> + <title><link linkend="quickbook.syntax.phrase.anchors">Anchors</link></title> +<programlisting><!--quickbook-escape-prefix-->[#named_anchor] +<!--quickbook-escape-postfix--></programlisting> + <para> + A named anchor is a hook that can be referenced by a link elsewhere in + the document. You can then reference an anchor with <literal>[link named_anchor +Some link text]</literal>. + See <link linkend="quickbook.syntax.phrase.anchor_links">Anchor links</link>, + <link linkend="quickbook.syntax.block.section">Section</link> and <link + linkend="quickbook.syntax.block.headings">Heading</link>. + </para> + </section> + <section id="quickbook.syntax.phrase.links"> + <title><link linkend="quickbook.syntax.phrase.links">Links</link></title> +<programlisting><!--quickbook-escape-prefix-->[@http://www.boost.org this is [*boost's] website....] +<!--quickbook-escape-postfix--></programlisting> + <para> + will generate: + </para> + <para> + <ulink url="http://www.boost.org">this is <emphasis role="bold">boost's</emphasis> + website....</ulink> + </para> + <para> + URL links where the link text is the link itself is common. Example: + </para> +<programlisting><!--quickbook-escape-prefix-->see http://spirit.sourceforge.net/ +<!--quickbook-escape-postfix--></programlisting> + <para> + so, when the text is absent in a link markup, the URL is assumed. Example: + </para> +<programlisting>see <!--quickbook-escape-prefix-->[@http://spirit.sourceforge.net/]<!--quickbook-escape-postfix--> +</programlisting> + <para> + will generate: + </para> + <para> + see <ulink url="http://spirit.sourceforge.net/">http://spirit.sourceforge.net/</ulink> + </para> + </section> + <section id="quickbook.syntax.phrase.anchor_links"> + <title><link linkend="quickbook.syntax.phrase.anchor_links">Anchor links</link></title> + <para> + You can link within a document using: + </para> +<programlisting><!--quickbook-escape-prefix-->[link section_id.normalized_header_text The link text] +<!--quickbook-escape-postfix--></programlisting> + <para> + See sections <link linkend="quickbook.syntax.block.section">Section</link> + and <link linkend="quickbook.syntax.block.headings">Heading</link> for + more info. + </para> + </section> + <section id="quickbook.syntax.phrase.refentry_links"> + <title><link linkend="quickbook.syntax.phrase.refentry_links">refentry links</link></title> + <para> + In addition, you can link internally to an XML refentry like: + </para> +<programlisting><!--quickbook-escape-prefix-->[link xml.refentry The link text] +<!--quickbook-escape-postfix--></programlisting> + <para> + This gets converted into <literal><link linkend="xml.refentry">The + link text</link></literal>. + </para> + <para> + Like URLs, the link text is optional. If this is not present, the link + text will automatically be the refentry. Example: + </para> +<programlisting><!--quickbook-escape-prefix-->[link xml.refentry] +<!--quickbook-escape-postfix--></programlisting> + <para> + This gets converted into <literal><link linkend="xml.refentry">xml.refentry</link></literal>. + </para> + </section> + <section id="quickbook.syntax.phrase.code_links"> + <title><link linkend="quickbook.syntax.phrase.code_links">Code Links</link></title> + <para> + If you want to link to a function, class, member, enum, concept or header + in the reference section, you can use: + </para> +<programlisting><!--quickbook-escape-prefix-->[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] +<!--quickbook-escape-postfix--></programlisting> + <para> + 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: + </para> +<programlisting><!--quickbook-escape-prefix-->[classref boost::bar::baz] +<!--quickbook-escape-postfix--></programlisting> + <para> + would have "boost::bar::baz" as the link text. + </para> + </section> + <section id="quickbook.syntax.phrase.escape"> + <title><link linkend="quickbook.syntax.phrase.escape">Escape</link></title> + <para> + The escape mark-up is used when we don't want to do any processing. + </para> +<programlisting>''' +escape (no processing/formatting) +''' +</programlisting> + <para> + Escaping allows us to pass XML markup to <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink> + or <ulink url="http://www.docbook.org/">DocBook</ulink>. For example: + </para> +<programlisting>''' +<emphasis role="bold">This is direct XML markup</emphasis> +''' +</programlisting> + <para> + <emphasis role="bold">This is direct XML markup</emphasis> + </para> + <important> + <para> + Be careful when using the escape. The text must conform to <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink>/<ulink + url="http://www.docbook.org/">DocBook</ulink> syntax. + </para> + </important> + </section> + <section id="quickbook.syntax.phrase.single_char_escape"> + <title><link linkend="quickbook.syntax.phrase.single_char_escape">Single + char escape</link></title> + <para> + 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 <code><phrase + role="special">[</phrase></code> and <code><phrase role="special">]</phrase></code>. + For example, how do you escape the triple quote? Simple: <literal>\'\'\'</literal> + </para> + <para> + <code><phrase role="special">\</phrase><phrase role="identifier">n</phrase></code> + has a special meaning. It is used to generate line breaks. + </para> + <warning> + <para> + <code><phrase role="special">\</phrase><phrase role="identifier">n</phrase></code> + and <code><phrase role="special">[</phrase><phrase role="identifier">br</phrase><phrase + role="special">]</phrase></code> are now deprecated. <link linkend="quickbook.syntax.block.blurbs">Blurbs</link>, + <link linkend="quickbook.syntax.block.admonitions">Admonitions</link> + and table cells (see <link linkend="quickbook.syntax.block.tables">Tables</link>) + may now contain paragraphs. + </para> + </warning> + <para> + The escaped space: <code><phrase role="special">\</phrase> </code> also + has a special meaning. The escaped space is removed from the output. + </para> + </section> + <section id="quickbook.syntax.phrase.images"> + <title><link linkend="quickbook.syntax.phrase.images">Images</link></title> +<programlisting><!--quickbook-escape-prefix-->[$image.jpg] +<!--quickbook-escape-postfix--></programlisting> + </section> + <section id="quickbook.syntax.phrase.footnotes"> + <title><link linkend="quickbook.syntax.phrase.footnotes">Footnotes</link></title> + <para> + As of version 1.3, QuickBook supports footnotes. Just put the text of the + footnote in a <code><phrase role="special">[</phrase><phrase role="identifier">footnote</phrase><phrase + role="special">]</phrase></code> block, and the text will be put at the + bottom of the current page. For example, this: + </para> +<programlisting><!--quickbook-escape-prefix-->[footnote A sample footnote] +<!--quickbook-escape-postfix--></programlisting> + <para> + will generate this<footnote id="quickbook.syntax.phrase.footnotes.f0"> + <para> + A sample footnote + </para> + </footnote>. + </para> + <section id="quickbook.syntax.phrase.footnotes.macro_expansion"> + <title><link linkend="quickbook.syntax.phrase.footnotes.macro_expansion">Macro + Expansion</link></title> +<programlisting><!--quickbook-escape-prefix-->__a_macro_identifier__ +<!--quickbook-escape-postfix--></programlisting> + <para> + See <link linkend="quickbook.syntax.block.macros">Macros</link> for details. + </para> + </section> + <section id="quickbook.syntax.phrase.footnotes.template_expansion"> + <title><link linkend="quickbook.syntax.phrase.footnotes.template_expansion">Template + Expansion</link></title> +<programlisting><!--quickbook-escape-prefix-->[a_template_identifier] +<!--quickbook-escape-postfix--></programlisting> + <para> + See <link linkend="quickbook.syntax.block.templates">Templates</link> + for details. + </para> + </section> + </section> + </section> + <section id="quickbook.syntax.block"> + <title><link linkend="quickbook.syntax.block">Block Level Elements</link></title> + <section id="quickbook.syntax.block.document"> + <title><link linkend="quickbook.syntax.block.document">Document</link></title> + <para> + Every document must begin with a Document Info section, which should look + like this: + </para> +<programlisting><!--quickbook-escape-prefix-->[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] +] +<!--quickbook-escape-postfix--></programlisting> + <para> + Where document-type is one of: + </para> + <itemizedlist> + <listitem> + <simpara> + book + </simpara> + </listitem> + <listitem> + <simpara> + article + </simpara> + </listitem> + <listitem> + <simpara> + library + </simpara> + </listitem> + <listitem> + <simpara> + chapter + </simpara> + </listitem> + <listitem> + <simpara> + part + </simpara> + </listitem> + <listitem> + <simpara> + appendix + </simpara> + </listitem> + <listitem> + <simpara> + preface + </simpara> + </listitem> + <listitem> + <simpara> + qandadiv + </simpara> + </listitem> + <listitem> + <simpara> + qandaset + </simpara> + </listitem> + <listitem> + <simpara> + reference + </simpara> + </listitem> + <listitem> + <simpara> + set + </simpara> + </listitem> + </itemizedlist> + <para> + quickbook 1.3 declares the version of quickbook the document is written + for. In its absence, version 1.1 is assumed. + </para> + <para> + <literal>version</literal>, <literal>id</literal>, <literal>dirname</literal>, + <literal>copyright</literal>, <literal>purpose</literal>, <literal>category</literal>, + <literal>authors</literal>, <literal>license</literal>, <literal>last-revision</literal> + and <literal>source-mode</literal> are optional information. + </para> + <para> + <literal>source-type</literal> is a lowercase string setting the initial + <link linkend="quickbook.syntax.phrase.source_mode">Source Mode</link>. + If the <literal>source-mode</literal> field is omitted, a default value + of <literal>c++</literal> will be used. + </para> + </section> + <section id="quickbook.syntax.block.section"> + <title><link linkend="quickbook.syntax.block.section">Section</link></title> + <para> + Starting a new section is accomplished with: + </para> +<programlisting><!--quickbook-escape-prefix-->[section:id The Section Title] +<!--quickbook-escape-postfix--></programlisting> + <para> + where <emphasis>id</emphasis> 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 <literal>a-Z</literal>, + <literal>A-Z</literal>, <literal>0-9</literal> and <literal>_</literal>. + 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". + </para> + <para> + End a section with: + </para> +<programlisting><!--quickbook-escape-prefix-->[endsect] +<!--quickbook-escape-postfix--></programlisting> + <para> + Sections can nest, and that results in a hierarchy in the table of contents. + </para> + </section> + <section id="quickbook.syntax.block.xinclude"> + <title><link linkend="quickbook.syntax.block.xinclude">xinclude</link></title> + <para> + You can include another XML file with: + </para> +<programlisting><!--quickbook-escape-prefix-->[xinclude file.xml] +<!--quickbook-escape-postfix--></programlisting> + <para> + This is useful when file.xml has been generated by Doxygen and contains + your reference section. + </para> + </section> + <section id="quickbook.syntax.block.paragraphs"> + <title><link linkend="quickbook.syntax.block.paragraphs">Paragraphs</link></title> + <para> + 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. + </para> + </section> + <section id="quickbook.syntax.block.lists"> + <title><link linkend="quickbook.syntax.block.lists">Lists</link></title> + <section id="quickbook.syntax.block.lists.ordered_lists"> + <title><link linkend="quickbook.syntax.block.lists.ordered_lists">Ordered + lists</link></title> +<programlisting># One +# Two +# Three +</programlisting> + <para> + will generate: + </para> + <orderedlist> + <listitem> + <simpara> + One + </simpara> + </listitem> + <listitem> + <simpara> + Two + </simpara> + </listitem> + <listitem> + <simpara> + Three + </simpara> + </listitem> + </orderedlist> + </section> + <section id="quickbook.syntax.block.lists.list_hierarchies"> + <title><link linkend="quickbook.syntax.block.lists.list_hierarchies">List + Hierarchies</link></title> + <para> + List hierarchies are supported. Example: + </para> +<programlisting># One +# Two +# Three + # Three.a + # Three.b + # Three.c +# Four + # Four.a + # Four.a.i + # Four.a.ii +# Five +</programlisting> + <para> + will generate: + </para> + <orderedlist> + <listitem> + <simpara> + One + </simpara> + </listitem> + <listitem> + <simpara> + Two + </simpara> + </listitem> + <listitem> + <simpara> + Three + <orderedlist> + <listitem> + <simpara> + Three.a + </simpara> + </listitem> + <listitem> + <simpara> + Three.b + </simpara> + </listitem> + <listitem> + <simpara> + Three.c + </simpara> + </listitem> + </orderedlist> + </simpara> + </listitem> + <listitem> + <simpara> + Fourth + <orderedlist> + <listitem> + <simpara> + Four.a + <orderedlist> + <listitem> + <simpara> + Four.a.i + </simpara> + </listitem> + <listitem> + <simpara> + Four.a.ii + </simpara> + </listitem> + </orderedlist> + </simpara> + </listitem> + </orderedlist> + </simpara> + </listitem> + <listitem> + <simpara> + Five + </simpara> + </listitem> + </orderedlist> + </section> + <section id="quickbook.syntax.block.lists.long_list_lines"> + <title><link linkend="quickbook.syntax.block.lists.long_list_lines">Long + List Lines</link></title> + <para> + Long lines will be wrapped appropriately. Example: + </para> +<programlisting># 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. +</programlisting> + <orderedlist> + <listitem> + <simpara> + A short item. + </simpara> + </listitem> + <listitem> + <simpara> + 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. + </simpara> + </listitem> + <listitem> + <simpara> + A short item. + </simpara> + </listitem> + </orderedlist> + </section> + <section id="quickbook.syntax.block.lists.unordered_lists"> + <title><link linkend="quickbook.syntax.block.lists.unordered_lists">Unordered + lists</link></title> +<programlisting><!--quickbook-escape-prefix-->* First +* Second +* Third +<!--quickbook-escape-postfix--></programlisting> + <para> + will generate: + </para> + <itemizedlist> + <listitem> + <simpara> + First + </simpara> + </listitem> + <listitem> + <simpara> + Second + </simpara> + </listitem> + <listitem> + <simpara> + Third + </simpara> + </listitem> + </itemizedlist> + </section> + <section id="quickbook.syntax.block.lists.mixed_lists"> + <title><link linkend="quickbook.syntax.block.lists.mixed_lists">Mixed lists</link></title> + <para> + Mixed lists (ordered and unordered) are supported. Example: + </para> +<programlisting><!--quickbook-escape-prefix--># One +# Two +# Three + * Three.a + * Three.b + * Three.c +# Four +<!--quickbook-escape-postfix--></programlisting> + <para> + will generate: + </para> + <orderedlist> + <listitem> + <simpara> + One + </simpara> + </listitem> + <listitem> + <simpara> + Two + </simpara> + </listitem> + <listitem> + <simpara> + Three + <itemizedlist> + <listitem> + <simpara> + Three.a + </simpara> + </listitem> + <listitem> + <simpara> + Three.b + </simpara> + </listitem> + <listitem> + <simpara> + Three.c + </simpara> + </listitem> + </itemizedlist> + </simpara> + </listitem> + <listitem> + <simpara> + Four + </simpara> + </listitem> + </orderedlist> + <para> + And... + </para> +<programlisting><!--quickbook-escape-prefix--># 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 +<!--quickbook-escape-postfix--></programlisting> + <para> + will generate: + </para> + <orderedlist> + <listitem> + <simpara> + 1 + <itemizedlist> + <listitem> + <simpara> + 1.a + <orderedlist> + <listitem> + <simpara> + 1.a.1 + </simpara> + </listitem> + <listitem> + <simpara> + 1.a.2 + </simpara> + </listitem> + </orderedlist> + </simpara> + </listitem> + <listitem> + <simpara> + 1.b + </simpara> + </listitem> + </itemizedlist> + </simpara> + </listitem> + <listitem> + <simpara> + 2 + <itemizedlist> + <listitem> + <simpara> + 2.a + </simpara> + </listitem> + <listitem> + <simpara> + 2.b + <orderedlist> + <listitem> + <simpara> + 2.b.1 + </simpara> + </listitem> + <listitem> + <simpara> + 2.b.2 + <itemizedlist> + <listitem> + <simpara> + 2.b.2.a + </simpara> + </listitem> + <listitem> + <simpara> + 2.b.2.b + </simpara> + </listitem> + </itemizedlist> + </simpara> + </listitem> + </orderedlist> + </simpara> + </listitem> + </itemizedlist> + </simpara> + </listitem> + </orderedlist> + </section> + </section> + <section id="quickbook.syntax.block.code"> + <title><link linkend="quickbook.syntax.block.code">Code</link></title> + <para> + Preformatted code starts with a space or a tab. The code will be syntax + highlighted according to the current <link linkend="quickbook.syntax.phrase.source_mode">Source + Mode</link>: + </para> +<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">iostream</phrase><phrase role="special">></phrase> + +<phrase role="keyword">int</phrase> <phrase role="identifier">main</phrase><phrase role="special">()</phrase> +<phrase role="special">{</phrase> + <phrase role="comment">// Sample code</phrase> + <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="string">"Hello, World\n"</phrase><phrase role="special">;</phrase> + <phrase role="keyword">return</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase> +<phrase role="special">}</phrase> +</programlisting> +<programlisting><phrase role="keyword">import</phrase> <phrase role="identifier">cgi</phrase> + +<phrase role="keyword">def</phrase> <phrase role="identifier">cookForHtml</phrase><phrase role="special">(</phrase><phrase role="identifier">text</phrase><phrase role="special">):</phrase> + <phrase role="string">'''"Cooks" the input text for HTML.'''</phrase> + + <phrase role="keyword">return</phrase> <phrase role="identifier">cgi</phrase><phrase role="special">.</phrase><phrase role="identifier">escape</phrase><phrase role="special">(</phrase><phrase role="identifier">text</phrase><phrase role="special">)</phrase> +</programlisting> + <para> + Macros that are already defined are expanded in source code. Example: + </para> +<programlisting><!--quickbook-escape-prefix-->[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__; +<!--quickbook-escape-postfix--></programlisting> + <para> + Generates: + </para> +<programlisting><phrase role="keyword">using</phrase> <ulink url="http://www.boost.org/libs/libraries.htm">boost</ulink><phrase role="special">::</phrase><ulink url="http://www.boost.org/doc/html/array/reference.html">array</ulink><phrase role="special">;</phrase> +</programlisting> + </section> + <section id="quickbook.syntax.block.escape_back"> + <title><link linkend="quickbook.syntax.block.escape_back">Escaping Back To + QuickBook</link></title> + <para> + 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 <emphasis>escape-back</emphasis> delimiter. In C++ + and Python, the delimiter is the double tick (back-quote): "``" + and "``". Example: + </para> +<programlisting><!--quickbook-escape-prefix-->void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``() +{ +} +<!--quickbook-escape-postfix--></programlisting> + <para> + Will generate: + </para> +<programlisting><phrase role="keyword">void</phrase> <ulink url="http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz">foo</ulink><phrase role="special">()</phrase> +<phrase role="special">{</phrase> +<phrase role="special">}</phrase> +</programlisting> + <para> + When escaping from code to QuickBook, only phrase level markups are allowed. + Block level markups like lists, tables etc. are not allowed. + </para> + </section> + <section id="quickbook.syntax.block.preformatted"> + <title><link linkend="quickbook.syntax.block.preformatted">Preformatted</link></title> + <para> + Sometimes, you don't want some preformatted text to be parsed as C++. In + such cases, use the <literal>[pre ... ]</literal> markup block. + </para> +<programlisting><!--quickbook-escape-prefix-->[pre + + Some *preformatted* text Some *preformatted* text + + Some *preformatted* text Some *preformatted* text + + Some *preformatted* text Some *preformatted* text + +] +<!--quickbook-escape-postfix--></programlisting> + <para> + 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: + </para> +<programlisting>Some <emphasis role="bold">preformatted</emphasis> text Some <emphasis role="bold">preformatted</emphasis> text + + Some <emphasis role="bold">preformatted</emphasis> text Some <emphasis role="bold">preformatted</emphasis> text + + Some <emphasis role="bold">preformatted</emphasis> text Some <emphasis role="bold">preformatted</emphasis> text + +</programlisting> + <para> + Notice that unlike Code, phrase markup such as font style is still permitted + inside <literal>pre</literal> blocks. + </para> + </section> + <section id="quickbook.syntax.block.blockquote"> + <title><link linkend="quickbook.syntax.block.blockquote">Blockquote</link></title> +<programlisting><!--quickbook-escape-prefix-->[:sometext...]<!--quickbook-escape-postfix--> +</programlisting> + <blockquote> + <para> + Indents the paragraph. This applies to one paragraph only. + </para> + </blockquote> + </section> + <section id="quickbook.syntax.block.admonitions"> + <title><link linkend="quickbook.syntax.block.admonitions">Admonitions</link></title> +<programlisting><!--quickbook-escape-prefix-->[note This is a note] +[tip This is a tip] +[important This is important] +[caution This is a caution] +[warning This is a warning] +<!--quickbook-escape-postfix--></programlisting> + <para> + generates <ulink url="http://www.docbook.org/">DocBook</ulink> admonitions: + </para> + <note> + <para> + This is a note + </para> + </note> + <tip> + <para> + This is a tip + </para> + </tip> + <important> + <para> + This is important + </para> + </important> + <caution> + <para> + This is a caution + </para> + </caution> + <warning> + <para> + This is a warning + </para> + </warning> + <para> + These are the only admonitions supported by <ulink url="http://www.docbook.org/">DocBook</ulink>. + So, for example <literal>[information This is some information]</literal> + is unlikely to produce the desired effect. + </para> + </section> + <section id="quickbook.syntax.block.headings"> + <title><link linkend="quickbook.syntax.block.headings">Headings</link></title> +<programlisting><!--quickbook-escape-prefix-->[h1 Heading 1] +[h2 Heading 2] +[h3 Heading 3] +[h4 Heading 4] +[h5 Heading 5] +[h6 Heading 6] +<!--quickbook-escape-postfix--></programlisting> + <bridgehead renderas="sect1" id="quickbook.syntax.block.headings.h0"> + <phrase id="quickbook.syntax.block.headings.heading_1"/><link linkend="quickbook.syntax.block.headings.heading_1">Heading + 1</link> + </bridgehead> + <bridgehead renderas="sect2" id="quickbook.syntax.block.headings.h1"> + <phrase id="quickbook.syntax.block.headings.heading_2"/><link linkend="quickbook.syntax.block.headings.heading_2">Heading + 2</link> + </bridgehead> + <bridgehead renderas="sect3" id="quickbook.syntax.block.headings.h2"> + <phrase id="quickbook.syntax.block.headings.heading_3"/><link linkend="quickbook.syntax.block.headings.heading_3">Heading + 3</link> + </bridgehead> + <bridgehead renderas="sect4" id="quickbook.syntax.block.headings.h3"> + <phrase id="quickbook.syntax.block.headings.heading_4"/><link linkend="quickbook.syntax.block.headings.heading_4">Heading + 4</link> + </bridgehead> + <bridgehead renderas="sect5" id="quickbook.syntax.block.headings.h4"> + <phrase id="quickbook.syntax.block.headings.heading_5"/><link linkend="quickbook.syntax.block.headings.heading_5">Heading + 5</link> + </bridgehead> + <bridgehead renderas="sect6" id="quickbook.syntax.block.headings.h5"> + <phrase id="quickbook.syntax.block.headings.heading_6"/><link linkend="quickbook.syntax.block.headings.heading_6">Heading + 6</link> + </bridgehead> + <para> + Headings 1-3 [h1 h2 and h3] will automatically have anchors with normalized + names with <literal>name="section_id.normalized_header_text"</literal> + (i.e. valid characters are <literal>a-z</literal>, <literal>A-Z</literal>, + <literal>0-9</literal> and <literal>_</literal>. 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 <literal>section_2.heading_1</literal>). + You can use: + </para> +<programlisting><!--quickbook-escape-prefix-->[link section_id.normalized_header_text The link text] +<!--quickbook-escape-postfix--></programlisting> + <para> + to link to them. See <link linkend="quickbook.syntax.phrase.anchor_links">Anchor + links</link> and <link linkend="quickbook.syntax.block.section">Section</link> + for more info. + </para> + </section> + <section id="quickbook.syntax.block.generic_heading"> + <title><link linkend="quickbook.syntax.block.generic_heading">Generic Heading</link></title> + <para> + In cases when you don't want to care about the heading level (1 to 6), + you can use the <emphasis>Generic Heading</emphasis>: + </para> +<programlisting><!--quickbook-escape-prefix-->[heading Heading] +<!--quickbook-escape-postfix--></programlisting> + <para> + The <emphasis>Generic Heading</emphasis> 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 <emphasis>h2</emphasis>. + </para> + <para> + 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: + </para> +<programlisting><!--quickbook-escape-prefix-->[section A] +[h2 X] +[h2 Y] +[h2 Z] +[endsect] +<!--quickbook-escape-postfix--></programlisting> + <para> + 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: + </para> +<programlisting><!--quickbook-escape-prefix-->[section A] +[heading X] +[heading Y] +[heading Z] +[endsect] +<!--quickbook-escape-postfix--></programlisting> + <para> + 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 <emphasis>section</emphasis> and <emphasis>heading</emphasis>, you + have all you need. <emphasis>h1</emphasis>..<emphasis>h6</emphasis> becomes + redundant. <emphasis>h1</emphasis>..<emphasis>h6</emphasis> might be deprecated + in the future. + </para> + </section> + <section id="quickbook.syntax.block.macros"> + <title><link linkend="quickbook.syntax.block.macros">Macros</link></title> +<programlisting><!--quickbook-escape-prefix-->[def macro_identifier some text] +<!--quickbook-escape-postfix--></programlisting> + <para> + 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: + </para> +<programlisting><!--quickbook-escape-prefix-->[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&type=1]] +sf_logo +<!--quickbook-escape-postfix--></programlisting> + <para> + Now everywhere the sf_logo is placed, the picture will be inlined. + </para> + <para> + <inlinemediaobject><imageobject><imagedata fileref="http://sourceforge.net/sflogo.php?group_id=28447&type=1"></imagedata></imageobject> + <textobject> + <phrase>sflogo</phrase> + </textobject> + </inlinemediaobject> + </para> + <tip> + <para> + 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. <literal>__spirit__</literal>). The reason is to avoid unwanted + macro replacement. + </para> + </tip> + <para> + Links (URLS) and images are good candidates for macros. <emphasis role="bold">1</emphasis>) + 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. <emphasis role="bold">2</emphasis>) + The syntax is not pretty. It's easier to read and write, e.g. <literal>__spirit__</literal> + than <literal>[@http://spirit.sourceforge.net Spirit]</literal>. + </para> + <para> + Some more examples: + </para> +<programlisting><!--quickbook-escape-prefix-->[def :-) [$theme/smiley.png]] +[def __spirit__ [@http://spirit.sourceforge.net Spirit]] +<!--quickbook-escape-postfix--></programlisting> + <para> + (See <link linkend="quickbook.syntax.phrase.images">Images</link> and + <link linkend="quickbook.syntax.phrase.links">Links</link>) + </para> + <para> + Invoking these macros: + </para> +<programlisting><!--quickbook-escape-prefix-->Hi __spirit__ :-) +<!--quickbook-escape-postfix--></programlisting> + <para> + will generate this: + </para> + <para> + Hi <ulink url="http://spirit.sourceforge.net">Spirit</ulink> <inlinemediaobject><imageobject><imagedata + fileref="images/smiley.png"></imagedata></imageobject> + <textobject> + <phrase>smiley</phrase> + </textobject> + </inlinemediaobject> + </para> + </section> + <section id="quickbook.syntax.block.predefined_macros"> + <title><link linkend="quickbook.syntax.block.predefined_macros">Predefined + Macros</link></title> + <para> + Quickbook has some predefined macros that you can already use. + </para> + <table frame="all" id="quickbook.syntax.block.predefined_macros.t0"> + <title>Predefined Macros</title> + <tgroup cols="3"> + <thead> + <row> + <entry> + <para> + Macro + </para> + </entry> + <entry> + <para> + Meaning + </para> + </entry> + <entry> + <para> + Example + </para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para> + __DATE__ + </para> + </entry> + <entry> + <para> + Today's date + </para> + </entry> + <entry> + <para> + 2000-Dec-20 + </para> + </entry> + </row> + <row> + <entry> + <para> + __TIME__ + </para> + </entry> + <entry> + <para> + The current time + </para> + </entry> + <entry> + <para> + 12:00:00 PM + </para> + </entry> + </row> + <row> + <entry> + <para> + __FILENAME__ + </para> + </entry> + <entry> + <para> + Quickbook source filename + </para> + </entry> + <entry> + <para> + quickbook_manual-1_4.quickbook + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + </section> + <section id="quickbook.syntax.block.templates"> + <title><link linkend="quickbook.syntax.block.templates">Templates</link></title> + <para> + 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). + </para> + <para> + Example template: + </para> +<programlisting><!--quickbook-escape-prefix-->[template person[name age what] + +Hi, my name is [name]. I am [age] years old. I am a [what]. + +] +<!--quickbook-escape-postfix--></programlisting> + <bridgehead renderas="sect5" id="quickbook.syntax.block.templates.h0"> + <phrase id="quickbook.syntax.block.templates.template_identifier"/><link + linkend="quickbook.syntax.block.templates.template_identifier">Template + Identifier</link> + </bridgehead> + <para> + Template identifiers can either consist of: + </para> + <itemizedlist> + <listitem> + <simpara> + 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. + </simpara> + </listitem> + <listitem> + <simpara> + A single character punctuation (a non-alphanumeric printable character) + </simpara> + </listitem> + </itemizedlist> + <bridgehead renderas="sect5" id="quickbook.syntax.block.templates.h1"> + <phrase id="quickbook.syntax.block.templates.formal_template_arguments"/><link + linkend="quickbook.syntax.block.templates.formal_template_arguments">Formal + Template Arguments</link> + </bridgehead> + <para> + 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. + </para> + <para> + A template formal argument temporarily hides a template of the same name + at the point where the <link linkend="quickbook.syntax.block.templates.template_expansion">template + is expanded</link>. Note that the body of the <literal>person</literal> + template above refers to <literal>name</literal> <literal>age</literal> + and <literal>what</literal> as <literal>[name]</literal> <literal>[age]</literal> + and <literal>[what]</literal>. <literal>name</literal> <literal>age</literal> + and <literal>what</literal> are actually templates that exist in the duration + of the template call. + </para> + <bridgehead renderas="sect5" id="quickbook.syntax.block.templates.h2"> + <phrase id="quickbook.syntax.block.templates.template_body"/><link linkend="quickbook.syntax.block.templates.template_body">Template + Body</link> + </bridgehead> + <para> + 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: + </para> +<programlisting><!--quickbook-escape-prefix-->[template sample[arg1 arg2...argN] replacement text... ] +<!--quickbook-escape-postfix--></programlisting> + <para> + Block templates are of the form: + </para> +<programlisting><!--quickbook-escape-prefix-->[template sample[arg1 arg2...argN] +replacement text... +] +<!--quickbook-escape-postfix--></programlisting> + <para> + 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. + </para> + <bridgehead renderas="sect5" id="quickbook.syntax.block.templates.h3"> + <phrase id="quickbook.syntax.block.templates.template_expansion"/><link + linkend="quickbook.syntax.block.templates.template_expansion">Template + Expansion</link> + </bridgehead> + <para> + You expand a template this way: + </para> +<programlisting><!--quickbook-escape-prefix-->[template_identifier arg1..arg2..arg3] +<!--quickbook-escape-postfix--></programlisting> + <para> + At template expansion, you supply the actual arguments. The template will + be expanded with your supplied arguments. Example: + </para> +<programlisting><!--quickbook-escape-prefix-->[person James Bond..39..Spy] +[person Santa Clause..87..Big Red Fatso] +<!--quickbook-escape-postfix--></programlisting> + <para> + Which will expand to: + </para> + <para> + Hi, my name is James Bond. I am 39 years old. I am a Spy. + </para> + <para> + Hi, my name is Santa Clause. I am 87 years old. I am a Big Red Fatso. + </para> + <caution> + <para> + 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. + </para> + </caution> + <para> + Each actual argument can be a word, a text fragment or just about any + <link linkend="quickbook.syntax.phrase">QuickBook phrase</link>. Arguments + are separated by the double dot <literal>".."</literal> and terminated + by the close parenthesis. + </para> + <bridgehead renderas="sect5" id="quickbook.syntax.block.templates.h4"> + <phrase id="quickbook.syntax.block.templates.nullary_templates"/><link + linkend="quickbook.syntax.block.templates.nullary_templates">Nullary Templates</link> + </bridgehead> + <para> + Nullary templates look and act like simple macros. Example: + </para> +<programlisting><!--quickbook-escape-prefix-->[template alpha[]'''&#945;'''] +[template beta[]'''&#946;'''] +<!--quickbook-escape-postfix--></programlisting> + <para> + Expanding: + </para> +<programlisting><!--quickbook-escape-prefix-->Some squigles...[*[alpha][beta]]<!--quickbook-escape-postfix--></programlisting> + <para> + We have: + </para> + <para> + Some squiggles...<emphasis role="bold">αβ</emphasis> + </para> + <para> + The difference with macros are + </para> + <itemizedlist> + <listitem> + <simpara> + The explicit <link linkend="quickbook.syntax.block.templates.template_expansion">template + expansion syntax</link>. 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. + </simpara> + </listitem> + <listitem> + <simpara> + 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. + </simpara> + </listitem> + </itemizedlist> + <para> + The empty brackets after the template identifier (<literal>alpha[]</literal>) + indicates no arguments. If the template body does not look like a template + argument list, we can elide the empty brackets. Example: + </para> +<programlisting><!--quickbook-escape-prefix-->[template aristotle_quote Aristotle: [*['Education is the best provision +for the journey to old age.]]] +<!--quickbook-escape-postfix--></programlisting> + <para> + Expanding: + </para> +<programlisting><!--quickbook-escape-prefix-->Here's a quote from [aristotle_quote]. +<!--quickbook-escape-postfix--></programlisting> + <para> + We have: + </para> + <para> + Here's a quote from Aristotle: <emphasis role="bold"><emphasis>Education + is the best provision for the journey to old age.</emphasis></emphasis>. + </para> + <para> + The disadvantage is that you can't avoid the space between the template + identifier, <code><phrase role="identifier">aristotle_quote</phrase></code>, + 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: "<code><phrase role="special">\</phrase> </code>". + Example: + </para> +<programlisting><!--quickbook-escape-prefix-->[template tag\ _tag] +<!--quickbook-escape-postfix--></programlisting> + <para> + Then expanding: + </para> +<programlisting><!--quickbook-escape-prefix-->`struct` x[tag]; +<!--quickbook-escape-postfix--></programlisting> + <para> + We have: + </para> + <para> + <code><phrase role="keyword">struct</phrase></code> x_tag; + </para> + <para> + You have a couple of ways to do it. I personally prefer the explicit empty + brackets, though. + </para> + <bridgehead renderas="sect5" id="quickbook.syntax.block.templates.h5"> + <phrase id="quickbook.syntax.block.templates.simple_arguments"/><link linkend="quickbook.syntax.block.templates.simple_arguments">Simple + Arguments</link> + </bridgehead> + <para> + As mentioned, arguments are separated by the double dot <literal>".."</literal>. + If there are less arguments passed than expected, QuickBook attempts to + break the last argument into two or more arguments following this logic: + </para> + <itemizedlist> + <listitem> + <simpara> + Break the last argument into two, at the first space found (<literal>'', + '\n', \t' or '\r'</literal>). + </simpara> + </listitem> + <listitem> + <simpara> + Repeat until there are enough arguments or if there are no more spaces + found (in which case, an error is reported). + </simpara> + </listitem> + </itemizedlist> + <para> + For example: + </para> +<programlisting><!--quickbook-escape-prefix-->[template simple[a b c d] [a][b][c][d]] +[simple w x y z] +<!--quickbook-escape-postfix--></programlisting> + <para> + will produce: + </para> + <para> + wxyz + </para> + <para> + "w x y z" is initially treated as a single argument because we + didn't supply any <literal>".."</literal> separators. However, + since <literal>simple</literal> expects 4 arguments, "w x y z" + is broken down iteratively (applying the logic above) until we have "w", + "x", "y" and "z". + </para> + <para> + QuickBook only tries to get the arguments it needs. For example: + </para> +<programlisting><!--quickbook-escape-prefix-->[simple w x y z trail] +<!--quickbook-escape-postfix--></programlisting> + <para> + will produce: + </para> + <para> + wxyz trail + </para> + <para> + The arguments being: "w", "x", "y" and "z + trail". + </para> + <para> + It should be obvious now that for simple arguments with no spaces, we can + get by without separating the arguments with <literal>".."</literal> + separators. It is possible to combine <literal>".."</literal> + separators with the argument passing simplification presented above. Example: + </para> +<programlisting><!--quickbook-escape-prefix-->[simple what do you think ..m a n?] +<!--quickbook-escape-postfix--></programlisting> + <para> + will produce: + </para> + <para> + what do you think man? + </para> + <bridgehead renderas="sect5" id="quickbook.syntax.block.templates.h6"> + <phrase id="quickbook.syntax.block.templates.punctuation_templates"/><link + linkend="quickbook.syntax.block.templates.punctuation_templates">Punctuation + Templates</link> + </bridgehead> + <para> + 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 linkend="quickbook.syntax.block.templates.template_identifier">template + identifiers</link>. Example: + </para> +<programlisting><!--quickbook-escape-prefix-->[template ![bar] <!--quickbook-escape-postfix--><hey><!--quickbook-escape-prefix-->[bar]<!--quickbook-escape-postfix--></hey><!--quickbook-escape-prefix-->] +<!--quickbook-escape-postfix--></programlisting> + <para> + Now, expanding this: + </para> +<programlisting><!--quickbook-escape-prefix-->[!baz] +<!--quickbook-escape-postfix--></programlisting> + <para> + We will have: + </para> +<programlisting><hey>baz</hey> +</programlisting> + </section> + <section id="quickbook.syntax.block.blurbs"> + <title><link linkend="quickbook.syntax.block.blurbs">Blurbs</link></title> +<programlisting><!--quickbook-escape-prefix-->[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++. +] +<!--quickbook-escape-postfix--></programlisting> + <para> + will generate this: + </para> + <sidebar role="blurb"> + <para> + <inlinemediaobject><imageobject><imagedata fileref="images/smiley.png"></imagedata></imageobject> + <textobject> + <phrase>smiley</phrase> + </textobject> + </inlinemediaobject> <emphasis role="bold">An eye catching advertisement + or note...</emphasis> + </para> + <para> + <ulink url="http://spirit.sourceforge.net">Spirit</ulink> 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++. + </para> + </sidebar> + <note> + <para> + Prefer <link linkend="quickbook.syntax.block.admonitions">admonitions</link> + wherever appropriate. + </para> + </note> + </section> + <section id="quickbook.syntax.block.tables"> + <title><link linkend="quickbook.syntax.block.tables">Tables</link></title> +<programlisting><!--quickbook-escape-prefix-->[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]] +] +<!--quickbook-escape-postfix--></programlisting> + <para> + will generate: + </para> + <table frame="all" id="quickbook.syntax.block.tables.t0"> + <title>A Simple Table</title> + <tgroup cols="3"> + <thead> + <row> + <entry> + <para> + Heading 1 + </para> + </entry> + <entry> + <para> + Heading 2 + </para> + </entry> + <entry> + <para> + Heading 3 + </para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para> + R0-C0 + </para> + </entry> + <entry> + <para> + R0-C1 + </para> + </entry> + <entry> + <para> + R0-C2 + </para> + </entry> + </row> + <row> + <entry> + <para> + R2-C0 + </para> + </entry> + <entry> + <para> + R2-C1 + </para> + </entry> + <entry> + <para> + R2-C2 + </para> + </entry> + </row> + <row> + <entry> + <para> + R3-C0 + </para> + </entry> + <entry> + <para> + R3-C1 + </para> + </entry> + <entry> + <para> + R3-C2 + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + <para> + The table title is optional. The first row of the table is automatically + treated as the table header; that is, it is wrapped in <literal><thead>...</thead></literal> + 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: + </para> +<programlisting><!--quickbook-escape-prefix-->[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] + ] +] +<!--quickbook-escape-postfix--></programlisting> + <para> + and thus: + </para> + <table frame="all" id="quickbook.syntax.block.tables.t1"> + <title>Table with fat cells</title> + <tgroup cols="2"> + <thead> + <row> + <entry> + <para> + Heading 1 + </para> + </entry> + <entry> + <para> + Heading 2 + </para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para> + Row 0, Col 0: a small cell + </para> + </entry> + <entry> + <para> + Row 0, Col 1: a big fat cell with paragraphs + </para> + <para> + Boost provides free peer-reviewed portable C++ source libraries. + </para> + <para> + 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. + </para> + </entry> + </row> + <row> + <entry> + <para> + Row 1, Col 0: a small cell + </para> + </entry> + <entry> + <para> + Row 1, Col 1: a small cell + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + <para> + Here's how to have preformatted blocks of code in a table cell: + </para> +<programlisting><!--quickbook-escape-prefix-->[table Table with code + [[Comment] [Code]] + [ + [My first program] + [<!--quickbook-escape-postfix-->`` + #include <iostream> + + int main() + { + std::cout << "Hello, World!" << std::endl; + return 0; + } + ``<!--quickbook-escape-prefix-->] + ] +] +<!--quickbook-escape-postfix--></programlisting> + <table frame="all" id="quickbook.syntax.block.tables.t2"> + <title>Table with code</title> + <tgroup cols="2"> + <thead> + <row> + <entry> + <para> + Comment + </para> + </entry> + <entry> + <para> + Code + </para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para> + My first program + </para> + </entry> + <entry> + <para> +<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">iostream</phrase><phrase role="special">></phrase> + +<phrase role="keyword">int</phrase> <phrase role="identifier">main</phrase><phrase role="special">()</phrase> +<phrase role="special">{</phrase> + <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="string">"Hello, World!"</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase> + <phrase role="keyword">return</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase> +<phrase role="special">}</phrase> +</programlisting> + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + </section> + <section id="quickbook.syntax.block.variable_lists"> + <title><link linkend="quickbook.syntax.block.variable_lists">Variable Lists</link></title> +<programlisting><!--quickbook-escape-prefix-->[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]] +] +<!--quickbook-escape-postfix--></programlisting> + <para> + will generate: + </para> + <variablelist> + <title>A Variable List</title> + <varlistentry> + <term>term 1</term> + <listitem> + <para> + The definition of term 1 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>term 2</term> + <listitem> + <para> + The definition of term 2 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>term 3</term> + <listitem> + <para> + The definition of term 3 + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + 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". + </para> + </section> + <section id="quickbook.syntax.block.include"> + <title><link linkend="quickbook.syntax.block.include">Include</link></title> + <para> + You can include one QuickBook file from another. The syntax is simply: + </para> +<programlisting><!--quickbook-escape-prefix-->[include someother.qbk] +<!--quickbook-escape-postfix--></programlisting> + <para> + The included file will be processed as if it had been cut and pasted into + the current document, with the following exceptions: + </para> + <itemizedlist> + <listitem> + <simpara> + The __FILENAME__ predefined macro will reflect the name of the file currently being + processed. + </simpara> + </listitem> + <listitem> + <simpara> + Any macros defined in the included file are scoped to that file. + </simpara> + </listitem> + </itemizedlist> + <para> + The <literal>[include]</literal> 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: + </para> +<programlisting><!--quickbook-escape-prefix-->[include:someid someother.qbk] +<!--quickbook-escape-postfix--></programlisting> + <para> + 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 <literal>[link someid.intro The Intro]</literal>. + </para> + </section> + <section id="quickbook.syntax.block.import"> + <title><link linkend="quickbook.syntax.block.import">Import</link></title> + <para> + 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. + </para> + <para> + QuickBook's import facility provides a nice solution. + </para> + <bridgehead renderas="sect5" id="quickbook.syntax.block.import.h0"> + <phrase id="quickbook.syntax.block.import.example"/><link linkend="quickbook.syntax.block.import.example">Example</link> + </bridgehead> + <para> + You can effortlessly import code snippets from source code into your QuickBook. + The following illustrates how this is done: + </para> +<programlisting><!--quickbook-escape-prefix-->[import ../test/stub.cpp] +[foo] +[bar] +<!--quickbook-escape-postfix--></programlisting> + <para> + The first line: + </para> +<programlisting><!--quickbook-escape-prefix-->[import ../test/stub.cpp] +<!--quickbook-escape-postfix--></programlisting> + <para> + collects specially marked-up code snippets from <ulink url="../../test/stub.cpp">stub.cpp</ulink> + and places them in your QuickBook file as virtual templates. Each of the + specially marked-up code snippets has a name (e.g. <code><phrase role="identifier">foo</phrase></code> + and <code><phrase role="identifier">bar</phrase></code> 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: + </para> +<programlisting><!--quickbook-escape-prefix-->[foo] +[bar] +<!--quickbook-escape-postfix--></programlisting> + <para> + And the result is: + </para> + <para> + This is the <emphasis role="bold"><emphasis>foo</emphasis></emphasis> function. + </para> + <para> + This description can have paragraphs... + </para> + <itemizedlist> + <listitem> + <simpara> + lists + </simpara> + </listitem> + <listitem> + <simpara> + etc. + </simpara> + </listitem> + </itemizedlist> + <para> + And any quickbook block markup. + </para> + <para> +<programlisting><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">foo</phrase><phrase role="special">()</phrase> +<phrase role="special">{</phrase> + <phrase role="comment">// return 'em, foo man!</phrase> + <phrase role="keyword">return</phrase> <phrase role="string">"foo"</phrase><phrase role="special">;</phrase> +<phrase role="special">}</phrase> +</programlisting> + </para> + <para> + This is the <emphasis role="bold"><emphasis>bar</emphasis></emphasis> function + </para> + <para> +<programlisting><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">bar</phrase><phrase role="special">()</phrase> +<phrase role="special">{</phrase> + <phrase role="comment">// return 'em, bar man!</phrase> + <phrase role="keyword">return</phrase> <phrase role="string">"bar"</phrase><phrase role="special">;</phrase> +<phrase role="special">}</phrase> +</programlisting> + </para> + <para> + Some trailing text here + </para> + <bridgehead renderas="sect5" id="quickbook.syntax.block.import.h1"> + <phrase id="quickbook.syntax.block.import.code_snippet_markup"/><link linkend="quickbook.syntax.block.import.code_snippet_markup">Code + Snippet Markup</link> + </bridgehead> + <para> + Note how the code snippets in <ulink url="../../test/stub.cpp">stub.cpp</ulink> + get marked up. We use distinguishable comments following the form: + </para> +<programlisting><phrase role="comment">//[id</phrase> +<phrase role="identifier">some</phrase> <phrase role="identifier">code</phrase> <phrase role="identifier">here</phrase> +<phrase role="comment">//]</phrase> +</programlisting> + <para> + The first comment line above initiates a named code-snippet. This prefix + will not be visible in quickbook. The entire code-snippet in between <code><phrase + role="comment">//[id</phrase></code> and <code><phrase role="comment">//]</phrase></code> + will be inserted as a template in quickbook with name <emphasis><emphasis>id</emphasis></emphasis>. + The comment <code><phrase role="comment">//]</phrase></code> ends a code-snippet + This too will not be visible in quickbook. + </para> + <bridgehead renderas="sect5" id="quickbook.syntax.block.import.h2"> + <phrase id="quickbook.syntax.block.import.special_comments"/><link linkend="quickbook.syntax.block.import.special_comments">Special + Comments</link> + </bridgehead> + <para> + Special comments of the form: + </para> +<programlisting><phrase role="comment">//` some [*quickbook] markup here</phrase> +</programlisting> + <para> + and: + </para> +<programlisting><phrase role="comment">/*` some [*quickbook] markup here */</phrase> +</programlisting> + <para> + will be parsed by QuickBook. This can contain quickbook <emphasis>blocks</emphasis> + (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. + </para> + <bridgehead renderas="sect5" id="quickbook.syntax.block.import.h3"> + <phrase id="quickbook.syntax.block.import.callouts"/><link linkend="quickbook.syntax.block.import.callouts">Callouts</link> + </bridgehead> + <para> + Special comments of the form: + </para> +<programlisting><phrase role="comment">/*< some [*quickbook] markup here >*/</phrase> +</programlisting> + <para> + 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 <ulink url="http://www.docbook.org/tdg/en/html/callout.html">Callouts</ulink> + for details. Example: + </para> + <para> +<programlisting><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">foo_bar</phrase><phrase role="special">()</phrase> <co id="quickbook.syntax.block.import.c0" linkends="quickbook.syntax.block.import.c1" /> +<phrase role="special">{</phrase> + <phrase role="keyword">return</phrase> <phrase role="string">"foo-bar"</phrase><phrase role="special">;</phrase> <co id="quickbook.syntax.block.import.c2" linkends="quickbook.syntax.block.import.c3" /> +<phrase role="special">}</phrase> +</programlisting> + </para> + <calloutlist> + <callout arearefs="quickbook.syntax.block.import.c0" id="quickbook.syntax.block.import.c1"> + <para> + The <emphasis>Mythical</emphasis> FooBar. See <ulink url="http://en.wikipedia.org/wiki/Foobar">Foobar + for details</ulink> + </para> + </callout> + <callout arearefs="quickbook.syntax.block.import.c2" id="quickbook.syntax.block.import.c3"> + <para> + return 'em, foo-bar man! + </para> + </callout> + </calloutlist> + <para> + Checkout <ulink url="../../test/stub.cpp">stub.cpp</ulink> to see the actual + code. + </para> + </section> + </section> + </section> + <section id="quickbook.install"> + <title><link linkend="quickbook.install">Installation and configuration</link></title> + <para> + This section provides some guidelines on how to install and configure BoostBook + and Quickbook under several operating systems. + </para> + <para> + 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 <code><phrase role="identifier">bin</phrase></code> + and <code><phrase role="identifier">bin</phrase><phrase role="special">.</phrase><phrase + role="identifier">v2</phrase></code> directories generated by the build before + trying again. Otherwise your configuration fixes will not take any effect. + </para> + <section id="quickbook.install.windows"> + <title><link linkend="quickbook.install.windows">Windows 2000, XP, 2003, Vista</link></title> + <blockquote> + <para> + <emphasis>Section contributed by Julio M. Merino Vidal</emphasis> + </para> + </blockquote> + <para> + 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. + </para> + <orderedlist> + <listitem> + <simpara> + First of all you need to have a copy of <code><phrase role="identifier">xsltproc</phrase></code> + for Windows. There are many ways to get this tool, but to keep things + simple, use the <ulink url="http://www.zlatkovic.com/pub/libxml/">binary + packages</ulink> made by Igor Zlatkovic. At the very least, you need + to download the following packages: <code><phrase role="identifier">iconv</phrase></code>, + <code><phrase role="identifier">zlib</phrase></code>, <code><phrase role="identifier">libxml2</phrase></code> + and <code><phrase role="identifier">libxslt</phrase></code>. + </simpara> + </listitem> + <listitem> + <simpara> + Unpack all these packages in the same directory so that you get unique + <code><phrase role="identifier">bin</phrase></code>, <code><phrase role="identifier">include</phrase></code> + and <code><phrase role="identifier">lib</phrase></code> directories within + the hierarchy. These instructions use <code><phrase role="identifier">C</phrase><phrase + role="special">:\</phrase><phrase role="identifier">Users</phrase><phrase + role="special">\</phrase><phrase role="identifier">example</phrase><phrase + role="special">\</phrase><phrase role="identifier">Documents</phrase><phrase + role="special">\</phrase><phrase role="identifier">boost</phrase><phrase + role="special">\</phrase><phrase role="identifier">xml</phrase></code> + as the root for all files. + </simpara> + </listitem> + <listitem> + <simpara> + From the command line, go to the <code><phrase role="identifier">bin</phrase></code> + directory and launch <code><phrase role="identifier">xsltproc</phrase><phrase + role="special">.</phrase><phrase role="identifier">exe</phrase></code> + to ensure it works. You should get usage information on screen. + </simpara> + </listitem> + <listitem> + <simpara> + Download <ulink url="http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip">Docbook + XML 4.2</ulink> and unpack it in the same directory used above. That + is: <code><phrase role="identifier">C</phrase><phrase role="special">:\</phrase><phrase + role="identifier">Users</phrase><phrase role="special">\</phrase><phrase + role="identifier">example</phrase><phrase role="special">\</phrase><phrase + role="identifier">Documents</phrase><phrase role="special">\</phrase><phrase + role="identifier">boost</phrase><phrase role="special">\</phrase><phrase + role="identifier">xml</phrase><phrase role="special">\</phrase><phrase + role="identifier">docbook</phrase><phrase role="special">-</phrase><phrase + role="identifier">xml</phrase></code>. + </simpara> + </listitem> + <listitem> + <simpara> + Download the latest <ulink url="http://sourceforge.net/project/showfiles.php?group_id=21935&package_id=16608">Docbook + XSL</ulink> version and unpack it, again in the same directory used before. + To make things easier, rename the directory created during the extraction + to <code><phrase role="identifier">docbook</phrase><phrase role="special">-</phrase><phrase + role="identifier">xsl</phrase></code> (bypassing the version name): + <code><phrase role="identifier">C</phrase><phrase role="special">:\</phrase><phrase + role="identifier">Users</phrase><phrase role="special">\</phrase><phrase + role="identifier">example</phrase><phrase role="special">\</phrase><phrase + role="identifier">Documents</phrase><phrase role="special">\</phrase><phrase + role="identifier">boost</phrase><phrase role="special">\</phrase><phrase + role="identifier">xml</phrase><phrase role="special">\</phrase><phrase + role="identifier">docbook</phrase><phrase role="special">-</phrase><phrase + role="identifier">xsl</phrase></code>. + </simpara> + </listitem> + <listitem> + <simpara> + Add the following to your <code><phrase role="identifier">user</phrase><phrase + role="special">-</phrase><phrase role="identifier">config</phrase><phrase + role="special">.</phrase><phrase role="identifier">jam</phrase></code> + file, which should live in your home directory (<code><phrase role="special">%</phrase><phrase + role="identifier">HOMEDRIVE</phrase><phrase role="special">%%</phrase><phrase + role="identifier">HOMEPATH</phrase><phrase role="special">%</phrase></code>). + You must already have it somewhere or otherwise you could not be building + Boost (i.e. missing tools configuration). + </simpara> + </listitem> + </orderedlist> +<programlisting><phrase role="identifier">using</phrase> <phrase role="identifier">xsltproc</phrase> + <phrase role="special">:</phrase> <phrase role="string">"C:/Users/example/Documents/boost/xml/bin/xsltproc.exe"</phrase> + <phrase role="special">;</phrase> + +<phrase role="identifier">using</phrase> <phrase role="identifier">boostbook</phrase> + <phrase role="special">:</phrase> <phrase role="string">"C:/Users/example/Documents/boost/xml/docbook-xsl"</phrase> + <phrase role="special">:</phrase> <phrase role="string">"C:/Users/example/Documents/boost/xml/docbook-xml"</phrase> + <phrase role="special">;</phrase> +</programlisting> + <para> + 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: + </para> + <orderedlist> + <listitem> + <simpara> + Go to Quickbook's source directory (<code><phrase role="identifier">BOOST_ROOT</phrase><phrase + role="special">\</phrase><phrase role="identifier">tools</phrase><phrase + role="special">\</phrase><phrase role="identifier">quickbook</phrase></code>). + </simpara> + </listitem> + <listitem> + <simpara> + Build the utility by issuing <code><phrase role="identifier">bjam</phrase> + <phrase role="special">--</phrase><phrase role="identifier">v2</phrase></code>. + </simpara> + </listitem> + <listitem> + <simpara> + Copy the resulting <code><phrase role="identifier">quickbook</phrase><phrase + role="special">.</phrase><phrase role="identifier">exe</phrase></code> + binary (located under the <code><phrase role="identifier">BOOST_ROOT</phrase><phrase + role="special">\</phrase><phrase role="identifier">bin</phrase><phrase + role="special">.</phrase><phrase role="identifier">v2</phrase></code> + hierarchy) to a safe place. Following our previous example, you can install + it into: <code><phrase role="identifier">C</phrase><phrase role="special">:\</phrase><phrase + role="identifier">Users</phrase><phrase role="special">\</phrase><phrase + role="identifier">example</phrase><phrase role="special">\</phrase><phrase + role="identifier">Documents</phrase><phrase role="special">\</phrase><phrase + role="identifier">boost</phrase><phrase role="special">\</phrase><phrase + role="identifier">xml</phrase><phrase role="special">\</phrase><phrase + role="identifier">bin</phrase></code>. + </simpara> + </listitem> + <listitem> + <simpara> + Add the following to your <code><phrase role="identifier">user</phrase><phrase + role="special">-</phrase><phrase role="identifier">config</phrase><phrase + role="special">.</phrase><phrase role="identifier">jam</phrase></code> + file: + </simpara> + </listitem> + </orderedlist> +<programlisting><phrase role="identifier">using</phrase> <phrase role="identifier">quickbook</phrase> + <phrase role="special">:</phrase> <phrase role="string">"C:/Users/example/Documents/boost/xml/bin/quickbook.exe"</phrase> + <phrase role="special">;</phrase> +</programlisting> + </section> + <section id="quickbook.install.linux"> + <title><link linkend="quickbook.install.linux">Debian, Ubuntu</link></title> + <para> + 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. + </para> + <para> + First install the <code><phrase role="identifier">bjam</phrase></code>, + <code><phrase role="identifier">xsltproc</phrase></code>, <code><phrase role="identifier">docbook</phrase><phrase + role="special">-</phrase><phrase role="identifier">xsl</phrase></code> and + <code><phrase role="identifier">docbook</phrase><phrase role="special">-</phrase><phrase + role="identifier">xml</phrase></code> packages. For example, using <code><phrase + role="identifier">apt</phrase><phrase role="special">-</phrase><phrase role="identifier">get</phrase></code>: + </para> +<programlisting><phrase role="identifier">sudo</phrase> <phrase role="identifier">apt</phrase><phrase role="special">-</phrase><phrase role="identifier">get</phrase> <phrase role="identifier">install</phrase> <phrase role="identifier">xsltprc</phrase> <phrase role="identifier">docbook</phrase><phrase role="special">-</phrase><phrase role="identifier">xsl</phrase> <phrase role="identifier">docbook</phrase><phrase role="special">-</phrase><phrase role="identifier">xml</phrase> +</programlisting> + <para> + If you're planning on building boost's documentation, you'll also need to + install the <code><phrase role="identifier">doxygen</phrase></code> package + as well. + </para> + <para> + Next, we need to configure Boost Build to compile BoostBook files. Add the + following to your <code><phrase role="identifier">user</phrase><phrase role="special">-</phrase><phrase + role="identifier">config</phrase><phrase role="special">.</phrase><phrase + role="identifier">jam</phrase></code> 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 <code><phrase role="identifier">user</phrase><phrase + role="special">-</phrase><phrase role="identifier">config</phrase><phrase + role="special">.</phrase><phrase role="identifier">jam</phrase></code>, see + the <ulink url="http://boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html">Boost + Build documentation</ulink>. + </para> +<programlisting><phrase role="identifier">using</phrase> <phrase role="identifier">xsltproc</phrase> <phrase role="special">;</phrase> + +<phrase role="identifier">using</phrase> <phrase role="identifier">boostbook</phrase> + <phrase role="special">:</phrase> <phrase role="special">/</phrase><phrase role="identifier">usr</phrase><phrase role="special">/</phrase><phrase role="identifier">share</phrase><phrase role="special">/</phrase><phrase role="identifier">xml</phrase><phrase role="special">/</phrase><phrase role="identifier">docbook</phrase><phrase role="special">/</phrase><phrase role="identifier">stylesheet</phrase><phrase role="special">/</phrase><phrase role="identifier">nwalsh</phrase> + <phrase role="special">:</phrase> <phrase role="special">/</phrase><phrase role="identifier">usr</phrase><phrase role="special">/</phrase><phrase role="identifier">share</phrase><phrase role="special">/</phrase><phrase role="identifier">xml</phrase><phrase role="special">/</phrase><phrase role="identifier">docbook</phrase><phrase role="special">/</phrase><phrase role="identifier">schema</phrase><phrase role="special">/</phrase><phrase role="identifier">dtd</phrase><phrase role="special">/</phrase><phrase role="number">4.2</phrase> + <phrase role="special">;</phrase> + +<phrase role="comment"># Remove this line if you're not using doxygen</phrase> +<phrase role="identifier">using</phrase> <phrase role="identifier">doxygen</phrase> <phrase role="special">;</phrase> +</programlisting> + <para> + 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: + </para> + <orderedlist> + <listitem> + <simpara> + Go to Quickbook's source directory (<code><phrase role="identifier">BOOST_ROOT</phrase><phrase + role="special">/</phrase><phrase role="identifier">tools</phrase><phrase + role="special">/</phrase><phrase role="identifier">quickbook</phrase></code>). + </simpara> + </listitem> + <listitem> + <simpara> + Build the utility by issuing <code><phrase role="identifier">bjam</phrase> + <phrase role="special">--</phrase><phrase role="identifier">v2</phrase></code>. + </simpara> + </listitem> + <listitem> + <simpara> + Copy the resulting <code><phrase role="identifier">quickbook</phrase></code> + binary (located under the <code><phrase role="identifier">BOOST_ROOT</phrase><phrase + role="special">/</phrase><phrase role="identifier">bin</phrase><phrase + role="special">.</phrase><phrase role="identifier">v2</phrase></code> + hierarchy) to a safe place. The traditional location is <code><phrase + role="special">/</phrase><phrase role="identifier">usr</phrase><phrase + role="special">/</phrase><phrase role="identifier">local</phrase><phrase + role="special">/</phrase><phrase role="identifier">bin</phrase></code>. + </simpara> + </listitem> + <listitem> + <simpara> + Add the following to your <code><phrase role="identifier">user</phrase><phrase + role="special">-</phrase><phrase role="identifier">config</phrase><phrase + role="special">.</phrase><phrase role="identifier">jam</phrase></code> + file, using the full path of the quickbook executable: + </simpara> + </listitem> + </orderedlist> +<programlisting><phrase role="identifier">using</phrase> <phrase role="identifier">quickbook</phrase> + <phrase role="special">:</phrase> <phrase role="special">/</phrase><phrase role="identifier">usr</phrase><phrase role="special">/</phrase><phrase role="identifier">local</phrase><phrase role="special">/</phrase><phrase role="identifier">bin</phrase><phrase role="special">/</phrase><phrase role="identifier">quickbook</phrase> + <phrase role="special">;</phrase> +</programlisting> + </section> + </section> + <section id="quickbook.editors"> + <title><link linkend="quickbook.editors">Editor Support</link></title> + <para> + 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. + </para> + <sidebar role="blurb"> + <para> + <inlinemediaobject><imageobject><imagedata fileref="images/note.png"></imagedata></imageobject> + <textobject> + <phrase>note</phrase> + </textobject> + </inlinemediaobject> You may submit your settings, tips, and suggestions to + the authors, or through the <ulink url="https://lists.sourceforge.net/lists/listinfo/boost-">docs + Boost Docs mailing list</ulink>. + </para> + </sidebar> + <section id="quickbook.editors.scite"> + <title><link linkend="quickbook.editors.scite">Scintilla Text Editor</link></title> + <blockquote> + <para> + <emphasis>Section contributed by Dean Michael Berris</emphasis> + </para> + </blockquote> + <para> + The Scintilla Text Editor (SciTE) is a free source code editor for Win32 + and X. It uses the SCIntilla source code editing component. + </para> + <sidebar role="blurb"> + <para> + <inlinemediaobject><imageobject><imagedata fileref="images/tip.png"></imagedata></imageobject> + <textobject> + <phrase>tip</phrase> + </textobject> + </inlinemediaobject> SciTE can be downloaded from <ulink url="http://www.scintilla.org/SciTE.html">http://www.scintilla.org/SciTE.html</ulink> + </para> + </sidebar> + <para> + You can use the following settings to highlight quickbook tags when editing + quickbook files. + </para> +<programlisting><!--quickbook-escape-prefix-->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=] +<!--quickbook-escape-postfix--></programlisting> + <sidebar role="blurb"> + <para> + <inlinemediaobject><imageobject><imagedata fileref="images/note.png"></imagedata></imageobject> + <textobject> + <phrase>note</phrase> + </textobject> + </inlinemediaobject> Thanks to Rene Rivera for the above SciTE settings. + </para> + </sidebar> + </section> + </section> + <section id="quickbook.faq"> + <title><link linkend="quickbook.faq">Frequently Asked Questions</link></title> + <bridgehead renderas="sect3" id="quickbook.faq.h0"> + <phrase id="quickbook.faq.can_i_use_quickbook_for_non_boost_documentation_"/><link + linkend="quickbook.faq.can_i_use_quickbook_for_non_boost_documentation_">Can + I use QuickBook for non-Boost documentation?</link> + </bridgehead> + <para> + QuickBook can be used for non-Boost documentation with a little extra work. + </para> + <blockquote> + <para> + <emphasis>Faq contributed by Michael Marcin</emphasis> + </para> + </blockquote> + <para> + 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. + </para> + <para> + For example: + </para> +<programlisting>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 + ; +</programlisting> + </section> + <section id="quickbook.ref"> + <title><link linkend="quickbook.ref">Quick Reference</link></title> + <para> + [cpp] + </para> + <table frame="all" id="quickbook.ref.t0"> + <title>Syntax Compendium</title> + <tgroup cols="3"> + <thead> + <row> + <entry> + <para> + To do this... + </para> + </entry> + <entry> + <para> + Use this... + </para> + </entry> + <entry> + <para> + See this... + </para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para> + comment + </para> + </entry> + <entry> + <para> + <literal>[/ some comment]</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.comments">Comments</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + <emphasis>italics</emphasis> + </para> + </entry> + <entry> + <para> + <literal>['italics] or /italics/</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.phrase.font_styles">Font Styles</link> + and <link linkend="quickbook.syntax.phrase.simple_formatting">Simple + formatting</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + <emphasis role="bold">bold</emphasis> + </para> + </entry> + <entry> + <para> + <literal>[*bold] or *bold*</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.phrase.font_styles">Font Styles</link> + and <link linkend="quickbook.syntax.phrase.simple_formatting">Simple + formatting</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + <emphasis role="underline">underline</emphasis> + </para> + </entry> + <entry> + <para> + <literal>[_underline] or _underline_</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.phrase.font_styles">Font Styles</link> + and <link linkend="quickbook.syntax.phrase.simple_formatting">Simple + formatting</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + <literal>teletype</literal> + </para> + </entry> + <entry> + <para> + <literal>[^teletype] or =teletype=</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.phrase.font_styles">Font Styles</link> + and <link linkend="quickbook.syntax.phrase.simple_formatting">Simple + formatting</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + <emphasis role="strikethrough">strikethrough</emphasis> + </para> + </entry> + <entry> + <para> + <literal>[-strikethrough]</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.phrase.font_styles">Font Styles</link> + and <link linkend="quickbook.syntax.phrase.simple_formatting">Simple + formatting</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + <replaceable>replaceable</replaceable> + </para> + </entry> + <entry> + <para> + <literal>[~replaceable]</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.phrase.replaceable">Replaceble</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + source mode + </para> + </entry> + <entry> + <para> + <literal>[c++]</literal> or <literal>[python]</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.phrase.source_mode">Source Mode</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + inline code + </para> + </entry> + <entry> + <para> + <literal>`int main();`</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.phrase.inline_code">Inline code</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + code block + </para> + </entry> + <entry> + <para> + <literal>``int main();``</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.block.code">Code</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + code escape + </para> + </entry> + <entry> + <para> + <literal>``from c++ to QuickBook``</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.block.escape_back">Escaping Back + To QuickBook</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + line break + </para> + </entry> + <entry> + <para> + <literal>[br] or \n</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.phrase.line_break">line-break</link> + <emphasis role="bold">DEPRECATED</emphasis> + </para> + </entry> + </row> + <row> + <entry> + <para> + anchor + </para> + </entry> + <entry> + <para> + <literal>[#anchor]</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.phrase.anchors">Anchors</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + link + </para> + </entry> + <entry> + <para> + <literal>[@http://www.boost.org Boost]</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.phrase.links">Links</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + anchor link + </para> + </entry> + <entry> + <para> + <literal>[link section.anchor Link text]</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.phrase.anchor_links">Anchor links</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + refentry link + </para> + </entry> + <entry> + <para> + <literal>[link xml.refentry Link text]</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.phrase.refentry_links">refentry links</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + function link + </para> + </entry> + <entry> + <para> + <literal>[funcref fully::qualified::function_name Link text]</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.phrase.code_links">function, class, + member, enum, macro, concept or header links</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + class link + </para> + </entry> + <entry> + <para> + <literal>[classref fully::qualified::class_name Link text]</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.phrase.code_links">function, class, + member, enum, macro, concept or header links</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + member link + </para> + </entry> + <entry> + <para> + <literal>[memberref fully::qualified::member_name Link text]</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.phrase.code_links">function, class, + member, enum, macro, concept or header links</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + enum link + </para> + </entry> + <entry> + <para> + <literal>[enumref fully::qualified::enum_name Link text]</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.phrase.code_links">function, class, + member, enum, macro, concept or header links</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + macro link + </para> + </entry> + <entry> + <para> + <literal>[macroref MACRO_NAME Link text]</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.phrase.code_links">function, class, + member, enum, macro, concept or header links</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + concept link + </para> + </entry> + <entry> + <para> + <literal>[conceptref ConceptName Link text]</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.phrase.code_links">function, class, + member, enum, macro, concept or header links</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + header link + </para> + </entry> + <entry> + <para> + <literal>[headerref path/to/header.hpp Link text]</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.phrase.code_links">function, class, + member, enum, macro, concept or header links</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + escape + </para> + </entry> + <entry> + <para> + <literal>'''escaped text (no processing/formatting)'''</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.phrase.escape">Escape</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + single char escape + </para> + </entry> + <entry> + <para> + <literal>\c</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.phrase.single_char_escape">Single + char escape</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + images + </para> + </entry> + <entry> + <para> + <literal>[$image.jpg]</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.phrase.images">Images</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + begin section + </para> + </entry> + <entry> + <para> + <literal>[section The Section Title]</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.block.section">Section</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + end section + </para> + </entry> + <entry> + <para> + <literal>[endsect]</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.block.section">Section</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + paragraph + </para> + </entry> + <entry> + <para> + No markup. Paragraphs start left-flushed and are terminated by two + or more newlines. + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.block.paragraphs">Paragraphs</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + ordered list + </para> + </entry> + <entry> +<programlisting><!--quickbook-escape-prefix--># one +# two +# three +<!--quickbook-escape-postfix--></programlisting> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.block.lists.ordered_lists">Ordered + lists</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + unordered list + </para> + </entry> + <entry> +<programlisting><!--quickbook-escape-prefix-->* one +* two +* three +<!--quickbook-escape-postfix--></programlisting> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.block.lists.unordered_lists">Unordered + lists</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + code + </para> + </entry> + <entry> + <para> + No markup. Preformatted code starts with a space or a tab. + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.block.code">Code</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + preformatted + </para> + </entry> + <entry> + <para> + <literal>[pre preformatted]</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.block.preformatted">Preformatted</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + block quote + </para> + </entry> + <entry> + <para> + <literal>[:sometext...]</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.block.blockquote">Blockquote</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + heading 1 + </para> + </entry> + <entry> + <para> + <literal>[h1 Heading 1]</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.block.headings">Heading</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + heading 2 + </para> + </entry> + <entry> + <para> + <literal>[h2 Heading 2]</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.block.headings">Heading</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + heading 3 + </para> + </entry> + <entry> + <para> + <literal>[h3 Heading 3]</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.block.headings">Heading</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + heading 4 + </para> + </entry> + <entry> + <para> + <literal>[h4 Heading 4]</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.block.headings">Heading</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + heading 5 + </para> + </entry> + <entry> + <para> + <literal>[h5 Heading 5]</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.block.headings">Heading</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + heading 6 + </para> + </entry> + <entry> + <para> + <literal>[h6 Heading 6]</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.block.headings">Heading</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + macro + </para> + </entry> + <entry> + <para> + <literal>[def macro_identifier some text]</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.block.macros">Macros</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + template + </para> + </entry> + <entry> + <para> + <literal>[template[a b] [a] body [b]]</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.block.templates">Templates</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + blurb + </para> + </entry> + <entry> + <para> + <literal>[blurb advertisement or note...]</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.block.blurbs">Blurbs</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + admonition + </para> + </entry> + <entry> + <para> + <literal>[warning Warning text...]</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.block.admonitions">Admonitions</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + table + </para> + </entry> + <entry> +<programlisting><!--quickbook-escape-prefix-->[table Title +[[a][b][c]] +[[a][b][c]] +] +<!--quickbook-escape-postfix--></programlisting> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.block.tables">Tables</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + variablelist + </para> + </entry> + <entry> +<programlisting><!--quickbook-escape-prefix-->[variablelist Title +[[a][b]] +[[a][b]] +] +<!--quickbook-escape-postfix--></programlisting> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.block.variable_lists">Variable Lists</link> + </para> + </entry> + </row> + <row> + <entry> + <para> + include + </para> + </entry> + <entry> + <para> + <literal>[include someother.qbk]</literal> + </para> + </entry> + <entry> + <para> + <link linkend="quickbook.syntax.block.include">Include</link> + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + </section> +</article> diff --git a/src/boost/tools/quickbook/test/quickbook_manual-1_4.gold-html b/src/boost/tools/quickbook/test/quickbook_manual-1_4.gold-html new file mode 100644 index 000000000..0eeaf54e2 --- /dev/null +++ b/src/boost/tools/quickbook/test/quickbook_manual-1_4.gold-html @@ -0,0 +1,4177 @@ +<!DOCTYPE html> +<html> + <head></head> + <body> + <h3> + Quickbook 1.4 + </h3> + <div class="authorgroup"> + <h3 class="author"> + Joel de Guzman + </h3> + <h3 class="author"> + Eric Niebler + </h3> + </div> + <p class="copyright"> + 2002, 2004, 2006 Joel de Guzman, Eric Niebler + </p> + <div class="legalnotice"> + <p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> + </div> + <div class="toc"> + <p> + <b>Table of contents</b> + </p> + <ul> + <li> + <a href="#quickbook.intro">Introduction</a> + </li> + <li> + <a href="#quickbook.change_log">Change Log</a> + </li> + <li> + <a href="#quickbook.syntax">Syntax Summary</a> + </li> + <li> + <a href="#quickbook.install">Installation and configuration</a> + </li> + <li> + <a href="#quickbook.editors">Editor Support</a> + </li> + <li> + <a href="#quickbook.faq">Frequently Asked Questions</a> + </li> + <li> + <a href="#quickbook.ref">Quick Reference</a> + </li> + </ul> + </div> + <div id="quickbook.intro"> + <h3> + Introduction + </h3> + <div id="quickbook.intro"> + <blockquote> + <p> + <span class="bold"><strong><span class="emphasis"><em><q>Why program + by hand in five days what you can spend five years of your life automating?</q></em></span></strong></span> + </p> + <p> + -- Terrence Parr, author ANTLR/PCCTS + </p> + </blockquote> + <p> + Well, QuickBook started as a weekend hack. It was originally intended to + be a sample application using <a href="http://spirit.sourceforge.net">Spirit</a>. + What is it? What you are viewing now, this documentation, is autogenerated + by QuickBook. These files were generated from one master: + </p> + <blockquote> + <p> + <a href="../quickbook.qbk">quickbook.qbk</a> + </p> + </blockquote> + <p> + 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 <a href="http://www.boost.org/doc/html/boostbook.html">BoostBook</a> + instead of HTML. The <a href="http://www.boost.org/doc/html/boostbook.html">BoostBook</a> + documentation format is an extension of <a href="http://www.docbook.org/">DocBook</a>, + an SGML or XML based format for describing documentation. + </p> + <p> + 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. + </p> + <p> + Features include: + </p> + <ul> + <li> + <div> + generate <a href="http://www.boost.org/doc/html/boostbook.html">BoostBook</a> + xml, to generate HTML, PostScript and PDF + </div> + </li> + <li> + <div> + simple markup to link to Doxygen-generated entities + </div> + </li> + <li> + <div> + macro system for simple text substitution + </div> + </li> + <li> + <div> + simple markup for italics, bold, preformatted, blurbs, code samples, + tables, URLs, anchors, images, etc. + </div> + </li> + <li> + <div> + automatic syntax coloring of code samples + </div> + </li> + <li> + <div> + CSS support + </div> + </li> + </ul> + </div> + </div> + <div id="quickbook.change_log"> + <h3> + Change Log + </h3> + <div id="quickbook.change_log"> + <h3 id="quickbook.change_log.version_1_3"> + Version 1.3 + </h3> + <ul> + <li> + <div> + Quickbook file inclusion [include]. + </div> + </li> + <li> + <div> + Better xml output (pretty layout). Check out the generated XML. + </div> + </li> + <li> + <div> + Regression testing facility: to make sure your document will always + be compatible (full backward compatibility) regardless of changes to + QuickBook. + </div> + </li> + <li> + <div> + Code cleanup and refactoring. + </div> + </li> + <li> + <div> + Allow phrase markup in the doc-info. + </div> + </li> + <li> + <div> + Preformatted code blocks via ``code`` (double ticks) allows code in + tables and lists, for example. + </div> + </li> + <li> + <div> + 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. + </div> + </li> + <li> + <div> + Better (intuitive) paragraph termination. Some markups may terminate + a paragraph. Example: +<pre class="programlisting"><span class="special">[</span><span class="identifier">section</span> <span class="identifier">x</span><span class="special">]</span> +<span class="identifier">blah</span><span class="special">...</span> +<span class="special">[</span><span class="identifier">endsect</span><span class="special">]</span></pre> + </div> + </li> + <li> + <div> + Fully qualified section and headers. Subsection names are concatenated + to the ID to avoid clashing. Example: <code><span class="identifier">doc_name</span><span + class="special">.</span><span class="identifier">sect_name</span><span + class="special">.</span><span class="identifier">sub_sect_name</span><span + class="special">.</span><span class="identifier">sub_sub_sect_name</span></code> + </div> + </li> + <li> + <div> + Better &nbsp; and whitespace handling in code snippets. + </div> + </li> + <li> + <div> + [xinclude] fixes up the relative path to the target XML file when input_directory + is not the same as the output_directory. + </div> + </li> + <li> + <div> + Allow untitled tables. + </div> + </li> + <li> + <div> + Allow phrase markups in section titles. + </div> + </li> + <li> + <div> + Allow escaping back to QuickBook from code, code blocks and inline + code. + </div> + </li> + <li> + <div> + Footnotes, with the [footnote This is the footnote] syntax. + </div> + </li> + <li> + <div> + Post-processor bug fix for escaped XML code that it does not recognize. + </div> + </li> + <li> + <div> + Replaceable, with the [~replacement] syntax. + </div> + </li> + <li> + <div> + Generic Headers + </div> + </li> + <li> + <div> + Code changes to allow full recursion (i.e. Collectors and push/pop + functions) + </div> + </li> + <li> + <div> + Various code cleanup/maintenance + </div> + </li> + <li> + <div> + Templates! + </div> + </li> + <li> + <div> + [conceptref] for referencing BoostBook <concept> entities. + </div> + </li> + <li> + <div> + Allow escape of spaces. The escaped space is removed from the output. + Syntax: <code><span class="special">\</span> </code>. + </div> + </li> + <li> + <div> + Nested comments are now allowed. + </div> + </li> + <li> + <div> + Quickbook blocks can nest inside comments. + </div> + </li> + <li> + <div> + <a href="#quickbook.syntax.block.import">Import</a> facility. + </div> + </li> + <li> + <div> + Callouts on imported code + </div> + </li> + <li> + <div> + Simple markups can now span a whole block. + </div> + </li> + <li> + <div> + <a href="#quickbook.syntax.block.blurbs">Blurbs</a>, <a href="#quickbook.syntax.block.admonitions">Admonitions</a> + and table cells (see <a href="#quickbook.syntax.block.tables">Tables</a>) + may now contain paragraphs. + </div> + </li> + <li> + <div> + <code><span class="special">\</span><span class="identifier">n</span></code> + and <code><span class="special">[</span><span class="identifier">br</span><span + class="special">]</span></code> are now deprecated. + </div> + </li> + </ul> + </div> + </div> + <div id="quickbook.syntax"> + <h3> + Syntax Summary + </h3> + <div id="quickbook.syntax"> + <p> + 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. + </p> + <p> + 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. + </p> + </div> + <div id="quickbook.syntax.comments"> + <h3> + Comments + </h3> + <div id="quickbook.syntax.comments"> + <p> + Can be placed anywhere. + </p> +<pre class="programlisting">[/ comment (no output generated) ] +</pre> +<pre class="programlisting">[/ comments can be nested [/ some more here] ] +</pre> +<pre class="programlisting">[/ Quickbook blocks can nest inside comments. [*Comment this out too!] ] +</pre> + </div> + </div> + <div id="quickbook.syntax.phrase"> + <h3> + Phrase Level Elements + </h3> + <div id="quickbook.syntax.phrase"> + </div> + <div id="quickbook.syntax.phrase.font_styles"> + <h3> + Font Styles + </h3> + <div id="quickbook.syntax.phrase.font_styles"> +<pre class="programlisting">['italic], [*bold], [_underline], [^teletype], [-strikethrough] +</pre> + <p> + will generate: + </p> + <p> + <span class="emphasis"><em>italic</em></span>, <span class="bold"><strong>bold</strong></span>, + <span class="underline">underline</span>, <tt>teletype</tt>, <span + class="strikethrough">strikethrough</span> + </p> + <p> + Like all non-terminal phrase level elements, this can of course be + nested: + </p> +<pre class="programlisting">[*['bold-italic]] +</pre> + <p> + will generate: + </p> + <p> + <span class="bold"><strong><span class="emphasis"><em>bold-italic</em></span></strong></span> + </p> + </div> + </div> + <div id="quickbook.syntax.phrase.replaceable"> + <h3> + Replaceable + </h3> + <div id="quickbook.syntax.phrase.replaceable"> + <p> + When you want content that may or must be replaced by the user, use + the syntax: + </p> +<pre class="programlisting">[~replacement] +</pre> + <p> + This will generate: + </p> + <p> + <em class="replaceable">replacement</em> + </p> + </div> + </div> + <div id="quickbook.syntax.phrase.quotations"> + <h3> + Quotations + </h3> + <div id="quickbook.syntax.phrase.quotations"> +<pre class="programlisting">["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein +</pre> + <p> + will generate: + </p> + <p> + <q>A question that sometimes drives me hazy: am I or are the others + crazy?</q>--Einstein + </p> + <p> + 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>). + </p> + <p> + Like all phrase elements, quotations may be nested. Example: + </p> +<pre class="programlisting">["Here's the rule for bargains: ["Do other men, for they would do you.] That's +the true business precept.] +</pre> + <p> + will generate: + </p> + <p> + <q>Here's the rule for bargains: <q>Do other men, for they would do + you.</q> That's the true business precept.</q> + </p> + </div> + </div> + <div id="quickbook.syntax.phrase.simple_formatting"> + <h3> + Simple formatting + </h3> + <div id="quickbook.syntax.phrase.simple_formatting"> + <p> + Simple markup for formatting text, common in many applications, is + now supported: + </p> +<pre class="programlisting">/italic/, *bold*, _underline_, =teletype= +</pre> + <p> + will generate: + </p> + <p> + <span class="emphasis"><em>italic</em></span>, <span class="bold"><strong>bold</strong></span>, + <span class="underline">underline</span>, <tt>teletype</tt> + </p> + <p> + Unlike QuickBook's standard formatting scheme, the rules for simpler + alternatives are much stricter<a id="quickbook.syntax.phrase.simple_formatting.f0" + href="#footnote-1"><sup class="footnote">[1]</sup></a>. + </p> + <ul> + <li> + <div> + Simple markups cannot nest. You can combine a simple markup with + a nestable markup. + </div> + </li> + <li> + <div> + Simple markups cannot contain any other form of quickbook markup. + </div> + </li> + <li> + <div> + A non-space character must follow the leading markup + </div> + </li> + <li> + <div> + A non-space character must precede the trailing markup + </div> + </li> + <li> + <div> + A space or a punctuation must follow the trailing markup + </div> + </li> + <li> + <div> + 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: ']'. + </div> + </li> + <li> + <div> + A line starting with the star will be interpreted as an unordered + list. See <a href="#quickbook.syntax.block.lists.unordered_lists">Unordered + lists</a>. + </div> + </li> + </ul> + <div id="quickbook.syntax.phrase.simple_formatting.t0" class="table"> + <table> + <caption>More Formatting Samples</caption> + <thead> + <tr> + <th> + <p> + Markup + </p> + </th> + <th> + <p> + Result + </p> + </th> + </tr> + </thead> + <tbody> + <tr> + <td> + <p> + <tt>*Bold*</tt> + </p> + </td> + <td> + <p> + <span class="bold"><strong>Bold</strong></span> + </p> + </td> + </tr> + <tr> + <td> + <p> + <tt>*Is bold*</tt> + </p> + </td> + <td> + <p> + <span class="bold"><strong>Is bold</strong></span> + </p> + </td> + </tr> + <tr> + <td> + <p> + <tt>* Not bold* *Not bold * * Not bold *</tt> + </p> + </td> + <td> + <p> + * Not bold* *Not bold * * Not bold * + </p> + </td> + </tr> + <tr> + <td> + <p> + <tt>This*Isn't*Bold (no bold)</tt> + </p> + </td> + <td> + <p> + This*Isn't*Bold (no bold) + </p> + </td> + </tr> + <tr> + <td> + <p> + <tt>(*Bold Inside*) (parenthesis not bold)</tt> + </p> + </td> + <td> + <p> + (<span class="bold"><strong>Bold Inside</strong></span>) + (parenthesis not bold) + </p> + </td> + </tr> + <tr> + <td> + <p> + <tt>*(Bold Outside)* (parenthesis bold)</tt> + </p> + </td> + <td> + <p> + <span class="bold"><strong>(Bold Outside)</strong></span> + (parenthesis bold) + </p> + </td> + </tr> + <tr> + <td> + <p> + <tt>3*4*5 = 60 (no bold)</tt> + </p> + </td> + <td> + <p> + 3*4*5 = 60 (no bold) + </p> + </td> + </tr> + <tr> + <td> + <p> + <tt>3 * 4 * 5 = 60 (no bold)</tt> + </p> + </td> + <td> + <p> + 3 * 4 * 5 = 60 (no bold) + </p> + </td> + </tr> + <tr> + <td> + <p> + <tt>3 *4* 5 = 60 (4 is bold)</tt> + </p> + </td> + <td> + <p> + 3 <span class="bold"><strong>4</strong></span> 5 = 60 (4 + is bold) + </p> + </td> + </tr> + <tr> + <td> + <p> + <tt>*This is bold* this is not *but this is*</tt> + </p> + </td> + <td> + <p> + <span class="bold"><strong>This is bold</strong></span> this + is not <span class="bold"><strong>but this is</strong></span> + </p> + </td> + </tr> + <tr> + <td> + <p> + <tt>*This is bold*.</tt> + </p> + </td> + <td> + <p> + <span class="bold"><strong>This is bold</strong></span>. + </p> + </td> + </tr> + <tr> + <td> + <p> + <tt>*B*. (bold B)</tt> + </p> + </td> + <td> + <p> + <span class="bold"><strong>B</strong></span>. (bold B) + </p> + </td> + </tr> + <tr> + <td> + <p> + <tt>['*Bold-Italic*]</tt> + </p> + </td> + <td> + <p> + <span class="emphasis"><em><span class="bold"><strong>Bold-Italic</strong></span></em></span> + </p> + </td> + </tr> + <tr> + <td> + <p> + <tt>*side-by*/-side/</tt> + </p> + </td> + <td> + <p> + <span class="bold"><strong>side-by</strong></span><span class="emphasis"><em>-side</em></span> + </p> + </td> + </tr> + </tbody> + </table> + </div> + <p> + 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: + </p> +<pre class="programlisting">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. +</pre> + <p> + Baa baa black sheep, <span class="bold"><strong>have you any wool? + Yes sir, yes sir, three bags full!</strong></span> One for the master, + one for the dame, And one for the little boy who lives down the lane. + </p> + <p> + But in the following paragraph, bold is not applied: + </p> +<pre class="programlisting">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. +</pre> + <p> + 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. + </p> + </div> + </div> + <div id="quickbook.syntax.phrase.inline_code"> + <h3> + Inline code + </h3> + <div id="quickbook.syntax.phrase.inline_code"> + <p> + Inlining code in paragraphs is quite common when writing C++ documentation. + We provide a very simple markup for this. For example, this: + </p> +<pre class="programlisting">This text has inlined code `int main() { return 0; }` in it. +</pre> + <p> + will generate: + </p> + <p> + This text has inlined code <code><span class="keyword">int</span> + <span class="identifier">main</span><span class="special">()</span> + <span class="special">{</span> <span class="keyword">return</span> + <span class="number">0</span><span class="special">;</span> <span class="special">}</span></code> + in it. The code will be syntax highlighted. + </p> + <div class="note"> + <p> + We simply enclose the code with the tick: <tt>"`"</tt>, not the single + quote: <code><span class="string">"'"</span></code>. Note + too that <tt>`some code`</tt> is preferred over <tt>[^some code]</tt>. + </p> + </div> + </div> + </div> + <div id="quickbook.syntax.phrase.code_blocks"> + <h3> + Code blocks + </h3> + <div id="quickbook.syntax.phrase.code_blocks"> + <p> + Preformatted code simply starts with a space or a tab (See <a href="#quickbook.syntax.block.code">Code</a>). + However, such a simple syntax cannot be used as phrase elements in + lists (See <a href="#quickbook.syntax.block.lists.ordered_lists">Ordered + lists</a> and <a href="#quickbook.syntax.block.lists.unordered_lists">Unordered + lists</a>), tables (See <a href="#quickbook.syntax.block.tables">Tables</a>), + etc. Inline code (see above) can. The problem is, inline code does + not allow formatting with newlines, spaces, and tabs. These are lost. + </p> + <p> + 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: + </p> +<pre class="programlisting">`` + #include <iostream> + + int main() + { + std::cout << "Hello, World!" << std::endl; + return 0; + } +`` +</pre> + <p> + will generate: + </p> + <p> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span> + +<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> +<span class="special">{</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Hello, World!"</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> + <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> +<span class="special">}</span> +</pre> + </p> + </div> + </div> + <div id="quickbook.syntax.phrase.source_mode"> + <h3> + Source Mode + </h3> + <div id="quickbook.syntax.phrase.source_mode"> + <p> + 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 <a href="#quickbook.syntax.block.document">Document</a> + section. + </p> + <p> + To change the source mode, use the <tt>[source-mode]</tt> markup, where + <tt>source-mode</tt> is one of the supported modes. For example, this: + </p> +<pre class="programlisting">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`. +</pre> + <p> + will generate: + </p> + <p> + Python's <code><span class="keyword">import</span></code> is rather + like C++'s <code><span class="preprocessor">#include</span></code>. + A C++ comment <code><span class="comment">// looks like this</span></code> + whereas a Python comment <code><span class="comment">#looks like this</span></code>. + </p> + <div id="quickbook.syntax.phrase.source_mode.t0" class="table"> + <table> + <caption>Supported Source Modes</caption> + <thead> + <tr> + <th> + <p> + Mode + </p> + </th> + <th> + <p> + Source Mode Markup + </p> + </th> + </tr> + </thead> + <tbody> + <tr> + <td> + <p> + C++ + </p> + </td> + <td> + <p> + <tt>[c++]</tt> + </p> + </td> + </tr> + <tr> + <td> + <p> + Python + </p> + </td> + <td> + <p> + <tt>[python]</tt> + </p> + </td> + </tr> + </tbody> + </table> + </div> + <div class="note"> + <p> + The source mode strings are lowercase. + </p> + </div> + </div> + </div> + <div id="quickbook.syntax.phrase.line_break"> + <h3> + line-break + </h3> + <div id="quickbook.syntax.phrase.line_break"> +<pre class="programlisting">[br] +</pre> + <div class="warning"> + <p> + <code><span class="special">[</span><span class="identifier">br</span><span + class="special">]</span></code> is now deprecated. <a href="#quickbook.syntax.block.blurbs">Blurbs</a>, + <a href="#quickbook.syntax.block.admonitions">Admonitions</a> and + table cells (see <a href="#quickbook.syntax.block.tables">Tables</a>) + may now contain paragraphs. + </p> + </div> + </div> + </div> + <div id="quickbook.syntax.phrase.anchors"> + <h3> + Anchors + </h3> + <div id="quickbook.syntax.phrase.anchors"> +<pre class="programlisting">[#named_anchor] +</pre> + <p> + A named anchor is a hook that can be referenced by a link elsewhere + in the document. You can then reference an anchor with <tt>[link named_anchor + Some link text]</tt>. See <a href="#quickbook.syntax.phrase.anchor_links">Anchor + links</a>, <a href="#quickbook.syntax.block.section">Section</a> and + <a href="#quickbook.syntax.block.headings">Heading</a>. + </p> + </div> + </div> + <div id="quickbook.syntax.phrase.links"> + <h3> + Links + </h3> + <div id="quickbook.syntax.phrase.links"> +<pre class="programlisting">[@http://www.boost.org this is [*boost's] website....] +</pre> + <p> + will generate: + </p> + <p> + <a href="http://www.boost.org">this is <span class="bold"><strong>boost's</strong></span> + website....</a> + </p> + <p> + URL links where the link text is the link itself is common. Example: + </p> +<pre class="programlisting">see http://spirit.sourceforge.net/ +</pre> + <p> + so, when the text is absent in a link markup, the URL is assumed. Example: + </p> +<pre class="programlisting">see [@http://spirit.sourceforge.net/] +</pre> + <p> + will generate: + </p> + <p> + see <a href="http://spirit.sourceforge.net/">http://spirit.sourceforge.net/</a> + </p> + </div> + </div> + <div id="quickbook.syntax.phrase.anchor_links"> + <h3> + Anchor links + </h3> + <div id="quickbook.syntax.phrase.anchor_links"> + <p> + You can link within a document using: + </p> +<pre class="programlisting">[link section_id.normalized_header_text The link text] +</pre> + <p> + See sections <a href="#quickbook.syntax.block.section">Section</a> + and <a href="#quickbook.syntax.block.headings">Heading</a> for more + info. + </p> + </div> + </div> + <div id="quickbook.syntax.phrase.refentry_links"> + <h3> + refentry links + </h3> + <div id="quickbook.syntax.phrase.refentry_links"> + <p> + In addition, you can link internally to an XML refentry like: + </p> +<pre class="programlisting">[link xml.refentry The link text] +</pre> + <p> + This gets converted into <tt><link linkend="xml.refentry">The + link text</link></tt>. + </p> + <p> + Like URLs, the link text is optional. If this is not present, the link + text will automatically be the refentry. Example: + </p> +<pre class="programlisting">[link xml.refentry] +</pre> + <p> + This gets converted into <tt><link linkend="xml.refentry">xml.refentry</link></tt>. + </p> + </div> + </div> + <div id="quickbook.syntax.phrase.code_links"> + <h3> + Code Links + </h3> + <div id="quickbook.syntax.phrase.code_links"> + <p> + If you want to link to a function, class, member, enum, concept or + header in the reference section, you can use: + </p> +<pre class="programlisting">[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] +</pre> + <p> + 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: + </p> +<pre class="programlisting">[classref boost::bar::baz] +</pre> + <p> + would have "boost::bar::baz" as the link text. + </p> + </div> + </div> + <div id="quickbook.syntax.phrase.escape"> + <h3> + Escape + </h3> + <div id="quickbook.syntax.phrase.escape"> + <p> + The escape mark-up is used when we don't want to do any processing. + </p> +<pre class="programlisting">''' +escape (no processing/formatting) +''' +</pre> + <p> + Escaping allows us to pass XML markup to <a href="http://www.boost.org/doc/html/boostbook.html">BoostBook</a> + or <a href="http://www.docbook.org/">DocBook</a>. For example: + </p> +<pre class="programlisting">''' +<emphasis role="bold">This is direct XML markup</emphasis> +''' +</pre> + <p> + <span class="bold"><strong>This is direct XML markup</strong></span> + </p> + <div class="important"> + <p> + Be careful when using the escape. The text must conform to <a href="http://www.boost.org/doc/html/boostbook.html">BoostBook</a>/<a + href="http://www.docbook.org/">DocBook</a> syntax. + </p> + </div> + </div> + </div> + <div id="quickbook.syntax.phrase.single_char_escape"> + <h3> + Single char escape + </h3> + <div id="quickbook.syntax.phrase.single_char_escape"> + <p> + 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 <code><span class="special">[</span></code> and <code><span + class="special">]</span></code>. For example, how do you escape the + triple quote? Simple: <tt>\'\'\'</tt> + </p> + <p> + <code><span class="special">\</span><span class="identifier">n</span></code> + has a special meaning. It is used to generate line breaks. + </p> + <div class="warning"> + <p> + <code><span class="special">\</span><span class="identifier">n</span></code> + and <code><span class="special">[</span><span class="identifier">br</span><span + class="special">]</span></code> are now deprecated. <a href="#quickbook.syntax.block.blurbs">Blurbs</a>, + <a href="#quickbook.syntax.block.admonitions">Admonitions</a> and + table cells (see <a href="#quickbook.syntax.block.tables">Tables</a>) + may now contain paragraphs. + </p> + </div> + <p> + The escaped space: <code><span class="special">\</span> </code> also + has a special meaning. The escaped space is removed from the output. + </p> + </div> + </div> + <div id="quickbook.syntax.phrase.images"> + <h3> + Images + </h3> + <div id="quickbook.syntax.phrase.images"> +<pre class="programlisting">[$image.jpg] +</pre> + </div> + </div> + <div id="quickbook.syntax.phrase.footnotes"> + <h3> + Footnotes + </h3> + <div id="quickbook.syntax.phrase.footnotes"> + <p> + As of version 1.3, QuickBook supports footnotes. Just put the text + of the footnote in a <code><span class="special">[</span><span class="identifier">footnote</span><span + class="special">]</span></code> block, and the text will be put at + the bottom of the current page. For example, this: + </p> +<pre class="programlisting">[footnote A sample footnote] +</pre> + <p> + will generate this<a id="quickbook.syntax.phrase.footnotes.f0" href="#footnote-2"><sup + class="footnote">[2]</sup></a>. + </p> + </div> + <div id="quickbook.syntax.phrase.footnotes.macro_expansion"> + <h3> + Macro Expansion + </h3> + <div id="quickbook.syntax.phrase.footnotes.macro_expansion"> +<pre class="programlisting">__a_macro_identifier__ +</pre> + <p> + See <a href="#quickbook.syntax.block.macros">Macros</a> for details. + </p> + </div> + </div> + <div id="quickbook.syntax.phrase.footnotes.template_expansion"> + <h3> + Template Expansion + </h3> + <div id="quickbook.syntax.phrase.footnotes.template_expansion"> +<pre class="programlisting">[a_template_identifier] +</pre> + <p> + See <a href="#quickbook.syntax.block.templates">Templates</a> for + details. + </p> + </div> + </div> + </div> + </div> + <div id="quickbook.syntax.block"> + <h3> + Block Level Elements + </h3> + <div id="quickbook.syntax.block"> + </div> + <div id="quickbook.syntax.block.document"> + <h3> + Document + </h3> + <div id="quickbook.syntax.block.document"> + <p> + Every document must begin with a Document Info section, which should + look like this: + </p> +<pre class="programlisting">[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] +] +</pre> + <p> + Where document-type is one of: + </p> + <ul> + <li> + <div> + book + </div> + </li> + <li> + <div> + article + </div> + </li> + <li> + <div> + library + </div> + </li> + <li> + <div> + chapter + </div> + </li> + <li> + <div> + part + </div> + </li> + <li> + <div> + appendix + </div> + </li> + <li> + <div> + preface + </div> + </li> + <li> + <div> + qandadiv + </div> + </li> + <li> + <div> + qandaset + </div> + </li> + <li> + <div> + reference + </div> + </li> + <li> + <div> + set + </div> + </li> + </ul> + <p> + quickbook 1.3 declares the version of quickbook the document is written + for. In its absence, version 1.1 is assumed. + </p> + <p> + <tt>version</tt>, <tt>id</tt>, <tt>dirname</tt>, <tt>copyright</tt>, + <tt>purpose</tt>, <tt>category</tt>, <tt>authors</tt>, <tt>license</tt>, + <tt>last-revision</tt> and <tt>source-mode</tt> are optional information. + </p> + <p> + <tt>source-type</tt> is a lowercase string setting the initial <a href="#quickbook.syntax.phrase.source_mode">Source + Mode</a>. If the <tt>source-mode</tt> field is omitted, a default value + of <tt>c++</tt> will be used. + </p> + </div> + </div> + <div id="quickbook.syntax.block.section"> + <h3> + Section + </h3> + <div id="quickbook.syntax.block.section"> + <p> + Starting a new section is accomplished with: + </p> +<pre class="programlisting">[section:id The Section Title] +</pre> + <p> + where <span class="emphasis"><em>id</em></span> 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 <tt>a-Z</tt>, <tt>A-Z</tt>, <tt>0-9</tt> and <tt>_</tt>. 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". + </p> + <p> + End a section with: + </p> +<pre class="programlisting">[endsect] +</pre> + <p> + Sections can nest, and that results in a hierarchy in the table of + contents. + </p> + </div> + </div> + <div id="quickbook.syntax.block.xinclude"> + <h3> + xinclude + </h3> + <div id="quickbook.syntax.block.xinclude"> + <p> + You can include another XML file with: + </p> +<pre class="programlisting">[xinclude file.xml] +</pre> + <p> + This is useful when file.xml has been generated by Doxygen and contains + your reference section. + </p> + </div> + </div> + <div id="quickbook.syntax.block.paragraphs"> + <h3> + Paragraphs + </h3> + <div id="quickbook.syntax.block.paragraphs"> + <p> + 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. + </p> + </div> + </div> + <div id="quickbook.syntax.block.lists"> + <h3> + Lists + </h3> + <div id="quickbook.syntax.block.lists"> + </div> + <div id="quickbook.syntax.block.lists.ordered_lists"> + <h3> + Ordered lists + </h3> + <div id="quickbook.syntax.block.lists.ordered_lists"> +<pre class="programlisting"># One +# Two +# Three +</pre> + <p> + will generate: + </p> + <ol> + <li> + <div> + One + </div> + </li> + <li> + <div> + Two + </div> + </li> + <li> + <div> + Three + </div> + </li> + </ol> + </div> + </div> + <div id="quickbook.syntax.block.lists.list_hierarchies"> + <h3> + List Hierarchies + </h3> + <div id="quickbook.syntax.block.lists.list_hierarchies"> + <p> + List hierarchies are supported. Example: + </p> +<pre class="programlisting"># One +# Two +# Three + # Three.a + # Three.b + # Three.c +# Four + # Four.a + # Four.a.i + # Four.a.ii +# Five +</pre> + <p> + will generate: + </p> + <ol> + <li> + <div> + One + </div> + </li> + <li> + <div> + Two + </div> + </li> + <li> + <div> + Three + <ol> + <li> + <div> + Three.a + </div> + </li> + <li> + <div> + Three.b + </div> + </li> + <li> + <div> + Three.c + </div> + </li> + </ol> + </div> + </li> + <li> + <div> + Fourth + <ol> + <li> + <div> + Four.a + <ol> + <li> + <div> + Four.a.i + </div> + </li> + <li> + <div> + Four.a.ii + </div> + </li> + </ol> + </div> + </li> + </ol> + </div> + </li> + <li> + <div> + Five + </div> + </li> + </ol> + </div> + </div> + <div id="quickbook.syntax.block.lists.long_list_lines"> + <h3> + Long List Lines + </h3> + <div id="quickbook.syntax.block.lists.long_list_lines"> + <p> + Long lines will be wrapped appropriately. Example: + </p> +<pre class="programlisting"># 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. +</pre> + <ol> + <li> + <div> + A short item. + </div> + </li> + <li> + <div> + 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. + </div> + </li> + <li> + <div> + A short item. + </div> + </li> + </ol> + </div> + </div> + <div id="quickbook.syntax.block.lists.unordered_lists"> + <h3> + Unordered lists + </h3> + <div id="quickbook.syntax.block.lists.unordered_lists"> +<pre class="programlisting">* First +* Second +* Third +</pre> + <p> + will generate: + </p> + <ul> + <li> + <div> + First + </div> + </li> + <li> + <div> + Second + </div> + </li> + <li> + <div> + Third + </div> + </li> + </ul> + </div> + </div> + <div id="quickbook.syntax.block.lists.mixed_lists"> + <h3> + Mixed lists + </h3> + <div id="quickbook.syntax.block.lists.mixed_lists"> + <p> + Mixed lists (ordered and unordered) are supported. Example: + </p> +<pre class="programlisting"># One +# Two +# Three + * Three.a + * Three.b + * Three.c +# Four +</pre> + <p> + will generate: + </p> + <ol> + <li> + <div> + One + </div> + </li> + <li> + <div> + Two + </div> + </li> + <li> + <div> + Three + <ul> + <li> + <div> + Three.a + </div> + </li> + <li> + <div> + Three.b + </div> + </li> + <li> + <div> + Three.c + </div> + </li> + </ul> + </div> + </li> + <li> + <div> + Four + </div> + </li> + </ol> + <p> + And... + </p> +<pre class="programlisting"># 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 +</pre> + <p> + will generate: + </p> + <ol> + <li> + <div> + 1 + <ul> + <li> + <div> + 1.a + <ol> + <li> + <div> + 1.a.1 + </div> + </li> + <li> + <div> + 1.a.2 + </div> + </li> + </ol> + </div> + </li> + <li> + <div> + 1.b + </div> + </li> + </ul> + </div> + </li> + <li> + <div> + 2 + <ul> + <li> + <div> + 2.a + </div> + </li> + <li> + <div> + 2.b + <ol> + <li> + <div> + 2.b.1 + </div> + </li> + <li> + <div> + 2.b.2 + <ul> + <li> + <div> + 2.b.2.a + </div> + </li> + <li> + <div> + 2.b.2.b + </div> + </li> + </ul> + </div> + </li> + </ol> + </div> + </li> + </ul> + </div> + </li> + </ol> + </div> + </div> + </div> + <div id="quickbook.syntax.block.code"> + <h3> + Code + </h3> + <div id="quickbook.syntax.block.code"> + <p> + Preformatted code starts with a space or a tab. The code will be syntax + highlighted according to the current <a href="#quickbook.syntax.phrase.source_mode">Source + Mode</a>: + </p> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span> + +<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> +<span class="special">{</span> + <span class="comment">// Sample code</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Hello, World\n"</span><span class="special">;</span> + <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> +<span class="special">}</span> +</pre> +<pre class="programlisting"><span class="keyword">import</span> <span class="identifier">cgi</span> + +<span class="keyword">def</span> <span class="identifier">cookForHtml</span><span class="special">(</span><span class="identifier">text</span><span class="special">):</span> + <span class="string">'''"Cooks" the input text for HTML.'''</span> + + <span class="keyword">return</span> <span class="identifier">cgi</span><span class="special">.</span><span class="identifier">escape</span><span class="special">(</span><span class="identifier">text</span><span class="special">)</span> +</pre> + <p> + Macros that are already defined are expanded in source code. Example: + </p> +<pre class="programlisting">[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__; +</pre> + <p> + Generates: + </p> +<pre class="programlisting"><span class="keyword">using</span> <a href="http://www.boost.org/libs/libraries.htm">boost</a><span class="special">::</span><a href="http://www.boost.org/doc/html/array/reference.html">array</a><span class="special">;</span> +</pre> + </div> + </div> + <div id="quickbook.syntax.block.escape_back"> + <h3> + Escaping Back To QuickBook + </h3> + <div id="quickbook.syntax.block.escape_back"> + <p> + 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 <span class="emphasis"><em>escape-back</em></span> + delimiter. In C++ and Python, the delimiter is the double tick (back-quote): + "``" and "``". Example: + </p> +<pre class="programlisting">void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``() +{ +} +</pre> + <p> + Will generate: + </p> +<pre class="programlisting"><span class="keyword">void</span> <a href="http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz">foo</a><span class="special">()</span> +<span class="special">{</span> +<span class="special">}</span> +</pre> + <p> + When escaping from code to QuickBook, only phrase level markups are + allowed. Block level markups like lists, tables etc. are not allowed. + </p> + </div> + </div> + <div id="quickbook.syntax.block.preformatted"> + <h3> + Preformatted + </h3> + <div id="quickbook.syntax.block.preformatted"> + <p> + Sometimes, you don't want some preformatted text to be parsed as C++. + In such cases, use the <tt>[pre ... ]</tt> markup block. + </p> +<pre class="programlisting">[pre + + Some *preformatted* text Some *preformatted* text + + Some *preformatted* text Some *preformatted* text + + Some *preformatted* text Some *preformatted* text + +] +</pre> + <p> + 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: + </p> +<pre class="programlisting">Some <span class="bold"><strong>preformatted</strong></span> text Some <span class="bold"><strong>preformatted</strong></span> text + + Some <span class="bold"><strong>preformatted</strong></span> text Some <span class="bold"><strong>preformatted</strong></span> text + + Some <span class="bold"><strong>preformatted</strong></span> text Some <span class="bold"><strong>preformatted</strong></span> text + +</pre> + <p> + Notice that unlike Code, phrase markup such as font style is still + permitted inside <tt>pre</tt> blocks. + </p> + </div> + </div> + <div id="quickbook.syntax.block.blockquote"> + <h3> + Blockquote + </h3> + <div id="quickbook.syntax.block.blockquote"> +<pre class="programlisting">[:sometext...] +</pre> + <blockquote> + <p> + Indents the paragraph. This applies to one paragraph only. + </p> + </blockquote> + </div> + </div> + <div id="quickbook.syntax.block.admonitions"> + <h3> + Admonitions + </h3> + <div id="quickbook.syntax.block.admonitions"> +<pre class="programlisting">[note This is a note] +[tip This is a tip] +[important This is important] +[caution This is a caution] +[warning This is a warning] +</pre> + <p> + generates <a href="http://www.docbook.org/">DocBook</a> admonitions: + </p> + <div class="note"> + <p> + This is a note + </p> + </div> + <div class="tip"> + <p> + This is a tip + </p> + </div> + <div class="important"> + <p> + This is important + </p> + </div> + <div class="caution"> + <p> + This is a caution + </p> + </div> + <div class="warning"> + <p> + This is a warning + </p> + </div> + <p> + These are the only admonitions supported by <a href="http://www.docbook.org/">DocBook</a>. + So, for example <tt>[information This is some information]</tt> is + unlikely to produce the desired effect. + </p> + </div> + </div> + <div id="quickbook.syntax.block.headings"> + <h3> + Headings + </h3> + <div id="quickbook.syntax.block.headings"> +<pre class="programlisting">[h1 Heading 1] +[h2 Heading 2] +[h3 Heading 3] +[h4 Heading 4] +[h5 Heading 5] +[h6 Heading 6] +</pre> + <h1 id="quickbook.syntax.block.headings.heading_1"> + Heading 1 + </h1> + <h2 id="quickbook.syntax.block.headings.heading_2"> + Heading 2 + </h2> + <h3 id="quickbook.syntax.block.headings.heading_3"> + Heading 3 + </h3> + <h4 id="quickbook.syntax.block.headings.heading_4"> + Heading 4 + </h4> + <h5 id="quickbook.syntax.block.headings.heading_5"> + Heading 5 + </h5> + <h6 id="quickbook.syntax.block.headings.heading_6"> + Heading 6 + </h6> + <p> + Headings 1-3 [h1 h2 and h3] will automatically have anchors with normalized + names with <tt>name="section_id.normalized_header_text"</tt> + (i.e. valid characters are <tt>a-z</tt>, <tt>A-Z</tt>, <tt>0-9</tt> + and <tt>_</tt>. 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 <tt>section_2.heading_1</tt>). + You can use: + </p> +<pre class="programlisting">[link section_id.normalized_header_text The link text] +</pre> + <p> + to link to them. See <a href="#quickbook.syntax.phrase.anchor_links">Anchor + links</a> and <a href="#quickbook.syntax.block.section">Section</a> + for more info. + </p> + </div> + </div> + <div id="quickbook.syntax.block.generic_heading"> + <h3> + Generic Heading + </h3> + <div id="quickbook.syntax.block.generic_heading"> + <p> + In cases when you don't want to care about the heading level (1 to + 6), you can use the <span class="emphasis"><em>Generic Heading</em></span>: + </p> +<pre class="programlisting">[heading Heading] +</pre> + <p> + The <span class="emphasis"><em>Generic Heading</em></span> 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 + <span class="emphasis"><em>h2</em></span>. + </p> + <p> + 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: + </p> +<pre class="programlisting">[section A] +[h2 X] +[h2 Y] +[h2 Z] +[endsect] +</pre> + <p> + 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: + </p> +<pre class="programlisting">[section A] +[heading X] +[heading Y] +[heading Z] +[endsect] +</pre> + <p> + 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 <span class="emphasis"><em>section</em></span> and <span + class="emphasis"><em>heading</em></span>, you have all you need. <span + class="emphasis"><em>h1</em></span>..<span class="emphasis"><em>h6</em></span> + becomes redundant. <span class="emphasis"><em>h1</em></span>..<span + class="emphasis"><em>h6</em></span> might be deprecated in the future. + </p> + </div> + </div> + <div id="quickbook.syntax.block.macros"> + <h3> + Macros + </h3> + <div id="quickbook.syntax.block.macros"> +<pre class="programlisting">[def macro_identifier some text] +</pre> + <p> + 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: + </p> +<pre class="programlisting">[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&type=1]] +sf_logo +</pre> + <p> + Now everywhere the sf_logo is placed, the picture will be inlined. + </p> + <p> + <span class="inlinemediaobject"><img src="http://sourceforge.net/sflogo.php?group_id=28447&type=1" + alt="[]"/></span> + </p> + <div class="tip"> + <p> + 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. <tt>__spirit__</tt>). The reason is + to avoid unwanted macro replacement. + </p> + </div> + <p> + Links (URLS) and images are good candidates for macros. <span class="bold"><strong>1</strong></span>) + 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. + <span class="bold"><strong>2</strong></span>) The syntax is not pretty. + It's easier to read and write, e.g. <tt>__spirit__</tt> than <tt>[@http://spirit.sourceforge.net + Spirit]</tt>. + </p> + <p> + Some more examples: + </p> +<pre class="programlisting">[def :-) [$theme/smiley.png]] +[def __spirit__ [@http://spirit.sourceforge.net Spirit]] +</pre> + <p> + (See <a href="#quickbook.syntax.phrase.images">Images</a> and <a href="#quickbook.syntax.phrase.links">Links</a>) + </p> + <p> + Invoking these macros: + </p> +<pre class="programlisting">Hi __spirit__ :-) +</pre> + <p> + will generate this: + </p> + <p> + Hi <a href="http://spirit.sourceforge.net">Spirit</a> <span class="inlinemediaobject"><img + src="images/smiley.png" alt="[]"/></span> + </p> + </div> + </div> + <div id="quickbook.syntax.block.predefined_macros"> + <h3> + Predefined Macros + </h3> + <div id="quickbook.syntax.block.predefined_macros"> + <p> + Quickbook has some predefined macros that you can already use. + </p> + <div id="quickbook.syntax.block.predefined_macros.t0" class="table"> + <table> + <caption>Predefined Macros</caption> + <thead> + <tr> + <th> + <p> + Macro + </p> + </th> + <th> + <p> + Meaning + </p> + </th> + <th> + <p> + Example + </p> + </th> + </tr> + </thead> + <tbody> + <tr> + <td> + <p> + __DATE__ + </p> + </td> + <td> + <p> + Today's date + </p> + </td> + <td> + <p> + 2000-Dec-20 + </p> + </td> + </tr> + <tr> + <td> + <p> + __TIME__ + </p> + </td> + <td> + <p> + The current time + </p> + </td> + <td> + <p> + 12:00:00 PM + </p> + </td> + </tr> + <tr> + <td> + <p> + __FILENAME__ + </p> + </td> + <td> + <p> + Quickbook source filename + </p> + </td> + <td> + <p> + quickbook_manual-1_4.quickbook + </p> + </td> + </tr> + </tbody> + </table> + </div> + </div> + </div> + <div id="quickbook.syntax.block.templates"> + <h3> + Templates + </h3> + <div id="quickbook.syntax.block.templates"> + <p> + 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). + </p> + <p> + Example template: + </p> +<pre class="programlisting">[template person[name age what] + +Hi, my name is [name]. I am [age] years old. I am a [what]. + +] +</pre> + <h5 id="quickbook.syntax.block.templates.template_identifier"> + Template Identifier + </h5> + <p> + Template identifiers can either consist of: + </p> + <ul> + <li> + <div> + 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. + </div> + </li> + <li> + <div> + A single character punctuation (a non-alphanumeric printable character) + </div> + </li> + </ul> + <h5 id="quickbook.syntax.block.templates.formal_template_arguments"> + Formal Template Arguments + </h5> + <p> + 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. + </p> + <p> + A template formal argument temporarily hides a template of the same + name at the point where the <a href="#quickbook.syntax.block.templates.template_expansion">template + is expanded</a>. Note that the body of the <tt>person</tt> template + above refers to <tt>name</tt> <tt>age</tt> and <tt>what</tt> as <tt>[name]</tt> + <tt>[age]</tt> and <tt>[what]</tt>. <tt>name</tt> <tt>age</tt> and + <tt>what</tt> are actually templates that exist in the duration of + the template call. + </p> + <h5 id="quickbook.syntax.block.templates.template_body"> + Template Body + </h5> + <p> + 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: + </p> +<pre class="programlisting">[template sample[arg1 arg2...argN] replacement text... ] +</pre> + <p> + Block templates are of the form: + </p> +<pre class="programlisting">[template sample[arg1 arg2...argN] +replacement text... +] +</pre> + <p> + 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. + </p> + <h5 id="quickbook.syntax.block.templates.template_expansion"> + Template Expansion + </h5> + <p> + You expand a template this way: + </p> +<pre class="programlisting">[template_identifier arg1..arg2..arg3] +</pre> + <p> + At template expansion, you supply the actual arguments. The template + will be expanded with your supplied arguments. Example: + </p> +<pre class="programlisting">[person James Bond..39..Spy] +[person Santa Clause..87..Big Red Fatso] +</pre> + <p> + Which will expand to: + </p> + <p> + Hi, my name is James Bond. I am 39 years old. I am a Spy. + </p> + <p> + Hi, my name is Santa Clause. I am 87 years old. I am a Big Red Fatso. + </p> + <div class="caution"> + <p> + 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. + </p> + </div> + <p> + Each actual argument can be a word, a text fragment or just about any + <a href="#quickbook.syntax.phrase">QuickBook phrase</a>. Arguments + are separated by the double dot <tt>".."</tt> and terminated + by the close parenthesis. + </p> + <h5 id="quickbook.syntax.block.templates.nullary_templates"> + Nullary Templates + </h5> + <p> + Nullary templates look and act like simple macros. Example: + </p> +<pre class="programlisting">[template alpha[]'''&#945;'''] +[template beta[]'''&#946;'''] +</pre> + <p> + Expanding: + </p> +<pre class="programlisting">Some squigles...[*[alpha][beta]]</pre> + <p> + We have: + </p> + <p> + Some squiggles...<span class="bold"><strong>αβ</strong></span> + </p> + <p> + The difference with macros are + </p> + <ul> + <li> + <div> + The explicit <a href="#quickbook.syntax.block.templates.template_expansion">template + expansion syntax</a>. 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. + </div> + </li> + <li> + <div> + 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. + </div> + </li> + </ul> + <p> + The empty brackets after the template identifier (<tt>alpha[]</tt>) + indicates no arguments. If the template body does not look like a template + argument list, we can elide the empty brackets. Example: + </p> +<pre class="programlisting">[template aristotle_quote Aristotle: [*['Education is the best provision +for the journey to old age.]]] +</pre> + <p> + Expanding: + </p> +<pre class="programlisting">Here's a quote from [aristotle_quote]. +</pre> + <p> + We have: + </p> + <p> + Here's a quote from Aristotle: <span class="bold"><strong><span class="emphasis"><em>Education + is the best provision for the journey to old age.</em></span></strong></span>. + </p> + <p> + The disadvantage is that you can't avoid the space between the template + identifier, <code><span class="identifier">aristotle_quote</span></code>, + 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: "<code><span class="special">\</span> + </code>". Example: + </p> +<pre class="programlisting">[template tag\ _tag] +</pre> + <p> + Then expanding: + </p> +<pre class="programlisting">`struct` x[tag]; +</pre> + <p> + We have: + </p> + <p> + <code><span class="keyword">struct</span></code> x_tag; + </p> + <p> + You have a couple of ways to do it. I personally prefer the explicit + empty brackets, though. + </p> + <h5 id="quickbook.syntax.block.templates.simple_arguments"> + Simple Arguments + </h5> + <p> + As mentioned, arguments are separated by the double dot <tt>".."</tt>. + If there are less arguments passed than expected, QuickBook attempts + to break the last argument into two or more arguments following this + logic: + </p> + <ul> + <li> + <div> + Break the last argument into two, at the first space found (<tt>'', + '\n', \t' or '\r'</tt>). + </div> + </li> + <li> + <div> + Repeat until there are enough arguments or if there are no more + spaces found (in which case, an error is reported). + </div> + </li> + </ul> + <p> + For example: + </p> +<pre class="programlisting">[template simple[a b c d] [a][b][c][d]] +[simple w x y z] +</pre> + <p> + will produce: + </p> + <p> + wxyz + </p> + <p> + "w x y z" is initially treated as a single argument because + we didn't supply any <tt>".."</tt> separators. However, since + <tt>simple</tt> expects 4 arguments, "w x y z" is broken + down iteratively (applying the logic above) until we have "w", + "x", "y" and "z". + </p> + <p> + QuickBook only tries to get the arguments it needs. For example: + </p> +<pre class="programlisting">[simple w x y z trail] +</pre> + <p> + will produce: + </p> + <p> + wxyz trail + </p> + <p> + The arguments being: "w", "x", "y" and + "z trail". + </p> + <p> + It should be obvious now that for simple arguments with no spaces, + we can get by without separating the arguments with <tt>".."</tt> + separators. It is possible to combine <tt>".."</tt> separators + with the argument passing simplification presented above. Example: + </p> +<pre class="programlisting">[simple what do you think ..m a n?] +</pre> + <p> + will produce: + </p> + <p> + what do you think man? + </p> + <h5 id="quickbook.syntax.block.templates.punctuation_templates"> + Punctuation Templates + </h5> + <p> + 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 <a href="#quickbook.syntax.block.templates.template_identifier">template + identifiers</a>. Example: + </p> +<pre class="programlisting">[template ![bar] <hey>[bar]</hey>] +</pre> + <p> + Now, expanding this: + </p> +<pre class="programlisting">[!baz] +</pre> + <p> + We will have: + </p> +<pre class="programlisting"><hey>baz</hey> +</pre> + </div> + </div> + <div id="quickbook.syntax.block.blurbs"> + <h3> + Blurbs + </h3> + <div id="quickbook.syntax.block.blurbs"> +<pre class="programlisting">[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++. +] +</pre> + <p> + will generate this: + </p> + <div class="blurb"> + <p> + <span class="inlinemediaobject"><img src="images/smiley.png" alt="[]"/></span> + <span class="bold"><strong>An eye catching advertisement or note...</strong></span> + </p> + <p> + <a href="http://spirit.sourceforge.net">Spirit</a> 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++. + </p> + </div> + <div class="note"> + <p> + Prefer <a href="#quickbook.syntax.block.admonitions">admonitions</a> + wherever appropriate. + </p> + </div> + </div> + </div> + <div id="quickbook.syntax.block.tables"> + <h3> + Tables + </h3> + <div id="quickbook.syntax.block.tables"> +<pre class="programlisting">[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]] +] +</pre> + <p> + will generate: + </p> + <div id="quickbook.syntax.block.tables.t0" class="table"> + <table> + <caption>A Simple Table</caption> + <thead> + <tr> + <th> + <p> + Heading 1 + </p> + </th> + <th> + <p> + Heading 2 + </p> + </th> + <th> + <p> + Heading 3 + </p> + </th> + </tr> + </thead> + <tbody> + <tr> + <td> + <p> + R0-C0 + </p> + </td> + <td> + <p> + R0-C1 + </p> + </td> + <td> + <p> + R0-C2 + </p> + </td> + </tr> + <tr> + <td> + <p> + R2-C0 + </p> + </td> + <td> + <p> + R2-C1 + </p> + </td> + <td> + <p> + R2-C2 + </p> + </td> + </tr> + <tr> + <td> + <p> + R3-C0 + </p> + </td> + <td> + <p> + R3-C1 + </p> + </td> + <td> + <p> + R3-C2 + </p> + </td> + </tr> + </tbody> + </table> + </div> + <p> + The table title is optional. The first row of the table is automatically + treated as the table header; that is, it is wrapped in <tt><thead>...</thead></tt> + 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: + </p> +<pre class="programlisting">[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] + ] +] +</pre> + <p> + and thus: + </p> + <div id="quickbook.syntax.block.tables.t1" class="table"> + <table> + <caption>Table with fat cells</caption> + <thead> + <tr> + <th> + <p> + Heading 1 + </p> + </th> + <th> + <p> + Heading 2 + </p> + </th> + </tr> + </thead> + <tbody> + <tr> + <td> + <p> + Row 0, Col 0: a small cell + </p> + </td> + <td> + <p> + Row 0, Col 1: a big fat cell with paragraphs + </p> + <p> + Boost provides free peer-reviewed portable C++ source libraries. + </p> + <p> + 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. + </p> + </td> + </tr> + <tr> + <td> + <p> + Row 1, Col 0: a small cell + </p> + </td> + <td> + <p> + Row 1, Col 1: a small cell + </p> + </td> + </tr> + </tbody> + </table> + </div> + <p> + Here's how to have preformatted blocks of code in a table cell: + </p> +<pre class="programlisting">[table Table with code + [[Comment] [Code]] + [ + [My first program] + [`` + #include <iostream> + + int main() + { + std::cout << "Hello, World!" << std::endl; + return 0; + } + ``] + ] +] +</pre> + <div id="quickbook.syntax.block.tables.t2" class="table"> + <table> + <caption>Table with code</caption> + <thead> + <tr> + <th> + <p> + Comment + </p> + </th> + <th> + <p> + Code + </p> + </th> + </tr> + </thead> + <tbody> + <tr> + <td> + <p> + My first program + </p> + </td> + <td> + <p> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span> + +<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> +<span class="special">{</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Hello, World!"</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> + <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> +<span class="special">}</span> +</pre> + </p> + </td> + </tr> + </tbody> + </table> + </div> + </div> + </div> + <div id="quickbook.syntax.block.variable_lists"> + <h3> + Variable Lists + </h3> + <div id="quickbook.syntax.block.variable_lists"> +<pre class="programlisting">[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]] +] +</pre> + <p> + will generate: + </p> + <dl> + <dt> + term 1 + </dt> + <dd> + <p> + The definition of term 1 + </p> + </dd> + <dt> + term 2 + </dt> + <dd> + <p> + The definition of term 2 + </p> + </dd> + <dt> + term 3 + </dt> + <dd> + <p> + The definition of term 3 + </p> + </dd> + </dl> + <p> + 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". + </p> + </div> + </div> + <div id="quickbook.syntax.block.include"> + <h3> + Include + </h3> + <div id="quickbook.syntax.block.include"> + <p> + You can include one QuickBook file from another. The syntax is simply: + </p> +<pre class="programlisting">[include someother.qbk] +</pre> + <p> + The included file will be processed as if it had been cut and pasted + into the current document, with the following exceptions: + </p> + <ul> + <li> + <div> + The __FILENAME__ predefined macro will reflect the name of the + file currently being processed. + </div> + </li> + <li> + <div> + Any macros defined in the included file are scoped to that file. + </div> + </li> + </ul> + <p> + The <tt>[include]</tt> 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: + </p> +<pre class="programlisting">[include:someid someother.qbk] +</pre> + <p> + 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 <tt>[link someid.intro The Intro]</tt>. + </p> + </div> + </div> + <div id="quickbook.syntax.block.import"> + <h3> + Import + </h3> + <div id="quickbook.syntax.block.import"> + <p> + 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. + </p> + <p> + QuickBook's import facility provides a nice solution. + </p> + <h5 id="quickbook.syntax.block.import.example"> + Example + </h5> + <p> + You can effortlessly import code snippets from source code into your + QuickBook. The following illustrates how this is done: + </p> +<pre class="programlisting">[import ../test/stub.cpp] +[foo] +[bar] +</pre> + <p> + The first line: + </p> +<pre class="programlisting">[import ../test/stub.cpp] +</pre> + <p> + collects specially marked-up code snippets from <a href="../../test/stub.cpp">stub.cpp</a> + and places them in your QuickBook file as virtual templates. Each of + the specially marked-up code snippets has a name (e.g. <code><span + class="identifier">foo</span></code> and <code><span class="identifier">bar</span></code> + 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: + </p> +<pre class="programlisting">[foo] +[bar] +</pre> + <p> + And the result is: + </p> + <p> + This is the <span class="bold"><strong><span class="emphasis"><em>foo</em></span></strong></span> + function. + </p> + <p> + This description can have paragraphs... + </p> + <ul> + <li> + <div> + lists + </div> + </li> + <li> + <div> + etc. + </div> + </li> + </ul> + <p> + And any quickbook block markup. + </p> + <p> +<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">foo</span><span class="special">()</span> +<span class="special">{</span> + <span class="comment">// return 'em, foo man!</span> + <span class="keyword">return</span> <span class="string">"foo"</span><span class="special">;</span> +<span class="special">}</span> +</pre> + </p> + <p> + This is the <span class="bold"><strong><span class="emphasis"><em>bar</em></span></strong></span> + function + </p> + <p> +<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">bar</span><span class="special">()</span> +<span class="special">{</span> + <span class="comment">// return 'em, bar man!</span> + <span class="keyword">return</span> <span class="string">"bar"</span><span class="special">;</span> +<span class="special">}</span> +</pre> + </p> + <p> + Some trailing text here + </p> + <h5 id="quickbook.syntax.block.import.code_snippet_markup"> + Code Snippet Markup + </h5> + <p> + Note how the code snippets in <a href="../../test/stub.cpp">stub.cpp</a> + get marked up. We use distinguishable comments following the form: + </p> +<pre class="programlisting"><span class="comment">//[id</span> +<span class="identifier">some</span> <span class="identifier">code</span> <span class="identifier">here</span> +<span class="comment">//]</span> +</pre> + <p> + The first comment line above initiates a named code-snippet. This prefix + will not be visible in quickbook. The entire code-snippet in between + <code><span class="comment">//[id</span></code> and <code><span class="comment">//]</span></code> + will be inserted as a template in quickbook with name <span class="emphasis"><em><span + class="emphasis"><em>id</em></span></em></span>. The comment <code><span + class="comment">//]</span></code> ends a code-snippet This too will + not be visible in quickbook. + </p> + <h5 id="quickbook.syntax.block.import.special_comments"> + Special Comments + </h5> + <p> + Special comments of the form: + </p> +<pre class="programlisting"><span class="comment">//` some [*quickbook] markup here</span> +</pre> + <p> + and: + </p> +<pre class="programlisting"><span class="comment">/*` some [*quickbook] markup here */</span> +</pre> + <p> + will be parsed by QuickBook. This can contain quickbook <span class="emphasis"><em>blocks</em></span> + (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. + </p> + <h5 id="quickbook.syntax.block.import.callouts"> + Callouts + </h5> + <p> + Special comments of the form: + </p> +<pre class="programlisting"><span class="comment">/*< some [*quickbook] markup here >*/</span> +</pre> + <p> + 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 + <a href="http://www.docbook.org/tdg/en/html/callout.html">Callouts</a> + for details. Example: + </p> + <p> +<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">foo_bar</span><span class="special">()</span> <a href="#quickbook.syntax.block.import.c1">(1)</a> +<span class="special">{</span> + <span class="keyword">return</span> <span class="string">"foo-bar"</span><span class="special">;</span> <a href="#quickbook.syntax.block.import.c3">(2)</a> +<span class="special">}</span> +</pre> + </p> + <div> + <div id="quickbook.syntax.block.import.c1"> + <a href="#quickbook.syntax.block.import.c0">(1)</a> + <p> + The <span class="emphasis"><em>Mythical</em></span> FooBar. See + <a href="http://en.wikipedia.org/wiki/Foobar">Foobar for details</a> + </p> + </div> + <div id="quickbook.syntax.block.import.c3"> + <a href="#quickbook.syntax.block.import.c2">(2)</a> + <p> + return 'em, foo-bar man! + </p> + </div> + </div> + <p> + Checkout <a href="../../test/stub.cpp">stub.cpp</a> to see the actual + code. + </p> + </div> + </div> + </div> + </div> + <div id="quickbook.install"> + <h3> + Installation and configuration + </h3> + <div id="quickbook.install"> + <p> + This section provides some guidelines on how to install and configure BoostBook + and Quickbook under several operating systems. + </p> + <p> + 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 <code><span class="identifier">bin</span></code> + and <code><span class="identifier">bin</span><span class="special">.</span><span + class="identifier">v2</span></code> directories generated by the build + before trying again. Otherwise your configuration fixes will not take any + effect. + </p> + </div> + <div id="quickbook.install.windows"> + <h3> + Windows 2000, XP, 2003, Vista + </h3> + <div id="quickbook.install.windows"> + <blockquote> + <p> + <span class="emphasis"><em>Section contributed by Julio M. Merino Vidal</em></span> + </p> + </blockquote> + <p> + 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. + </p> + <ol> + <li> + <div> + First of all you need to have a copy of <code><span class="identifier">xsltproc</span></code> + for Windows. There are many ways to get this tool, but to keep things + simple, use the <a href="http://www.zlatkovic.com/pub/libxml/">binary + packages</a> made by Igor Zlatkovic. At the very least, you need + to download the following packages: <code><span class="identifier">iconv</span></code>, + <code><span class="identifier">zlib</span></code>, <code><span class="identifier">libxml2</span></code> + and <code><span class="identifier">libxslt</span></code>. + </div> + </li> + <li> + <div> + Unpack all these packages in the same directory so that you get unique + <code><span class="identifier">bin</span></code>, <code><span class="identifier">include</span></code> + and <code><span class="identifier">lib</span></code> directories + within the hierarchy. These instructions use <code><span class="identifier">C</span><span + class="special">:\</span><span class="identifier">Users</span><span + class="special">\</span><span class="identifier">example</span><span + class="special">\</span><span class="identifier">Documents</span><span + class="special">\</span><span class="identifier">boost</span><span + class="special">\</span><span class="identifier">xml</span></code> + as the root for all files. + </div> + </li> + <li> + <div> + From the command line, go to the <code><span class="identifier">bin</span></code> + directory and launch <code><span class="identifier">xsltproc</span><span + class="special">.</span><span class="identifier">exe</span></code> + to ensure it works. You should get usage information on screen. + </div> + </li> + <li> + <div> + Download <a href="http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip">Docbook + XML 4.2</a> and unpack it in the same directory used above. That + is: <code><span class="identifier">C</span><span class="special">:\</span><span + class="identifier">Users</span><span class="special">\</span><span + class="identifier">example</span><span class="special">\</span><span + class="identifier">Documents</span><span class="special">\</span><span + class="identifier">boost</span><span class="special">\</span><span + class="identifier">xml</span><span class="special">\</span><span + class="identifier">docbook</span><span class="special">-</span><span + class="identifier">xml</span></code>. + </div> + </li> + <li> + <div> + Download the latest <a href="http://sourceforge.net/project/showfiles.php?group_id=21935&package_id=16608">Docbook + XSL</a> version and unpack it, again in the same directory used before. + To make things easier, rename the directory created during the extraction + to <code><span class="identifier">docbook</span><span class="special">-</span><span + class="identifier">xsl</span></code> (bypassing the version name): + <code><span class="identifier">C</span><span class="special">:\</span><span + class="identifier">Users</span><span class="special">\</span><span + class="identifier">example</span><span class="special">\</span><span + class="identifier">Documents</span><span class="special">\</span><span + class="identifier">boost</span><span class="special">\</span><span + class="identifier">xml</span><span class="special">\</span><span + class="identifier">docbook</span><span class="special">-</span><span + class="identifier">xsl</span></code>. + </div> + </li> + <li> + <div> + Add the following to your <code><span class="identifier">user</span><span + class="special">-</span><span class="identifier">config</span><span + class="special">.</span><span class="identifier">jam</span></code> + file, which should live in your home directory (<code><span class="special">%</span><span + class="identifier">HOMEDRIVE</span><span class="special">%%</span><span + class="identifier">HOMEPATH</span><span class="special">%</span></code>). + You must already have it somewhere or otherwise you could not be + building Boost (i.e. missing tools configuration). + </div> + </li> + </ol> +<pre class="programlisting"><span class="identifier">using</span> <span class="identifier">xsltproc</span> + <span class="special">:</span> <span class="string">"C:/Users/example/Documents/boost/xml/bin/xsltproc.exe"</span> + <span class="special">;</span> + +<span class="identifier">using</span> <span class="identifier">boostbook</span> + <span class="special">:</span> <span class="string">"C:/Users/example/Documents/boost/xml/docbook-xsl"</span> + <span class="special">:</span> <span class="string">"C:/Users/example/Documents/boost/xml/docbook-xml"</span> + <span class="special">;</span> +</pre> + <p> + 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: + </p> + <ol> + <li> + <div> + Go to Quickbook's source directory (<code><span class="identifier">BOOST_ROOT</span><span + class="special">\</span><span class="identifier">tools</span><span + class="special">\</span><span class="identifier">quickbook</span></code>). + </div> + </li> + <li> + <div> + Build the utility by issuing <code><span class="identifier">bjam</span> + <span class="special">--</span><span class="identifier">v2</span></code>. + </div> + </li> + <li> + <div> + Copy the resulting <code><span class="identifier">quickbook</span><span + class="special">.</span><span class="identifier">exe</span></code> + binary (located under the <code><span class="identifier">BOOST_ROOT</span><span + class="special">\</span><span class="identifier">bin</span><span + class="special">.</span><span class="identifier">v2</span></code> + hierarchy) to a safe place. Following our previous example, you can + install it into: <code><span class="identifier">C</span><span class="special">:\</span><span + class="identifier">Users</span><span class="special">\</span><span + class="identifier">example</span><span class="special">\</span><span + class="identifier">Documents</span><span class="special">\</span><span + class="identifier">boost</span><span class="special">\</span><span + class="identifier">xml</span><span class="special">\</span><span + class="identifier">bin</span></code>. + </div> + </li> + <li> + <div> + Add the following to your <code><span class="identifier">user</span><span + class="special">-</span><span class="identifier">config</span><span + class="special">.</span><span class="identifier">jam</span></code> + file: + </div> + </li> + </ol> +<pre class="programlisting"><span class="identifier">using</span> <span class="identifier">quickbook</span> + <span class="special">:</span> <span class="string">"C:/Users/example/Documents/boost/xml/bin/quickbook.exe"</span> + <span class="special">;</span> +</pre> + </div> + </div> + <div id="quickbook.install.linux"> + <h3> + Debian, Ubuntu + </h3> + <div id="quickbook.install.linux"> + <p> + 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. + </p> + <p> + First install the <code><span class="identifier">bjam</span></code>, + <code><span class="identifier">xsltproc</span></code>, <code><span class="identifier">docbook</span><span + class="special">-</span><span class="identifier">xsl</span></code> and + <code><span class="identifier">docbook</span><span class="special">-</span><span + class="identifier">xml</span></code> packages. For example, using <code><span + class="identifier">apt</span><span class="special">-</span><span class="identifier">get</span></code>: + </p> +<pre class="programlisting"><span class="identifier">sudo</span> <span class="identifier">apt</span><span class="special">-</span><span class="identifier">get</span> <span class="identifier">install</span> <span class="identifier">xsltprc</span> <span class="identifier">docbook</span><span class="special">-</span><span class="identifier">xsl</span> <span class="identifier">docbook</span><span class="special">-</span><span class="identifier">xml</span> +</pre> + <p> + If you're planning on building boost's documentation, you'll also need + to install the <code><span class="identifier">doxygen</span></code> package + as well. + </p> + <p> + Next, we need to configure Boost Build to compile BoostBook files. Add + the following to your <code><span class="identifier">user</span><span + class="special">-</span><span class="identifier">config</span><span class="special">.</span><span + class="identifier">jam</span></code> 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 <code><span class="identifier">user</span><span + class="special">-</span><span class="identifier">config</span><span class="special">.</span><span + class="identifier">jam</span></code>, see the <a href="http://boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html">Boost + Build documentation</a>. + </p> +<pre class="programlisting"><span class="identifier">using</span> <span class="identifier">xsltproc</span> <span class="special">;</span> + +<span class="identifier">using</span> <span class="identifier">boostbook</span> + <span class="special">:</span> <span class="special">/</span><span class="identifier">usr</span><span class="special">/</span><span class="identifier">share</span><span class="special">/</span><span class="identifier">xml</span><span class="special">/</span><span class="identifier">docbook</span><span class="special">/</span><span class="identifier">stylesheet</span><span class="special">/</span><span class="identifier">nwalsh</span> + <span class="special">:</span> <span class="special">/</span><span class="identifier">usr</span><span class="special">/</span><span class="identifier">share</span><span class="special">/</span><span class="identifier">xml</span><span class="special">/</span><span class="identifier">docbook</span><span class="special">/</span><span class="identifier">schema</span><span class="special">/</span><span class="identifier">dtd</span><span class="special">/</span><span class="number">4.2</span> + <span class="special">;</span> + +<span class="comment"># Remove this line if you're not using doxygen</span> +<span class="identifier">using</span> <span class="identifier">doxygen</span> <span class="special">;</span> +</pre> + <p> + 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: + </p> + <ol> + <li> + <div> + Go to Quickbook's source directory (<code><span class="identifier">BOOST_ROOT</span><span + class="special">/</span><span class="identifier">tools</span><span + class="special">/</span><span class="identifier">quickbook</span></code>). + </div> + </li> + <li> + <div> + Build the utility by issuing <code><span class="identifier">bjam</span> + <span class="special">--</span><span class="identifier">v2</span></code>. + </div> + </li> + <li> + <div> + Copy the resulting <code><span class="identifier">quickbook</span></code> + binary (located under the <code><span class="identifier">BOOST_ROOT</span><span + class="special">/</span><span class="identifier">bin</span><span + class="special">.</span><span class="identifier">v2</span></code> + hierarchy) to a safe place. The traditional location is <code><span + class="special">/</span><span class="identifier">usr</span><span + class="special">/</span><span class="identifier">local</span><span + class="special">/</span><span class="identifier">bin</span></code>. + </div> + </li> + <li> + <div> + Add the following to your <code><span class="identifier">user</span><span + class="special">-</span><span class="identifier">config</span><span + class="special">.</span><span class="identifier">jam</span></code> + file, using the full path of the quickbook executable: + </div> + </li> + </ol> +<pre class="programlisting"><span class="identifier">using</span> <span class="identifier">quickbook</span> + <span class="special">:</span> <span class="special">/</span><span class="identifier">usr</span><span class="special">/</span><span class="identifier">local</span><span class="special">/</span><span class="identifier">bin</span><span class="special">/</span><span class="identifier">quickbook</span> + <span class="special">;</span> +</pre> + </div> + </div> + </div> + <div id="quickbook.editors"> + <h3> + Editor Support + </h3> + <div id="quickbook.editors"> + <p> + 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. + </p> + <div class="blurb"> + <p> + <span class="inlinemediaobject"><img src="images/note.png" alt="[]"/></span> + You may submit your settings, tips, and suggestions to the authors, or + through the <a href="https://lists.sourceforge.net/lists/listinfo/boost-">docs + Boost Docs mailing list</a>. + </p> + </div> + </div> + <div id="quickbook.editors.scite"> + <h3> + Scintilla Text Editor + </h3> + <div id="quickbook.editors.scite"> + <blockquote> + <p> + <span class="emphasis"><em>Section contributed by Dean Michael Berris</em></span> + </p> + </blockquote> + <p> + The Scintilla Text Editor (SciTE) is a free source code editor for Win32 + and X. It uses the SCIntilla source code editing component. + </p> + <div class="blurb"> + <p> + <span class="inlinemediaobject"><img src="images/tip.png" alt="[]"/></span> + SciTE can be downloaded from <a href="http://www.scintilla.org/SciTE.html">http://www.scintilla.org/SciTE.html</a> + </p> + </div> + <p> + You can use the following settings to highlight quickbook tags when editing + quickbook files. + </p> +<pre class="programlisting">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=] +</pre> + <div class="blurb"> + <p> + <span class="inlinemediaobject"><img src="images/note.png" alt="[]"/></span> + Thanks to Rene Rivera for the above SciTE settings. + </p> + </div> + </div> + </div> + </div> + <div id="quickbook.faq"> + <h3> + Frequently Asked Questions + </h3> + <div id="quickbook.faq"> + <h3 id="quickbook.faq.can_i_use_quickbook_for_non_boost_documentation_"> + Can I use QuickBook for non-Boost documentation? + </h3> + <p> + QuickBook can be used for non-Boost documentation with a little extra work. + </p> + <blockquote> + <p> + <span class="emphasis"><em>Faq contributed by Michael Marcin</em></span> + </p> + </blockquote> + <p> + 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. + </p> + <p> + For example: + </p> +<pre class="programlisting">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 + ; +</pre> + </div> + </div> + <div id="quickbook.ref"> + <h3> + Quick Reference + </h3> + <div id="quickbook.ref"> + <p> + [cpp] + </p> + <div id="quickbook.ref.t0" class="table"> + <table> + <caption>Syntax Compendium</caption> + <thead> + <tr> + <th> + <p> + To do this... + </p> + </th> + <th> + <p> + Use this... + </p> + </th> + <th> + <p> + See this... + </p> + </th> + </tr> + </thead> + <tbody> + <tr> + <td> + <p> + comment + </p> + </td> + <td> + <p> + <tt>[/ some comment]</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.comments">Comments</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + <span class="emphasis"><em>italics</em></span> + </p> + </td> + <td> + <p> + <tt>['italics] or /italics/</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.phrase.font_styles">Font Styles</a> + and <a href="#quickbook.syntax.phrase.simple_formatting">Simple + formatting</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + <span class="bold"><strong>bold</strong></span> + </p> + </td> + <td> + <p> + <tt>[*bold] or *bold*</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.phrase.font_styles">Font Styles</a> + and <a href="#quickbook.syntax.phrase.simple_formatting">Simple + formatting</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + <span class="underline">underline</span> + </p> + </td> + <td> + <p> + <tt>[_underline] or _underline_</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.phrase.font_styles">Font Styles</a> + and <a href="#quickbook.syntax.phrase.simple_formatting">Simple + formatting</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + <tt>teletype</tt> + </p> + </td> + <td> + <p> + <tt>[^teletype] or =teletype=</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.phrase.font_styles">Font Styles</a> + and <a href="#quickbook.syntax.phrase.simple_formatting">Simple + formatting</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + <span class="strikethrough">strikethrough</span> + </p> + </td> + <td> + <p> + <tt>[-strikethrough]</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.phrase.font_styles">Font Styles</a> + and <a href="#quickbook.syntax.phrase.simple_formatting">Simple + formatting</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + <em class="replaceable">replaceable</em> + </p> + </td> + <td> + <p> + <tt>[~replaceable]</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.phrase.replaceable">Replaceble</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + source mode + </p> + </td> + <td> + <p> + <tt>[c++]</tt> or <tt>[python]</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.phrase.source_mode">Source Mode</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + inline code + </p> + </td> + <td> + <p> + <tt>`int main();`</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.phrase.inline_code">Inline code</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + code block + </p> + </td> + <td> + <p> + <tt>``int main();``</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.block.code">Code</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + code escape + </p> + </td> + <td> + <p> + <tt>``from c++ to QuickBook``</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.block.escape_back">Escaping Back To + QuickBook</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + line break + </p> + </td> + <td> + <p> + <tt>[br] or \n</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.phrase.line_break">line-break</a> + <span class="bold"><strong>DEPRECATED</strong></span> + </p> + </td> + </tr> + <tr> + <td> + <p> + anchor + </p> + </td> + <td> + <p> + <tt>[#anchor]</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.phrase.anchors">Anchors</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + link + </p> + </td> + <td> + <p> + <tt>[@http://www.boost.org Boost]</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.phrase.links">Links</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + anchor link + </p> + </td> + <td> + <p> + <tt>[link section.anchor Link text]</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.phrase.anchor_links">Anchor links</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + refentry link + </p> + </td> + <td> + <p> + <tt>[link xml.refentry Link text]</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.phrase.refentry_links">refentry links</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + function link + </p> + </td> + <td> + <p> + <tt>[funcref fully::qualified::function_name Link text]</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.phrase.code_links">function, class, + member, enum, macro, concept or header links</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + class link + </p> + </td> + <td> + <p> + <tt>[classref fully::qualified::class_name Link text]</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.phrase.code_links">function, class, + member, enum, macro, concept or header links</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + member link + </p> + </td> + <td> + <p> + <tt>[memberref fully::qualified::member_name Link text]</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.phrase.code_links">function, class, + member, enum, macro, concept or header links</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + enum link + </p> + </td> + <td> + <p> + <tt>[enumref fully::qualified::enum_name Link text]</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.phrase.code_links">function, class, + member, enum, macro, concept or header links</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + macro link + </p> + </td> + <td> + <p> + <tt>[macroref MACRO_NAME Link text]</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.phrase.code_links">function, class, + member, enum, macro, concept or header links</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + concept link + </p> + </td> + <td> + <p> + <tt>[conceptref ConceptName Link text]</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.phrase.code_links">function, class, + member, enum, macro, concept or header links</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + header link + </p> + </td> + <td> + <p> + <tt>[headerref path/to/header.hpp Link text]</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.phrase.code_links">function, class, + member, enum, macro, concept or header links</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + escape + </p> + </td> + <td> + <p> + <tt>'''escaped text (no processing/formatting)'''</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.phrase.escape">Escape</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + single char escape + </p> + </td> + <td> + <p> + <tt>\c</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.phrase.single_char_escape">Single + char escape</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + images + </p> + </td> + <td> + <p> + <tt>[$image.jpg]</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.phrase.images">Images</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + begin section + </p> + </td> + <td> + <p> + <tt>[section The Section Title]</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.block.section">Section</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + end section + </p> + </td> + <td> + <p> + <tt>[endsect]</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.block.section">Section</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + paragraph + </p> + </td> + <td> + <p> + No markup. Paragraphs start left-flushed and are terminated by + two or more newlines. + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.block.paragraphs">Paragraphs</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + ordered list + </p> + </td> + <td> +<pre class="programlisting"># one +# two +# three +</pre> + </td> + <td> + <p> + <a href="#quickbook.syntax.block.lists.ordered_lists">Ordered + lists</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + unordered list + </p> + </td> + <td> +<pre class="programlisting">* one +* two +* three +</pre> + </td> + <td> + <p> + <a href="#quickbook.syntax.block.lists.unordered_lists">Unordered + lists</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + code + </p> + </td> + <td> + <p> + No markup. Preformatted code starts with a space or a tab. + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.block.code">Code</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + preformatted + </p> + </td> + <td> + <p> + <tt>[pre preformatted]</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.block.preformatted">Preformatted</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + block quote + </p> + </td> + <td> + <p> + <tt>[:sometext...]</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.block.blockquote">Blockquote</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + heading 1 + </p> + </td> + <td> + <p> + <tt>[h1 Heading 1]</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.block.headings">Heading</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + heading 2 + </p> + </td> + <td> + <p> + <tt>[h2 Heading 2]</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.block.headings">Heading</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + heading 3 + </p> + </td> + <td> + <p> + <tt>[h3 Heading 3]</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.block.headings">Heading</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + heading 4 + </p> + </td> + <td> + <p> + <tt>[h4 Heading 4]</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.block.headings">Heading</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + heading 5 + </p> + </td> + <td> + <p> + <tt>[h5 Heading 5]</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.block.headings">Heading</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + heading 6 + </p> + </td> + <td> + <p> + <tt>[h6 Heading 6]</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.block.headings">Heading</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + macro + </p> + </td> + <td> + <p> + <tt>[def macro_identifier some text]</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.block.macros">Macros</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + template + </p> + </td> + <td> + <p> + <tt>[template[a b] [a] body [b]]</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.block.templates">Templates</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + blurb + </p> + </td> + <td> + <p> + <tt>[blurb advertisement or note...]</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.block.blurbs">Blurbs</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + admonition + </p> + </td> + <td> + <p> + <tt>[warning Warning text...]</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.block.admonitions">Admonitions</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + table + </p> + </td> + <td> +<pre class="programlisting">[table Title +[[a][b][c]] +[[a][b][c]] +] +</pre> + </td> + <td> + <p> + <a href="#quickbook.syntax.block.tables">Tables</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + variablelist + </p> + </td> + <td> +<pre class="programlisting">[variablelist Title +[[a][b]] +[[a][b]] +] +</pre> + </td> + <td> + <p> + <a href="#quickbook.syntax.block.variable_lists">Variable Lists</a> + </p> + </td> + </tr> + <tr> + <td> + <p> + include + </p> + </td> + <td> + <p> + <tt>[include someother.qbk]</tt> + </p> + </td> + <td> + <p> + <a href="#quickbook.syntax.block.include">Include</a> + </p> + </td> + </tr> + </tbody> + </table> + </div> + </div> + </div> + <div class="footnotes"> + <br/> + <hr/> + <div id="footnote-1" class="footnote"> + <p> + <a href="#quickbook.syntax.phrase.simple_formatting.f0"><sup>[1]</sup></a> + Thanks to David Barrett, author of <a href="http://quinthar.com/qwikiwiki/index.php?page=Home">Qwiki</a>, + for sharing these samples and teaching me these obscure formatting rules. + I wasn't sure at all if <a href="http://spirit.sourceforge.net">Spirit</a>, + being more or less a formal EBNF parser, can handle the context sensitivity + and ambiguity. + </p> + </div> + <div id="footnote-2" class="footnote"> + <p> + <a href="#quickbook.syntax.phrase.footnotes.f0"><sup>[2]</sup></a> A sample + footnote + </p> + </div> + </div> + </body> +</html> |