townforge/quickbook
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
cc
quickbook/test/quickbook_manual-1_4.gold-html

4178 lines
147 KiB
Plaintext
Raw Permalink Blame History

<!DOCTYPE html>
<html>
<head></head>
<body>
<h3>
Quickbook 1.4
</h3>
<div class="authorgroup">
<h3 class="author">
Joel de Guzman
</h3>
<h3 class="author">
Eric Niebler
</h3>
</div>
<p class="copyright">
2002, 2004, 2006 Joel de Guzman, Eric Niebler
</p>
<div class="legalnotice">
<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)
</p>
</div>
<div class="toc">
<p>
<b>Table of contents</b>
</p>
<ul>
<li>
<a href="#quickbook.intro">Introduction</a>
</li>
<li>
<a href="#quickbook.change_log">Change Log</a>
</li>
<li>
<a href="#quickbook.syntax">Syntax Summary</a>
</li>
<li>
<a href="#quickbook.install">Installation and configuration</a>
</li>
<li>
<a href="#quickbook.editors">Editor Support</a>
</li>
<li>
<a href="#quickbook.faq">Frequently Asked Questions</a>
</li>
<li>
<a href="#quickbook.ref">Quick Reference</a>
</li>
</ul>
</div>
<div id="quickbook.intro">
<h3>
Introduction
</h3>
<div id="quickbook.intro">
<blockquote>
<p>
<span class="bold"><strong><span class="emphasis"><em><q>Why program
by hand in five days what you can spend five years of your life automating?</q></em></span></strong></span>
</p>
<p>
-- Terrence Parr, author ANTLR/PCCTS
</p>
</blockquote>
<p>
Well, QuickBook started as a weekend hack. It was originally intended to
be a sample application using <a href="http://spirit.sourceforge.net">Spirit</a>.
What is it? What you are viewing now, this documentation, is autogenerated
by QuickBook. These files were generated from one master:
</p>
<blockquote>
<p>
<a href="../quickbook.qbk">quickbook.qbk</a>
</p>
</blockquote>
<p>
Originally named QuickDoc, this funky tool that never dies evolved into
a funkier tool thanks to Eric Niebler who resurrected the project making
it generate <a href="http://www.boost.org/doc/html/boostbook.html">BoostBook</a>
instead of HTML. The <a href="http://www.boost.org/doc/html/boostbook.html">BoostBook</a>
documentation format is an extension of <a href="http://www.docbook.org/">DocBook</a>,
an SGML or XML based format for describing documentation.
</p>
<p>
QuickBook is a WikiWiki style documentation tool geared towards C++ documentation
using simple rules and markup for simple formatting tasks. QuickBook extends
the WikiWiki concept. Like the WikiWiki, QuickBook documents are simple
text files. A single QuickBook document can generate a fully linked set
of nice HTML and PostScript/PDF documents complete with images and syntax-
colorized source code.
</p>
<p>
Features include:
</p>
<ul>
<li>
<div>
generate <a href="http://www.boost.org/doc/html/boostbook.html">BoostBook</a>
xml, to generate HTML, PostScript and PDF
</div>
</li>
<li>
<div>
simple markup to link to Doxygen-generated entities
</div>
</li>
<li>
<div>
macro system for simple text substitution
</div>
</li>
<li>
<div>
simple markup for italics, bold, preformatted, blurbs, code samples,
tables, URLs, anchors, images, etc.
</div>
</li>
<li>
<div>
automatic syntax coloring of code samples
</div>
</li>
<li>
<div>
CSS support
</div>
</li>
</ul>
</div>
</div>
<div id="quickbook.change_log">
<h3>
Change Log
</h3>
<div id="quickbook.change_log">
<h3 id="quickbook.change_log.version_1_3">
Version 1.3
</h3>
<ul>
<li>
<div>
Quickbook file inclusion [include].
</div>
</li>
<li>
<div>
Better xml output (pretty layout). Check out the generated XML.
</div>
</li>
<li>
<div>
Regression testing facility: to make sure your document will always
be compatible (full backward compatibility) regardless of changes to
QuickBook.
</div>
</li>
<li>
<div>
Code cleanup and refactoring.
</div>
</li>
<li>
<div>
Allow phrase markup in the doc-info.
</div>
</li>
<li>
<div>
Preformatted code blocks via ``code`` (double ticks) allows code in
tables and lists, for example.
</div>
</li>
<li>
<div>
Quickbook versioning; allows full backward compatibility. You have
to add [quickbook 1.3] to the doc-info header to enable the new features.
Without this, QuickBook will assume that the document is a pre-1.3
document.
</div>
</li>
<li>
<div>
Better (intuitive) paragraph termination. Some markups may terminate
a paragraph. Example:
<pre class="programlisting"><span class="special">[</span><span class="identifier">section</span> <span class="identifier">x</span><span class="special">]</span>
<span class="identifier">blah</span><span class="special">...</span>
<span class="special">[</span><span class="identifier">endsect</span><span class="special">]</span></pre>
</div>
</li>
<li>
<div>
Fully qualified section and headers. Subsection names are concatenated
to the ID to avoid clashing. Example: <code><span class="identifier">doc_name</span><span
class="special">.</span><span class="identifier">sect_name</span><span
class="special">.</span><span class="identifier">sub_sect_name</span><span
class="special">.</span><span class="identifier">sub_sub_sect_name</span></code>
</div>
</li>
<li>
<div>
Better &amp;nbsp; and whitespace handling in code snippets.
</div>
</li>
<li>
<div>
[xinclude] fixes up the relative path to the target XML file when input_directory
is not the same as the output_directory.
</div>
</li>
<li>
<div>
Allow untitled tables.
</div>
</li>
<li>
<div>
Allow phrase markups in section titles.
</div>
</li>
<li>
<div>
Allow escaping back to QuickBook from code, code blocks and inline
code.
</div>
</li>
<li>
<div>
Footnotes, with the [footnote This is the footnote] syntax.
</div>
</li>
<li>
<div>
Post-processor bug fix for escaped XML code that it does not recognize.
</div>
</li>
<li>
<div>
Replaceable, with the [~replacement] syntax.
</div>
</li>
<li>
<div>
Generic Headers
</div>
</li>
<li>
<div>
Code changes to allow full recursion (i.e. Collectors and push/pop
functions)
</div>
</li>
<li>
<div>
Various code cleanup/maintenance
</div>
</li>
<li>
<div>
Templates!
</div>
</li>
<li>
<div>
[conceptref] for referencing BoostBook &lt;concept&gt; entities.
</div>
</li>
<li>
<div>
Allow escape of spaces. The escaped space is removed from the output.
Syntax: <code><span class="special">\</span> </code>.
</div>
</li>
<li>
<div>
Nested comments are now allowed.
</div>
</li>
<li>
<div>
Quickbook blocks can nest inside comments.
</div>
</li>
<li>
<div>
<a href="#quickbook.syntax.block.import">Import</a> facility.
</div>
</li>
<li>
<div>
Callouts on imported code
</div>
</li>
<li>
<div>
Simple markups can now span a whole block.
</div>
</li>
<li>
<div>
<a href="#quickbook.syntax.block.blurbs">Blurbs</a>, <a href="#quickbook.syntax.block.admonitions">Admonitions</a>
and table cells (see <a href="#quickbook.syntax.block.tables">Tables</a>)
may now contain paragraphs.
</div>
</li>
<li>
<div>
<code><span class="special">\</span><span class="identifier">n</span></code>
and <code><span class="special">[</span><span class="identifier">br</span><span
class="special">]</span></code> are now deprecated.
</div>
</li>
</ul>
</div>
</div>
<div id="quickbook.syntax">
<h3>
Syntax Summary
</h3>
<div id="quickbook.syntax">
<p>
A QuickBook document is composed of one or more blocks. An example of a
block is the paragraph or a C++ code snippet. Some blocks have special
mark-ups. Blocks, except code snippets which have their own grammar (C++
or Python), are composed of one or more phrases. A phrase can be a simple
contiguous run of characters. Phrases can have special mark-ups. Marked
up phrases can recursively contain other phrases, but cannot contain blocks.
A terminal is a self contained block-level or phrase-level element that
does not nest anything.
</p>
<p>
Blocks, in general, are delimited by two end-of-lines (the block terminator).
Phrases in each block cannot contain a block terminator. This way, syntax
errors such as un-matched closing brackets do not go haywire and corrupt
anything past a single block.
</p>
</div>
<div id="quickbook.syntax.comments">
<h3>
Comments
</h3>
<div id="quickbook.syntax.comments">
<p>
Can be placed anywhere.
</p>
<pre class="programlisting">[/ comment (no output generated) ]
</pre>
<pre class="programlisting">[/ comments can be nested [/ some more here] ]
</pre>
<pre class="programlisting">[/ Quickbook blocks can nest inside comments. [*Comment this out too!] ]
</pre>
</div>
</div>
<div id="quickbook.syntax.phrase">
<h3>
Phrase Level Elements
</h3>
<div id="quickbook.syntax.phrase">
</div>
<div id="quickbook.syntax.phrase.font_styles">
<h3>
Font Styles
</h3>
<div id="quickbook.syntax.phrase.font_styles">
<pre class="programlisting">['italic], [*bold], [_underline], [^teletype], [-strikethrough]
</pre>
<p>
will generate:
</p>
<p>
<span class="emphasis"><em>italic</em></span>, <span class="bold"><strong>bold</strong></span>,
<span class="underline">underline</span>, <tt>teletype</tt>, <span
class="strikethrough">strikethrough</span>
</p>
<p>
Like all non-terminal phrase level elements, this can of course be
nested:
</p>
<pre class="programlisting">[*['bold-italic]]
</pre>
<p>
will generate:
</p>
<p>
<span class="bold"><strong><span class="emphasis"><em>bold-italic</em></span></strong></span>
</p>
</div>
</div>
<div id="quickbook.syntax.phrase.replaceable">
<h3>
Replaceable
</h3>
<div id="quickbook.syntax.phrase.replaceable">
<p>
When you want content that may or must be replaced by the user, use
the syntax:
</p>
<pre class="programlisting">[~replacement]
</pre>
<p>
This will generate:
</p>
<p>
<em class="replaceable">replacement</em>
</p>
</div>
</div>
<div id="quickbook.syntax.phrase.quotations">
<h3>
Quotations
</h3>
<div id="quickbook.syntax.phrase.quotations">
<pre class="programlisting">["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein
</pre>
<p>
will generate:
</p>
<p>
<q>A question that sometimes drives me hazy: am I or are the others
crazy?</q>--Einstein
</p>
<p>
Note the proper left and right quote marks. Also, while you can simply
use ordinary quote marks like &quot;quoted&quot;, our quotation, above,
will generate correct DocBook quotations (e.g. &lt;quote&gt;quoted&lt;/quote&gt;).
</p>
<p>
Like all phrase elements, quotations may be nested. Example:
</p>
<pre class="programlisting">["Here's the rule for bargains: ["Do other men, for they would do you.] That's
the true business precept.]
</pre>
<p>
will generate:
</p>
<p>
<q>Here's the rule for bargains: <q>Do other men, for they would do
you.</q> That's the true business precept.</q>
</p>
</div>
</div>
<div id="quickbook.syntax.phrase.simple_formatting">
<h3>
Simple formatting
</h3>
<div id="quickbook.syntax.phrase.simple_formatting">
<p>
Simple markup for formatting text, common in many applications, is
now supported:
</p>
<pre class="programlisting">/italic/, *bold*, _underline_, =teletype=
</pre>
<p>
will generate:
</p>
<p>
<span class="emphasis"><em>italic</em></span>, <span class="bold"><strong>bold</strong></span>,
<span class="underline">underline</span>, <tt>teletype</tt>
</p>
<p>
Unlike QuickBook's standard formatting scheme, the rules for simpler
alternatives are much stricter<a id="quickbook.syntax.phrase.simple_formatting.f0"
href="#footnote-1"><sup class="footnote">[1]</sup></a>.
</p>
<ul>
<li>
<div>
Simple markups cannot nest. You can combine a simple markup with
a nestable markup.
</div>
</li>
<li>
<div>
Simple markups cannot contain any other form of quickbook markup.
</div>
</li>
<li>
<div>
A non-space character must follow the leading markup
</div>
</li>
<li>
<div>
A non-space character must precede the trailing markup
</div>
</li>
<li>
<div>
A space or a punctuation must follow the trailing markup
</div>
</li>
<li>
<div>
If the matching markup cannot be found within a block, the formatting
will not be applied. This is to ensure that un-matched formatting
markups, which can be a common mistake, does not corrupt anything
past a single block. We do not want the rest of the document to
be rendered bold just because we forgot a trailing '*'. A single
block is terminated by two end of lines or the close bracket: ']'.
</div>
</li>
<li>
<div>
A line starting with the star will be interpreted as an unordered
list. See <a href="#quickbook.syntax.block.lists.unordered_lists">Unordered
lists</a>.
</div>
</li>
</ul>
<div id="quickbook.syntax.phrase.simple_formatting.t0" class="table">
<table>
<caption>More Formatting Samples</caption>
<thead>
<tr>
<th>
<p>
Markup
</p>
</th>
<th>
<p>
Result
</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>
<tt>*Bold*</tt>
</p>
</td>
<td>
<p>
<span class="bold"><strong>Bold</strong></span>
</p>
</td>
</tr>
<tr>
<td>
<p>
<tt>*Is bold*</tt>
</p>
</td>
<td>
<p>
<span class="bold"><strong>Is bold</strong></span>
</p>
</td>
</tr>
<tr>
<td>
<p>
<tt>* Not bold* *Not bold * * Not bold *</tt>
</p>
</td>
<td>
<p>
* Not bold* *Not bold * * Not bold *
</p>
</td>
</tr>
<tr>
<td>
<p>
<tt>This*Isn't*Bold (no bold)</tt>
</p>
</td>
<td>
<p>
This*Isn't*Bold (no bold)
</p>
</td>
</tr>
<tr>
<td>
<p>
<tt>(*Bold Inside*) (parenthesis not bold)</tt>
</p>
</td>
<td>
<p>
(<span class="bold"><strong>Bold Inside</strong></span>)
(parenthesis not bold)
</p>
</td>
</tr>
<tr>
<td>
<p>
<tt>*(Bold Outside)* (parenthesis bold)</tt>
</p>
</td>
<td>
<p>
<span class="bold"><strong>(Bold Outside)</strong></span>
(parenthesis bold)
</p>
</td>
</tr>
<tr>
<td>
<p>
<tt>3*4*5 = 60 (no bold)</tt>
</p>
</td>
<td>
<p>
3*4*5 = 60 (no bold)
</p>
</td>
</tr>
<tr>
<td>
<p>
<tt>3 * 4 * 5 = 60 (no bold)</tt>
</p>
</td>
<td>
<p>
3 * 4 * 5 = 60 (no bold)
</p>
</td>
</tr>
<tr>
<td>
<p>
<tt>3 *4* 5 = 60 (4 is bold)</tt>
</p>
</td>
<td>
<p>
3 <span class="bold"><strong>4</strong></span> 5 = 60 (4
is bold)
</p>
</td>
</tr>
<tr>
<td>
<p>
<tt>*This is bold* this is not *but this is*</tt>
</p>
</td>
<td>
<p>
<span class="bold"><strong>This is bold</strong></span> this
is not <span class="bold"><strong>but this is</strong></span>
</p>
</td>
</tr>
<tr>
<td>
<p>
<tt>*This is bold*.</tt>
</p>
</td>
<td>
<p>
<span class="bold"><strong>This is bold</strong></span>.
</p>
</td>
</tr>
<tr>
<td>
<p>
<tt>*B*. (bold B)</tt>
</p>
</td>
<td>
<p>
<span class="bold"><strong>B</strong></span>. (bold B)
</p>
</td>
</tr>
<tr>
<td>
<p>
<tt>['*Bold-Italic*]</tt>
</p>
</td>
<td>
<p>
<span class="emphasis"><em><span class="bold"><strong>Bold-Italic</strong></span></em></span>
</p>
</td>
</tr>
<tr>
<td>
<p>
<tt>*side-by*/-side/</tt>
</p>
</td>
<td>
<p>
<span class="bold"><strong>side-by</strong></span><span class="emphasis"><em>-side</em></span>
</p>
</td>
</tr>
</tbody>
</table>
</div>
<p>
As mentioned, simple markups cannot go past a single block. The text
from &quot;have&quot; to &quot;full&quot; in the following paragraph
will be rendered as bold:
</p>
<pre class="programlisting">Baa baa black sheep, *have you any wool?
Yes sir, yes sir, three bags full!*
One for the master, one for the dame,
And one for the little boy who lives down the lane.
</pre>
<p>
Baa baa black sheep, <span class="bold"><strong>have you any wool?
Yes sir, yes sir, three bags full!</strong></span> One for the master,
one for the dame, And one for the little boy who lives down the lane.
</p>
<p>
But in the following paragraph, bold is not applied:
</p>
<pre class="programlisting">Baa baa black sheep, *have you any wool?
Yes sir, yes sir, three bags full!
One for the master, one for the dame,
And one for the little boy who lives down the lane.
</pre>
<p>
Baa baa black sheep, *have you any wool? Yes sir, yes sir, three bags
full! One for the master, one for the dame, And one for the little
boy who lives down the lane.
</p>
</div>
</div>
<div id="quickbook.syntax.phrase.inline_code">
<h3>
Inline code
</h3>
<div id="quickbook.syntax.phrase.inline_code">
<p>
Inlining code in paragraphs is quite common when writing C++ documentation.
We provide a very simple markup for this. For example, this:
</p>
<pre class="programlisting">This text has inlined code `int main() { return 0; }` in it.
</pre>
<p>
will generate:
</p>
<p>
This text has inlined code <code><span class="keyword">int</span>
<span class="identifier">main</span><span class="special">()</span>
<span class="special">{</span> <span class="keyword">return</span>
<span class="number">0</span><span class="special">;</span> <span class="special">}</span></code>
in it. The code will be syntax highlighted.
</p>
<div class="note">
<p>
We simply enclose the code with the tick: <tt>"`"</tt>, not the single
quote: <code><span class="string">&quot;'&quot;</span></code>. Note
too that <tt>`some code`</tt> is preferred over <tt>[^some code]</tt>.
</p>
</div>
</div>
</div>
<div id="quickbook.syntax.phrase.code_blocks">
<h3>
Code blocks
</h3>
<div id="quickbook.syntax.phrase.code_blocks">
<p>
Preformatted code simply starts with a space or a tab (See <a href="#quickbook.syntax.block.code">Code</a>).
However, such a simple syntax cannot be used as phrase elements in
lists (See <a href="#quickbook.syntax.block.lists.ordered_lists">Ordered
lists</a> and <a href="#quickbook.syntax.block.lists.unordered_lists">Unordered
lists</a>), tables (See <a href="#quickbook.syntax.block.tables">Tables</a>),
etc. Inline code (see above) can. The problem is, inline code does
not allow formatting with newlines, spaces, and tabs. These are lost.
</p>
<p>
We provide a phrase level markup that is a mix between the two. By
using the double-tick, instead of the single-tick, we are telling QuickBook
to use preformatted blocks of code. Example:
</p>
<pre class="programlisting">``
#include &lt;iostream&gt;
int main()
{
std::cout &lt;&lt; &quot;Hello, World!&quot; &lt;&lt; std::endl;
return 0;
}
``
</pre>
<p>
will generate:
</p>
<p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</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">&lt;&lt;</span> <span class="string">&quot;Hello, World!&quot;</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="special">}</span>
</pre>
</p>
</div>
</div>
<div id="quickbook.syntax.phrase.source_mode">
<h3>
Source Mode
</h3>
<div id="quickbook.syntax.phrase.source_mode">
<p>
If a document contains more than one type of source code then the source
mode may be changed dynamically as the document is processed. All QuickBook
documents are initially in C++ mode by default, though an alternative
initial value may be set in the <a href="#quickbook.syntax.block.document">Document</a>
section.
</p>
<p>
To change the source mode, use the <tt>[source-mode]</tt> markup, where
<tt>source-mode</tt> is one of the supported modes. For example, this:
</p>
<pre class="programlisting">Python's [python] `import` is rather like C++'s [c++] `#include`. A
C++ comment `// looks like this` whereas a Python comment [python]
`# looks like this`.
</pre>
<p>
will generate:
</p>
<p>
Python's <code><span class="keyword">import</span></code> is rather
like C++'s <code><span class="preprocessor">#include</span></code>.
A C++ comment <code><span class="comment">// looks like this</span></code>
whereas a Python comment <code><span class="comment">#looks like this</span></code>.
</p>
<div id="quickbook.syntax.phrase.source_mode.t0" class="table">
<table>
<caption>Supported Source Modes</caption>
<thead>
<tr>
<th>
<p>
Mode
</p>
</th>
<th>
<p>
Source Mode Markup
</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>
C++
</p>
</td>
<td>
<p>
<tt>[c++]</tt>
</p>
</td>
</tr>
<tr>
<td>
<p>
Python
</p>
</td>
<td>
<p>
<tt>[python]</tt>
</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="note">
<p>
The source mode strings are lowercase.
</p>
</div>
</div>
</div>
<div id="quickbook.syntax.phrase.line_break">
<h3>
line-break
</h3>
<div id="quickbook.syntax.phrase.line_break">
<pre class="programlisting">[br]
</pre>
<div class="warning">
<p>
<code><span class="special">[</span><span class="identifier">br</span><span
class="special">]</span></code> is now deprecated. <a href="#quickbook.syntax.block.blurbs">Blurbs</a>,
<a href="#quickbook.syntax.block.admonitions">Admonitions</a> and
table cells (see <a href="#quickbook.syntax.block.tables">Tables</a>)
may now contain paragraphs.
</p>
</div>
</div>
</div>
<div id="quickbook.syntax.phrase.anchors">
<h3>
Anchors
</h3>
<div id="quickbook.syntax.phrase.anchors">
<pre class="programlisting">[#named_anchor]
</pre>
<p>
A named anchor is a hook that can be referenced by a link elsewhere
in the document. You can then reference an anchor with <tt>[link named_anchor
Some link text]</tt>. See <a href="#quickbook.syntax.phrase.anchor_links">Anchor
links</a>, <a href="#quickbook.syntax.block.section">Section</a> and
<a href="#quickbook.syntax.block.headings">Heading</a>.
</p>
</div>
</div>
<div id="quickbook.syntax.phrase.links">
<h3>
Links
</h3>
<div id="quickbook.syntax.phrase.links">
<pre class="programlisting">[@http://www.boost.org this is [*boost's] website....]
</pre>
<p>
will generate:
</p>
<p>
<a href="http://www.boost.org">this is <span class="bold"><strong>boost's</strong></span>
website....</a>
</p>
<p>
URL links where the link text is the link itself is common. Example:
</p>
<pre class="programlisting">see http://spirit.sourceforge.net/
</pre>
<p>
so, when the text is absent in a link markup, the URL is assumed. Example:
</p>
<pre class="programlisting">see [@http://spirit.sourceforge.net/]
</pre>
<p>
will generate:
</p>
<p>
see <a href="http://spirit.sourceforge.net/">http://spirit.sourceforge.net/</a>
</p>
</div>
</div>
<div id="quickbook.syntax.phrase.anchor_links">
<h3>
Anchor links
</h3>
<div id="quickbook.syntax.phrase.anchor_links">
<p>
You can link within a document using:
</p>
<pre class="programlisting">[link section_id.normalized_header_text The link text]
</pre>
<p>
See sections <a href="#quickbook.syntax.block.section">Section</a>
and <a href="#quickbook.syntax.block.headings">Heading</a> for more
info.
</p>
</div>
</div>
<div id="quickbook.syntax.phrase.refentry_links">
<h3>
refentry links
</h3>
<div id="quickbook.syntax.phrase.refentry_links">
<p>
In addition, you can link internally to an XML refentry like:
</p>
<pre class="programlisting">[link xml.refentry The link text]
</pre>
<p>
This gets converted into <tt>&lt;link linkend=&quot;xml.refentry&quot;&gt;The
link text&lt;/link&gt;</tt>.
</p>
<p>
Like URLs, the link text is optional. If this is not present, the link
text will automatically be the refentry. Example:
</p>
<pre class="programlisting">[link xml.refentry]
</pre>
<p>
This gets converted into <tt>&lt;link linkend=&quot;xml.refentry&quot;&gt;xml.refentry&lt;/link&gt;</tt>.
</p>
</div>
</div>
<div id="quickbook.syntax.phrase.code_links">
<h3>
Code Links
</h3>
<div id="quickbook.syntax.phrase.code_links">
<p>
If you want to link to a function, class, member, enum, concept or
header in the reference section, you can use:
</p>
<pre class="programlisting">[funcref fully::qualified::function_name The link text]
[classref fully::qualified::class_name The link text]
[memberref fully::qualified::member_name The link text]
[enumref fully::qualified::enum_name The link text]
[macroref MACRO_NAME The link text]
[conceptref ConceptName The link text]
[headerref path/to/header.hpp The link text]
</pre>
<p>
Again, the link text is optional. If this is not present, the link
text will automatically be the function, class, member, enum, macro,
concept or header. Example:
</p>
<pre class="programlisting">[classref boost::bar::baz]
</pre>
<p>
would have &quot;boost::bar::baz&quot; as the link text.
</p>
</div>
</div>
<div id="quickbook.syntax.phrase.escape">
<h3>
Escape
</h3>
<div id="quickbook.syntax.phrase.escape">
<p>
The escape mark-up is used when we don't want to do any processing.
</p>
<pre class="programlisting">'''
escape (no processing/formatting)
'''
</pre>
<p>
Escaping allows us to pass XML markup to <a href="http://www.boost.org/doc/html/boostbook.html">BoostBook</a>
or <a href="http://www.docbook.org/">DocBook</a>. For example:
</p>
<pre class="programlisting">'''
&lt;emphasis role=&quot;bold&quot;&gt;This is direct XML markup&lt;/emphasis&gt;
'''
</pre>
<p>
<span class="bold"><strong>This is direct XML markup</strong></span>
</p>
<div class="important">
<p>
Be careful when using the escape. The text must conform to <a href="http://www.boost.org/doc/html/boostbook.html">BoostBook</a>/<a
href="http://www.docbook.org/">DocBook</a> syntax.
</p>
</div>
</div>
</div>
<div id="quickbook.syntax.phrase.single_char_escape">
<h3>
Single char escape
</h3>
<div id="quickbook.syntax.phrase.single_char_escape">
<p>
The backslash may be used to escape a single punctuation character.
The punctuation immediately after the backslash is passed without any
processing. This is useful when we need to escape QuickBook punctuations
such as <code><span class="special">[</span></code> and <code><span
class="special">]</span></code>. For example, how do you escape the
triple quote? Simple: <tt>\'\'\'</tt>
</p>
<p>
<code><span class="special">\</span><span class="identifier">n</span></code>
has a special meaning. It is used to generate line breaks.
</p>
<div class="warning">
<p>
<code><span class="special">\</span><span class="identifier">n</span></code>
and <code><span class="special">[</span><span class="identifier">br</span><span
class="special">]</span></code> are now deprecated. <a href="#quickbook.syntax.block.blurbs">Blurbs</a>,
<a href="#quickbook.syntax.block.admonitions">Admonitions</a> and
table cells (see <a href="#quickbook.syntax.block.tables">Tables</a>)
may now contain paragraphs.
</p>
</div>
<p>
The escaped space: <code><span class="special">\</span> </code> also
has a special meaning. The escaped space is removed from the output.
</p>
</div>
</div>
<div id="quickbook.syntax.phrase.images">
<h3>
Images
</h3>
<div id="quickbook.syntax.phrase.images">
<pre class="programlisting">[$image.jpg]
</pre>
</div>
</div>
<div id="quickbook.syntax.phrase.footnotes">
<h3>
Footnotes
</h3>
<div id="quickbook.syntax.phrase.footnotes">
<p>
As of version 1.3, QuickBook supports footnotes. Just put the text
of the footnote in a <code><span class="special">[</span><span class="identifier">footnote</span><span
class="special">]</span></code> block, and the text will be put at
the bottom of the current page. For example, this:
</p>
<pre class="programlisting">[footnote A sample footnote]
</pre>
<p>
will generate this<a id="quickbook.syntax.phrase.footnotes.f0" href="#footnote-2"><sup
class="footnote">[2]</sup></a>.
</p>
</div>
<div id="quickbook.syntax.phrase.footnotes.macro_expansion">
<h3>
Macro Expansion
</h3>
<div id="quickbook.syntax.phrase.footnotes.macro_expansion">
<pre class="programlisting">__a_macro_identifier__
</pre>
<p>
See <a href="#quickbook.syntax.block.macros">Macros</a> for details.
</p>
</div>
</div>
<div id="quickbook.syntax.phrase.footnotes.template_expansion">
<h3>
Template Expansion
</h3>
<div id="quickbook.syntax.phrase.footnotes.template_expansion">
<pre class="programlisting">[a_template_identifier]
</pre>
<p>
See <a href="#quickbook.syntax.block.templates">Templates</a> for
details.
</p>
</div>
</div>
</div>
</div>
<div id="quickbook.syntax.block">
<h3>
Block Level Elements
</h3>
<div id="quickbook.syntax.block">
</div>
<div id="quickbook.syntax.block.document">
<h3>
Document
</h3>
<div id="quickbook.syntax.block.document">
<p>
Every document must begin with a Document Info section, which should
look like this:
</p>
<pre class="programlisting">[document-type The Document Title
[quickbook 1.3]
[version 1.0]
[id the_document_name]
[dirname the_document_dir]
[copyright 2000 2002 2003 Joe Blow, Jane Doe]
[purpose The document's reason for being]
[category The document's category]
[authors [Blow, Joe], [Doe, Jane]]
[license The document's license]
[source-mode source-type]
]
</pre>
<p>
Where document-type is one of:
</p>
<ul>
<li>
<div>
book
</div>
</li>
<li>
<div>
article
</div>
</li>
<li>
<div>
library
</div>
</li>
<li>
<div>
chapter
</div>
</li>
<li>
<div>
part
</div>
</li>
<li>
<div>
appendix
</div>
</li>
<li>
<div>
preface
</div>
</li>
<li>
<div>
qandadiv
</div>
</li>
<li>
<div>
qandaset
</div>
</li>
<li>
<div>
reference
</div>
</li>
<li>
<div>
set
</div>
</li>
</ul>
<p>
quickbook 1.3 declares the version of quickbook the document is written
for. In its absence, version 1.1 is assumed.
</p>
<p>
<tt>version</tt>, <tt>id</tt>, <tt>dirname</tt>, <tt>copyright</tt>,
<tt>purpose</tt>, <tt>category</tt>, <tt>authors</tt>, <tt>license</tt>,
<tt>last-revision</tt> and <tt>source-mode</tt> are optional information.
</p>
<p>
<tt>source-type</tt> is a lowercase string setting the initial <a href="#quickbook.syntax.phrase.source_mode">Source
Mode</a>. If the <tt>source-mode</tt> field is omitted, a default value
of <tt>c++</tt> will be used.
</p>
</div>
</div>
<div id="quickbook.syntax.block.section">
<h3>
Section
</h3>
<div id="quickbook.syntax.block.section">
<p>
Starting a new section is accomplished with:
</p>
<pre class="programlisting">[section:id The Section Title]
</pre>
<p>
where <span class="emphasis"><em>id</em></span> is optional. id will
be the filename of the generated section. If it is not present, &quot;The
Section Title&quot; will be normalized and become the id. Valid characters
are <tt>a-Z</tt>, <tt>A-Z</tt>, <tt>0-9</tt> and <tt>_</tt>. All non-valid
characters are converted to underscore and all upper-case are converted
to lower case. Thus: &quot;The Section Title&quot; will be normalized
to &quot;the_section_title&quot;.
</p>
<p>
End a section with:
</p>
<pre class="programlisting">[endsect]
</pre>
<p>
Sections can nest, and that results in a hierarchy in the table of
contents.
</p>
</div>
</div>
<div id="quickbook.syntax.block.xinclude">
<h3>
xinclude
</h3>
<div id="quickbook.syntax.block.xinclude">
<p>
You can include another XML file with:
</p>
<pre class="programlisting">[xinclude file.xml]
</pre>
<p>
This is useful when file.xml has been generated by Doxygen and contains
your reference section.
</p>
</div>
</div>
<div id="quickbook.syntax.block.paragraphs">
<h3>
Paragraphs
</h3>
<div id="quickbook.syntax.block.paragraphs">
<p>
Paragraphs start left-flushed and are terminated by two or more newlines.
No markup is needed for paragraphs. QuickBook automatically detects
paragraphs from the context. Block markups [section, endsect, h1, h2,
h3, h4, h5, h6, blurb, (block-quote) ':', pre, def, table and include
] may also terminate a paragraph.
</p>
</div>
</div>
<div id="quickbook.syntax.block.lists">
<h3>
Lists
</h3>
<div id="quickbook.syntax.block.lists">
</div>
<div id="quickbook.syntax.block.lists.ordered_lists">
<h3>
Ordered lists
</h3>
<div id="quickbook.syntax.block.lists.ordered_lists">
<pre class="programlisting"># One
# Two
# Three
</pre>
<p>
will generate:
</p>
<ol>
<li>
<div>
One
</div>
</li>
<li>
<div>
Two
</div>
</li>
<li>
<div>
Three
</div>
</li>
</ol>
</div>
</div>
<div id="quickbook.syntax.block.lists.list_hierarchies">
<h3>
List Hierarchies
</h3>
<div id="quickbook.syntax.block.lists.list_hierarchies">
<p>
List hierarchies are supported. Example:
</p>
<pre class="programlisting"># One
# Two
# Three
# Three.a
# Three.b
# Three.c
# Four
# Four.a
# Four.a.i
# Four.a.ii
# Five
</pre>
<p>
will generate:
</p>
<ol>
<li>
<div>
One
</div>
</li>
<li>
<div>
Two
</div>
</li>
<li>
<div>
Three
<ol>
<li>
<div>
Three.a
</div>
</li>
<li>
<div>
Three.b
</div>
</li>
<li>
<div>
Three.c
</div>
</li>
</ol>
</div>
</li>
<li>
<div>
Fourth
<ol>
<li>
<div>
Four.a
<ol>
<li>
<div>
Four.a.i
</div>
</li>
<li>
<div>
Four.a.ii
</div>
</li>
</ol>
</div>
</li>
</ol>
</div>
</li>
<li>
<div>
Five
</div>
</li>
</ol>
</div>
</div>
<div id="quickbook.syntax.block.lists.long_list_lines">
<h3>
Long List Lines
</h3>
<div id="quickbook.syntax.block.lists.long_list_lines">
<p>
Long lines will be wrapped appropriately. Example:
</p>
<pre class="programlisting"># A short item.
# A very long item. A very long item. A very long item.
A very long item. A very long item. A very long item.
A very long item. A very long item. A very long item.
A very long item. A very long item. A very long item.
A very long item. A very long item. A very long item.
# A short item.
</pre>
<ol>
<li>
<div>
A short item.
</div>
</li>
<li>
<div>
A very long item. A very long item. A very long item. A very
long item. A very long item. A very long item. A very long item.
A very long item. A very long item. A very long item. A very
long item. A very long item. A very long item. A very long item.
A very long item.
</div>
</li>
<li>
<div>
A short item.
</div>
</li>
</ol>
</div>
</div>
<div id="quickbook.syntax.block.lists.unordered_lists">
<h3>
Unordered lists
</h3>
<div id="quickbook.syntax.block.lists.unordered_lists">
<pre class="programlisting">* First
* Second
* Third
</pre>
<p>
will generate:
</p>
<ul>
<li>
<div>
First
</div>
</li>
<li>
<div>
Second
</div>
</li>
<li>
<div>
Third
</div>
</li>
</ul>
</div>
</div>
<div id="quickbook.syntax.block.lists.mixed_lists">
<h3>
Mixed lists
</h3>
<div id="quickbook.syntax.block.lists.mixed_lists">
<p>
Mixed lists (ordered and unordered) are supported. Example:
</p>
<pre class="programlisting"># One
# Two
# Three
* Three.a
* Three.b
* Three.c
# Four
</pre>
<p>
will generate:
</p>
<ol>
<li>
<div>
One
</div>
</li>
<li>
<div>
Two
</div>
</li>
<li>
<div>
Three
<ul>
<li>
<div>
Three.a
</div>
</li>
<li>
<div>
Three.b
</div>
</li>
<li>
<div>
Three.c
</div>
</li>
</ul>
</div>
</li>
<li>
<div>
Four
</div>
</li>
</ol>
<p>
And...
</p>
<pre class="programlisting"># 1
* 1.a
# 1.a.1
# 1.a.2
* 1.b
# 2
* 2.a
* 2.b
# 2.b.1
# 2.b.2
* 2.b.2.a
* 2.b.2.b
</pre>
<p>
will generate:
</p>
<ol>
<li>
<div>
1
<ul>
<li>
<div>
1.a
<ol>
<li>
<div>
1.a.1
</div>
</li>
<li>
<div>
1.a.2
</div>
</li>
</ol>
</div>
</li>
<li>
<div>
1.b
</div>
</li>
</ul>
</div>
</li>
<li>
<div>
2
<ul>
<li>
<div>
2.a
</div>
</li>
<li>
<div>
2.b
<ol>
<li>
<div>
2.b.1
</div>
</li>
<li>
<div>
2.b.2
<ul>
<li>
<div>
2.b.2.a
</div>
</li>
<li>
<div>
2.b.2.b
</div>
</li>
</ul>
</div>
</li>
</ol>
</div>
</li>
</ul>
</div>
</li>
</ol>
</div>
</div>
</div>
<div id="quickbook.syntax.block.code">
<h3>
Code
</h3>
<div id="quickbook.syntax.block.code">
<p>
Preformatted code starts with a space or a tab. The code will be syntax
highlighted according to the current <a href="#quickbook.syntax.phrase.source_mode">Source
Mode</a>:
</p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</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">&lt;&lt;</span> <span class="string">&quot;Hello, World\n&quot;</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">'''&quot;Cooks&quot; the input text for HTML.'''</span>
<span class="keyword">return</span> <span class="identifier">cgi</span><span class="special">.</span><span class="identifier">escape</span><span class="special">(</span><span class="identifier">text</span><span class="special">)</span>
</pre>
<p>
Macros that are already defined are expanded in source code. Example:
</p>
<pre class="programlisting">[def __array__ [@http://www.boost.org/doc/html/array/reference.html array]]
[def __boost__ [@http://www.boost.org/libs/libraries.htm boost]]
using __boost__::__array__;
</pre>
<p>
Generates:
</p>
<pre class="programlisting"><span class="keyword">using</span> <a href="http://www.boost.org/libs/libraries.htm">boost</a><span class="special">::</span><a href="http://www.boost.org/doc/html/array/reference.html">array</a><span class="special">;</span>
</pre>
</div>
</div>
<div id="quickbook.syntax.block.escape_back">
<h3>
Escaping Back To QuickBook
</h3>
<div id="quickbook.syntax.block.escape_back">
<p>
Inside code, code blocks and inline code, QuickBook does not allow
any markup to avoid conflicts with the target syntax (e.g. c++). In
case you need to switch back to QuickBook markup inside code, you can
do so using a language specific <span class="emphasis"><em>escape-back</em></span>
delimiter. In C++ and Python, the delimiter is the double tick (back-quote):
&quot;``&quot; and &quot;``&quot;. Example:
</p>
<pre class="programlisting">void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``()
{
}
</pre>
<p>
Will generate:
</p>
<pre class="programlisting"><span class="keyword">void</span> <a href="http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz">foo</a><span class="special">()</span>
<span class="special">{</span>
<span class="special">}</span>
</pre>
<p>
When escaping from code to QuickBook, only phrase level markups are
allowed. Block level markups like lists, tables etc. are not allowed.
</p>
</div>
</div>
<div id="quickbook.syntax.block.preformatted">
<h3>
Preformatted
</h3>
<div id="quickbook.syntax.block.preformatted">
<p>
Sometimes, you don't want some preformatted text to be parsed as C++.
In such cases, use the <tt>[pre ... ]</tt> markup block.
</p>
<pre class="programlisting">[pre
Some *preformatted* text Some *preformatted* text
Some *preformatted* text Some *preformatted* text
Some *preformatted* text Some *preformatted* text
]
</pre>
<p>
Spaces, tabs and newlines are rendered as-is. Unlike all quickbook
block level markup, pre (and Code) are the only ones that allow multiple
newlines. The markup above will generate:
</p>
<pre class="programlisting">Some <span class="bold"><strong>preformatted</strong></span> text Some <span class="bold"><strong>preformatted</strong></span> text
Some <span class="bold"><strong>preformatted</strong></span> text Some <span class="bold"><strong>preformatted</strong></span> text
Some <span class="bold"><strong>preformatted</strong></span> text Some <span class="bold"><strong>preformatted</strong></span> text
</pre>
<p>
Notice that unlike Code, phrase markup such as font style is still
permitted inside <tt>pre</tt> blocks.
</p>
</div>
</div>
<div id="quickbook.syntax.block.blockquote">
<h3>
Blockquote
</h3>
<div id="quickbook.syntax.block.blockquote">
<pre class="programlisting">[:sometext...]
</pre>
<blockquote>
<p>
Indents the paragraph. This applies to one paragraph only.
</p>
</blockquote>
</div>
</div>
<div id="quickbook.syntax.block.admonitions">
<h3>
Admonitions
</h3>
<div id="quickbook.syntax.block.admonitions">
<pre class="programlisting">[note This is a note]
[tip This is a tip]
[important This is important]
[caution This is a caution]
[warning This is a warning]
</pre>
<p>
generates <a href="http://www.docbook.org/">DocBook</a> admonitions:
</p>
<div class="note">
<p>
This is a note
</p>
</div>
<div class="tip">
<p>
This is a tip
</p>
</div>
<div class="important">
<p>
This is important
</p>
</div>
<div class="caution">
<p>
This is a caution
</p>
</div>
<div class="warning">
<p>
This is a warning
</p>
</div>
<p>
These are the only admonitions supported by <a href="http://www.docbook.org/">DocBook</a>.
So, for example <tt>[information This is some information]</tt> is
unlikely to produce the desired effect.
</p>
</div>
</div>
<div id="quickbook.syntax.block.headings">
<h3>
Headings
</h3>
<div id="quickbook.syntax.block.headings">
<pre class="programlisting">[h1 Heading 1]
[h2 Heading 2]
[h3 Heading 3]
[h4 Heading 4]
[h5 Heading 5]
[h6 Heading 6]
</pre>
<h1 id="quickbook.syntax.block.headings.heading_1">
Heading 1
</h1>
<h2 id="quickbook.syntax.block.headings.heading_2">
Heading 2
</h2>
<h3 id="quickbook.syntax.block.headings.heading_3">
Heading 3
</h3>
<h4 id="quickbook.syntax.block.headings.heading_4">
Heading 4
</h4>
<h5 id="quickbook.syntax.block.headings.heading_5">
Heading 5
</h5>
<h6 id="quickbook.syntax.block.headings.heading_6">
Heading 6
</h6>
<p>
Headings 1-3 [h1 h2 and h3] will automatically have anchors with normalized
names with <tt>name=&quot;section_id.normalized_header_text&quot;</tt>
(i.e. valid characters are <tt>a-z</tt>, <tt>A-Z</tt>, <tt>0-9</tt>
and <tt>_</tt>. All non-valid characters are converted to underscore
and all upper-case are converted to lower-case. For example: Heading
1 in section Section 2 will be normalized to <tt>section_2.heading_1</tt>).
You can use:
</p>
<pre class="programlisting">[link section_id.normalized_header_text The link text]
</pre>
<p>
to link to them. See <a href="#quickbook.syntax.phrase.anchor_links">Anchor
links</a> and <a href="#quickbook.syntax.block.section">Section</a>
for more info.
</p>
</div>
</div>
<div id="quickbook.syntax.block.generic_heading">
<h3>
Generic Heading
</h3>
<div id="quickbook.syntax.block.generic_heading">
<p>
In cases when you don't want to care about the heading level (1 to
6), you can use the <span class="emphasis"><em>Generic Heading</em></span>:
</p>
<pre class="programlisting">[heading Heading]
</pre>
<p>
The <span class="emphasis"><em>Generic Heading</em></span> assumes
the level, plus one, of the innermost section where it is placed. For
example, if it is placed in the outermost section, then, it assumes
<span class="emphasis"><em>h2</em></span>.
</p>
<p>
Headings are often used as an alternative to sections. It is used particularly
if you do not want to start a new section. In many cases, however,
headings in a particular section is just flat. Example:
</p>
<pre class="programlisting">[section A]
[h2 X]
[h2 Y]
[h2 Z]
[endsect]
</pre>
<p>
Here we use h2 assuming that section A is the outermost level. If it
is placed in an inner level, you'll have to use h3, h4, etc. depending
on where the section is. In general, it is the section level plus one.
It is rather tedious, however, to scan the section level everytime.
If you rewrite the example above as shown below, this will be automatic:
</p>
<pre class="programlisting">[section A]
[heading X]
[heading Y]
[heading Z]
[endsect]
</pre>
<p>
They work well regardless where you place them. You can rearrange sections
at will without any extra work to ensure correct heading levels. In
fact, with <span class="emphasis"><em>section</em></span> and <span
class="emphasis"><em>heading</em></span>, you have all you need. <span
class="emphasis"><em>h1</em></span>..<span class="emphasis"><em>h6</em></span>
becomes redundant. <span class="emphasis"><em>h1</em></span>..<span
class="emphasis"><em>h6</em></span> might be deprecated in the future.
</p>
</div>
</div>
<div id="quickbook.syntax.block.macros">
<h3>
Macros
</h3>
<div id="quickbook.syntax.block.macros">
<pre class="programlisting">[def macro_identifier some text]
</pre>
<p>
When a macro is defined, the identifier replaces the text anywhere
in the file, in paragraphs, in markups, etc. macro_identifier is a
string of non- white space characters except ']'. A macro may not follow
an alphabetic character or the underscore. The replacement text can
be any phrase (even marked up). Example:
</p>
<pre class="programlisting">[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&amp;type=1]]
sf_logo
</pre>
<p>
Now everywhere the sf_logo is placed, the picture will be inlined.
</p>
<p>
<span class="inlinemediaobject"><img src="http://sourceforge.net/sflogo.php?group_id=28447&amp;type=1"
alt="[]"/></span>
</p>
<div class="tip">
<p>
It's a good idea to use macro identifiers that are distinguishable.
For instance, in this document, macro identifiers have two leading
and trailing underscores (e.g. <tt>__spirit__</tt>). The reason is
to avoid unwanted macro replacement.
</p>
</div>
<p>
Links (URLS) and images are good candidates for macros. <span class="bold"><strong>1</strong></span>)
They tend to change a lot. It is a good idea to place all links and
images in one place near the top to make it easy to make changes.
<span class="bold"><strong>2</strong></span>) The syntax is not pretty.
It's easier to read and write, e.g. <tt>__spirit__</tt> than <tt>[@http://spirit.sourceforge.net
Spirit]</tt>.
</p>
<p>
Some more examples:
</p>
<pre class="programlisting">[def :-) [$theme/smiley.png]]
[def __spirit__ [@http://spirit.sourceforge.net Spirit]]
</pre>
<p>
(See <a href="#quickbook.syntax.phrase.images">Images</a> and <a href="#quickbook.syntax.phrase.links">Links</a>)
</p>
<p>
Invoking these macros:
</p>
<pre class="programlisting">Hi __spirit__ :-)
</pre>
<p>
will generate this:
</p>
<p>
Hi <a href="http://spirit.sourceforge.net">Spirit</a> <span class="inlinemediaobject"><img
src="images/smiley.png" alt="[]"/></span>
</p>
</div>
</div>
<div id="quickbook.syntax.block.predefined_macros">
<h3>
Predefined Macros
</h3>
<div id="quickbook.syntax.block.predefined_macros">
<p>
Quickbook has some predefined macros that you can already use.
</p>
<div id="quickbook.syntax.block.predefined_macros.t0" class="table">
<table>
<caption>Predefined Macros</caption>
<thead>
<tr>
<th>
<p>
Macro
</p>
</th>
<th>
<p>
Meaning
</p>
</th>
<th>
<p>
Example
</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>
__DATE__
</p>
</td>
<td>
<p>
Today's date
</p>
</td>
<td>
<p>
2000-Dec-20
</p>
</td>
</tr>
<tr>
<td>
<p>
__TIME__
</p>
</td>
<td>
<p>
The current time
</p>
</td>
<td>
<p>
12:00:00 PM
</p>
</td>
</tr>
<tr>
<td>
<p>
__FILENAME__
</p>
</td>
<td>
<p>
Quickbook source filename
</p>
</td>
<td>
<p>
quickbook_manual-1_4.quickbook
</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div id="quickbook.syntax.block.templates">
<h3>
Templates
</h3>
<div id="quickbook.syntax.block.templates">
<p>
Templates provide a more versatile text substitution mechanism. Templates
come in handy when you need to create parameterizable, multi-line,
boilerplate text that you specify once and expand many times. Templates
accept one or more arguments. These arguments act like place-holders
for text replacement. Unlike simple macros, which are limited to phrase
level markup, templates can contain block level markup (e.g. paragraphs,
code blocks and tables).
</p>
<p>
Example template:
</p>
<pre class="programlisting">[template person[name age what]
Hi, my name is [name]. I am [age] years old. I am a [what].
]
</pre>
<h5 id="quickbook.syntax.block.templates.template_identifier">
Template Identifier
</h5>
<p>
Template identifiers can either consist of:
</p>
<ul>
<li>
<div>
An initial alphabetic character or the underscore, followed by
zero or more alphanumeric characters or the underscore. This is
similar to your typical C/C++ identifier.
</div>
</li>
<li>
<div>
A single character punctuation (a non-alphanumeric printable character)
</div>
</li>
</ul>
<h5 id="quickbook.syntax.block.templates.formal_template_arguments">
Formal Template Arguments
</h5>
<p>
Template formal arguments are identifiers consisting of an initial
alphabetic character or the underscore, followed by zero or more alphanumeric
characters or the underscore. This is similar to your typical C/C++
identifier.
</p>
<p>
A template formal argument temporarily hides a template of the same
name at the point where the <a href="#quickbook.syntax.block.templates.template_expansion">template
is expanded</a>. Note that the body of the <tt>person</tt> template
above refers to <tt>name</tt> <tt>age</tt> and <tt>what</tt> as <tt>[name]</tt>
<tt>[age]</tt> and <tt>[what]</tt>. <tt>name</tt> <tt>age</tt> and
<tt>what</tt> are actually templates that exist in the duration of
the template call.
</p>
<h5 id="quickbook.syntax.block.templates.template_body">
Template Body
</h5>
<p>
The template body can be just about any QuickBook block or phrase.
There are actually two forms. Templates may be phrase or block level.
Phrase templates are of the form:
</p>
<pre class="programlisting">[template sample[arg1 arg2...argN] replacement text... ]
</pre>
<p>
Block templates are of the form:
</p>
<pre class="programlisting">[template sample[arg1 arg2...argN]
replacement text...
]
</pre>
<p>
The basic rule is as follows: if a newline immediately follows the
argument list, then it is a block template, otherwise, it is a phrase
template. Phrase templates are typically expanded as part of phrases.
Like macros, block level elements are not allowed in phrase templates.
</p>
<h5 id="quickbook.syntax.block.templates.template_expansion">
Template Expansion
</h5>
<p>
You expand a template this way:
</p>
<pre class="programlisting">[template_identifier arg1..arg2..arg3]
</pre>
<p>
At template expansion, you supply the actual arguments. The template
will be expanded with your supplied arguments. Example:
</p>
<pre class="programlisting">[person James Bond..39..Spy]
[person Santa Clause..87..Big Red Fatso]
</pre>
<p>
Which will expand to:
</p>
<p>
Hi, my name is James Bond. I am 39 years old. I am a Spy.
</p>
<p>
Hi, my name is Santa Clause. I am 87 years old. I am a Big Red Fatso.
</p>
<div class="caution">
<p>
A word of caution: Templates are recursive. A template can call another
template or even itself, directly or indirectly. There are no control
structures in QuickBook (yet) so this will always mean infinite recursion.
QuickBook can detect this situation and report an error if recursion
exceeds a certain limit.
</p>
</div>
<p>
Each actual argument can be a word, a text fragment or just about any
<a href="#quickbook.syntax.phrase">QuickBook phrase</a>. Arguments
are separated by the double dot <tt>&quot;..&quot;</tt> and terminated
by the close parenthesis.
</p>
<h5 id="quickbook.syntax.block.templates.nullary_templates">
Nullary Templates
</h5>
<p>
Nullary templates look and act like simple macros. Example:
</p>
<pre class="programlisting">[template alpha[]&apos;&apos;&apos;&amp;#945;&apos;&apos;&apos;]
[template beta[]&apos;&apos;&apos;&amp;#946;&apos;&apos;&apos;]
</pre>
<p>
Expanding:
</p>
<pre class="programlisting">Some squigles...[*[alpha][beta]]</pre>
<p>
We have:
</p>
<p>
Some squiggles...<span class="bold"><strong>&#945;&#946;</strong></span>
</p>
<p>
The difference with macros are
</p>
<ul>
<li>
<div>
The explicit <a href="#quickbook.syntax.block.templates.template_expansion">template
expansion syntax</a>. This is an advantage because, now, we don't
have to use obscure naming conventions like double underscores
(e.g. __alpha__) to avoid unwanted macro replacement.
</div>
</li>
<li>
<div>
The template is expanded at the point where it is invoked. A macro
is expanded immediately at its point of declaration. This is subtle
and can cause a slight difference in behavior especially if you
refer to other macros and templates in the body.
</div>
</li>
</ul>
<p>
The empty brackets after the template identifier (<tt>alpha[]</tt>)
indicates no arguments. If the template body does not look like a template
argument list, we can elide the empty brackets. Example:
</p>
<pre class="programlisting">[template aristotle_quote Aristotle: [*['Education is the best provision
for the journey to old age.]]]
</pre>
<p>
Expanding:
</p>
<pre class="programlisting">Here's a quote from [aristotle_quote].
</pre>
<p>
We have:
</p>
<p>
Here's a quote from Aristotle: <span class="bold"><strong><span class="emphasis"><em>Education
is the best provision for the journey to old age.</em></span></strong></span>.
</p>
<p>
The disadvantage is that you can't avoid the space between the template
identifier, <code><span class="identifier">aristotle_quote</span></code>,
and the template body &quot;Aristotle...&quot;. This space will be
part of the template body. If that space is unwanted, use empty brackets
or use the space escape: &quot;<code><span class="special">\</span>
</code>&quot;. Example:
</p>
<pre class="programlisting">[template tag\ _tag]
</pre>
<p>
Then expanding:
</p>
<pre class="programlisting">`struct` x[tag];
</pre>
<p>
We have:
</p>
<p>
<code><span class="keyword">struct</span></code> x_tag;
</p>
<p>
You have a couple of ways to do it. I personally prefer the explicit
empty brackets, though.
</p>
<h5 id="quickbook.syntax.block.templates.simple_arguments">
Simple Arguments
</h5>
<p>
As mentioned, arguments are separated by the double dot <tt>&quot;..&quot;</tt>.
If there are less arguments passed than expected, QuickBook attempts
to break the last argument into two or more arguments following this
logic:
</p>
<ul>
<li>
<div>
Break the last argument into two, at the first space found (<tt>'',
'\n', \t' or '\r'</tt>).
</div>
</li>
<li>
<div>
Repeat until there are enough arguments or if there are no more
spaces found (in which case, an error is reported).
</div>
</li>
</ul>
<p>
For example:
</p>
<pre class="programlisting">[template simple[a b c d] [a][b][c][d]]
[simple w x y z]
</pre>
<p>
will produce:
</p>
<p>
wxyz
</p>
<p>
&quot;w x y z&quot; is initially treated as a single argument because
we didn't supply any <tt>&quot;..&quot;</tt> separators. However, since
<tt>simple</tt> expects 4 arguments, &quot;w x y z&quot; is broken
down iteratively (applying the logic above) until we have &quot;w&quot;,
&quot;x&quot;, &quot;y&quot; and &quot;z&quot;.
</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: &quot;w&quot;, &quot;x&quot;, &quot;y&quot; and
&quot;z trail&quot;.
</p>
<p>
It should be obvious now that for simple arguments with no spaces,
we can get by without separating the arguments with <tt>&quot;..&quot;</tt>
separators. It is possible to combine <tt>&quot;..&quot;</tt> separators
with the argument passing simplification presented above. Example:
</p>
<pre class="programlisting">[simple what do you think ..m a n?]
</pre>
<p>
will produce:
</p>
<p>
what do you think man?
</p>
<h5 id="quickbook.syntax.block.templates.punctuation_templates">
Punctuation Templates
</h5>
<p>
With templates, one of our objectives is to allow us to rewrite QuickBook
in QuickBook (as a qbk library). For that to happen, we need to accommodate
single character punctuation templates which are fairly common in QuickBook.
You might have noticed that single character punctuations are allowed
as <a href="#quickbook.syntax.block.templates.template_identifier">template
identifiers</a>. Example:
</p>
<pre class="programlisting">[template ![bar] &lt;hey&gt;[bar]&lt;/hey&gt;]
</pre>
<p>
Now, expanding this:
</p>
<pre class="programlisting">[!baz]
</pre>
<p>
We will have:
</p>
<pre class="programlisting">&lt;hey&gt;baz&lt;/hey&gt;
</pre>
</div>
</div>
<div id="quickbook.syntax.block.blurbs">
<h3>
Blurbs
</h3>
<div id="quickbook.syntax.block.blurbs">
<pre class="programlisting">[blurb :-) [*An eye catching advertisement or note...]
__spirit__ is an object-oriented recursive-descent parser generator framework
implemented using template meta-programming techniques. Expression templates
allow us to approximate the syntax of Extended Backus-Normal Form (EBNF)
completely in C++.
]
</pre>
<p>
will generate this:
</p>
<div class="blurb">
<p>
<span class="inlinemediaobject"><img src="images/smiley.png" alt="[]"/></span>
<span class="bold"><strong>An eye catching advertisement or note...</strong></span>
</p>
<p>
<a href="http://spirit.sourceforge.net">Spirit</a> is an object-oriented
recursive-descent parser generator framework implemented using template
meta-programming techniques. Expression templates allow us to approximate
the syntax of Extended Backus-Normal Form (EBNF) completely in C++.
</p>
</div>
<div class="note">
<p>
Prefer <a href="#quickbook.syntax.block.admonitions">admonitions</a>
wherever appropriate.
</p>
</div>
</div>
</div>
<div id="quickbook.syntax.block.tables">
<h3>
Tables
</h3>
<div id="quickbook.syntax.block.tables">
<pre class="programlisting">[table A Simple Table
[[Heading 1] [Heading 2] [Heading 3]]
[[R0-C0] [R0-C1] [R0-C2]]
[[R1-C0] [R1-C1] [R1-C2]]
[[R2-C0] [R2-C1] [R2-C2]]
]
</pre>
<p>
will generate:
</p>
<div id="quickbook.syntax.block.tables.t0" class="table">
<table>
<caption>A Simple Table</caption>
<thead>
<tr>
<th>
<p>
Heading 1
</p>
</th>
<th>
<p>
Heading 2
</p>
</th>
<th>
<p>
Heading 3
</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>
R0-C0
</p>
</td>
<td>
<p>
R0-C1
</p>
</td>
<td>
<p>
R0-C2
</p>
</td>
</tr>
<tr>
<td>
<p>
R2-C0
</p>
</td>
<td>
<p>
R2-C1
</p>
</td>
<td>
<p>
R2-C2
</p>
</td>
</tr>
<tr>
<td>
<p>
R3-C0
</p>
</td>
<td>
<p>
R3-C1
</p>
</td>
<td>
<p>
R3-C2
</p>
</td>
</tr>
</tbody>
</table>
</div>
<p>
The table title is optional. The first row of the table is automatically
treated as the table header; that is, it is wrapped in <tt>&lt;thead&gt;...&lt;/thead&gt;</tt>
XML tags. Note that unlike the original QuickDoc, the columns are nested
in [ cells... ]. The syntax is free-format and allows big cells to
be formatted nicely. Example:
</p>
<pre class="programlisting">[table Table with fat cells
[[Heading 1] [Heading 2]]
[
[Row 0, Col 0: a small cell]
[
Row 0, Col 1: a big fat cell with paragraphs
Boost provides free peer-reviewed portable C++ source libraries.
We emphasize libraries that work well with the C++ Standard Library.
Boost libraries are intended to be widely useful, and usable across
a broad spectrum of applications. The Boost license encourages both
commercial and non-commercial use.
]
]
[
[Row 1, Col 0: a small cell]
[Row 1, Col 1: a small cell]
]
]
</pre>
<p>
and thus:
</p>
<div id="quickbook.syntax.block.tables.t1" class="table">
<table>
<caption>Table with fat cells</caption>
<thead>
<tr>
<th>
<p>
Heading 1
</p>
</th>
<th>
<p>
Heading 2
</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>
Row 0, Col 0: a small cell
</p>
</td>
<td>
<p>
Row 0, Col 1: a big fat cell with paragraphs
</p>
<p>
Boost provides free peer-reviewed portable C++ source libraries.
</p>
<p>
We emphasize libraries that work well with the C++ Standard
Library. Boost libraries are intended to be widely useful,
and usable across a broad spectrum of applications. The Boost
license encourages both commercial and non-commercial use.
</p>
</td>
</tr>
<tr>
<td>
<p>
Row 1, Col 0: a small cell
</p>
</td>
<td>
<p>
Row 1, Col 1: a small cell
</p>
</td>
</tr>
</tbody>
</table>
</div>
<p>
Here's how to have preformatted blocks of code in a table cell:
</p>
<pre class="programlisting">[table Table with code
[[Comment] [Code]]
[
[My first program]
[``
#include &lt;iostream&gt;
int main()
{
std::cout &lt;&lt; &quot;Hello, World!&quot; &lt;&lt; std::endl;
return 0;
}
``]
]
]
</pre>
<div id="quickbook.syntax.block.tables.t2" class="table">
<table>
<caption>Table with code</caption>
<thead>
<tr>
<th>
<p>
Comment
</p>
</th>
<th>
<p>
Code
</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>
My first program
</p>
</td>
<td>
<p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</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">&lt;&lt;</span> <span class="string">&quot;Hello, World!&quot;</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="special">}</span>
</pre>
</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div id="quickbook.syntax.block.variable_lists">
<h3>
Variable Lists
</h3>
<div id="quickbook.syntax.block.variable_lists">
<pre class="programlisting">[variablelist A Variable List
[[term 1] [The definition of term 1]]
[[term 2] [The definition of term 2]]
[[term 3] [The definition of term 3]]
]
</pre>
<p>
will generate:
</p>
<dl>
<dt>
term 1
</dt>
<dd>
<p>
The definition of term 1
</p>
</dd>
<dt>
term 2
</dt>
<dd>
<p>
The definition of term 2
</p>
</dd>
<dt>
term 3
</dt>
<dd>
<p>
The definition of term 3
</p>
</dd>
</dl>
<p>
The rules for variable lists are the same as for tables, except that
only 2 &quot;columns&quot; are allowed. The first column contains the
terms, and the second column contains the definitions. Those familiar
with HTML will recognize this as a &quot;definition list&quot;.
</p>
</div>
</div>
<div id="quickbook.syntax.block.include">
<h3>
Include
</h3>
<div id="quickbook.syntax.block.include">
<p>
You can include one QuickBook file from another. The syntax is simply:
</p>
<pre class="programlisting">[include someother.qbk]
</pre>
<p>
The included file will be processed as if it had been cut and pasted
into the current document, with the following exceptions:
</p>
<ul>
<li>
<div>
The __FILENAME__ predefined macro will reflect the name of the
file currently being processed.
</div>
</li>
<li>
<div>
Any macros defined in the included file are scoped to that file.
</div>
</li>
</ul>
<p>
The <tt>[include]</tt> directive lets you specify a document id to
use for the included file. When this id is not explicitly specified,
the id defaults to the filename (&quot;someother&quot;, 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 &quot;Intro&quot;,
the named anchor for that section will be &quot;someid.intro&quot;,
and you can link to it with <tt>[link someid.intro The Intro]</tt>.
</p>
</div>
</div>
<div id="quickbook.syntax.block.import">
<h3>
Import
</h3>
<div id="quickbook.syntax.block.import">
<p>
When documenting code, you'd surely need to present code from actual
source files. While it is possible to copy some code and paste them
in your QuickBook file, doing so is error prone and the extracted code
in the documentation tends to get out of sync with the actual code
as the code evolves. The problem, as always, is that once documentation
is written, the tendency is for the docs to languish in the archives
without maintenance.
</p>
<p>
QuickBook's import facility provides a nice solution.
</p>
<h5 id="quickbook.syntax.block.import.example">
Example
</h5>
<p>
You can effortlessly import code snippets from source code into your
QuickBook. The following illustrates how this is done:
</p>
<pre class="programlisting">[import ../test/stub.cpp]
[foo]
[bar]
</pre>
<p>
The first line:
</p>
<pre class="programlisting">[import ../test/stub.cpp]
</pre>
<p>
collects specially marked-up code snippets from <a href="../../test/stub.cpp">stub.cpp</a>
and places them in your QuickBook file as virtual templates. Each of
the specially marked-up code snippets has a name (e.g. <code><span
class="identifier">foo</span></code> and <code><span class="identifier">bar</span></code>
in the example above). This shall be the template identifier for that
particular code snippet. The second and third line above does the actual
template expansion:
</p>
<pre class="programlisting">[foo]
[bar]
</pre>
<p>
And the result is:
</p>
<p>
This is the <span class="bold"><strong><span class="emphasis"><em>foo</em></span></strong></span>
function.
</p>
<p>
This description can have paragraphs...
</p>
<ul>
<li>
<div>
lists
</div>
</li>
<li>
<div>
etc.
</div>
</li>
</ul>
<p>
And any quickbook block markup.
</p>
<p>
<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">foo</span><span class="special">()</span>
<span class="special">{</span>
<span class="comment">// return 'em, foo man!</span>
<span class="keyword">return</span> <span class="string">&quot;foo&quot;</span><span class="special">;</span>
<span class="special">}</span>
</pre>
</p>
<p>
This is the <span class="bold"><strong><span class="emphasis"><em>bar</em></span></strong></span>
function
</p>
<p>
<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">bar</span><span class="special">()</span>
<span class="special">{</span>
<span class="comment">// return 'em, bar man!</span>
<span class="keyword">return</span> <span class="string">&quot;bar&quot;</span><span class="special">;</span>
<span class="special">}</span>
</pre>
</p>
<p>
Some trailing text here
</p>
<h5 id="quickbook.syntax.block.import.code_snippet_markup">
Code Snippet Markup
</h5>
<p>
Note how the code snippets in <a href="../../test/stub.cpp">stub.cpp</a>
get marked up. We use distinguishable comments following the form:
</p>
<pre class="programlisting"><span class="comment">//[id</span>
<span class="identifier">some</span> <span class="identifier">code</span> <span class="identifier">here</span>
<span class="comment">//]</span>
</pre>
<p>
The first comment line above initiates a named code-snippet. This prefix
will not be visible in quickbook. The entire code-snippet in between
<code><span class="comment">//[id</span></code> and <code><span class="comment">//]</span></code>
will be inserted as a template in quickbook with name <span class="emphasis"><em><span
class="emphasis"><em>id</em></span></em></span>. The comment <code><span
class="comment">//]</span></code> ends a code-snippet This too will
not be visible in quickbook.
</p>
<h5 id="quickbook.syntax.block.import.special_comments">
Special Comments
</h5>
<p>
Special comments of the form:
</p>
<pre class="programlisting"><span class="comment">//` some [*quickbook] markup here</span>
</pre>
<p>
and:
</p>
<pre class="programlisting"><span class="comment">/*` some [*quickbook] markup here */</span>
</pre>
<p>
will be parsed by QuickBook. This can contain quickbook <span class="emphasis"><em>blocks</em></span>
(e.g. sections, paragraphs, tables, etc). In the first case, the initial
slash-slash, tick and white-space shall be ignored. In the second,
the initial slash-star-tick and the final star-slash shall be ignored.
</p>
<h5 id="quickbook.syntax.block.import.callouts">
Callouts
</h5>
<p>
Special comments of the form:
</p>
<pre class="programlisting"><span class="comment">/*&lt; some [*quickbook] markup here &gt;*/</span>
</pre>
<p>
will be regarded as callouts. These will be collected, numbered and
rendered as a &quot;callout bug&quot; (a small icon with a number).
After the whole snippet is parsed, the callout list is generated. See
<a href="http://www.docbook.org/tdg/en/html/callout.html">Callouts</a>
for details. Example:
</p>
<p>
<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">foo_bar</span><span class="special">()</span> <a href="#quickbook.syntax.block.import.c1">(1)</a>
<span class="special">{</span>
<span class="keyword">return</span> <span class="string">&quot;foo-bar&quot;</span><span class="special">;</span> <a href="#quickbook.syntax.block.import.c3">(2)</a>
<span class="special">}</span>
</pre>
</p>
<div>
<div id="quickbook.syntax.block.import.c1">
<a href="#quickbook.syntax.block.import.c0">(1)</a>
<p>
The <span class="emphasis"><em>Mythical</em></span> FooBar. See
<a href="http://en.wikipedia.org/wiki/Foobar">Foobar for details</a>
</p>
</div>
<div id="quickbook.syntax.block.import.c3">
<a href="#quickbook.syntax.block.import.c2">(2)</a>
<p>
return 'em, foo-bar man!
</p>
</div>
</div>
<p>
Checkout <a href="../../test/stub.cpp">stub.cpp</a> to see the actual
code.
</p>
</div>
</div>
</div>
</div>
<div id="quickbook.install">
<h3>
Installation and configuration
</h3>
<div id="quickbook.install">
<p>
This section provides some guidelines on how to install and configure BoostBook
and Quickbook under several operating systems.
</p>
<p>
Before continuing, it is very important that you keep this in mind: if
you try to build some documents and the process breaks due to misconfiguration,
be absolutely sure to delete any <code><span class="identifier">bin</span></code>
and <code><span class="identifier">bin</span><span class="special">.</span><span
class="identifier">v2</span></code> directories generated by the build
before trying again. Otherwise your configuration fixes will not take any
effect.
</p>
</div>
<div id="quickbook.install.windows">
<h3>
Windows 2000, XP, 2003, Vista
</h3>
<div id="quickbook.install.windows">
<blockquote>
<p>
<span class="emphasis"><em>Section contributed by Julio M. Merino Vidal</em></span>
</p>
</blockquote>
<p>
The following instructions apply to any Windows system based on Windows
2000, including Windows XP, Windows 2003 Server and Windows Vista. The
paths shown below are taken from a Windows Vista machine; you will need
to adjust them to match your system in case you are running an older
version.
</p>
<ol>
<li>
<div>
First of all you need to have a copy of <code><span class="identifier">xsltproc</span></code>
for Windows. There are many ways to get this tool, but to keep things
simple, use the <a href="http://www.zlatkovic.com/pub/libxml/">binary
packages</a> made by Igor Zlatkovic. At the very least, you need
to download the following packages: <code><span class="identifier">iconv</span></code>,
<code><span class="identifier">zlib</span></code>, <code><span class="identifier">libxml2</span></code>
and <code><span class="identifier">libxslt</span></code>.
</div>
</li>
<li>
<div>
Unpack all these packages in the same directory so that you get unique
<code><span class="identifier">bin</span></code>, <code><span class="identifier">include</span></code>
and <code><span class="identifier">lib</span></code> directories
within the hierarchy. These instructions use <code><span class="identifier">C</span><span
class="special">:\</span><span class="identifier">Users</span><span
class="special">\</span><span class="identifier">example</span><span
class="special">\</span><span class="identifier">Documents</span><span
class="special">\</span><span class="identifier">boost</span><span
class="special">\</span><span class="identifier">xml</span></code>
as the root for all files.
</div>
</li>
<li>
<div>
From the command line, go to the <code><span class="identifier">bin</span></code>
directory and launch <code><span class="identifier">xsltproc</span><span
class="special">.</span><span class="identifier">exe</span></code>
to ensure it works. You should get usage information on screen.
</div>
</li>
<li>
<div>
Download <a href="http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip">Docbook
XML 4.2</a> and unpack it in the same directory used above. That
is: <code><span class="identifier">C</span><span class="special">:\</span><span
class="identifier">Users</span><span class="special">\</span><span
class="identifier">example</span><span class="special">\</span><span
class="identifier">Documents</span><span class="special">\</span><span
class="identifier">boost</span><span class="special">\</span><span
class="identifier">xml</span><span class="special">\</span><span
class="identifier">docbook</span><span class="special">-</span><span
class="identifier">xml</span></code>.
</div>
</li>
<li>
<div>
Download the latest <a href="http://sourceforge.net/project/showfiles.php?group_id=21935&amp;package_id=16608">Docbook
XSL</a> version and unpack it, again in the same directory used before.
To make things easier, rename the directory created during the extraction
to <code><span class="identifier">docbook</span><span class="special">-</span><span
class="identifier">xsl</span></code> (bypassing the version name):
<code><span class="identifier">C</span><span class="special">:\</span><span
class="identifier">Users</span><span class="special">\</span><span
class="identifier">example</span><span class="special">\</span><span
class="identifier">Documents</span><span class="special">\</span><span
class="identifier">boost</span><span class="special">\</span><span
class="identifier">xml</span><span class="special">\</span><span
class="identifier">docbook</span><span class="special">-</span><span
class="identifier">xsl</span></code>.
</div>
</li>
<li>
<div>
Add the following to your <code><span class="identifier">user</span><span
class="special">-</span><span class="identifier">config</span><span
class="special">.</span><span class="identifier">jam</span></code>
file, which should live in your home directory (<code><span class="special">%</span><span
class="identifier">HOMEDRIVE</span><span class="special">%%</span><span
class="identifier">HOMEPATH</span><span class="special">%</span></code>).
You must already have it somewhere or otherwise you could not be
building Boost (i.e. missing tools configuration).
</div>
</li>
</ol>
<pre class="programlisting"><span class="identifier">using</span> <span class="identifier">xsltproc</span>
<span class="special">:</span> <span class="string">&quot;C:/Users/example/Documents/boost/xml/bin/xsltproc.exe&quot;</span>
<span class="special">;</span>
<span class="identifier">using</span> <span class="identifier">boostbook</span>
<span class="special">:</span> <span class="string">&quot;C:/Users/example/Documents/boost/xml/docbook-xsl&quot;</span>
<span class="special">:</span> <span class="string">&quot;C:/Users/example/Documents/boost/xml/docbook-xml&quot;</span>
<span class="special">;</span>
</pre>
<p>
The above steps are enough to get a functional BoostBook setup. Quickbook
will be automatically built when needed. If you want to avoid these rebuilds:
</p>
<ol>
<li>
<div>
Go to Quickbook's source directory (<code><span class="identifier">BOOST_ROOT</span><span
class="special">\</span><span class="identifier">tools</span><span
class="special">\</span><span class="identifier">quickbook</span></code>).
</div>
</li>
<li>
<div>
Build the utility by issuing <code><span class="identifier">bjam</span>
<span class="special">--</span><span class="identifier">v2</span></code>.
</div>
</li>
<li>
<div>
Copy the resulting <code><span class="identifier">quickbook</span><span
class="special">.</span><span class="identifier">exe</span></code>
binary (located under the <code><span class="identifier">BOOST_ROOT</span><span
class="special">\</span><span class="identifier">bin</span><span
class="special">.</span><span class="identifier">v2</span></code>
hierarchy) to a safe place. Following our previous example, you can
install it into: <code><span class="identifier">C</span><span class="special">:\</span><span
class="identifier">Users</span><span class="special">\</span><span
class="identifier">example</span><span class="special">\</span><span
class="identifier">Documents</span><span class="special">\</span><span
class="identifier">boost</span><span class="special">\</span><span
class="identifier">xml</span><span class="special">\</span><span
class="identifier">bin</span></code>.
</div>
</li>
<li>
<div>
Add the following to your <code><span class="identifier">user</span><span
class="special">-</span><span class="identifier">config</span><span
class="special">.</span><span class="identifier">jam</span></code>
file:
</div>
</li>
</ol>
<pre class="programlisting"><span class="identifier">using</span> <span class="identifier">quickbook</span>
<span class="special">:</span> <span class="string">&quot;C:/Users/example/Documents/boost/xml/bin/quickbook.exe&quot;</span>
<span class="special">;</span>
</pre>
</div>
</div>
<div id="quickbook.install.linux">
<h3>
Debian, Ubuntu
</h3>
<div id="quickbook.install.linux">
<p>
The following instructions apply to Debian and its derivatives. They
are based on a Ubuntu Edgy install but should work on other Debian based
systems.
</p>
<p>
First install the <code><span class="identifier">bjam</span></code>,
<code><span class="identifier">xsltproc</span></code>, <code><span class="identifier">docbook</span><span
class="special">-</span><span class="identifier">xsl</span></code> and
<code><span class="identifier">docbook</span><span class="special">-</span><span
class="identifier">xml</span></code> packages. For example, using <code><span
class="identifier">apt</span><span class="special">-</span><span class="identifier">get</span></code>:
</p>
<pre class="programlisting"><span class="identifier">sudo</span> <span class="identifier">apt</span><span class="special">-</span><span class="identifier">get</span> <span class="identifier">install</span> <span class="identifier">xsltprc</span> <span class="identifier">docbook</span><span class="special">-</span><span class="identifier">xsl</span> <span class="identifier">docbook</span><span class="special">-</span><span class="identifier">xml</span>
</pre>
<p>
If you're planning on building boost's documentation, you'll also need
to install the <code><span class="identifier">doxygen</span></code> package
as well.
</p>
<p>
Next, we need to configure Boost Build to compile BoostBook files. Add
the following to your <code><span class="identifier">user</span><span
class="special">-</span><span class="identifier">config</span><span class="special">.</span><span
class="identifier">jam</span></code> file, which should be in your home
directory. If you don't have one, create a file containing this text.
For more information on setting up <code><span class="identifier">user</span><span
class="special">-</span><span class="identifier">config</span><span class="special">.</span><span
class="identifier">jam</span></code>, see the <a href="http://boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html">Boost
Build documentation</a>.
</p>
<pre class="programlisting"><span class="identifier">using</span> <span class="identifier">xsltproc</span> <span class="special">;</span>
<span class="identifier">using</span> <span class="identifier">boostbook</span>
<span class="special">:</span> <span class="special">/</span><span class="identifier">usr</span><span class="special">/</span><span class="identifier">share</span><span class="special">/</span><span class="identifier">xml</span><span class="special">/</span><span class="identifier">docbook</span><span class="special">/</span><span class="identifier">stylesheet</span><span class="special">/</span><span class="identifier">nwalsh</span>
<span class="special">:</span> <span class="special">/</span><span class="identifier">usr</span><span class="special">/</span><span class="identifier">share</span><span class="special">/</span><span class="identifier">xml</span><span class="special">/</span><span class="identifier">docbook</span><span class="special">/</span><span class="identifier">schema</span><span class="special">/</span><span class="identifier">dtd</span><span class="special">/</span><span class="number">4.2</span>
<span class="special">;</span>
<span class="comment"># Remove this line if you're not using doxygen</span>
<span class="identifier">using</span> <span class="identifier">doxygen</span> <span class="special">;</span>
</pre>
<p>
The above steps are enough to get a functional BoostBook setup. Quickbook
will be automatically built when needed. If you want to avoid these rebuilds:
</p>
<ol>
<li>
<div>
Go to Quickbook's source directory (<code><span class="identifier">BOOST_ROOT</span><span
class="special">/</span><span class="identifier">tools</span><span
class="special">/</span><span class="identifier">quickbook</span></code>).
</div>
</li>
<li>
<div>
Build the utility by issuing <code><span class="identifier">bjam</span>
<span class="special">--</span><span class="identifier">v2</span></code>.
</div>
</li>
<li>
<div>
Copy the resulting <code><span class="identifier">quickbook</span></code>
binary (located under the <code><span class="identifier">BOOST_ROOT</span><span
class="special">/</span><span class="identifier">bin</span><span
class="special">.</span><span class="identifier">v2</span></code>
hierarchy) to a safe place. The traditional location is <code><span
class="special">/</span><span class="identifier">usr</span><span
class="special">/</span><span class="identifier">local</span><span
class="special">/</span><span class="identifier">bin</span></code>.
</div>
</li>
<li>
<div>
Add the following to your <code><span class="identifier">user</span><span
class="special">-</span><span class="identifier">config</span><span
class="special">.</span><span class="identifier">jam</span></code>
file, using the full path of the quickbook executable:
</div>
</li>
</ol>
<pre class="programlisting"><span class="identifier">using</span> <span class="identifier">quickbook</span>
<span class="special">:</span> <span class="special">/</span><span class="identifier">usr</span><span class="special">/</span><span class="identifier">local</span><span class="special">/</span><span class="identifier">bin</span><span class="special">/</span><span class="identifier">quickbook</span>
<span class="special">;</span>
</pre>
</div>
</div>
</div>
<div id="quickbook.editors">
<h3>
Editor Support
</h3>
<div id="quickbook.editors">
<p>
Editing quickbook files is usually done with text editors both simple and
powerful. The following sections list the settings for some editors which
can help make editing quickbook files a bit easier.
</p>
<div class="blurb">
<p>
<span class="inlinemediaobject"><img src="images/note.png" alt="[]"/></span>
You may submit your settings, tips, and suggestions to the authors, or
through the <a href="https://lists.sourceforge.net/lists/listinfo/boost-">docs
Boost Docs mailing list</a>.
</p>
</div>
</div>
<div id="quickbook.editors.scite">
<h3>
Scintilla Text Editor
</h3>
<div id="quickbook.editors.scite">
<blockquote>
<p>
<span class="emphasis"><em>Section contributed by Dean Michael Berris</em></span>
</p>
</blockquote>
<p>
The Scintilla Text Editor (SciTE) is a free source code editor for Win32
and X. It uses the SCIntilla source code editing component.
</p>
<div class="blurb">
<p>
<span class="inlinemediaobject"><img src="images/tip.png" alt="[]"/></span>
SciTE can be downloaded from <a href="http://www.scintilla.org/SciTE.html">http://www.scintilla.org/SciTE.html</a>
</p>
</div>
<p>
You can use the following settings to highlight quickbook tags when editing
quickbook files.
</p>
<pre class="programlisting">qbk=*.qbk
lexer.*.qbk=props
use.tabs.$(qbk)=0
tab.size.$(qbk)=4
indent.size.$(qbk)=4
style.props.32=$(font.base)
comment.stream.start.props=[/
comment.stream.end.props=]
comment.box.start.props=[/
comment.box.middle.props=
comment.box.end.props=]
</pre>
<div class="blurb">
<p>
<span class="inlinemediaobject"><img src="images/note.png" alt="[]"/></span>
Thanks to Rene Rivera for the above SciTE settings.
</p>
</div>
</div>
</div>
</div>
<div id="quickbook.faq">
<h3>
Frequently Asked Questions
</h3>
<div id="quickbook.faq">
<h3 id="quickbook.faq.can_i_use_quickbook_for_non_boost_documentation_">
Can I use QuickBook for non-Boost documentation?
</h3>
<p>
QuickBook can be used for non-Boost documentation with a little extra work.
</p>
<blockquote>
<p>
<span class="emphasis"><em>Faq contributed by Michael Marcin</em></span>
</p>
</blockquote>
<p>
When building HTML documentation with BoostBook a Boost C++ Libraries header
is added to the files. When using QuickBook to document projects outside
of Boost this is not desirable. This behavior can be overridden at the
BoostBook level by specifying some XSLT options. When using Boost Build
version 2 (BBv2) this can be achieved by adding parameters to the BoostBook
target declaration.
</p>
<p>
For example:
</p>
<pre class="programlisting">using quickbook ;
xml my_doc : my_doc.qbk ;
boostbook standalone
:
my_doc
:
&lt;xsl:param&gt;boost.image.src=images/my_project_logo.png
&lt;xsl:param&gt;boost.image.alt=&quot;\&quot;My Project\&quot;&quot;
&lt;xsl:param&gt;boost.image.w=100
&lt;xsl:param&gt;boost.image.h=50
&lt;xsl:param&gt;nav.layout=none
;
</pre>
</div>
</div>
<div id="quickbook.ref">
<h3>
Quick Reference
</h3>
<div id="quickbook.ref">
<p>
[cpp]
</p>
<div id="quickbook.ref.t0" class="table">
<table>
<caption>Syntax Compendium</caption>
<thead>
<tr>
<th>
<p>
To do this...
</p>
</th>
<th>
<p>
Use this...
</p>
</th>
<th>
<p>
See this...
</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>
comment
</p>
</td>
<td>
<p>
<tt>[/ some comment]</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.comments">Comments</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="emphasis"><em>italics</em></span>
</p>
</td>
<td>
<p>
<tt>['italics] or /italics/</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.phrase.font_styles">Font Styles</a>
and <a href="#quickbook.syntax.phrase.simple_formatting">Simple
formatting</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="bold"><strong>bold</strong></span>
</p>
</td>
<td>
<p>
<tt>[*bold] or *bold*</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.phrase.font_styles">Font Styles</a>
and <a href="#quickbook.syntax.phrase.simple_formatting">Simple
formatting</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="underline">underline</span>
</p>
</td>
<td>
<p>
<tt>[_underline] or _underline_</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.phrase.font_styles">Font Styles</a>
and <a href="#quickbook.syntax.phrase.simple_formatting">Simple
formatting</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
<tt>teletype</tt>
</p>
</td>
<td>
<p>
<tt>[^teletype] or =teletype=</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.phrase.font_styles">Font Styles</a>
and <a href="#quickbook.syntax.phrase.simple_formatting">Simple
formatting</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="strikethrough">strikethrough</span>
</p>
</td>
<td>
<p>
<tt>[-strikethrough]</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.phrase.font_styles">Font Styles</a>
and <a href="#quickbook.syntax.phrase.simple_formatting">Simple
formatting</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
<em class="replaceable">replaceable</em>
</p>
</td>
<td>
<p>
<tt>[~replaceable]</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.phrase.replaceable">Replaceble</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
source mode
</p>
</td>
<td>
<p>
<tt>[c++]</tt> or <tt>[python]</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.phrase.source_mode">Source Mode</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
inline code
</p>
</td>
<td>
<p>
<tt>`int main();`</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.phrase.inline_code">Inline code</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
code block
</p>
</td>
<td>
<p>
<tt>``int main();``</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.block.code">Code</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
code escape
</p>
</td>
<td>
<p>
<tt>``from c++ to QuickBook``</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.block.escape_back">Escaping Back To
QuickBook</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
line break
</p>
</td>
<td>
<p>
<tt>[br] or \n</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.phrase.line_break">line-break</a>
<span class="bold"><strong>DEPRECATED</strong></span>
</p>
</td>
</tr>
<tr>
<td>
<p>
anchor
</p>
</td>
<td>
<p>
<tt>[#anchor]</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.phrase.anchors">Anchors</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
link
</p>
</td>
<td>
<p>
<tt>[@http://www.boost.org Boost]</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.phrase.links">Links</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
anchor link
</p>
</td>
<td>
<p>
<tt>[link section.anchor Link text]</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.phrase.anchor_links">Anchor links</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
refentry link
</p>
</td>
<td>
<p>
<tt>[link xml.refentry Link text]</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.phrase.refentry_links">refentry links</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
function link
</p>
</td>
<td>
<p>
<tt>[funcref fully::qualified::function_name Link text]</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.phrase.code_links">function, class,
member, enum, macro, concept or header links</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
class link
</p>
</td>
<td>
<p>
<tt>[classref fully::qualified::class_name Link text]</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.phrase.code_links">function, class,
member, enum, macro, concept or header links</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
member link
</p>
</td>
<td>
<p>
<tt>[memberref fully::qualified::member_name Link text]</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.phrase.code_links">function, class,
member, enum, macro, concept or header links</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
enum link
</p>
</td>
<td>
<p>
<tt>[enumref fully::qualified::enum_name Link text]</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.phrase.code_links">function, class,
member, enum, macro, concept or header links</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
macro link
</p>
</td>
<td>
<p>
<tt>[macroref MACRO_NAME Link text]</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.phrase.code_links">function, class,
member, enum, macro, concept or header links</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
concept link
</p>
</td>
<td>
<p>
<tt>[conceptref ConceptName Link text]</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.phrase.code_links">function, class,
member, enum, macro, concept or header links</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
header link
</p>
</td>
<td>
<p>
<tt>[headerref path/to/header.hpp Link text]</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.phrase.code_links">function, class,
member, enum, macro, concept or header links</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
escape
</p>
</td>
<td>
<p>
<tt>'''escaped text (no processing/formatting)'''</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.phrase.escape">Escape</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
single char escape
</p>
</td>
<td>
<p>
<tt>\c</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.phrase.single_char_escape">Single
char escape</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
images
</p>
</td>
<td>
<p>
<tt>[$image.jpg]</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.phrase.images">Images</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
begin section
</p>
</td>
<td>
<p>
<tt>[section The Section Title]</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.block.section">Section</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
end section
</p>
</td>
<td>
<p>
<tt>[endsect]</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.block.section">Section</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
paragraph
</p>
</td>
<td>
<p>
No markup. Paragraphs start left-flushed and are terminated by
two or more newlines.
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.block.paragraphs">Paragraphs</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
ordered list
</p>
</td>
<td>
<pre class="programlisting"># one
# two
# three
</pre>
</td>
<td>
<p>
<a href="#quickbook.syntax.block.lists.ordered_lists">Ordered
lists</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
unordered list
</p>
</td>
<td>
<pre class="programlisting">* one
* two
* three
</pre>
</td>
<td>
<p>
<a href="#quickbook.syntax.block.lists.unordered_lists">Unordered
lists</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
code
</p>
</td>
<td>
<p>
No markup. Preformatted code starts with a space or a tab.
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.block.code">Code</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
preformatted
</p>
</td>
<td>
<p>
<tt>[pre preformatted]</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.block.preformatted">Preformatted</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
block quote
</p>
</td>
<td>
<p>
<tt>[:sometext...]</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.block.blockquote">Blockquote</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
heading 1
</p>
</td>
<td>
<p>
<tt>[h1 Heading 1]</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.block.headings">Heading</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
heading 2
</p>
</td>
<td>
<p>
<tt>[h2 Heading 2]</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.block.headings">Heading</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
heading 3
</p>
</td>
<td>
<p>
<tt>[h3 Heading 3]</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.block.headings">Heading</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
heading 4
</p>
</td>
<td>
<p>
<tt>[h4 Heading 4]</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.block.headings">Heading</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
heading 5
</p>
</td>
<td>
<p>
<tt>[h5 Heading 5]</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.block.headings">Heading</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
heading 6
</p>
</td>
<td>
<p>
<tt>[h6 Heading 6]</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.block.headings">Heading</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
macro
</p>
</td>
<td>
<p>
<tt>[def macro_identifier some text]</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.block.macros">Macros</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
template
</p>
</td>
<td>
<p>
<tt>[template[a b] [a] body [b]]</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.block.templates">Templates</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
blurb
</p>
</td>
<td>
<p>
<tt>[blurb advertisement or note...]</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.block.blurbs">Blurbs</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
admonition
</p>
</td>
<td>
<p>
<tt>[warning Warning text...]</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.block.admonitions">Admonitions</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
table
</p>
</td>
<td>
<pre class="programlisting">[table Title
[[a][b][c]]
[[a][b][c]]
]
</pre>
</td>
<td>
<p>
<a href="#quickbook.syntax.block.tables">Tables</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
variablelist
</p>
</td>
<td>
<pre class="programlisting">[variablelist Title
[[a][b]]
[[a][b]]
]
</pre>
</td>
<td>
<p>
<a href="#quickbook.syntax.block.variable_lists">Variable Lists</a>
</p>
</td>
</tr>
<tr>
<td>
<p>
include
</p>
</td>
<td>
<p>
<tt>[include someother.qbk]</tt>
</p>
</td>
<td>
<p>
<a href="#quickbook.syntax.block.include">Include</a>
</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="footnotes">
<br/>
<hr/>
<div id="footnote-1" class="footnote">
<p>
<a href="#quickbook.syntax.phrase.simple_formatting.f0"><sup>[1]</sup></a>
Thanks to David Barrett, author of <a href="http://quinthar.com/qwikiwiki/index.php?page=Home">Qwiki</a>,
for sharing these samples and teaching me these obscure formatting rules.
I wasn't sure at all if <a href="http://spirit.sourceforge.net">Spirit</a>,
being more or less a formal EBNF parser, can handle the context sensitivity
and ambiguity.
</p>
</div>
<div id="footnote-2" class="footnote">
<p>
<a href="#quickbook.syntax.phrase.footnotes.f0"><sup>[2]</sup></a> A sample
footnote
</p>
</div>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink