| <?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> |
| <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> <anchor |
| id="quickbook.change_log.version_1_3"/> |
| <bridgehead renderas="sect3"> |
| <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> |
| <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"> |
| <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"> |
| <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> |
| <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 |
| </simpara> |
| <orderedlist> |
| <listitem> |
| <simpara> |
| Three.a |
| </simpara> |
| </listitem> |
| <listitem> |
| <simpara> |
| Three.b |
| </simpara> |
| </listitem> |
| <listitem> |
| <simpara> |
| Three.c |
| </simpara> |
| </listitem> |
| </orderedlist> |
| </listitem> |
| <listitem> |
| <simpara> |
| Fourth |
| </simpara> |
| <orderedlist> |
| <listitem> |
| <simpara> |
| Four.a |
| </simpara> |
| <orderedlist> |
| <listitem> |
| <simpara> |
| Four.a.i |
| </simpara> |
| </listitem> |
| <listitem> |
| <simpara> |
| Four.a.ii |
| </simpara> |
| </listitem> |
| </orderedlist> |
| </listitem> |
| </orderedlist> |
| </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 |
| </simpara> |
| <itemizedlist> |
| <listitem> |
| <simpara> |
| Three.a |
| </simpara> |
| </listitem> |
| <listitem> |
| <simpara> |
| Three.b |
| </simpara> |
| </listitem> |
| <listitem> |
| <simpara> |
| Three.c |
| </simpara> |
| </listitem> |
| </itemizedlist> |
| </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 |
| </simpara> |
| <itemizedlist> |
| <listitem> |
| <simpara> |
| 1.a |
| </simpara> |
| <orderedlist> |
| <listitem> |
| <simpara> |
| 1.a.1 |
| </simpara> |
| </listitem> |
| <listitem> |
| <simpara> |
| 1.a.2 |
| </simpara> |
| </listitem> |
| </orderedlist> |
| </listitem> |
| <listitem> |
| <simpara> |
| 1.b |
| </simpara> |
| </listitem> |
| </itemizedlist> |
| </listitem> |
| <listitem> |
| <simpara> |
| 2 |
| </simpara> |
| <itemizedlist> |
| <listitem> |
| <simpara> |
| 2.a |
| </simpara> |
| </listitem> |
| <listitem> |
| <simpara> |
| 2.b |
| </simpara> |
| <orderedlist> |
| <listitem> |
| <simpara> |
| 2.b.1 |
| </simpara> |
| </listitem> |
| <listitem> |
| <simpara> |
| 2.b.2 |
| </simpara> |
| <itemizedlist> |
| <listitem> |
| <simpara> |
| 2.b.2.a |
| </simpara> |
| </listitem> |
| <listitem> |
| <simpara> |
| 2.b.2.b |
| </simpara> |
| </listitem> |
| </itemizedlist> |
| </listitem> |
| </orderedlist> |
| </listitem> |
| </itemizedlist> |
| </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> |
| <anchor id="quickbook.syntax.block.headings.heading_1"/> |
| <bridgehead renderas="sect1"> |
| <link linkend="quickbook.syntax.block.headings.heading_1">Heading 1</link> |
| </bridgehead> |
| <anchor id="quickbook.syntax.block.headings.heading_2"/> |
| <bridgehead renderas="sect2"> |
| <link linkend="quickbook.syntax.block.headings.heading_2">Heading 2</link> |
| </bridgehead> |
| <anchor id="quickbook.syntax.block.headings.heading_3"/> |
| <bridgehead renderas="sect3"> |
| <link linkend="quickbook.syntax.block.headings.heading_3">Heading 3</link> |
| </bridgehead> |
| <anchor id="quickbook.syntax.block.headings.heading_4"/> |
| <bridgehead renderas="sect4"> |
| <link linkend="quickbook.syntax.block.headings.heading_4">Heading 4</link> |
| </bridgehead> |
| <anchor id="quickbook.syntax.block.headings.heading_5"/> |
| <bridgehead renderas="sect5"> |
| <link linkend="quickbook.syntax.block.headings.heading_5">Heading 5</link> |
| </bridgehead> |
| <anchor id="quickbook.syntax.block.headings.heading_6"/> |
| <bridgehead renderas="sect6"> |
| <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"> |
| <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> |
| NO_FILENAME_MACRO_GENERATED_IN_DEBUG_MODE |
| </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> |
| <anchor id="quickbook.syntax.block.templates.template_identifier"/> |
| <bridgehead renderas="sect5"> |
| <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> |
| <anchor id="quickbook.syntax.block.templates.formal_template_arguments"/> |
| <bridgehead renderas="sect5"> |
| <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> |
| <anchor id="quickbook.syntax.block.templates.template_body"/> |
| <bridgehead renderas="sect5"> |
| <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> |
| <anchor id="quickbook.syntax.block.templates.template_expansion"/> |
| <bridgehead renderas="sect5"> |
| <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> |
| <anchor id="quickbook.syntax.block.templates.nullary_templates"/> |
| <bridgehead renderas="sect5"> |
| <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> |
| <anchor id="quickbook.syntax.block.templates.simple_arguments"/> |
| <bridgehead renderas="sect5"> |
| <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> |
| <anchor id="quickbook.syntax.block.templates.punctuation_templates"/> |
| <bridgehead renderas="sect5"> |
| <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"> |
| <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"> |
| <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"> |
| <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> |
| <anchor id="quickbook.syntax.block.import.example"/> |
| <bridgehead renderas="sect5"> |
| <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> |
| <anchor id="quickbook.syntax.block.import.code_snippet_markup"/> |
| <bridgehead renderas="sect5"> |
| <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> |
| <anchor id="quickbook.syntax.block.import.special_comments"/> |
| <bridgehead renderas="sect5"> |
| <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> |
| <anchor id="quickbook.syntax.block.import.callouts"/> |
| <bridgehead renderas="sect5"> |
| <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> <!--quickbook-escape-prefix--><co id="quickbook0co" linkends="quickbook0" /><!--quickbook-escape-postfix--> |
| <phrase role="special">{</phrase> |
| <phrase role="keyword">return</phrase> <phrase role="string">"foo-bar"</phrase><phrase role="special">;</phrase> <!--quickbook-escape-prefix--><co id="quickbook1co" linkends="quickbook1" /><!--quickbook-escape-postfix--> |
| <phrase role="special">}</phrase> |
| </programlisting> |
| </para> |
| <calloutlist> |
| <callout arearefs="quickbook0co" id="quickbook0"> |
| <para> |
| The <emphasis>Mythical</emphasis> FooBar. See <ulink url="http://en.wikipedia.org/wiki/Foobar">Foobar |
| for details</ulink> |
| </para> |
| </callout> |
| <callout arearefs="quickbook1co" id="quickbook1"> |
| <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> |
| <anchor id="quickbook.faq.can_i_use_quickbook_for_non_boost_documentation_"/> |
| <bridgehead renderas="sect3"> |
| <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<literal>images/my_project_logo.png |
| <xsl:param>boost.image.alt</literal>"\"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"> |
| <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> |