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