| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> |
| <title>Syntax Summary</title> |
| <link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css"> |
| <meta name="generator" content="DocBook XSL Stylesheets V1.75.2"> |
| <link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> |
| <link rel="up" href="../quickbook.html" title="Chapter 31. Quickbook 1.5"> |
| <link rel="prev" href="change_log.html" title="Change Log"> |
| <link rel="next" href="install.html" title="Installation and configuration"> |
| </head> |
| <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> |
| <table cellpadding="2" width="100%"><tr> |
| <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td> |
| <td align="center"><a href="../../../index.html">Home</a></td> |
| <td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td> |
| <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> |
| <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> |
| <td align="center"><a href="../../../more/index.htm">More</a></td> |
| </tr></table> |
| <hr> |
| <div class="spirit-nav"> |
| <a accesskey="p" href="change_log.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../quickbook.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="install.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h2 class="title" style="clear: both"> |
| <a name="quickbook.syntax"></a><a class="link" href="syntax.html" title="Syntax Summary">Syntax Summary</a> |
| </h2></div></div></div> |
| <div class="toc"><dl> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.comments">Comments</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase">Phrase Level Elements</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.block">Block Level Elements</a></span></dt> |
| </dl></div> |
| <p> |
| A QuickBook document is composed of one or more blocks. An example of a block |
| is the paragraph or a C++ code snippet. Some blocks have special mark-ups. |
| Blocks, except code snippets which have their own grammar (C++ or Python), |
| are composed of one or more phrases. A phrase can be a simple contiguous run |
| of characters. Phrases can have special mark-ups. Marked up phrases can recursively |
| contain other phrases, but cannot contain blocks. A terminal is a self contained |
| block-level or phrase-level element that does not nest anything. |
| </p> |
| <p> |
| Blocks, in general, are delimited by two end-of-lines (the block terminator). |
| Phrases in each block cannot contain a block terminator. This way, syntax errors |
| such as un-matched closing brackets do not go haywire and corrupt anything |
| past a single block. |
| </p> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="quickbook.syntax.comments"></a><a class="link" href="syntax.html#quickbook.syntax.comments" title="Comments">Comments</a> |
| </h3></div></div></div> |
| <p> |
| Can be placed anywhere. |
| </p> |
| <pre class="programlisting">[/ comment (no output generated) ] |
| </pre> |
| <pre class="programlisting">[/ comments can be nested [/ some more here] ] |
| </pre> |
| <pre class="programlisting">[/ Quickbook blocks can nest inside comments. [*Comment this out too!] ] |
| </pre> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="quickbook.syntax.phrase"></a><a class="link" href="syntax.html#quickbook.syntax.phrase" title="Phrase Level Elements">Phrase Level Elements</a> |
| </h3></div></div></div> |
| <div class="toc"><dl> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.font_styles">Font Styles</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.replaceable">Replaceable</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.quotations">Quotations</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.simple_formatting">Simple formatting</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.inline_code">Inline code</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.code_blocks">Code blocks</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.source_mode">Source Mode</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.line_break">line-break</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.anchors">Anchors</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.links">Links</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.anchor_links">Anchor links</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.refentry_links">refentry links</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.code_links">Code Links</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.escape">Escape</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.single_char_escape">Single |
| char escape</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.unicode_escape">Unicode escape</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.images">Images</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.footnotes">Footnotes</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.cond">Conditional Generation</a></span></dt> |
| </dl></div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.phrase.font_styles"></a><a class="link" href="syntax.html#quickbook.syntax.phrase.font_styles" title="Font Styles">Font Styles</a> |
| </h4></div></div></div> |
| <pre class="programlisting">['italic], [*bold], [_underline], [^teletype], [-strikethrough] |
| </pre> |
| <p> |
| will generate: |
| </p> |
| <p> |
| <span class="emphasis"><em>italic</em></span>, <span class="bold"><strong>bold</strong></span>, <span class="underline">underline</span>, <code class="literal">teletype</code>, <span class="strikethrough">strikethrough</span> |
| </p> |
| <p> |
| Like all non-terminal phrase level elements, this can of course be nested: |
| </p> |
| <pre class="programlisting">[*['bold-italic]] |
| </pre> |
| <p> |
| will generate: |
| </p> |
| <p> |
| <span class="bold"><strong><span class="emphasis"><em>bold-italic</em></span></strong></span> |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.phrase.replaceable"></a><a class="link" href="syntax.html#quickbook.syntax.phrase.replaceable" title="Replaceable">Replaceable</a> |
| </h4></div></div></div> |
| <p> |
| When you want content that may or must be replaced by the user, use the |
| syntax: |
| </p> |
| <pre class="programlisting">[~replacement] |
| </pre> |
| <p> |
| This will generate: |
| </p> |
| <p> |
| <em class="replaceable"><code>replacement</code></em> |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.phrase.quotations"></a><a class="link" href="syntax.html#quickbook.syntax.phrase.quotations" title="Quotations">Quotations</a> |
| </h4></div></div></div> |
| <pre class="programlisting">["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein |
| </pre> |
| <p> |
| will generate: |
| </p> |
| <p> |
| <span class="quote">“<span class="quote">A question that sometimes drives me hazy: am I or are the others |
| crazy?</span>”</span>--Einstein |
| </p> |
| <p> |
| Note the proper left and right quote marks. Also, while you can simply |
| use ordinary quote marks like "quoted", our quotation, above, |
| will generate correct DocBook quotations (e.g. <quote>quoted</quote>). |
| </p> |
| <p> |
| Like all phrase elements, quotations may be nested. Example: |
| </p> |
| <pre class="programlisting">["Here's the rule for bargains: ["Do other men, for they would do you.] That's |
| the true business precept.] |
| </pre> |
| <p> |
| will generate: |
| </p> |
| <p> |
| <span class="quote">“<span class="quote">Here's the rule for bargains: <span class="quote">‘<span class="quote">Do other men, for they would |
| do you.</span>’</span> That's the true business precept.</span>”</span> |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.phrase.simple_formatting"></a><a class="link" href="syntax.html#quickbook.syntax.phrase.simple_formatting" title="Simple formatting">Simple formatting</a> |
| </h4></div></div></div> |
| <p> |
| Simple markup for formatting text, common in many applications, is now |
| supported: |
| </p> |
| <pre class="programlisting">/italic/, *bold*, _underline_, =teletype= |
| </pre> |
| <p> |
| will generate: |
| </p> |
| <p> |
| <span class="emphasis"><em>italic</em></span>, <span class="bold"><strong>bold</strong></span>, <span class="underline">underline</span>, <code class="literal">teletype</code> |
| </p> |
| <p> |
| Unlike QuickBook's standard formatting scheme, the rules for simpler alternatives |
| are much stricter<sup>[<a name="id3238824" href="#ftn.id3238824" class="footnote">6</a>]</sup>. |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> |
| <li class="listitem"> |
| Simple markups cannot nest. You can combine a simple markup with a |
| nestable markup. |
| </li> |
| <li class="listitem"> |
| Simple markups cannot contain any other form of quickbook markup. |
| </li> |
| <li class="listitem"> |
| A non-space character must follow the leading markup |
| </li> |
| <li class="listitem"> |
| A non-space character must precede the trailing markup |
| </li> |
| <li class="listitem"> |
| A space or a punctuation must follow the trailing markup |
| </li> |
| <li class="listitem"> |
| 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: ']'. |
| </li> |
| <li class="listitem"> |
| A line starting with the star will be interpreted as an unordered list. |
| See <a class="link" href="syntax.html#quickbook.syntax.block.lists.unordered_lists" title="Unordered lists">Unordered |
| lists</a>. |
| </li> |
| </ul></div> |
| <div class="table"> |
| <a name="quickbook.syntax.phrase.simple_formatting.more_formatting_samples"></a><p class="title"><b>Table 31.1. More Formatting Samples</b></p> |
| <div class="table-contents"><table class="table" summary="More Formatting Samples"> |
| <colgroup> |
| <col> |
| <col> |
| </colgroup> |
| <thead><tr> |
| <th> |
| <p> |
| Markup |
| </p> |
| </th> |
| <th> |
| <p> |
| Result |
| </p> |
| </th> |
| </tr></thead> |
| <tbody> |
| <tr> |
| <td> |
| <p> |
| <code class="literal">*Bold*</code> |
| </p> |
| </td> |
| <td> |
| <p> |
| <span class="bold"><strong>Bold</strong></span> |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| <code class="literal">*Is bold*</code> |
| </p> |
| </td> |
| <td> |
| <p> |
| <span class="bold"><strong>Is bold</strong></span> |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| <code class="literal">* Not bold* *Not bold * * Not bold *</code> |
| </p> |
| </td> |
| <td> |
| <p> |
| * Not bold* *Not bold * * Not bold * |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| <code class="literal">This*Isn't*Bold (no bold)</code> |
| </p> |
| </td> |
| <td> |
| <p> |
| This*Isn't*Bold (no bold) |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| <code class="literal">(*Bold Inside*) (parenthesis not bold)</code> |
| </p> |
| </td> |
| <td> |
| <p> |
| (<span class="bold"><strong>Bold Inside</strong></span>) (parenthesis not |
| bold) |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| <code class="literal">*(Bold Outside)* (parenthesis bold)</code> |
| </p> |
| </td> |
| <td> |
| <p> |
| <span class="bold"><strong>(Bold Outside)</strong></span> (parenthesis |
| bold) |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| <code class="literal">3*4*5 = 60 (no bold)</code> |
| </p> |
| </td> |
| <td> |
| <p> |
| 3*4*5 = 60 (no bold) |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| <code class="literal">3 * 4 * 5 = 60 (no bold)</code> |
| </p> |
| </td> |
| <td> |
| <p> |
| 3 * 4 * 5 = 60 (no bold) |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| <code class="literal">3 *4* 5 = 60 (4 is bold)</code> |
| </p> |
| </td> |
| <td> |
| <p> |
| 3 <span class="bold"><strong>4</strong></span> 5 = 60 (4 is bold) |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| <code class="literal">*This is bold* this is not *but this is*</code> |
| </p> |
| </td> |
| <td> |
| <p> |
| <span class="bold"><strong>This is bold</strong></span> this is not <span class="bold"><strong>but this is</strong></span> |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| <code class="literal">*This is bold*.</code> |
| </p> |
| </td> |
| <td> |
| <p> |
| <span class="bold"><strong>This is bold</strong></span>. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| <code class="literal">*B*. (bold B)</code> |
| </p> |
| </td> |
| <td> |
| <p> |
| <span class="bold"><strong>B</strong></span>. (bold B) |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| <code class="literal">['*Bold-Italic*]</code> |
| </p> |
| </td> |
| <td> |
| <p> |
| <span class="emphasis"><em><span class="bold"><strong>Bold-Italic</strong></span></em></span> |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| <code class="literal">*side-by*/-side/</code> |
| </p> |
| </td> |
| <td> |
| <p> |
| <span class="bold"><strong>side-by</strong></span><span class="emphasis"><em>-side</em></span> |
| </p> |
| </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <br class="table-break"><p> |
| As mentioned, simple markups cannot go past a single block. The text from |
| "have" to "full" in the following paragraph will be |
| rendered as bold: |
| </p> |
| <pre class="programlisting">Baa baa black sheep, *have you any wool? |
| Yes sir, yes sir, three bags full!* |
| One for the master, one for the dame, |
| And one for the little boy who lives down the lane. |
| </pre> |
| <p> |
| Baa baa black sheep, <span class="bold"><strong>have you any wool? Yes sir, |
| yes sir, three bags full!</strong></span> One for the master, one for the dame, |
| And one for the little boy who lives down the lane. |
| </p> |
| <p> |
| But in the following paragraph, bold is not applied: |
| </p> |
| <pre class="programlisting">Baa baa black sheep, *have you any wool? |
| Yes sir, yes sir, three bags full! |
| One for the master, one for the dame, |
| And one for the little boy who lives down the lane. |
| </pre> |
| <p> |
| Baa baa black sheep, *have you any wool? Yes sir, yes sir, three bags full! |
| One for the master, one for the dame, And one for the little boy who lives |
| down the lane. |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.phrase.inline_code"></a><a class="link" href="syntax.html#quickbook.syntax.phrase.inline_code" title="Inline code">Inline code</a> |
| </h4></div></div></div> |
| <p> |
| Inlining code in paragraphs is quite common when writing C++ documentation. |
| We provide a very simple markup for this. For example, this: |
| </p> |
| <pre class="programlisting">This text has inlined code `int main() { return 0; }` in it. |
| </pre> |
| <p> |
| will generate: |
| </p> |
| <p> |
| This text has inlined code <code class="computeroutput"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> <span class="special">}</span></code> |
| in it. The code will be syntax highlighted. |
| </p> |
| <div class="note"><table border="0" summary="Note"> |
| <tr> |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td> |
| <th align="left">Note</th> |
| </tr> |
| <tr><td align="left" valign="top"><p> |
| We simply enclose the code with the tick: <code class="literal">"`"</code>, not the |
| single quote: <code class="computeroutput"><span class="string">"'"</span></code>. |
| Note too that <code class="literal">`some code`</code> is preferred over <code class="literal">[^some code]</code>. |
| </p></td></tr> |
| </table></div> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.phrase.code_blocks"></a><a class="link" href="syntax.html#quickbook.syntax.phrase.code_blocks" title="Code blocks">Code blocks</a> |
| </h4></div></div></div> |
| <p> |
| Preformatted code simply starts with a space or a tab (See <a class="link" href="syntax.html#quickbook.syntax.block.code" title="Code">Code</a>). |
| However, such a simple syntax cannot be used as phrase elements in lists |
| (See <a class="link" href="syntax.html#quickbook.syntax.block.lists.ordered_lists" title="Ordered lists">Ordered |
| lists</a> and <a class="link" href="syntax.html#quickbook.syntax.block.lists.unordered_lists" title="Unordered lists">Unordered |
| lists</a>), tables (See <a class="link" href="syntax.html#quickbook.syntax.block.tables" title="Tables">Tables</a>), |
| etc. Inline code (see above) can. The problem is, inline code does not |
| allow formatting with newlines, spaces, and tabs. These are lost. |
| </p> |
| <p> |
| We provide a phrase level markup that is a mix between the two. By using |
| the double-tick, instead of the single-tick, we are telling QuickBook to |
| use preformatted blocks of code. Example: |
| </p> |
| <pre class="programlisting">`` |
| #include <iostream> |
| |
| int main() |
| { |
| std::cout << "Hello, World!" << std::endl; |
| return 0; |
| } |
| `` |
| </pre> |
| <p> |
| will generate: |
| </p> |
| <p> |
| |
| </p> |
| <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span> |
| |
| <span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> |
| <span class="special">{</span> |
| <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Hello, World!"</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> |
| <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> |
| <span class="special">}</span> |
| </pre> |
| <p> |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.phrase.source_mode"></a><a class="link" href="syntax.html#quickbook.syntax.phrase.source_mode" title="Source Mode">Source Mode</a> |
| </h4></div></div></div> |
| <p> |
| If a document contains more than one type of source code then the source |
| mode may be changed dynamically as the document is processed. All QuickBook |
| documents are initially in C++ mode by default, though an alternative initial |
| value may be set in the <a class="link" href="syntax.html#quickbook.syntax.block.document" title="Document">Document</a> |
| section. |
| </p> |
| <p> |
| To change the source mode, use the <code class="literal">[source-mode]</code> markup, |
| where <code class="literal">source-mode</code> is one of the supported modes. For |
| example, this: |
| </p> |
| <pre class="programlisting">Python's [python] `import` is rather like C++'s [c++] `#include`. A |
| C++ comment `// looks like this` whereas a Python comment [python] |
| `# looks like this`. |
| </pre> |
| <p> |
| will generate: |
| </p> |
| <p> |
| Python's <code class="computeroutput"><span class="keyword">import</span></code> is rather |
| like C++'s <code class="computeroutput"><span class="preprocessor">#include</span></code>. |
| A C++ comment <code class="computeroutput"><span class="comment">// looks like this</span></code> |
| whereas a Python comment <code class="computeroutput"><span class="comment">#looks like this</span></code>. |
| </p> |
| <div class="table"> |
| <a name="quickbook.syntax.phrase.source_mode.supported_source_modes"></a><p class="title"><b>Table 31.2. Supported Source Modes</b></p> |
| <div class="table-contents"><table class="table" summary="Supported Source Modes"> |
| <colgroup> |
| <col> |
| <col> |
| </colgroup> |
| <thead><tr> |
| <th> |
| <p> |
| Mode |
| </p> |
| </th> |
| <th> |
| <p> |
| Source Mode Markup |
| </p> |
| </th> |
| </tr></thead> |
| <tbody> |
| <tr> |
| <td> |
| <p> |
| C++ |
| </p> |
| </td> |
| <td> |
| <p> |
| <code class="literal">[c++]</code> |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| Python |
| </p> |
| </td> |
| <td> |
| <p> |
| <code class="literal">[python]</code> |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| Plain Text |
| </p> |
| </td> |
| <td> |
| <p> |
| <code class="literal">[teletype]</code> |
| </p> |
| </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <br class="table-break"><div class="note"><table border="0" summary="Note"> |
| <tr> |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td> |
| <th align="left">Note</th> |
| </tr> |
| <tr><td align="left" valign="top"><p> |
| The source mode strings are lowercase. |
| </p></td></tr> |
| </table></div> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.phrase.line_break"></a><a class="link" href="syntax.html#quickbook.syntax.phrase.line_break" title="line-break">line-break</a> |
| </h4></div></div></div> |
| <pre class="programlisting">[br] |
| </pre> |
| <div class="warning"><table border="0" summary="Warning"> |
| <tr> |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../doc/src/images/warning.png"></td> |
| <th align="left">Warning</th> |
| </tr> |
| <tr><td align="left" valign="top"><p> |
| <code class="computeroutput"><span class="special">[</span><span class="identifier">br</span><span class="special">]</span></code> is now deprecated. <a class="link" href="syntax.html#quickbook.syntax.block.blurbs" title="Blurbs">Blurbs</a>, |
| <a class="link" href="syntax.html#quickbook.syntax.block.admonitions" title="Admonitions">Admonitions</a> |
| and table cells (see <a class="link" href="syntax.html#quickbook.syntax.block.tables" title="Tables">Tables</a>) |
| may now contain paragraphs. |
| </p></td></tr> |
| </table></div> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.phrase.anchors"></a><a class="link" href="syntax.html#quickbook.syntax.phrase.anchors" title="Anchors">Anchors</a> |
| </h4></div></div></div> |
| <pre class="programlisting">[#named_anchor] |
| </pre> |
| <p> |
| A named anchor is a hook that can be referenced by a link elsewhere in |
| the document. You can then reference an anchor with <code class="literal">[link named_anchor |
| Some link text]</code>. |
| See <a class="link" href="syntax.html#quickbook.syntax.phrase.anchor_links" title="Anchor links">Anchor links</a>, |
| <a class="link" href="syntax.html#quickbook.syntax.block.section" title="Section">Section</a> and <a class="link" href="syntax.html#quickbook.syntax.block.headings" title="Headings">Heading</a>. |
| </p> |
| <p> |
| These anchors are global and can be accessed from anywhere in the quickbook |
| documentation. Be careful to avoid clashes with anchors in other sections. |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.phrase.links"></a><a class="link" href="syntax.html#quickbook.syntax.phrase.links" title="Links">Links</a> |
| </h4></div></div></div> |
| <pre class="programlisting">[@http://www.boost.org this is [*boost's] website....] |
| </pre> |
| <p> |
| will generate: |
| </p> |
| <p> |
| <a href="http://www.boost.org" target="_top">this is <span class="bold"><strong>boost's</strong></span> |
| website....</a> |
| </p> |
| <p> |
| URL links where the link text is the link itself is common. Example: |
| </p> |
| <pre class="programlisting">see http://spirit.sourceforge.net/ |
| </pre> |
| <p> |
| so, when the text is absent in a link markup, the URL is assumed. Example: |
| </p> |
| <pre class="programlisting">see [@http://spirit.sourceforge.net/] |
| </pre> |
| <p> |
| will generate: |
| </p> |
| <p> |
| see <a href="http://spirit.sourceforge.net/" target="_top">http://spirit.sourceforge.net/</a> |
| </p> |
| <p> |
| Boostbook also support a custom url schema for linking to files within |
| the boost distribution: |
| </p> |
| <pre class="programlisting">[@boost:/libs/spirit/index.html the Boost.Spirit documentation] |
| </pre> |
| <p> |
| will generate: <a href="../../../libs/spirit/index.html" target="_top">the Boost.Spirit |
| documentation</a> |
| </p> |
| <p> |
| Note that this is only available when using BoostBook, and only for links |
| - it can't be used for images. |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.phrase.anchor_links"></a><a class="link" href="syntax.html#quickbook.syntax.phrase.anchor_links" title="Anchor links">Anchor links</a> |
| </h4></div></div></div> |
| <p> |
| You can link within a document using: |
| </p> |
| <pre class="programlisting">[link document_id.section_id.normalized_header_text The link text] |
| </pre> |
| <p> |
| See sections <a class="link" href="syntax.html#quickbook.syntax.block.section" title="Section">Section</a> |
| and <a class="link" href="syntax.html#quickbook.syntax.block.headings" title="Headings">Heading</a> for |
| more info. |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.phrase.refentry_links"></a><a class="link" href="syntax.html#quickbook.syntax.phrase.refentry_links" title="refentry links">refentry links</a> |
| </h4></div></div></div> |
| <p> |
| In addition, you can link internally to an XML refentry like: |
| </p> |
| <pre class="programlisting">[link xml.refentry The link text] |
| </pre> |
| <p> |
| This gets converted into <code class="literal"><link linkend="xml.refentry">The |
| link text</link></code>. |
| </p> |
| <p> |
| Like URLs, the link text is optional. If this is not present, the link |
| text will automatically be the refentry. Example: |
| </p> |
| <pre class="programlisting">[link xml.refentry] |
| </pre> |
| <p> |
| This gets converted into <code class="literal"><link linkend="xml.refentry">xml.refentry</link></code>. |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.phrase.code_links"></a><a class="link" href="syntax.html#quickbook.syntax.phrase.code_links" title="Code Links">Code Links</a> |
| </h4></div></div></div> |
| <p> |
| If you want to link to a function, class, member, enum, concept, global, |
| or header in the reference section, you can use: |
| </p> |
| <pre class="programlisting">[funcref fully::qualified::function_name The link text] |
| [classref fully::qualified::class_name The link text] |
| [memberref fully::qualified::member_name The link text] |
| [enumref fully::qualified::enum_name The link text] |
| [macroref MACRO_NAME The link text] |
| [conceptref ConceptName The link text] |
| [headerref path/to/header.hpp The link text] |
| [globalref fully::qualified::global The link text] |
| </pre> |
| <p> |
| Again, the link text is optional. If this is not present, the link text |
| will automatically be the function, class, member, enum, macro, concept, |
| global, or header name. Example: |
| </p> |
| <pre class="programlisting">[classref boost::bar::baz] |
| </pre> |
| <p> |
| would have "boost::bar::baz" as the link text. |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.phrase.escape"></a><a class="link" href="syntax.html#quickbook.syntax.phrase.escape" title="Escape">Escape</a> |
| </h4></div></div></div> |
| <p> |
| The escape mark-up is used when we don't want to do any processing. |
| </p> |
| <pre class="programlisting">''' |
| escape (no processing/formatting) |
| ''' |
| </pre> |
| <p> |
| Escaping allows us to pass XML markup to <a href="http://www.boost.org/doc/html/boostbook.html" target="_top">BoostBook</a> |
| or <a href="http://www.docbook.org/" target="_top">DocBook</a>. For example: |
| </p> |
| <pre class="programlisting">''' |
| <emphasis role="bold">This is direct XML markup</emphasis> |
| ''' |
| </pre> |
| <p> |
| <span class="bold"><strong>This is direct XML markup</strong></span> |
| </p> |
| <div class="important"><table border="0" summary="Important"> |
| <tr> |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../doc/src/images/important.png"></td> |
| <th align="left">Important</th> |
| </tr> |
| <tr><td align="left" valign="top"><p> |
| Be careful when using the escape. The text must conform to <a href="http://www.boost.org/doc/html/boostbook.html" target="_top">BoostBook</a>/<a href="http://www.docbook.org/" target="_top">DocBook</a> syntax. |
| </p></td></tr> |
| </table></div> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.phrase.single_char_escape"></a><a class="link" href="syntax.html#quickbook.syntax.phrase.single_char_escape" title="Single char escape">Single |
| char escape</a> |
| </h4></div></div></div> |
| <p> |
| The backslash may be used to escape a single punctuation character. The |
| punctuation immediately after the backslash is passed without any processing. |
| This is useful when we need to escape QuickBook punctuations such as <code class="computeroutput"><span class="special">[</span></code> and <code class="computeroutput"><span class="special">]</span></code>. |
| For example, how do you escape the triple quote? Simple: <code class="literal">\'\'\'</code> |
| </p> |
| <p> |
| <code class="computeroutput"><span class="special">\</span><span class="identifier">n</span></code> |
| has a special meaning. It is used to generate line breaks. |
| </p> |
| <div class="warning"><table border="0" summary="Warning"> |
| <tr> |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../doc/src/images/warning.png"></td> |
| <th align="left">Warning</th> |
| </tr> |
| <tr><td align="left" valign="top"><p> |
| <code class="computeroutput"><span class="special">\</span><span class="identifier">n</span></code> |
| and <code class="computeroutput"><span class="special">[</span><span class="identifier">br</span><span class="special">]</span></code> are now deprecated. <a class="link" href="syntax.html#quickbook.syntax.block.blurbs" title="Blurbs">Blurbs</a>, |
| <a class="link" href="syntax.html#quickbook.syntax.block.admonitions" title="Admonitions">Admonitions</a> |
| and table cells (see <a class="link" href="syntax.html#quickbook.syntax.block.tables" title="Tables">Tables</a>) |
| may now contain paragraphs. |
| </p></td></tr> |
| </table></div> |
| <p> |
| The escaped space: <code class="computeroutput"><span class="special">\</span> </code> also |
| has a special meaning. The escaped space is removed from the output. |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.phrase.unicode_escape"></a><a class="link" href="syntax.html#quickbook.syntax.phrase.unicode_escape" title="Unicode escape">Unicode escape</a> |
| </h4></div></div></div> |
| <p> |
| You can enter any 16-bit unicode character by using <code class="computeroutput"><span class="special">\</span><span class="identifier">u</span></code> followed by its 4 digit hexadecimal |
| code, or a 32-bit character by using <code class="computeroutput"><span class="special">\</span><span class="identifier">U</span></code> followed by an 8 digit hexadecimal |
| code. eg. |
| </p> |
| <pre class="programlisting">\u03B1 + \u03B2 |
| </pre> |
| <p> |
| will generate: |
| </p> |
| <div class="blockquote"><blockquote class="blockquote"><p> |
| α + β |
| </p></blockquote></div> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.phrase.images"></a><a class="link" href="syntax.html#quickbook.syntax.phrase.images" title="Images">Images</a> |
| </h4></div></div></div> |
| <pre class="programlisting">[$image.jpg] |
| </pre> |
| <p> |
| From version 1.5, you can also use <a href="http://www.docbook.org/tdg/en/html/imagedata.html" target="_top">DocBook |
| imagedata attributes</a>: |
| </p> |
| <pre class="programlisting">[$image.jpg [width 200in] [height 200in]] |
| </pre> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.phrase.footnotes"></a><a class="link" href="syntax.html#quickbook.syntax.phrase.footnotes" title="Footnotes">Footnotes</a> |
| </h4></div></div></div> |
| <div class="toc"><dl> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.footnotes.macro_expansion">Macro |
| Expansion</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.footnotes.template_expansion">Template |
| Expansion</a></span></dt> |
| </dl></div> |
| <p> |
| As of version 1.3, QuickBook supports footnotes. Just put the text of the |
| footnote in a <code class="computeroutput"><span class="special">[</span><span class="identifier">footnote</span><span class="special">]</span></code> block, and the text will be put at the |
| bottom of the current page. For example, this: |
| </p> |
| <pre class="programlisting">[footnote A sample footnote] |
| </pre> |
| <p> |
| will generate this<sup>[<a name="id3240728" href="#ftn.id3240728" class="footnote">7</a>]</sup>. |
| </p> |
| <div class="section"> |
| <div class="titlepage"><div><div><h5 class="title"> |
| <a name="quickbook.syntax.phrase.footnotes.macro_expansion"></a><a class="link" href="syntax.html#quickbook.syntax.phrase.footnotes.macro_expansion" title="Macro Expansion">Macro |
| Expansion</a> |
| </h5></div></div></div> |
| <pre class="programlisting">__a_macro_identifier__ |
| </pre> |
| <p> |
| See <a class="link" href="syntax.html#quickbook.syntax.block.macros" title="Macros">Macros</a> for details. |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h5 class="title"> |
| <a name="quickbook.syntax.phrase.footnotes.template_expansion"></a><a class="link" href="syntax.html#quickbook.syntax.phrase.footnotes.template_expansion" title="Template Expansion">Template |
| Expansion</a> |
| </h5></div></div></div> |
| <pre class="programlisting">[a_template_identifier] |
| </pre> |
| <p> |
| See <a class="link" href="syntax.html#quickbook.syntax.block.templates" title="Templates">Templates</a> |
| for details. |
| </p> |
| </div> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.phrase.cond"></a><a class="link" href="syntax.html#quickbook.syntax.phrase.cond" title="Conditional Generation">Conditional Generation</a> |
| </h4></div></div></div> |
| <p> |
| Like C++ <code class="computeroutput"><span class="comment">#ifdef</span></code>, you can generate |
| phrases depending on the presence of a macro. Example: |
| </p> |
| <pre class="programlisting">[? __to_be__ To be or not to be] |
| </pre> |
| <p> |
| Here, the phrase "To be or not to be" will only be generated |
| if the macro symbol __to_be__ has been previously defined. The phrase above will |
| not do anything since we haven't defined __to_be__. Now, let's define the symbol: |
| </p> |
| <pre class="programlisting">[def __to_be__] |
| </pre> |
| <p> |
| And try again: |
| </p> |
| <p> |
| To be or not to be |
| </p> |
| <p> |
| Yes!<sup>[<a name="id3240872" href="#ftn.id3240872" class="footnote">8</a>]</sup> |
| </p> |
| </div> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="quickbook.syntax.block"></a><a class="link" href="syntax.html#quickbook.syntax.block" title="Block Level Elements">Block Level Elements</a> |
| </h3></div></div></div> |
| <div class="toc"><dl> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.block.document">Document</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.block.section">Section</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.block.xinclude">xinclude</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.block.paragraphs">Paragraphs</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.block.lists">Lists</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.block.code">Code</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.block.escape_back">Escaping Back To |
| QuickBook</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.block.preformatted">Preformatted</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.block.blockquote">Blockquote</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.block.admonitions">Admonitions</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.block.headings">Headings</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.block.generic_heading">Generic Heading</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.block.macros">Macros</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.block.predefined_macros">Predefined |
| Macros</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.block.templates">Templates</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.block.blurbs">Blurbs</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.block.tables">Tables</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.block.variable_lists">Variable Lists</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.block.include">Include</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.block.import">Import</a></span></dt> |
| </dl></div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.block.document"></a><a class="link" href="syntax.html#quickbook.syntax.block.document" title="Document">Document</a> |
| </h4></div></div></div> |
| <p> |
| Every document must begin with a Document Info section, which should look |
| like this: |
| </p> |
| <pre class="programlisting">[document-type The Document Title |
| [quickbook 1.5] |
| [version 1.0] |
| [id the_document_name] |
| [dirname the_document_dir] |
| [copyright 2000 2002 2003 Joe Blow, Jane Doe] |
| [purpose The document's reason for being] |
| [category The document's category] |
| [authors [Blow, Joe] [Doe, Jane]] |
| [license The document's license] |
| [source-mode source-type] |
| ] |
| </pre> |
| <p> |
| Where document-type is one of: |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> |
| <li class="listitem"> |
| book |
| </li> |
| <li class="listitem"> |
| article |
| </li> |
| <li class="listitem"> |
| library |
| </li> |
| <li class="listitem"> |
| chapter |
| </li> |
| <li class="listitem"> |
| part |
| </li> |
| <li class="listitem"> |
| appendix |
| </li> |
| <li class="listitem"> |
| preface |
| </li> |
| <li class="listitem"> |
| qandadiv |
| </li> |
| <li class="listitem"> |
| qandaset |
| </li> |
| <li class="listitem"> |
| reference |
| </li> |
| <li class="listitem"> |
| set |
| </li> |
| </ul></div> |
| <p> |
| quickbook 1.5 declares the version of quickbook the document is written |
| for. In its absence, version 1.1 is assumed. |
| </p> |
| <p> |
| <code class="literal">version</code>, <code class="literal">id</code>, <code class="literal">dirname</code>, |
| <code class="literal">copyright</code>, <code class="literal">purpose</code>, <code class="literal">category</code>, |
| <code class="literal">authors</code>, <code class="literal">license</code>, <code class="literal">last-revision</code> |
| and <code class="literal">source-mode</code> are optional information. |
| </p> |
| <p> |
| <code class="literal">dirname</code>, <code class="literal">purpose</code> and <code class="literal">category</code> |
| are boostbook attributes which are only valid for <code class="literal">library</code> |
| documents. If you use them for other document types, quickbook will warn |
| about them, but still use them, generating invalid markup, that's just |
| ignored by the style sheets. |
| </p> |
| <p> |
| <code class="literal">source-type</code> is a lowercase string setting the initial |
| <a class="link" href="syntax.html#quickbook.syntax.phrase.source_mode" title="Source Mode">Source Mode</a>. |
| If the <code class="literal">source-mode</code> field is omitted, a default value |
| of <code class="literal">c++</code> will be used. |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.block.section"></a><a class="link" href="syntax.html#quickbook.syntax.block.section" title="Section">Section</a> |
| </h4></div></div></div> |
| <p> |
| Starting a new section is accomplished with: |
| </p> |
| <pre class="programlisting">[section:id The Section Title] |
| </pre> |
| <p> |
| where <span class="emphasis"><em>id</em></span> is optional. id will be the filename of the |
| generated section. If it is not present, "The Section Title" |
| will be normalized and become the id. Valid characters are <code class="literal">a-Z</code>, |
| <code class="literal">A-Z</code>, <code class="literal">0-9</code> and <code class="literal">_</code>. |
| All non-valid characters are converted to underscore and all upper-case |
| are converted to lower case. Thus: "The Section Title" will be |
| normalized to "the_section_title". |
| </p> |
| <p> |
| End a section with: |
| </p> |
| <pre class="programlisting">[endsect] |
| </pre> |
| <p> |
| Sections can nest, and that results in a hierarchy in the table of contents. |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.block.xinclude"></a><a class="link" href="syntax.html#quickbook.syntax.block.xinclude" title="xinclude">xinclude</a> |
| </h4></div></div></div> |
| <p> |
| You can include another XML file with: |
| </p> |
| <pre class="programlisting">[xinclude file.xml] |
| </pre> |
| <p> |
| This is useful when file.xml has been generated by Doxygen and contains |
| your reference section. |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.block.paragraphs"></a><a class="link" href="syntax.html#quickbook.syntax.block.paragraphs" title="Paragraphs">Paragraphs</a> |
| </h4></div></div></div> |
| <p> |
| Paragraphs start left-flushed and are terminated by two or more newlines. |
| No markup is needed for paragraphs. QuickBook automatically detects paragraphs |
| from the context. Block markups [section, endsect, h1, h2, h3, h4, h5, |
| h6, blurb, (block-quote) ':', pre, def, table and include ] may also terminate |
| a paragraph. This is a new paragraph... |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.block.lists"></a><a class="link" href="syntax.html#quickbook.syntax.block.lists" title="Lists">Lists</a> |
| </h4></div></div></div> |
| <div class="toc"><dl> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.block.lists.ordered_lists">Ordered |
| lists</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.block.lists.list_hierarchies">List |
| Hierarchies</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.block.lists.long_list_lines">Long |
| List Lines</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.block.lists.unordered_lists">Unordered |
| lists</a></span></dt> |
| <dt><span class="section"><a href="syntax.html#quickbook.syntax.block.lists.mixed_lists">Mixed lists</a></span></dt> |
| </dl></div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h5 class="title"> |
| <a name="quickbook.syntax.block.lists.ordered_lists"></a><a class="link" href="syntax.html#quickbook.syntax.block.lists.ordered_lists" title="Ordered lists">Ordered |
| lists</a> |
| </h5></div></div></div> |
| <pre class="programlisting"># One |
| # Two |
| # Three |
| </pre> |
| <p> |
| will generate: |
| </p> |
| <div class="orderedlist"><ol class="orderedlist" type="1"> |
| <li class="listitem"> |
| One |
| </li> |
| <li class="listitem"> |
| Two |
| </li> |
| <li class="listitem"> |
| Three |
| </li> |
| </ol></div> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h5 class="title"> |
| <a name="quickbook.syntax.block.lists.list_hierarchies"></a><a class="link" href="syntax.html#quickbook.syntax.block.lists.list_hierarchies" title="List Hierarchies">List |
| Hierarchies</a> |
| </h5></div></div></div> |
| <p> |
| List hierarchies are supported. Example: |
| </p> |
| <pre class="programlisting"># One |
| # Two |
| # Three |
| # Three.a |
| # Three.b |
| # Three.c |
| # Four |
| # Four.a |
| # Four.a.i |
| # Four.a.ii |
| # Five |
| </pre> |
| <p> |
| will generate: |
| </p> |
| <div class="orderedlist"><ol class="orderedlist" type="1"> |
| <li class="listitem"> |
| One |
| </li> |
| <li class="listitem"> |
| Two |
| </li> |
| <li class="listitem"> |
| <p class="simpara"> |
| Three |
| </p> |
| <div class="orderedlist"><ol class="orderedlist" type="a"> |
| <li class="listitem"> |
| Three.a |
| </li> |
| <li class="listitem"> |
| Three.b |
| </li> |
| <li class="listitem"> |
| Three.c |
| </li> |
| </ol></div> |
| </li> |
| <li class="listitem"> |
| <p class="simpara"> |
| Fourth |
| </p> |
| <div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"> |
| <p class="simpara"> |
| Four.a |
| </p> |
| <div class="orderedlist"><ol class="orderedlist" type="i"> |
| <li class="listitem"> |
| Four.a.i |
| </li> |
| <li class="listitem"> |
| Four.a.ii |
| </li> |
| </ol></div> |
| </li></ol></div> |
| </li> |
| <li class="listitem"> |
| Five |
| </li> |
| </ol></div> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h5 class="title"> |
| <a name="quickbook.syntax.block.lists.long_list_lines"></a><a class="link" href="syntax.html#quickbook.syntax.block.lists.long_list_lines" title="Long List Lines">Long |
| List Lines</a> |
| </h5></div></div></div> |
| <p> |
| Long lines will be wrapped appropriately. Example: |
| </p> |
| <pre class="programlisting"># A short item. |
| # A very long item. A very long item. A very long item. |
| A very long item. A very long item. A very long item. |
| A very long item. A very long item. A very long item. |
| A very long item. A very long item. A very long item. |
| A very long item. A very long item. A very long item. |
| # A short item. |
| </pre> |
| <div class="orderedlist"><ol class="orderedlist" type="1"> |
| <li class="listitem"> |
| A short item. |
| </li> |
| <li class="listitem"> |
| 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. |
| </li> |
| <li class="listitem"> |
| A short item. |
| </li> |
| </ol></div> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h5 class="title"> |
| <a name="quickbook.syntax.block.lists.unordered_lists"></a><a class="link" href="syntax.html#quickbook.syntax.block.lists.unordered_lists" title="Unordered lists">Unordered |
| lists</a> |
| </h5></div></div></div> |
| <pre class="programlisting">* First |
| * Second |
| * Third |
| </pre> |
| <p> |
| will generate: |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> |
| <li class="listitem"> |
| First |
| </li> |
| <li class="listitem"> |
| Second |
| </li> |
| <li class="listitem"> |
| Third |
| </li> |
| </ul></div> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h5 class="title"> |
| <a name="quickbook.syntax.block.lists.mixed_lists"></a><a class="link" href="syntax.html#quickbook.syntax.block.lists.mixed_lists" title="Mixed lists">Mixed lists</a> |
| </h5></div></div></div> |
| <p> |
| Mixed lists (ordered and unordered) are supported. Example: |
| </p> |
| <pre class="programlisting"># One |
| # Two |
| # Three |
| * Three.a |
| * Three.b |
| * Three.c |
| # Four |
| </pre> |
| <p> |
| will generate: |
| </p> |
| <div class="orderedlist"><ol class="orderedlist" type="1"> |
| <li class="listitem"> |
| One |
| </li> |
| <li class="listitem"> |
| Two |
| </li> |
| <li class="listitem"> |
| <p class="simpara"> |
| Three |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> |
| <li class="listitem"> |
| Three.a |
| </li> |
| <li class="listitem"> |
| Three.b |
| </li> |
| <li class="listitem"> |
| Three.c |
| </li> |
| </ul></div> |
| </li> |
| <li class="listitem"> |
| Four |
| </li> |
| </ol></div> |
| <p> |
| And... |
| </p> |
| <pre class="programlisting"># 1 |
| * 1.a |
| # 1.a.1 |
| # 1.a.2 |
| * 1.b |
| # 2 |
| * 2.a |
| * 2.b |
| # 2.b.1 |
| # 2.b.2 |
| * 2.b.2.a |
| * 2.b.2.b |
| </pre> |
| <p> |
| will generate: |
| </p> |
| <div class="orderedlist"><ol class="orderedlist" type="1"> |
| <li class="listitem"> |
| <p class="simpara"> |
| 1 |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> |
| <li class="listitem"> |
| <p class="simpara"> |
| 1.a |
| </p> |
| <div class="orderedlist"><ol class="orderedlist" type="a"> |
| <li class="listitem"> |
| 1.a.1 |
| </li> |
| <li class="listitem"> |
| 1.a.2 |
| </li> |
| </ol></div> |
| </li> |
| <li class="listitem"> |
| 1.b |
| </li> |
| </ul></div> |
| </li> |
| <li class="listitem"> |
| <p class="simpara"> |
| 2 |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> |
| <li class="listitem"> |
| 2.a |
| </li> |
| <li class="listitem"> |
| <p class="simpara"> |
| 2.b |
| </p> |
| <div class="orderedlist"><ol class="orderedlist" type="a"> |
| <li class="listitem"> |
| 2.b.1 |
| </li> |
| <li class="listitem"> |
| <p class="simpara"> |
| 2.b.2 |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" type="circle"> |
| <li class="listitem"> |
| 2.b.2.a |
| </li> |
| <li class="listitem"> |
| 2.b.2.b |
| </li> |
| </ul></div> |
| </li> |
| </ol></div> |
| </li> |
| </ul></div> |
| </li> |
| </ol></div> |
| </div> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.block.code"></a><a class="link" href="syntax.html#quickbook.syntax.block.code" title="Code">Code</a> |
| </h4></div></div></div> |
| <p> |
| Preformatted code starts with a space or a tab. The code will be syntax |
| highlighted according to the current <a class="link" href="syntax.html#quickbook.syntax.phrase.source_mode" title="Source Mode">Source |
| Mode</a>: |
| </p> |
| <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span> |
| |
| <span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> |
| <span class="special">{</span> |
| <span class="comment">// Sample code |
| </span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Hello, World\n"</span><span class="special">;</span> |
| <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> |
| <span class="special">}</span> |
| </pre> |
| <pre class="programlisting"><span class="keyword">import</span> <span class="identifier">cgi</span> |
| |
| <span class="keyword">def</span> <span class="identifier">cookForHtml</span><span class="special">(</span><span class="identifier">text</span><span class="special">):</span> |
| <span class="string">'''"Cooks" the input text for HTML.'''</span> |
| |
| <span class="keyword">return</span> <span class="identifier">cgi</span><span class="special">.</span><span class="identifier">escape</span><span class="special">(</span><span class="identifier">text</span><span class="special">)</span> |
| </pre> |
| <p> |
| Macros that are already defined are expanded in source code. Example: |
| </p> |
| <pre class="programlisting">[def __array__ [@http://www.boost.org/doc/html/array/reference.html array]] |
| [def __boost__ [@http://www.boost.org/libs/libraries.htm boost]] |
| |
| using __boost__::__array__; |
| </pre> |
| <p> |
| Generates: |
| </p> |
| <pre class="programlisting"><span class="keyword">using</span> <a href="http://www.boost.org/libs/libraries.htm" target="_top">boost</a><span class="special">::</span><a href="http://www.boost.org/doc/html/array/reference.html" target="_top">array</a><span class="special">;</span> |
| </pre> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.block.escape_back"></a><a class="link" href="syntax.html#quickbook.syntax.block.escape_back" title="Escaping Back To QuickBook">Escaping Back To |
| QuickBook</a> |
| </h4></div></div></div> |
| <p> |
| Inside code, code blocks and inline code, QuickBook does not allow any |
| markup to avoid conflicts with the target syntax (e.g. c++). In case you |
| need to switch back to QuickBook markup inside code, you can do so using |
| a language specific <span class="emphasis"><em>escape-back</em></span> delimiter. In C++ |
| and Python, the delimiter is the double tick (back-quote): "``" |
| and "``". Example: |
| </p> |
| <pre class="programlisting">void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``() |
| { |
| } |
| </pre> |
| <p> |
| Will generate: |
| </p> |
| <pre class="programlisting"><span class="keyword">void</span> <a href="http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz" target="_top">foo</a><span class="special">()</span> |
| <span class="special">{</span> |
| <span class="special">}</span> |
| </pre> |
| <p> |
| When escaping from code to QuickBook, only phrase level markups are allowed. |
| Block level markups like lists, tables etc. are not allowed. |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.block.preformatted"></a><a class="link" href="syntax.html#quickbook.syntax.block.preformatted" title="Preformatted">Preformatted</a> |
| </h4></div></div></div> |
| <p> |
| Sometimes, you don't want some preformatted text to be parsed as C++. In |
| such cases, use the <code class="literal">[pre ... ]</code> markup block. |
| </p> |
| <pre class="programlisting">[pre |
| |
| Some *preformatted* text Some *preformatted* text |
| |
| Some *preformatted* text Some *preformatted* text |
| |
| Some *preformatted* text Some *preformatted* text |
| |
| ] |
| </pre> |
| <p> |
| Spaces, tabs and newlines are rendered as-is. Unlike all quickbook block |
| level markup, pre (and Code) are the only ones that allow multiple newlines. |
| The markup above will generate: |
| </p> |
| <pre class="programlisting">Some <span class="bold"><strong>preformatted</strong></span> text Some <span class="bold"><strong>preformatted</strong></span> text |
| |
| Some <span class="bold"><strong>preformatted</strong></span> text Some <span class="bold"><strong>preformatted</strong></span> text |
| |
| Some <span class="bold"><strong>preformatted</strong></span> text Some <span class="bold"><strong>preformatted</strong></span> text |
| |
| </pre> |
| <p> |
| Notice that unlike Code, phrase markup such as font style is still permitted |
| inside <code class="literal">pre</code> blocks. |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.block.blockquote"></a><a class="link" href="syntax.html#quickbook.syntax.block.blockquote" title="Blockquote">Blockquote</a> |
| </h4></div></div></div> |
| <pre class="programlisting">[:sometext...] |
| </pre> |
| <div class="blockquote"><blockquote class="blockquote"><p> |
| Indents the paragraph. This applies to one paragraph only. |
| </p></blockquote></div> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.block.admonitions"></a><a class="link" href="syntax.html#quickbook.syntax.block.admonitions" title="Admonitions">Admonitions</a> |
| </h4></div></div></div> |
| <pre class="programlisting">[note This is a note] |
| [tip This is a tip] |
| [important This is important] |
| [caution This is a caution] |
| [warning This is a warning] |
| </pre> |
| <p> |
| generates <a href="http://www.docbook.org/" target="_top">DocBook</a> admonitions: |
| </p> |
| <div class="note"><table border="0" summary="Note"> |
| <tr> |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td> |
| <th align="left">Note</th> |
| </tr> |
| <tr><td align="left" valign="top"><p> |
| This is a note |
| </p></td></tr> |
| </table></div> |
| <div class="tip"><table border="0" summary="Tip"> |
| <tr> |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../doc/src/images/tip.png"></td> |
| <th align="left">Tip</th> |
| </tr> |
| <tr><td align="left" valign="top"><p> |
| This is a tip |
| </p></td></tr> |
| </table></div> |
| <div class="important"><table border="0" summary="Important"> |
| <tr> |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../doc/src/images/important.png"></td> |
| <th align="left">Important</th> |
| </tr> |
| <tr><td align="left" valign="top"><p> |
| This is important |
| </p></td></tr> |
| </table></div> |
| <div class="caution"><table border="0" summary="Caution"> |
| <tr> |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../doc/src/images/caution.png"></td> |
| <th align="left">Caution</th> |
| </tr> |
| <tr><td align="left" valign="top"><p> |
| This is a caution |
| </p></td></tr> |
| </table></div> |
| <div class="warning"><table border="0" summary="Warning"> |
| <tr> |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../doc/src/images/warning.png"></td> |
| <th align="left">Warning</th> |
| </tr> |
| <tr><td align="left" valign="top"><p> |
| This is a warning |
| </p></td></tr> |
| </table></div> |
| <p> |
| These are the only admonitions supported by <a href="http://www.docbook.org/" target="_top">DocBook</a>. |
| So, for example <code class="literal">[information This is some information]</code> |
| is unlikely to produce the desired effect. |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.block.headings"></a><a class="link" href="syntax.html#quickbook.syntax.block.headings" title="Headings">Headings</a> |
| </h4></div></div></div> |
| <pre class="programlisting">[h1 Heading 1] |
| [h2 Heading 2] |
| [h3 Heading 3] |
| [h4 Heading 4] |
| [h5 Heading 5] |
| [h6 Heading 6] |
| </pre> |
| <a name="quickbook.syntax.block.headings.heading_1"></a><h2> |
| <a name="id3242428"></a> |
| <a class="link" href="syntax.html#quickbook.syntax.block.headings.heading_1">Heading 1</a> |
| </h2> |
| <a name="quickbook.syntax.block.headings.heading_2"></a><h3> |
| <a name="id3242449"></a> |
| <a class="link" href="syntax.html#quickbook.syntax.block.headings.heading_2">Heading 2</a> |
| </h3> |
| <a name="quickbook.syntax.block.headings.heading_3"></a><h4> |
| <a name="id3242471"></a> |
| <a class="link" href="syntax.html#quickbook.syntax.block.headings.heading_3">Heading 3</a> |
| </h4> |
| <a name="quickbook.syntax.block.headings.heading_4"></a><h5> |
| <a name="id3242492"></a> |
| <a class="link" href="syntax.html#quickbook.syntax.block.headings.heading_4">Heading 4</a> |
| </h5> |
| <a name="quickbook.syntax.block.headings.heading_5"></a><h6> |
| <a name="id3242513"></a> |
| <a class="link" href="syntax.html#quickbook.syntax.block.headings.heading_5">Heading 5</a> |
| </h6> |
| <a name="quickbook.syntax.block.headings.heading_6"></a><h5> |
| <a name="id3242534"></a> |
| <a class="link" href="syntax.html#quickbook.syntax.block.headings.heading_6">Heading 6</a> |
| </h5> |
| <p> |
| Headings 1-3 [h1 h2 and h3] will automatically have anchors with normalized |
| names with <code class="literal">name="document_id.section_id.normalized_header_text"</code> |
| (i.e. valid characters are <code class="literal">a-z</code>, <code class="literal">A-Z</code>, |
| <code class="literal">0-9</code> and <code class="literal">_</code>. 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 <code class="literal">section_2.heading_1</code>). |
| You can use: |
| </p> |
| <pre class="programlisting">[link document_id.section_id.normalized_header_text The link text] |
| </pre> |
| <p> |
| to link to them. See <a class="link" href="syntax.html#quickbook.syntax.phrase.anchor_links" title="Anchor links">Anchor |
| links</a> and <a class="link" href="syntax.html#quickbook.syntax.block.section" title="Section">Section</a> |
| for more info. |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.block.generic_heading"></a><a class="link" href="syntax.html#quickbook.syntax.block.generic_heading" title="Generic Heading">Generic Heading</a> |
| </h4></div></div></div> |
| <p> |
| In cases when you don't want to care about the heading level (1 to 6), |
| you can use the <span class="emphasis"><em>Generic Heading</em></span>: |
| </p> |
| <pre class="programlisting">[heading Heading] |
| </pre> |
| <p> |
| The <span class="emphasis"><em>Generic Heading</em></span> assumes the level, plus one, of |
| the innermost section where it is placed. For example, if it is placed |
| in the outermost section, then, it assumes <span class="emphasis"><em>h2</em></span>. |
| </p> |
| <p> |
| Headings are often used as an alternative to sections. It is used particularly |
| if you do not want to start a new section. In many cases, however, headings |
| in a particular section is just flat. Example: |
| </p> |
| <pre class="programlisting">[section A] |
| [h2 X] |
| [h2 Y] |
| [h2 Z] |
| [endsect] |
| </pre> |
| <p> |
| Here we use h2 assuming that section A is the outermost level. If it is |
| placed in an inner level, you'll have to use h3, h4, etc. depending on |
| where the section is. In general, it is the section level plus one. It |
| is rather tedious, however, to scan the section level everytime. If you |
| rewrite the example above as shown below, this will be automatic: |
| </p> |
| <pre class="programlisting">[section A] |
| [heading X] |
| [heading Y] |
| [heading Z] |
| [endsect] |
| </pre> |
| <p> |
| They work well regardless where you place them. You can rearrange sections |
| at will without any extra work to ensure correct heading levels. In fact, |
| with <span class="emphasis"><em>section</em></span> and <span class="emphasis"><em>heading</em></span>, you |
| have all you need. <span class="emphasis"><em>h1</em></span>..<span class="emphasis"><em>h6</em></span> becomes |
| redundant. <span class="emphasis"><em>h1</em></span>..<span class="emphasis"><em>h6</em></span> might be deprecated |
| in the future. |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.block.macros"></a><a class="link" href="syntax.html#quickbook.syntax.block.macros" title="Macros">Macros</a> |
| </h4></div></div></div> |
| <pre class="programlisting">[def macro_identifier some text] |
| </pre> |
| <p> |
| When a macro is defined, the identifier replaces the text anywhere in the |
| file, in paragraphs, in markups, etc. macro_identifier is a string of non- |
| white space characters except ']'. A macro may not follow an alphabetic |
| character or the underscore. The replacement text can be any phrase (even |
| marked up). Example: |
| </p> |
| <pre class="programlisting">[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&type=1]] |
| sf_logo |
| </pre> |
| <p> |
| Now everywhere the sf_logo is placed, the picture will be inlined. |
| </p> |
| <p> |
| <span class="inlinemediaobject"></span> |
| </p> |
| <div class="tip"><table border="0" summary="Tip"> |
| <tr> |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../doc/src/images/tip.png"></td> |
| <th align="left">Tip</th> |
| </tr> |
| <tr><td align="left" valign="top"><p> |
| It's a good idea to use macro identifiers that are distinguishable. For |
| instance, in this document, macro identifiers have two leading and trailing |
| underscores (e.g. <code class="literal">__spirit__</code>). The reason is to avoid unwanted |
| macro replacement. |
| </p></td></tr> |
| </table></div> |
| <p> |
| Links (URLS) and images are good candidates for macros. <span class="bold"><strong>1</strong></span>) |
| They tend to change a lot. It is a good idea to place all links and images |
| in one place near the top to make it easy to make changes. <span class="bold"><strong>2</strong></span>) |
| The syntax is not pretty. It's easier to read and write, e.g. <code class="literal">__spirit__</code> |
| than <code class="literal">[@http://spirit.sourceforge.net Spirit]</code>. |
| </p> |
| <p> |
| Some more examples: |
| </p> |
| <pre class="programlisting">[def :-) [$theme/smiley.png]] |
| [def __spirit__ [@http://spirit.sourceforge.net Spirit]] |
| </pre> |
| <p> |
| (See <a class="link" href="syntax.html#quickbook.syntax.phrase.images" title="Images">Images</a> and |
| <a class="link" href="syntax.html#quickbook.syntax.phrase.links" title="Links">Links</a>) |
| </p> |
| <p> |
| Invoking these macros: |
| </p> |
| <pre class="programlisting">Hi __spirit__ :-) |
| </pre> |
| <p> |
| will generate this: |
| </p> |
| <p> |
| Hi <a href="http://spirit.sourceforge.net" target="_top">Spirit</a> <span class="inlinemediaobject"><img src="../../src/images/smiley.png" alt="smiley"></span> |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.block.predefined_macros"></a><a class="link" href="syntax.html#quickbook.syntax.block.predefined_macros" title="Predefined Macros">Predefined |
| Macros</a> |
| </h4></div></div></div> |
| <p> |
| Quickbook has some predefined macros that you can already use. |
| </p> |
| <div class="table"> |
| <a name="quickbook.syntax.block.predefined_macros.predefined_macros"></a><p class="title"><b>Table 31.3. Predefined Macros</b></p> |
| <div class="table-contents"><table class="table" summary="Predefined Macros"> |
| <colgroup> |
| <col> |
| <col> |
| <col> |
| </colgroup> |
| <thead><tr> |
| <th> |
| <p> |
| Macro |
| </p> |
| </th> |
| <th> |
| <p> |
| Meaning |
| </p> |
| </th> |
| <th> |
| <p> |
| Example |
| </p> |
| </th> |
| </tr></thead> |
| <tbody> |
| <tr> |
| <td> |
| <p> |
| __DATE__ |
| </p> |
| </td> |
| <td> |
| <p> |
| Today's date |
| </p> |
| </td> |
| <td> |
| <p> |
| 2010-Nov-10 |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| __TIME__ |
| </p> |
| </td> |
| <td> |
| <p> |
| The current time |
| </p> |
| </td> |
| <td> |
| <p> |
| 12:46:05 AM |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| __FILENAME__ |
| </p> |
| </td> |
| <td> |
| <p> |
| Quickbook source filename |
| </p> |
| </td> |
| <td> |
| <p> |
| /Users/daniel/boost/release/boost-release/tools/quickbook/doc/quickbook.qbk |
| </p> |
| </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <br class="table-break"> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.block.templates"></a><a class="link" href="syntax.html#quickbook.syntax.block.templates" title="Templates">Templates</a> |
| </h4></div></div></div> |
| <p> |
| Templates provide a more versatile text substitution mechanism. Templates |
| come in handy when you need to create parameterizable, multi-line, boilerplate |
| text that you specify once and expand many times. Templates accept one |
| or more arguments. These arguments act like place-holders for text replacement. |
| Unlike simple macros, which are limited to phrase level markup, templates |
| can contain block level markup (e.g. paragraphs, code blocks and tables). |
| </p> |
| <p> |
| Example template: |
| </p> |
| <pre class="programlisting">[template person[name age what] |
| |
| Hi, my name is [name]. I am [age] years old. I am a [what]. |
| |
| ] |
| </pre> |
| <a name="quickbook.syntax.block.templates.template_identifier"></a><h6> |
| <a name="id3243093"></a> |
| <a class="link" href="syntax.html#quickbook.syntax.block.templates.template_identifier">Template |
| Identifier</a> |
| </h6> |
| <p> |
| Template identifiers can either consist of: |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> |
| <li class="listitem"> |
| 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. |
| </li> |
| <li class="listitem"> |
| A single character punctuation (a non-alphanumeric printable character) |
| </li> |
| </ul></div> |
| <a name="quickbook.syntax.block.templates.formal_template_arguments"></a><h6> |
| <a name="id3243141"></a> |
| <a class="link" href="syntax.html#quickbook.syntax.block.templates.formal_template_arguments">Formal |
| Template Arguments</a> |
| </h6> |
| <p> |
| Template formal arguments are identifiers consisting of an initial alphabetic |
| character or the underscore, followed by zero or more alphanumeric characters |
| or the underscore. This is similar to your typical C/C++ identifier. |
| </p> |
| <p> |
| A template formal argument temporarily hides a template of the same name |
| at the point where the <a class="link" href="syntax.html#quickbook.syntax.block.templates.template_expansion">template |
| is expanded</a>. Note that the body of the <code class="literal">person</code> |
| template above refers to <code class="literal">name</code> <code class="literal">age</code> |
| and <code class="literal">what</code> as <code class="literal">[name]</code> <code class="literal">[age]</code> |
| and <code class="literal">[what]</code>. <code class="literal">name</code> <code class="literal">age</code> |
| and <code class="literal">what</code> are actually templates that exist in the duration |
| of the template call. |
| </p> |
| <a name="quickbook.syntax.block.templates.template_body"></a><h6> |
| <a name="id3243246"></a> |
| <a class="link" href="syntax.html#quickbook.syntax.block.templates.template_body">Template |
| Body</a> |
| </h6> |
| <p> |
| The template body can be just about any QuickBook block or phrase. There |
| are actually two forms. Templates may be phrase or block level. Phrase |
| templates are of the form: |
| </p> |
| <pre class="programlisting">[template sample[arg1 arg2...argN] replacement text... ] |
| </pre> |
| <p> |
| Block templates are of the form: |
| </p> |
| <pre class="programlisting">[template sample[arg1 arg2...argN] |
| replacement text... |
| ] |
| </pre> |
| <p> |
| The basic rule is as follows: if a newline immediately follows the argument |
| list, then it is a block template, otherwise, it is a phrase template. |
| Phrase templates are typically expanded as part of phrases. Like macros, |
| block level elements are not allowed in phrase templates. |
| </p> |
| <a name="quickbook.syntax.block.templates.template_expansion"></a><h6> |
| <a name="id3243299"></a> |
| <a class="link" href="syntax.html#quickbook.syntax.block.templates.template_expansion">Template |
| Expansion</a> |
| </h6> |
| <p> |
| You expand a template this way: |
| </p> |
| <pre class="programlisting">[template_identifier arg1..arg2..arg3] |
| </pre> |
| <p> |
| At template expansion, you supply the actual arguments. The template will |
| be expanded with your supplied arguments. Example: |
| </p> |
| <pre class="programlisting">[person James Bond..39..Spy] |
| [person Santa Clause..87..Big Red Fatso] |
| </pre> |
| <p> |
| Which will expand to: |
| </p> |
| <p> |
| Hi, my name is James Bond. I am 39 years old. I am a Spy. |
| </p> |
| <p> |
| Hi, my name is Santa Clause. I am 87 years old. I am a Big Red Fatso. |
| </p> |
| <div class="caution"><table border="0" summary="Caution"> |
| <tr> |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../doc/src/images/caution.png"></td> |
| <th align="left">Caution</th> |
| </tr> |
| <tr><td align="left" valign="top"><p> |
| A word of caution: Templates are recursive. A template can call another |
| template or even itself, directly or indirectly. There are no control |
| structures in QuickBook (yet) so this will always mean infinite recursion. |
| QuickBook can detect this situation and report an error if recursion |
| exceeds a certain limit. |
| </p></td></tr> |
| </table></div> |
| <p> |
| Each actual argument can be a word, a text fragment or just about any |
| <a class="link" href="syntax.html#quickbook.syntax.phrase" title="Phrase Level Elements">QuickBook phrase</a>. Arguments |
| are separated by the double dot <code class="literal">".."</code> and terminated |
| by the close parenthesis. |
| </p> |
| <a name="quickbook.syntax.block.templates.nullary_templates"></a><h6> |
| <a name="id3243390"></a> |
| <a class="link" href="syntax.html#quickbook.syntax.block.templates.nullary_templates">Nullary |
| Templates</a> |
| </h6> |
| <p> |
| Nullary templates look and act like simple macros. Example: |
| </p> |
| <pre class="programlisting">[template alpha[]'''&#945;'''] |
| [template beta[]'''&#946;'''] |
| </pre> |
| <p> |
| Expanding: |
| </p> |
| <pre class="programlisting">Some squigles...[*[alpha][beta]]</pre> |
| <p> |
| We have: |
| </p> |
| <p> |
| Some squiggles...<span class="bold"><strong>αβ</strong></span> |
| </p> |
| <p> |
| The difference with macros are |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> |
| <li class="listitem"> |
| The explicit <a class="link" href="syntax.html#quickbook.syntax.block.templates.template_expansion">template |
| expansion syntax</a>. This is an advantage because, now, we don't |
| have to use obscure naming conventions like double underscores (e.g. |
| __alpha__) to avoid unwanted macro replacement. |
| </li> |
| <li class="listitem"> |
| 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. |
| </li> |
| </ul></div> |
| <p> |
| The empty brackets after the template identifier (<code class="literal">alpha[]</code>) |
| indicates no arguments. If the template body does not look like a template |
| argument list, we can elide the empty brackets. Example: |
| </p> |
| <pre class="programlisting">[template aristotle_quote Aristotle: [*['Education is the best provision |
| for the journey to old age.]]] |
| </pre> |
| <p> |
| Expanding: |
| </p> |
| <pre class="programlisting">Here's a quote from [aristotle_quote]. |
| </pre> |
| <p> |
| We have: |
| </p> |
| <p> |
| Here's a quote from Aristotle: <span class="bold"><strong><span class="emphasis"><em>Education |
| is the best provision for the journey to old age.</em></span></strong></span>. |
| </p> |
| <p> |
| The disadvantage is that you can't avoid the space between the template |
| identifier, <code class="computeroutput"><span class="identifier">aristotle_quote</span></code>, |
| and the template body "Aristotle...". This space will be part |
| of the template body. If that space is unwanted, use empty brackets or |
| use the space escape: "<code class="computeroutput"><span class="special">\</span> </code>". |
| Example: |
| </p> |
| <pre class="programlisting">[template tag\ _tag] |
| </pre> |
| <p> |
| Then expanding: |
| </p> |
| <pre class="programlisting">`struct` x[tag]; |
| </pre> |
| <p> |
| We have: |
| </p> |
| <p> |
| <code class="computeroutput"><span class="keyword">struct</span></code> x_tag; |
| </p> |
| <p> |
| You have a couple of ways to do it. I personally prefer the explicit empty |
| brackets, though. |
| </p> |
| <a name="quickbook.syntax.block.templates.simple_arguments"></a><h6> |
| <a name="id3243597"></a> |
| <a class="link" href="syntax.html#quickbook.syntax.block.templates.simple_arguments">Simple |
| Arguments</a> |
| </h6> |
| <p> |
| As mentioned, arguments are separated by the double dot <code class="literal">".."</code>. |
| Alternatively, if the double dot isn't used and more than one argument |
| is expected, QuickBook uses whitespace to separate the arguments, following |
| this logic: |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> |
| <li class="listitem"> |
| Break the last argument into two, at the first space found (<code class="literal">'', |
| '\n', \t' or '\r'</code>). |
| </li> |
| <li class="listitem"> |
| Repeat until there are enough arguments or if there are no more spaces |
| found (in which case, an error is reported). |
| </li> |
| </ul></div> |
| <p> |
| For example: |
| </p> |
| <pre class="programlisting">[template simple[a b c d] [a][b][c][d]] |
| [simple w x y z] |
| </pre> |
| <p> |
| will produce: |
| </p> |
| <p> |
| wxyz |
| </p> |
| <p> |
| "w x y z" is initially treated as a single argument because we |
| didn't supply any <code class="literal">".."</code> separators. However, |
| since <code class="literal">simple</code> expects 4 arguments, "w x y z" |
| is broken down iteratively (applying the logic above) until we have "w", |
| "x", "y" and "z". |
| </p> |
| <p> |
| QuickBook only tries to get the arguments it needs. For example: |
| </p> |
| <pre class="programlisting">[simple w x y z trail] |
| </pre> |
| <p> |
| will produce: |
| </p> |
| <p> |
| wxyz trail |
| </p> |
| <p> |
| The arguments being: "w", "x", "y" and "z |
| trail". |
| </p> |
| <div class="caution"><table border="0" summary="Caution"> |
| <tr> |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../doc/src/images/caution.png"></td> |
| <th align="left">Caution</th> |
| </tr> |
| <tr><td align="left" valign="top"><p> |
| The behavior described here is for QuickBook 1.5. In older versions you |
| could use both the double dot and whitespace as separators in the same |
| template call. If your document is marked up as an older version, it |
| will use the old behavior, which is described in the <a href="http://www.boost.org/doc/libs/1_40_0/doc/html/quickbook/syntax.html#quickbook.syntax.block.templates.simple_arguments" target="_top">QuickBook |
| 1.4 documentation</a>. |
| </p></td></tr> |
| </table></div> |
| <a name="quickbook.syntax.block.templates.punctuation_templates"></a><h6> |
| <a name="id3243740"></a> |
| <a class="link" href="syntax.html#quickbook.syntax.block.templates.punctuation_templates">Punctuation |
| Templates</a> |
| </h6> |
| <p> |
| With templates, one of our objectives is to allow us to rewrite QuickBook |
| in QuickBook (as a qbk library). For that to happen, we need to accommodate |
| single character punctuation templates which are fairly common in QuickBook. |
| You might have noticed that single character punctuations are allowed as |
| <a class="link" href="syntax.html#quickbook.syntax.block.templates.template_identifier">template |
| identifiers</a>. Example: |
| </p> |
| <pre class="programlisting">[template ![bar] <hey>[bar]</hey>] |
| </pre> |
| <p> |
| Now, expanding this: |
| </p> |
| <pre class="programlisting">[!baz] |
| </pre> |
| <p> |
| We will have: |
| </p> |
| <pre class="programlisting"><hey>baz</hey> |
| </pre> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.block.blurbs"></a><a class="link" href="syntax.html#quickbook.syntax.block.blurbs" title="Blurbs">Blurbs</a> |
| </h4></div></div></div> |
| <pre class="programlisting">[blurb :-) [*An eye catching advertisement or note...] |
| |
| __spirit__ is an object-oriented recursive-descent parser generator framework |
| implemented using template meta-programming techniques. Expression templates |
| allow us to approximate the syntax of Extended Backus-Normal Form (EBNF) |
| completely in C++. |
| ] |
| </pre> |
| <p> |
| will generate this: |
| </p> |
| <div class="sidebar"> |
| <p class="title"><b></b></p> |
| <p> |
| <span class="inlinemediaobject"><img src="../../src/images/smiley.png" alt="smiley"></span> <span class="bold"><strong>An eye catching advertisement |
| or note...</strong></span> |
| </p> |
| <p> |
| <a href="http://spirit.sourceforge.net" target="_top">Spirit</a> is an object-oriented |
| recursive-descent parser generator framework implemented using template |
| meta-programming techniques. Expression templates allow us to approximate |
| the syntax of Extended Backus-Normal Form (EBNF) completely in C++. |
| </p> |
| </div> |
| <div class="note"><table border="0" summary="Note"> |
| <tr> |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td> |
| <th align="left">Note</th> |
| </tr> |
| <tr><td align="left" valign="top"><p> |
| Prefer <a class="link" href="syntax.html#quickbook.syntax.block.admonitions" title="Admonitions">admonitions</a> |
| wherever appropriate. |
| </p></td></tr> |
| </table></div> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.block.tables"></a><a class="link" href="syntax.html#quickbook.syntax.block.tables" title="Tables">Tables</a> |
| </h4></div></div></div> |
| <pre class="programlisting">[table:id A Simple Table |
| [[Heading 1] [Heading 2] [Heading 3]] |
| [[R0-C0] [R0-C1] [R0-C2]] |
| [[R1-C0] [R1-C1] [R1-C2]] |
| [[R2-C0] [R2-C1] [R2-C2]] |
| ] |
| </pre> |
| <p> |
| will generate: |
| </p> |
| <div class="table"> |
| <a name="quickbook.syntax.block.tables.id"></a><p class="title"><b>Table 31.4. A Simple Table</b></p> |
| <div class="table-contents"><table class="table" summary="A Simple Table"> |
| <colgroup> |
| <col> |
| <col> |
| <col> |
| </colgroup> |
| <thead><tr> |
| <th> |
| <p> |
| Heading 1 |
| </p> |
| </th> |
| <th> |
| <p> |
| Heading 2 |
| </p> |
| </th> |
| <th> |
| <p> |
| Heading 3 |
| </p> |
| </th> |
| </tr></thead> |
| <tbody> |
| <tr> |
| <td> |
| <p> |
| R0-C0 |
| </p> |
| </td> |
| <td> |
| <p> |
| R0-C1 |
| </p> |
| </td> |
| <td> |
| <p> |
| R0-C2 |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| R1-C0 |
| </p> |
| </td> |
| <td> |
| <p> |
| R1-C1 |
| </p> |
| </td> |
| <td> |
| <p> |
| R1-C2 |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| R2-C0 |
| </p> |
| </td> |
| <td> |
| <p> |
| R2-C1 |
| </p> |
| </td> |
| <td> |
| <p> |
| R2-C2 |
| </p> |
| </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <br class="table-break"><p> |
| The table title is optional. The first row of the table is automatically |
| treated as the table header; that is, it is wrapped in <code class="literal"><thead>...</thead></code> |
| XML tags. Note that unlike the original QuickDoc, the columns are nested |
| in [cells... ]. |
| </p> |
| <p> |
| Giving tables an id is a new feature for quickbook 1.5 onwards. As with |
| sections, the id is optional. If the table has a title but no id, an id |
| will be generated from the title. The table above can be linked to using: |
| </p> |
| <pre class="programlisting">[link quickbook.syntax.block.tables.id link to table] |
| </pre> |
| <p> |
| which will generate: |
| </p> |
| <p> |
| <a class="link" href="syntax.html#quickbook.syntax.block.tables.id" title="Table 31.4. A Simple Table">link to table</a> |
| </p> |
| <p> |
| The syntax is free-format and allows big cells to be formatted nicely. |
| Example: |
| </p> |
| <pre class="programlisting">[table Table with fat cells |
| [[Heading 1] [Heading 2]] |
| [ |
| [Row 0, Col 0: a small cell] |
| [ |
| Row 0, Col 1: a big fat cell with paragraphs |
| |
| Boost provides free peer-reviewed portable C++ source libraries. |
| |
| We emphasize libraries that work well with the C++ Standard Library. |
| Boost libraries are intended to be widely useful, and usable across |
| a broad spectrum of applications. The Boost license encourages both |
| commercial and non-commercial use. |
| ] |
| ] |
| [ |
| [Row 1, Col 0: a small cell] |
| [Row 1, Col 1: a small cell] |
| ] |
| ] |
| </pre> |
| <p> |
| and thus: |
| </p> |
| <div class="table"> |
| <a name="quickbook.syntax.block.tables.table_with_fat_cells"></a><p class="title"><b>Table 31.5. Table with fat cells</b></p> |
| <div class="table-contents"><table class="table" summary="Table with fat cells"> |
| <colgroup> |
| <col> |
| <col> |
| </colgroup> |
| <thead><tr> |
| <th> |
| <p> |
| Heading 1 |
| </p> |
| </th> |
| <th> |
| <p> |
| Heading 2 |
| </p> |
| </th> |
| </tr></thead> |
| <tbody> |
| <tr> |
| <td> |
| <p> |
| Row 0, Col 0: a small cell |
| </p> |
| </td> |
| <td> |
| <p> |
| Row 0, Col 1: a big fat cell with paragraphs |
| </p> |
| <p> |
| Boost provides free peer-reviewed portable C++ source libraries. |
| We emphasize libraries that work well with the C++ Standard Library. |
| Boost libraries are intended to be widely useful, and usable |
| across a broad spectrum of applications. The Boost license encourages |
| both commercial and non-commercial use. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| Row 1, Col 0: a small cell |
| </p> |
| </td> |
| <td> |
| <p> |
| Row 1, Col 1: a small cell |
| </p> |
| </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <br class="table-break"><p> |
| Here's how to have preformatted blocks of code in a table cell: |
| </p> |
| <pre class="programlisting">[table Table with code |
| [[Comment] [Code]] |
| [ |
| [My first program] |
| [`` |
| #include <iostream> |
| |
| int main() |
| { |
| std::cout << "Hello, World!" << std::endl; |
| return 0; |
| } |
| ``] |
| ] |
| ] |
| </pre> |
| <div class="table"> |
| <a name="quickbook.syntax.block.tables.table_with_code"></a><p class="title"><b>Table 31.6. Table with code</b></p> |
| <div class="table-contents"><table class="table" summary="Table with code"> |
| <colgroup> |
| <col> |
| <col> |
| </colgroup> |
| <thead><tr> |
| <th> |
| <p> |
| Comment |
| </p> |
| </th> |
| <th> |
| <p> |
| Code |
| </p> |
| </th> |
| </tr></thead> |
| <tbody><tr> |
| <td> |
| <p> |
| My first program |
| </p> |
| </td> |
| <td> |
| <p> |
| |
| </p> |
| <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span> |
| |
| <span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> |
| <span class="special">{</span> |
| <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Hello, World!"</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> |
| <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> |
| <span class="special">}</span> |
| </pre> |
| <p> |
| </p> |
| </td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| <br class="table-break"> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.block.variable_lists"></a><a class="link" href="syntax.html#quickbook.syntax.block.variable_lists" title="Variable Lists">Variable Lists</a> |
| </h4></div></div></div> |
| <pre class="programlisting">[variablelist A Variable List |
| [[term 1] [The definition of term 1]] |
| [[term 2] [The definition of term 2]] |
| [[term 3] [ |
| The definition of term 3. |
| |
| Definitions may contain paragraphs. |
| ]] |
| ] |
| </pre> |
| <p> |
| will generate: |
| </p> |
| <div class="variablelist"> |
| <p class="title"><b>A Variable List</b></p> |
| <dl> |
| <dt><span class="term">term 1</span></dt> |
| <dd><p> |
| The definition of term 1 |
| </p></dd> |
| <dt><span class="term">term 2</span></dt> |
| <dd><p> |
| The definition of term 2 |
| </p></dd> |
| <dt><span class="term">term 3</span></dt> |
| <dd> |
| <p> |
| The definition of term 3. |
| </p> |
| <p> |
| Definitions may contain paragraphs. |
| </p> |
| </dd> |
| </dl> |
| </div> |
| <p> |
| The rules for variable lists are the same as for tables, except that only |
| 2 "columns" are allowed. The first column contains the terms, |
| and the second column contains the definitions. Those familiar with HTML |
| will recognize this as a "definition list". |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.block.include"></a><a class="link" href="syntax.html#quickbook.syntax.block.include" title="Include">Include</a> |
| </h4></div></div></div> |
| <p> |
| You can include one QuickBook file from another. The syntax is simply: |
| </p> |
| <pre class="programlisting">[include someother.qbk] |
| </pre> |
| <p> |
| The included file will be processed as if it had been cut and pasted into |
| the current document, with the following exceptions: |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> |
| <li class="listitem"> |
| The __FILENAME__ predefined macro will reflect the name of the file currently being |
| processed. |
| </li> |
| <li class="listitem"> |
| Any macros defined in the included file are scoped to that file. |
| </li> |
| </ul></div> |
| <p> |
| The <code class="literal">[include]</code> directive lets you specify a document |
| id to use for the included file. When this id is not explicitly specified, |
| the id defaults to the filename ("someother", in the example |
| above). You can specify the id like this: |
| </p> |
| <pre class="programlisting">[include:someid someother.qbk] |
| </pre> |
| <p> |
| All auto-generated anchors will use the document id as a unique prefix. |
| So for instance, if there is a top section in someother.qbk named "Intro", |
| the named anchor for that section will be "someid.intro", and |
| you can link to it with <code class="literal">[link someid.intro The Intro]</code>. |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="quickbook.syntax.block.import"></a><a class="link" href="syntax.html#quickbook.syntax.block.import" title="Import">Import</a> |
| </h4></div></div></div> |
| <p> |
| When documenting code, you'd surely need to present code from actual source |
| files. While it is possible to copy some code and paste them in your QuickBook |
| file, doing so is error prone and the extracted code in the documentation |
| tends to get out of sync with the actual code as the code evolves. The |
| problem, as always, is that once documentation is written, the tendency |
| is for the docs to languish in the archives without maintenance. |
| </p> |
| <p> |
| QuickBook's import facility provides a nice solution. |
| </p> |
| <a name="quickbook.syntax.block.import.example"></a><h6> |
| <a name="id3244586"></a> |
| <a class="link" href="syntax.html#quickbook.syntax.block.import.example">Example</a> |
| </h6> |
| <p> |
| You can effortlessly import code snippets from source code into your QuickBook. |
| The following illustrates how this is done: |
| </p> |
| <pre class="programlisting">[import ../test/stub.cpp] |
| [foo] |
| [bar] |
| </pre> |
| <p> |
| The first line: |
| </p> |
| <pre class="programlisting">[import ../test/stub.cpp] |
| </pre> |
| <p> |
| collects specially marked-up code snippets from <a href="../../../tools/quickbook/test/stub.cpp" target="_top">stub.cpp</a> |
| and places them in your QuickBook file as virtual templates. Each of the |
| specially marked-up code snippets has a name (e.g. <code class="computeroutput"><span class="identifier">foo</span></code> |
| and <code class="computeroutput"><span class="identifier">bar</span></code> in the example |
| above). This shall be the template identifier for that particular code |
| snippet. The second and third line above does the actual template expansion: |
| </p> |
| <pre class="programlisting">[foo] |
| [bar] |
| </pre> |
| <p> |
| And the result is: |
| </p> |
| <p> |
| This is the <span class="bold"><strong><span class="emphasis"><em>foo</em></span></strong></span> function. |
| </p> |
| <p> |
| This description can have paragraphs... |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> |
| <li class="listitem"> |
| lists |
| </li> |
| <li class="listitem"> |
| etc. |
| </li> |
| </ul></div> |
| <p> |
| And any quickbook block markup. |
| </p> |
| <p> |
| |
| </p> |
| <pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">foo</span><span class="special">()</span> |
| <span class="special">{</span> |
| <span class="comment">// return 'em, foo man! |
| </span> <span class="keyword">return</span> <span class="string">"foo"</span><span class="special">;</span> |
| <span class="special">}</span> |
| </pre> |
| <p> |
| </p> |
| <p> |
| This is the <span class="bold"><strong><span class="emphasis"><em>bar</em></span></strong></span> function |
| </p> |
| <p> |
| |
| </p> |
| <pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">bar</span><span class="special">()</span> |
| <span class="special">{</span> |
| <span class="comment">// return 'em, bar man! |
| </span> <span class="keyword">return</span> <span class="string">"bar"</span><span class="special">;</span> |
| <span class="special">}</span></pre> |
| <p> |
| </p> |
| <p> |
| Some trailing text here |
| </p> |
| <a name="quickbook.syntax.block.import.code_snippet_markup"></a><h6> |
| <a name="id3244849"></a> |
| <a class="link" href="syntax.html#quickbook.syntax.block.import.code_snippet_markup">Code |
| Snippet Markup</a> |
| </h6> |
| <p> |
| Note how the code snippets in <a href="../../../tools/quickbook/test/stub.cpp" target="_top">stub.cpp</a> |
| get marked up. We use distinguishable comments following the form: |
| </p> |
| <pre class="programlisting"><span class="comment">//[id |
| </span><span class="identifier">some</span> <span class="identifier">code</span> <span class="identifier">here</span> |
| <span class="comment">//] |
| </span></pre> |
| <p> |
| The first comment line above initiates a named code-snippet. This prefix |
| will not be visible in quickbook. The entire code-snippet in between <code class="computeroutput"><span class="comment">//[id</span></code> and <code class="computeroutput"><span class="comment">//]</span></code> |
| will be inserted as a template in quickbook with name <span class="emphasis"><em><span class="emphasis"><em>id</em></span></em></span>. |
| The comment <code class="computeroutput"><span class="comment">//]</span></code> ends a code-snippet |
| This too will not be visible in quickbook. |
| </p> |
| <a name="quickbook.syntax.block.import.special_comments"></a><h6> |
| <a name="id3244954"></a> |
| <a class="link" href="syntax.html#quickbook.syntax.block.import.special_comments">Special |
| Comments</a> |
| </h6> |
| <p> |
| Special comments of the form: |
| </p> |
| <pre class="programlisting"><span class="comment">//` some [*quickbook] markup here |
| </span></pre> |
| <p> |
| and: |
| </p> |
| <pre class="programlisting"><span class="comment">/*` some [*quickbook] markup here */</span> |
| </pre> |
| <p> |
| will be parsed by QuickBook. This can contain quickbook <span class="emphasis"><em>blocks</em></span> |
| (e.g. sections, paragraphs, tables, etc). In the first case, the initial |
| slash-slash, tick and white-space shall be ignored. In the second, the |
| initial slash-star-tick and the final star-slash shall be ignored. |
| </p> |
| <p> |
| Special comments of the form: |
| </p> |
| <pre class="programlisting"><span class="comment">/*<- this C++ comment will be ignored ->*/</span> |
| </pre> |
| <p> |
| or |
| </p> |
| <pre class="programlisting"><span class="comment">/*<-*/</span> <span class="string">"this c++ code will be ignored"</span> <span class="comment">/*->*/</span> |
| </pre> |
| <p> |
| or |
| </p> |
| <pre class="programlisting"><span class="comment">//<- |
| </span><span class="keyword">private</span><span class="special">:</span> |
| <span class="keyword">int</span> <span class="identifier">some_member</span><span class="special">;</span> |
| <span class="comment">//-> |
| </span></pre> |
| <p> |
| can be used to inhibit code from passing through to quickbook. All text |
| between the delimeters will simply be ignored. |
| </p> |
| <a name="quickbook.syntax.block.import.callouts"></a><h6> |
| <a name="id3245104"></a> |
| <a class="link" href="syntax.html#quickbook.syntax.block.import.callouts">Callouts</a> |
| </h6> |
| <p> |
| Special comments of the form: |
| </p> |
| <pre class="programlisting"><span class="comment">/*< some [*quickbook] markup here >*/</span> |
| </pre> |
| <p> |
| will be regarded as callouts. These will be collected, numbered and rendered |
| as a "callout bug" (a small icon with a number). After the whole |
| snippet is parsed, the callout list is generated. See <a href="http://www.docbook.org/tdg/en/html/callout.html" target="_top">Callouts</a> |
| for details. Example: |
| </p> |
| <p> |
| |
| </p> |
| <pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">foo_bar</span><span class="special">()</span> <a class="co" name="quickbook0co" href="syntax.html#quickbook0"><img src="../../../doc/src/images/callouts/1.png" alt="1" border="0"></a> |
| <span class="special">{</span> |
| <span class="keyword">return</span> <span class="string">"foo-bar"</span><span class="special">;</span> <a class="co" name="quickbook1co" href="syntax.html#quickbook1"><img src="../../../doc/src/images/callouts/2.png" alt="2" border="0"></a> |
| <span class="special">}</span> |
| </pre> |
| <p> |
| </p> |
| <div class="calloutlist"><table border="0" summary="Callout list"> |
| <tr> |
| <td width="5%" valign="top" align="left"><p><a name="quickbook0"></a><a href="#quickbook0co"><img src="../../../doc/src/images/callouts/1.png" alt="1" border="0"></a> </p></td> |
| <td valign="top" align="left"><p> |
| The <span class="emphasis"><em>Mythical</em></span> FooBar. See <a href="http://en.wikipedia.org/wiki/Foobar" target="_top">Foobar |
| for details</a> |
| </p></td> |
| </tr> |
| <tr> |
| <td width="5%" valign="top" align="left"><p><a name="quickbook1"></a><a href="#quickbook1co"><img src="../../../doc/src/images/callouts/2.png" alt="2" border="0"></a> </p></td> |
| <td valign="top" align="left"><p> |
| return 'em, foo-bar man! |
| </p></td> |
| </tr> |
| </table></div> |
| <p> |
| This is the actual code: |
| </p> |
| <pre class="programlisting"><span class="comment">//[ foo_bar |
| </span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">foo_bar</span><span class="special">()</span> <span class="comment">/*< The /Mythical/ FooBar. |
| See [@http://en.wikipedia.org/wiki/Foobar Foobar for details] >*/</span> |
| <span class="special">{</span> |
| <span class="keyword">return</span> <span class="string">"foo-bar"</span><span class="special">;</span> <span class="comment">/*< return 'em, foo-bar man! >*/</span> |
| <span class="special">}</span> |
| <span class="comment">//] |
| </span></pre> |
| <p> |
| The callouts bugs are placed exactly where the special callout comment |
| is situated. It can be anywhere in the code. The bugs can be rather obtrusive, |
| however. They get in the way of the clarity of the code. Another special |
| callout comment style is available: |
| </p> |
| <pre class="programlisting"><span class="comment">/*<< some [*quickbook] markup here >>*/</span> |
| </pre> |
| <p> |
| This is the line-oriented version of the callout. With this, the "bug" |
| is placed at the very left of the code block, away from the actual code. |
| By placing it at the far left, the code is rendered un-obscured. Example: |
| </p> |
| <p> |
| |
| </p> |
| <pre class="programlisting"><span class="keyword">class</span> <span class="identifier">x</span> |
| <span class="special">{</span> |
| <span class="keyword">public</span><span class="special">:</span> |
| |
| <a class="co" name="quickbook2co" href="syntax.html#quickbook2"><img src="../../../doc/src/images/callouts/1.png" alt="1" border="0"></a><span class="identifier">x</span><span class="special">()</span> <span class="special">:</span> <span class="identifier">n</span><span class="special">(</span><span class="number">0</span><span class="special">)</span> |
| <span class="special">{</span> |
| <span class="special">}</span> |
| |
| <a class="co" name="quickbook3co" href="syntax.html#quickbook3"><img src="../../../doc/src/images/callouts/2.png" alt="2" border="0"></a><span class="special">~</span><span class="identifier">x</span><span class="special">()</span> |
| <span class="special">{</span> |
| <span class="special">}</span> |
| |
| <a class="co" name="quickbook4co" href="syntax.html#quickbook4"><img src="../../../doc/src/images/callouts/3.png" alt="3" border="0"></a><span class="keyword">int</span> <span class="identifier">get</span><span class="special">()</span> <span class="keyword">const</span> |
| <span class="special">{</span> |
| <span class="keyword">return</span> <span class="identifier">n</span><span class="special">;</span> |
| <span class="special">}</span> |
| |
| <a class="co" name="quickbook5co" href="syntax.html#quickbook5"><img src="../../../doc/src/images/callouts/4.png" alt="4" border="0"></a><span class="keyword">void</span> <span class="identifier">set</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">n_</span><span class="special">)</span> |
| <span class="special">{</span> |
| <span class="identifier">n</span> <span class="special">=</span> <span class="identifier">n_</span><span class="special">;</span> |
| <span class="special">}</span> |
| <span class="special">};</span> |
| </pre> |
| <p> |
| </p> |
| <div class="calloutlist"><table border="0" summary="Callout list"> |
| <tr> |
| <td width="5%" valign="top" align="left"><p><a name="quickbook2"></a><a href="#quickbook2co"><img src="../../../doc/src/images/callouts/1.png" alt="1" border="0"></a> </p></td> |
| <td valign="top" align="left"><p> |
| Constructor |
| </p></td> |
| </tr> |
| <tr> |
| <td width="5%" valign="top" align="left"><p><a name="quickbook3"></a><a href="#quickbook3co"><img src="../../../doc/src/images/callouts/2.png" alt="2" border="0"></a> </p></td> |
| <td valign="top" align="left"><p> |
| Destructor |
| </p></td> |
| </tr> |
| <tr> |
| <td width="5%" valign="top" align="left"><p><a name="quickbook4"></a><a href="#quickbook4co"><img src="../../../doc/src/images/callouts/3.png" alt="3" border="0"></a> </p></td> |
| <td valign="top" align="left"><p> |
| Get the <code class="computeroutput"><span class="identifier">n</span></code> member variable |
| </p></td> |
| </tr> |
| <tr> |
| <td width="5%" valign="top" align="left"><p><a name="quickbook5"></a><a href="#quickbook5co"><img src="../../../doc/src/images/callouts/4.png" alt="4" border="0"></a> </p></td> |
| <td valign="top" align="left"><p> |
| Set the <code class="computeroutput"><span class="identifier">n</span></code> member variable |
| </p></td> |
| </tr> |
| </table></div> |
| <p> |
| See the actual code here: <a href="../../../tools/quickbook/test/stub.cpp" target="_top">boost:/tools/quickbook/test/stub.cpp</a> |
| </p> |
| </div> |
| </div> |
| <div class="footnotes"> |
| <br><hr width="100" align="left"> |
| <div class="footnote"><p><sup>[<a name="ftn.id3238824" href="#id3238824" class="para">6</a>] </sup> |
| Thanks to David Barrett, author of <a href="http://quinthar.com/qwikiwiki/index.php?page=Home" target="_top">Qwiki</a>, |
| for sharing these samples and teaching me these obscure formatting rules. |
| I wasn't sure at all if <a href="http://spirit.sourceforge.net" target="_top">Spirit</a>, |
| being more or less a formal EBNF parser, can handle the context sensitivity |
| and ambiguity. |
| </p></div> |
| <div class="footnote"><p><sup>[<a name="ftn.id3240728" href="#id3240728" class="para">7</a>] </sup> |
| A sample footnote |
| </p></div> |
| <div class="footnote"><p><sup>[<a name="ftn.id3240872" href="#id3240872" class="para">8</a>] </sup> |
| Conditional Generation makes quickbook turing complete. |
| </p></div> |
| </div> |
| </div> |
| <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> |
| <td align="left"></td> |
| <td align="right"><div class="copyright-footer">Copyright © 2002, 2004, 2006 Joel de Guzman, |
| Eric Niebler<p> |
| Distributed under the Boost Software License, Version 1.0. (See accompanying |
| file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) |
| </p> |
| </div></td> |
| </tr></table> |
| <hr> |
| <div class="spirit-nav"> |
| <a accesskey="p" href="change_log.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../quickbook.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="install.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> |
| </div> |
| </body> |
| </html> |