2055 lines
80 KiB
HTML
2055 lines
80 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
||
<html>
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
||
<title>Block Level Elements</title>
|
||
<link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css">
|
||
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
|
||
<link rel="home" href="../../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
|
||
<link rel="up" href="../../quickbook.html" title="Chapter 51. Quickbook 1.7">
|
||
<link rel="prev" href="phrase.html" title="Phrase Level Elements">
|
||
<link rel="next" href="../versions.html" title="Language Versions">
|
||
</head>
|
||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||
<table cellpadding="2" width="100%"><tr>
|
||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td>
|
||
<td align="center"><a href="../../../../index.html">Home</a></td>
|
||
<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td>
|
||
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
|
||
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
|
||
<td align="center"><a href="../../../../more/index.htm">More</a></td>
|
||
</tr></table>
|
||
<hr>
|
||
<div class="spirit-nav">
|
||
<a accesskey="p" href="phrase.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../quickbook.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../versions.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||
<a name="quickbook.syntax.block"></a>Block Level Elements</h2></div></div></div>
|
||
<div class="toc"><dl class="toc">
|
||
<dt><span class="section"><a href="block.html#quickbook.syntax.block.xinclude">xinclude</a></span></dt>
|
||
<dt><span class="section"><a href="block.html#quickbook.syntax.block.paragraphs">Paragraphs</a></span></dt>
|
||
<dt><span class="section"><a href="block.html#quickbook.syntax.block.lists">Lists</a></span></dt>
|
||
<dt><span class="section"><a href="block.html#quickbook.syntax.block.code">Code</a></span></dt>
|
||
<dt><span class="section"><a href="block.html#quickbook.syntax.block.escape_back">Escaping
|
||
Back To QuickBook</a></span></dt>
|
||
<dt><span class="section"><a href="block.html#quickbook.syntax.block.preformatted">Preformatted</a></span></dt>
|
||
<dt><span class="section"><a href="block.html#quickbook.syntax.block.blockquote">Blockquote</a></span></dt>
|
||
<dt><span class="section"><a href="block.html#quickbook.syntax.block.admonitions">Admonitions</a></span></dt>
|
||
<dt><span class="section"><a href="block.html#quickbook.syntax.block.headings">Headings</a></span></dt>
|
||
<dt><span class="section"><a href="block.html#quickbook.syntax.block.generic_heading">Generic
|
||
Heading</a></span></dt>
|
||
<dt><span class="section"><a href="block.html#quickbook.syntax.block.macros">Macros</a></span></dt>
|
||
<dt><span class="section"><a href="block.html#quickbook.syntax.block.predefined_macros">Predefined
|
||
Macros</a></span></dt>
|
||
<dt><span class="section"><a href="block.html#quickbook.syntax.block.templates">Templates</a></span></dt>
|
||
<dt><span class="section"><a href="block.html#quickbook.syntax.block.blurbs">Blurbs</a></span></dt>
|
||
<dt><span class="section"><a href="block.html#quickbook.syntax.block.tables">Tables</a></span></dt>
|
||
<dt><span class="section"><a href="block.html#quickbook.syntax.block.variable_lists">Variable
|
||
Lists</a></span></dt>
|
||
<dt><span class="section"><a href="block.html#quickbook.syntax.block.include">Include</a></span></dt>
|
||
<dt><span class="section"><a href="block.html#quickbook.syntax.block.import">Import</a></span></dt>
|
||
<dt><span class="section"><a href="block.html#quickbook.syntax.block.block">Plain
|
||
blocks</a></span></dt>
|
||
</dl></div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="quickbook.syntax.block.xinclude"></a><a name="quickbook.ref.xinclude"></a><a class="link" href="block.html#quickbook.syntax.block.xinclude" title="xinclude">xinclude</a>
|
||
</h3></div></div></div>
|
||
<p>
|
||
You can include another XML file with:
|
||
</p>
|
||
<pre class="programlisting">[xinclude file.xml]
|
||
</pre>
|
||
<p>
|
||
This is useful when file.xml has been generated by Doxygen and contains your
|
||
reference section.
|
||
</p>
|
||
<p>
|
||
<code class="literal">xinclude</code> paths are normally used unchanged in the generated
|
||
documentation, which will not work if you wish them to be relative to the
|
||
current quickbook file. Quickbook can add a <code class="literal">xml:base</code> attribute
|
||
to the boostbook documentation to specify where <code class="literal">xinclude</code>
|
||
files should be found. For example, if you wish them to be relative to the
|
||
current quickbook file:
|
||
</p>
|
||
<pre class="programlisting">[article Article with xincludes
|
||
[quickbook 1.7]
|
||
[xmlbase .]
|
||
]
|
||
|
||
[xinclude file.xml]
|
||
</pre>
|
||
<p>
|
||
Now the xinclude should work if <code class="literal">file.xml</code> is in the same
|
||
directory as the quickbook file. Although it might not work if you distribute
|
||
the generated files (as their relative directories can change).
|
||
</p>
|
||
<p>
|
||
Say the article is generated in a sub-directory, by running something like:
|
||
</p>
|
||
<pre class="programlisting">quickbook article.qbk --output-file=output/article.xml
|
||
</pre>
|
||
<p>
|
||
This will generate a boostbook root tag:
|
||
</p>
|
||
<pre class="programlisting"><article id="article_with_xincludes"
|
||
last-revision="$Date: 2013/08/20 08:26:48 $"
|
||
xml:base=".."
|
||
xmlns:xi="http://www.w3.org/2001/XInclude">
|
||
</pre>
|
||
<p>
|
||
Because <code class="literal">xml:base</code> is set to <code class="literal">..</code>, the
|
||
xml processor will know to look in the parent directory to find <code class="literal">file.xml</code>,
|
||
which it comes across the <code class="literal">xi:include</code> tag.
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="quickbook.syntax.block.paragraphs"></a><a name="quickbook.ref.paragraphs"></a><a class="link" href="block.html#quickbook.syntax.block.paragraphs" title="Paragraphs">Paragraphs</a>
|
||
</h3></div></div></div>
|
||
<p>
|
||
Paragraphs start left-flushed and are terminated by two or more newlines.
|
||
No markup is needed for paragraphs. QuickBook automatically detects paragraphs
|
||
from the context. Block markups [section, endsect, h1, h2, h3, h4, h5, h6,
|
||
blurb, (block-quote) ':', pre, def, table and include ] may also terminate
|
||
a paragraph. This is a new paragraph...
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="quickbook.syntax.block.lists"></a><a name="quickbook.ref.lists"></a><a class="link" href="block.html#quickbook.syntax.block.lists" title="Lists">Lists</a>
|
||
</h3></div></div></div>
|
||
<div class="toc"><dl class="toc">
|
||
<dt><span class="section"><a href="block.html#quickbook.syntax.block.lists.ordered_lists">Ordered
|
||
lists</a></span></dt>
|
||
<dt><span class="section"><a href="block.html#quickbook.syntax.block.lists.list_hierarchies">List
|
||
Hierarchies</a></span></dt>
|
||
<dt><span class="section"><a href="block.html#quickbook.syntax.block.lists.long_list_lines">Long
|
||
List Lines</a></span></dt>
|
||
<dt><span class="section"><a href="block.html#quickbook.syntax.block.lists.unordered_lists">Unordered
|
||
lists</a></span></dt>
|
||
<dt><span class="section"><a href="block.html#quickbook.syntax.block.lists.mixed_lists">Mixed
|
||
lists</a></span></dt>
|
||
<dt><span class="section"><a href="block.html#quickbook.syntax.block.lists.list_paragraphs">Paragraphs
|
||
in lists</a></span></dt>
|
||
<dt><span class="section"><a href="block.html#quickbook.syntax.block.lists.list_tags">Explicit
|
||
list tags</a></span></dt>
|
||
</dl></div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="quickbook.syntax.block.lists.ordered_lists"></a><a name="quickbook.ref.ordered_lists"></a><a class="link" href="block.html#quickbook.syntax.block.lists.ordered_lists" title="Ordered lists">Ordered
|
||
lists</a>
|
||
</h4></div></div></div>
|
||
<pre class="programlisting"># One
|
||
# Two
|
||
# Three
|
||
</pre>
|
||
<p>
|
||
will generate:
|
||
</p>
|
||
<div class="orderedlist"><ol class="orderedlist" type="1">
|
||
<li class="listitem">
|
||
One
|
||
</li>
|
||
<li class="listitem">
|
||
Two
|
||
</li>
|
||
<li class="listitem">
|
||
Three
|
||
</li>
|
||
</ol></div>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="quickbook.syntax.block.lists.list_hierarchies"></a><a name="quickbook.ref.list_hierarchies"></a><a class="link" href="block.html#quickbook.syntax.block.lists.list_hierarchies" title="List Hierarchies">List
|
||
Hierarchies</a>
|
||
</h4></div></div></div>
|
||
<p>
|
||
List hierarchies are supported. Example:
|
||
</p>
|
||
<pre class="programlisting"># One
|
||
# Two
|
||
# Three
|
||
# Three.a
|
||
# Three.b
|
||
# Three.c
|
||
# Four
|
||
# Four.a
|
||
# Four.a.i
|
||
# Four.a.ii
|
||
# Five
|
||
</pre>
|
||
<p>
|
||
will generate:
|
||
</p>
|
||
<div class="orderedlist"><ol class="orderedlist" type="1">
|
||
<li class="listitem">
|
||
One
|
||
</li>
|
||
<li class="listitem">
|
||
Two
|
||
</li>
|
||
<li class="listitem">
|
||
Three
|
||
<div class="orderedlist"><ol class="orderedlist" type="a">
|
||
<li class="listitem">
|
||
Three.a
|
||
</li>
|
||
<li class="listitem">
|
||
Three.b
|
||
</li>
|
||
<li class="listitem">
|
||
Three.c
|
||
</li>
|
||
</ol></div>
|
||
</li>
|
||
<li class="listitem">
|
||
Fourth
|
||
<div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem">
|
||
Four.a
|
||
<div class="orderedlist"><ol class="orderedlist" type="i">
|
||
<li class="listitem">
|
||
Four.a.i
|
||
</li>
|
||
<li class="listitem">
|
||
Four.a.ii
|
||
</li>
|
||
</ol></div>
|
||
</li></ol></div>
|
||
</li>
|
||
<li class="listitem">
|
||
Five
|
||
</li>
|
||
</ol></div>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="quickbook.syntax.block.lists.long_list_lines"></a><a name="quickbook.ref.long_list_lines"></a><a class="link" href="block.html#quickbook.syntax.block.lists.long_list_lines" title="Long List Lines">Long
|
||
List Lines</a>
|
||
</h4></div></div></div>
|
||
<p>
|
||
Long lines will be wrapped appropriately. Example:
|
||
</p>
|
||
<pre class="programlisting"># A short item.
|
||
# A very long item. A very long item. A very long item.
|
||
A very long item. A very long item. A very long item.
|
||
A very long item. A very long item. A very long item.
|
||
A very long item. A very long item. A very long item.
|
||
A very long item. A very long item. A very long item.
|
||
# A short item.
|
||
</pre>
|
||
<div class="orderedlist"><ol class="orderedlist" type="1">
|
||
<li class="listitem">
|
||
A short item.
|
||
</li>
|
||
<li class="listitem">
|
||
A very long item. A very long item. A very long item. A very long item.
|
||
A very long item. A very long item. A very long item. A very long item.
|
||
A very long item. A very long item. A very long item. A very long item.
|
||
A very long item. A very long item. A very long item.
|
||
</li>
|
||
<li class="listitem">
|
||
A short item.
|
||
</li>
|
||
</ol></div>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="quickbook.syntax.block.lists.unordered_lists"></a><a name="quickbook.ref.unordered_lists"></a><a class="link" href="block.html#quickbook.syntax.block.lists.unordered_lists" title="Unordered lists">Unordered
|
||
lists</a>
|
||
</h4></div></div></div>
|
||
<pre class="programlisting">* First
|
||
* Second
|
||
* Third
|
||
</pre>
|
||
<p>
|
||
will generate:
|
||
</p>
|
||
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
|
||
<li class="listitem">
|
||
First
|
||
</li>
|
||
<li class="listitem">
|
||
Second
|
||
</li>
|
||
<li class="listitem">
|
||
Third
|
||
</li>
|
||
</ul></div>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="quickbook.syntax.block.lists.mixed_lists"></a><a name="quickbook.ref.mixed_lists"></a><a class="link" href="block.html#quickbook.syntax.block.lists.mixed_lists" title="Mixed lists">Mixed
|
||
lists</a>
|
||
</h4></div></div></div>
|
||
<p>
|
||
Mixed lists (ordered and unordered) are supported. Example:
|
||
</p>
|
||
<pre class="programlisting"># One
|
||
# Two
|
||
# Three
|
||
* Three.a
|
||
* Three.b
|
||
* Three.c
|
||
# Four
|
||
</pre>
|
||
<p>
|
||
will generate:
|
||
</p>
|
||
<div class="orderedlist"><ol class="orderedlist" type="1">
|
||
<li class="listitem">
|
||
One
|
||
</li>
|
||
<li class="listitem">
|
||
Two
|
||
</li>
|
||
<li class="listitem">
|
||
Three
|
||
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
|
||
<li class="listitem">
|
||
Three.a
|
||
</li>
|
||
<li class="listitem">
|
||
Three.b
|
||
</li>
|
||
<li class="listitem">
|
||
Three.c
|
||
</li>
|
||
</ul></div>
|
||
</li>
|
||
<li class="listitem">
|
||
Four
|
||
</li>
|
||
</ol></div>
|
||
<p>
|
||
And...
|
||
</p>
|
||
<pre class="programlisting"># 1
|
||
* 1.a
|
||
# 1.a.1
|
||
# 1.a.2
|
||
* 1.b
|
||
# 2
|
||
* 2.a
|
||
* 2.b
|
||
# 2.b.1
|
||
# 2.b.2
|
||
* 2.b.2.a
|
||
* 2.b.2.b
|
||
</pre>
|
||
<p>
|
||
will generate:
|
||
</p>
|
||
<div class="orderedlist"><ol class="orderedlist" type="1">
|
||
<li class="listitem">
|
||
1
|
||
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
|
||
<li class="listitem">
|
||
1.a
|
||
<div class="orderedlist"><ol class="orderedlist" type="a">
|
||
<li class="listitem">
|
||
1.a.1
|
||
</li>
|
||
<li class="listitem">
|
||
1.a.2
|
||
</li>
|
||
</ol></div>
|
||
</li>
|
||
<li class="listitem">
|
||
1.b
|
||
</li>
|
||
</ul></div>
|
||
</li>
|
||
<li class="listitem">
|
||
2
|
||
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
|
||
<li class="listitem">
|
||
2.a
|
||
</li>
|
||
<li class="listitem">
|
||
2.b
|
||
<div class="orderedlist"><ol class="orderedlist" type="a">
|
||
<li class="listitem">
|
||
2.b.1
|
||
</li>
|
||
<li class="listitem">
|
||
2.b.2
|
||
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; ">
|
||
<li class="listitem">
|
||
2.b.2.a
|
||
</li>
|
||
<li class="listitem">
|
||
2.b.2.b
|
||
</li>
|
||
</ul></div>
|
||
</li>
|
||
</ol></div>
|
||
</li>
|
||
</ul></div>
|
||
</li>
|
||
</ol></div>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="quickbook.syntax.block.lists.list_paragraphs"></a><a name="quickbook.ref.list_paragraphs"></a><a class="link" href="block.html#quickbook.syntax.block.lists.list_paragraphs" title="Paragraphs in lists">Paragraphs
|
||
in lists</a>
|
||
</h4></div></div></div>
|
||
<p>
|
||
In quickbook 1.7 onwards, you can nest paragraphs in lists by separating
|
||
them with blank lines:
|
||
</p>
|
||
<pre class="programlisting">* List item 1, paragraph 1
|
||
|
||
List item 1, paragraph 2
|
||
|
||
* List item 2, paragraph 1
|
||
|
||
List item 2, paragraph 2
|
||
</pre>
|
||
<p>
|
||
will generate:
|
||
</p>
|
||
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
|
||
<li class="listitem">
|
||
<p class="simpara">
|
||
List item 1, paragraph 1
|
||
</p>
|
||
<p class="simpara">
|
||
List item 1, paragraph 2
|
||
</p>
|
||
</li>
|
||
<li class="listitem">
|
||
<p class="simpara">
|
||
List item 2, paragraph 1
|
||
</p>
|
||
<p class="simpara">
|
||
List item 2, paragraph 2
|
||
</p>
|
||
</li>
|
||
</ul></div>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="quickbook.syntax.block.lists.list_tags"></a><a name="quickbook.ref.list_tags"></a><a class="link" href="block.html#quickbook.syntax.block.lists.list_tags" title="Explicit list tags">Explicit
|
||
list tags</a>
|
||
</h4></div></div></div>
|
||
<p>
|
||
Sometimes the wiki-style list markup can be tricky to use, especially if
|
||
you wish to include more complicated markup with the list. So in quickbook
|
||
1.6, an alternative way to mark up lists introduced:
|
||
</p>
|
||
<pre class="programlisting">[ordered_list [item1][item2]]
|
||
</pre>
|
||
<p>
|
||
is equivalent to:
|
||
</p>
|
||
<pre class="programlisting"># item1
|
||
# item2
|
||
</pre>
|
||
<p>
|
||
And:
|
||
</p>
|
||
<pre class="programlisting">[itemized_list [item1][item2]]
|
||
</pre>
|
||
<p>
|
||
is equivalent to:
|
||
</p>
|
||
<pre class="programlisting">* item1
|
||
* item2
|
||
</pre>
|
||
</div>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="quickbook.syntax.block.code"></a><a name="quickbook.ref.code"></a><a class="link" href="block.html#quickbook.syntax.block.code" title="Code">Code</a>
|
||
</h3></div></div></div>
|
||
<p>
|
||
Preformatted code starts with a space or a tab. The code will be syntax highlighted
|
||
according to the current <a class="link" href="phrase.html#quickbook.ref.source_mode">Source
|
||
Mode</a>:
|
||
</p>
|
||
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span>
|
||
|
||
<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
|
||
<span class="special">{</span>
|
||
<span class="comment">// Sample code</span>
|
||
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Hello, World\n"</span><span class="special">;</span>
|
||
<span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
|
||
<span class="special">}</span>
|
||
</pre>
|
||
<pre class="programlisting"><span class="keyword">import</span> <span class="identifier">cgi</span>
|
||
|
||
<span class="keyword">def</span> <span class="identifier">cookForHtml</span><span class="special">(</span><span class="identifier">text</span><span class="special">):</span>
|
||
<span class="string">'''"Cooks" the input text for HTML.'''</span>
|
||
|
||
<span class="keyword">return</span> <span class="identifier">cgi</span><span class="special">.</span><span class="identifier">escape</span><span class="special">(</span><span class="identifier">text</span><span class="special">)</span>
|
||
</pre>
|
||
<p>
|
||
Macros that are already defined are expanded in source code. Example:
|
||
</p>
|
||
<pre class="programlisting">[def __array__ [@http://www.boost.org/doc/html/array/reference.html array]]
|
||
[def __boost__ [@http://www.boost.org/libs/libraries.htm boost]]
|
||
|
||
using __boost__::__array__;
|
||
</pre>
|
||
<p>
|
||
Generates:
|
||
</p>
|
||
<pre class="programlisting">using <a href="http://www.boost.org/libs/libraries.htm" target="_top">boost</a>::<a href="http://www.boost.org/doc/html/array/reference.html" target="_top">array</a>;
|
||
</pre>
|
||
<p>
|
||
In quickbook 1.7 and later, you can include <a class="link" href="block.html#quickbook.ref.callouts">callouts</a>
|
||
in code blocks, like so:
|
||
</p>
|
||
<pre class="programlisting">[!c++]
|
||
std::string foo_bar() /*< The /Mythical/ FooBar.
|
||
See [@http://en.wikipedia.org/wiki/Foobar Foobar for details] >*/
|
||
{
|
||
return "foo-bar"; /*< return 'em, foo-bar man! >*/
|
||
}
|
||
</pre>
|
||
<p>
|
||
Which will generate:
|
||
</p>
|
||
<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">foo_bar</span><span class="special">()</span> <a class="co" name="quickbook.syntax.block.code.c0" href="block.html#quickbook.syntax.block.code.c1"><img src="../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a>
|
||
<span class="special">{</span>
|
||
<span class="keyword">return</span> <span class="string">"foo-bar"</span><span class="special">;</span> <a class="co" name="quickbook.syntax.block.code.c2" href="block.html#quickbook.syntax.block.code.c3"><img src="../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a>
|
||
<span class="special">}</span>
|
||
</pre>
|
||
<div class="calloutlist"><table border="0" summary="Callout list">
|
||
<tr>
|
||
<td width="5%" valign="top" align="left"><p><a name="quickbook.syntax.block.code.c1"></a><a href="#quickbook.syntax.block.code.c0"><img src="../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a> </p></td>
|
||
<td valign="top" align="left"><p>
|
||
The <span class="emphasis"><em>Mythical</em></span> FooBar. See <a href="http://en.wikipedia.org/wiki/Foobar" target="_top">Foobar
|
||
for details</a>
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td width="5%" valign="top" align="left"><p><a name="quickbook.syntax.block.code.c3"></a><a href="#quickbook.syntax.block.code.c2"><img src="../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a> </p></td>
|
||
<td valign="top" align="left"><p>
|
||
return 'em, foo-bar man!
|
||
</p></td>
|
||
</tr>
|
||
</table></div>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="quickbook.syntax.block.escape_back"></a><a name="quickbook.ref.escape_back"></a><a class="link" href="block.html#quickbook.syntax.block.escape_back" title="Escaping Back To QuickBook">Escaping
|
||
Back To QuickBook</a>
|
||
</h3></div></div></div>
|
||
<p>
|
||
Inside code, code blocks and inline code, QuickBook does not allow any markup
|
||
to avoid conflicts with the target syntax (e.g. c++). In case you need to
|
||
switch back to QuickBook markup inside code, you can do so using a language
|
||
specific <span class="emphasis"><em>escape-back</em></span> delimiter. In C++ and Python, the
|
||
delimiter is the double tick (back-quote): "``" and "``".
|
||
Example:
|
||
</p>
|
||
<pre class="programlisting">void <a href="http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz" target="_top">foo</a>()
|
||
{
|
||
}
|
||
</pre>
|
||
<p>
|
||
Will generate:
|
||
</p>
|
||
<pre class="programlisting">void <a href="http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz" target="_top">foo</a>()
|
||
{
|
||
}
|
||
</pre>
|
||
<p>
|
||
When escaping from code to QuickBook, only phrase level markups are allowed.
|
||
Block level markups like lists, tables etc. are not allowed.
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="quickbook.syntax.block.preformatted"></a><a name="quickbook.ref.preformatted"></a><a class="link" href="block.html#quickbook.syntax.block.preformatted" title="Preformatted">Preformatted</a>
|
||
</h3></div></div></div>
|
||
<p>
|
||
Sometimes, you don't want some preformatted text to be parsed as source code.
|
||
In such cases, use the <code class="literal">[pre ... ]</code> markup block.
|
||
</p>
|
||
<pre class="programlisting">[pre
|
||
|
||
Some *preformatted* text Some *preformatted* text
|
||
|
||
Some *preformatted* text Some *preformatted* text
|
||
|
||
Some *preformatted* text Some *preformatted* text
|
||
|
||
]
|
||
</pre>
|
||
<p>
|
||
Spaces, tabs and newlines are rendered as-is. Unlike all quickbook block
|
||
level markup, pre (and Code) are the only ones that allow multiple newlines.
|
||
The markup above will generate:
|
||
</p>
|
||
<pre class="programlisting">
|
||
Some <span class="bold"><strong>preformatted</strong></span> text Some <span class="bold"><strong>preformatted</strong></span> text
|
||
|
||
Some <span class="bold"><strong>preformatted</strong></span> text Some <span class="bold"><strong>preformatted</strong></span> text
|
||
|
||
Some <span class="bold"><strong>preformatted</strong></span> text Some <span class="bold"><strong>preformatted</strong></span> text
|
||
|
||
</pre>
|
||
<p>
|
||
Notice that unlike Code, phrase markup such as font style is still permitted
|
||
inside <code class="literal">pre</code> blocks.
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="quickbook.syntax.block.blockquote"></a><a name="quickbook.ref.blockquote"></a><a class="link" href="block.html#quickbook.syntax.block.blockquote" title="Blockquote">Blockquote</a>
|
||
</h3></div></div></div>
|
||
<pre class="programlisting">[:sometext...]
|
||
</pre>
|
||
<div class="blockquote"><blockquote class="blockquote"><p>
|
||
Indents the paragraph. This applies to one paragraph only.
|
||
</p></blockquote></div>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="quickbook.syntax.block.admonitions"></a><a name="quickbook.ref.admonitions"></a><a class="link" href="block.html#quickbook.syntax.block.admonitions" title="Admonitions">Admonitions</a>
|
||
</h3></div></div></div>
|
||
<pre class="programlisting">[note This is a note]
|
||
[tip This is a tip]
|
||
[important This is important]
|
||
[caution This is a caution]
|
||
[warning This is a warning]
|
||
</pre>
|
||
<p>
|
||
generates <a href="http://www.docbook.org/" target="_top">DocBook</a> admonitions:
|
||
</p>
|
||
<div class="note"><table border="0" summary="Note">
|
||
<tr>
|
||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../doc/src/images/note.png"></td>
|
||
<th align="left">Note</th>
|
||
</tr>
|
||
<tr><td align="left" valign="top"><p>
|
||
This is a note
|
||
</p></td></tr>
|
||
</table></div>
|
||
<div class="tip"><table border="0" summary="Tip">
|
||
<tr>
|
||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../doc/src/images/tip.png"></td>
|
||
<th align="left">Tip</th>
|
||
</tr>
|
||
<tr><td align="left" valign="top"><p>
|
||
This is a tip
|
||
</p></td></tr>
|
||
</table></div>
|
||
<div class="important"><table border="0" summary="Important">
|
||
<tr>
|
||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../doc/src/images/important.png"></td>
|
||
<th align="left">Important</th>
|
||
</tr>
|
||
<tr><td align="left" valign="top"><p>
|
||
This is important
|
||
</p></td></tr>
|
||
</table></div>
|
||
<div class="caution"><table border="0" summary="Caution">
|
||
<tr>
|
||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../doc/src/images/caution.png"></td>
|
||
<th align="left">Caution</th>
|
||
</tr>
|
||
<tr><td align="left" valign="top"><p>
|
||
This is a caution
|
||
</p></td></tr>
|
||
</table></div>
|
||
<div class="warning"><table border="0" summary="Warning">
|
||
<tr>
|
||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../doc/src/images/warning.png"></td>
|
||
<th align="left">Warning</th>
|
||
</tr>
|
||
<tr><td align="left" valign="top"><p>
|
||
This is a warning
|
||
</p></td></tr>
|
||
</table></div>
|
||
<p>
|
||
These are the only admonitions supported by <a href="http://www.docbook.org/" target="_top">DocBook</a>.
|
||
So, for example <code class="literal">[information This is some information]</code>
|
||
is unlikely to produce the desired effect.
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="quickbook.syntax.block.headings"></a><a name="quickbook.ref.headings"></a><a class="link" href="block.html#quickbook.syntax.block.headings" title="Headings">Headings</a>
|
||
</h3></div></div></div>
|
||
<pre class="programlisting">[h1 Heading 1]
|
||
[h2 Heading 2]
|
||
[h3 Heading 3]
|
||
[h4 Heading 4]
|
||
[h5 Heading 5]
|
||
[h6 Heading 6]
|
||
</pre>
|
||
<h2>
|
||
<a name="quickbook.syntax.block.headings.h0"></a>
|
||
<span class="phrase"><a name="quickbook.syntax.block.headings.heading_1"></a></span><a class="link" href="block.html#quickbook.syntax.block.headings.heading_1">Heading
|
||
1</a>
|
||
</h2>
|
||
<h3>
|
||
<a name="quickbook.syntax.block.headings.h1"></a>
|
||
<span class="phrase"><a name="quickbook.syntax.block.headings.heading_2"></a></span><a class="link" href="block.html#quickbook.syntax.block.headings.heading_2">Heading
|
||
2</a>
|
||
</h3>
|
||
<h4>
|
||
<a name="quickbook.syntax.block.headings.h2"></a>
|
||
<span class="phrase"><a name="quickbook.syntax.block.headings.heading_3"></a></span><a class="link" href="block.html#quickbook.syntax.block.headings.heading_3">Heading
|
||
3</a>
|
||
</h4>
|
||
<h5>
|
||
<a name="quickbook.syntax.block.headings.h3"></a>
|
||
<span class="phrase"><a name="quickbook.syntax.block.headings.heading_4"></a></span><a class="link" href="block.html#quickbook.syntax.block.headings.heading_4">Heading
|
||
4</a>
|
||
</h5>
|
||
<h6>
|
||
<a name="quickbook.syntax.block.headings.h4"></a>
|
||
<span class="phrase"><a name="quickbook.syntax.block.headings.heading_5"></a></span><a class="link" href="block.html#quickbook.syntax.block.headings.heading_5">Heading
|
||
5</a>
|
||
</h6>
|
||
<h4>
|
||
<a name="quickbook.syntax.block.headings.h5"></a>
|
||
<span class="phrase"><a name="quickbook.syntax.block.headings.heading_6"></a></span><a class="link" href="block.html#quickbook.syntax.block.headings.heading_6">Heading
|
||
6</a>
|
||
</h4>
|
||
<p>
|
||
You can specify an id for a heading:
|
||
</p>
|
||
<pre class="programlisting">[h1:heading_id A heading to link to]
|
||
</pre>
|
||
<p>
|
||
To link to it, you'll need to include the enclosing section's id:
|
||
</p>
|
||
<pre class="programlisting">[link document_id.section_id.heading_id The link text]
|
||
</pre>
|
||
<p>
|
||
Although you can preceed a heading by an <a class="link" href="phrase.html#quickbook.ref.anchors">anchor</a>
|
||
if you wish to use a location independent link.
|
||
</p>
|
||
<p>
|
||
If a heading doesn't have an id, one will be automatically generated with
|
||
a normalized name with <code class="literal">name="document_id.section_id.normalized_header_text"</code>
|
||
(i.e. valid characters are <code class="literal">a-z</code>, <code class="literal">A-Z</code>,
|
||
<code class="literal">0-9</code> and <code class="literal">_</code>. All non-valid characters
|
||
are converted to underscore and all upper-case are converted to lower-case.
|
||
For example: Heading 1 in section Section 2 will be normalized to <code class="literal">section_2.heading_1</code>).
|
||
You can use:
|
||
</p>
|
||
<pre class="programlisting">[link document_id.section_id.normalized_header_text The link text]
|
||
</pre>
|
||
<p>
|
||
to link to them. See <a class="link" href="phrase.html#quickbook.ref.anchor_links">Anchor links</a>
|
||
and <a class="link" href="structure.html#quickbook.ref.section">Section</a> for more info.
|
||
</p>
|
||
<div class="note"><table border="0" summary="Note">
|
||
<tr>
|
||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../doc/src/images/note.png"></td>
|
||
<th align="left">Note</th>
|
||
</tr>
|
||
<tr><td align="left" valign="top"><p>
|
||
Specifying heading ids is a quickbook 1.6 feature, earlier versions don't
|
||
support them.
|
||
</p></td></tr>
|
||
</table></div>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="quickbook.syntax.block.generic_heading"></a><a name="quickbook.ref.generic_heading"></a><a class="link" href="block.html#quickbook.syntax.block.generic_heading" title="Generic Heading">Generic
|
||
Heading</a>
|
||
</h3></div></div></div>
|
||
<p>
|
||
In cases when you don't want to care about the heading level (1 to 6), you
|
||
can use the <span class="emphasis"><em>Generic Heading</em></span>:
|
||
</p>
|
||
<pre class="programlisting">[heading Heading]
|
||
</pre>
|
||
<p>
|
||
The <span class="emphasis"><em>Generic Heading</em></span> assumes the level, plus one, of
|
||
the innermost section where it is placed. For example, if it is placed in
|
||
the outermost section, then, it assumes <span class="emphasis"><em>h2</em></span>.
|
||
</p>
|
||
<p>
|
||
Headings are often used as an alternative to sections. It is used particularly
|
||
if you do not want to start a new section. In many cases, however, headings
|
||
in a particular section is just flat. Example:
|
||
</p>
|
||
<pre class="programlisting">[section A]
|
||
[h2 X]
|
||
[h2:link_id Y]
|
||
[h2 Z]
|
||
[endsect]
|
||
</pre>
|
||
<p>
|
||
Here we use h2 assuming that section A is the outermost level. If it is placed
|
||
in an inner level, you'll have to use h3, h4, etc. depending on where the
|
||
section is. In general, it is the section level plus one. It is rather tedious,
|
||
however, to scan the section level everytime. If you rewrite the example
|
||
above as shown below, this will be automatic:
|
||
</p>
|
||
<pre class="programlisting">[section A]
|
||
[heading X]
|
||
[heading Y]
|
||
[heading Z]
|
||
[endsect]
|
||
</pre>
|
||
<p>
|
||
They work well regardless where you place them. You can rearrange sections
|
||
at will without any extra work to ensure correct heading levels. In fact,
|
||
with <span class="emphasis"><em>section</em></span> and <span class="emphasis"><em>heading</em></span>, you have
|
||
all you need. <span class="emphasis"><em>h1</em></span>..<span class="emphasis"><em>h6</em></span> becomes redundant.
|
||
<span class="emphasis"><em>h1</em></span>..<span class="emphasis"><em>h6</em></span> might be deprecated in the
|
||
future.
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="quickbook.syntax.block.macros"></a><a name="quickbook.ref.macros"></a><a class="link" href="block.html#quickbook.syntax.block.macros" title="Macros">Macros</a>
|
||
</h3></div></div></div>
|
||
<pre class="programlisting">[def macro_identifier some text]
|
||
</pre>
|
||
<p>
|
||
When a macro is defined, the identifier replaces the text anywhere in the
|
||
file, in paragraphs, in markups, etc. macro_identifier is a string of non-
|
||
white space characters except ']'. A macro may not follow an alphabetic character
|
||
or the underscore. The replacement text can be any phrase (even marked up).
|
||
Example:
|
||
</p>
|
||
<pre class="programlisting">[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&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&type=1"></span>
|
||
</p>
|
||
<div class="tip"><table border="0" summary="Tip">
|
||
<tr>
|
||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../doc/src/images/tip.png"></td>
|
||
<th align="left">Tip</th>
|
||
</tr>
|
||
<tr><td align="left" valign="top"><p>
|
||
It's a good idea to use macro identifiers that are distinguishable. For
|
||
instance, in this document, macro identifiers have two leading and trailing
|
||
underscores (e.g. <code class="literal">__spirit__</code>). The reason is to avoid
|
||
unwanted macro replacement.
|
||
</p></td></tr>
|
||
</table></div>
|
||
<p>
|
||
Links (URLS) and images are good candidates for macros. <span class="bold"><strong>1</strong></span>)
|
||
They tend to change a lot. It is a good idea to place all links and images
|
||
in one place near the top to make it easy to make changes. <span class="bold"><strong>2</strong></span>)
|
||
The syntax is not pretty. It's easier to read and write, e.g. <code class="literal">__spirit__</code>
|
||
than <code class="computeroutput">[@http://spirit.sourceforge.net Spirit]</code>.
|
||
</p>
|
||
<p>
|
||
Some more examples:
|
||
</p>
|
||
<pre class="programlisting">[def :-) [$theme/smiley.png]]
|
||
[def __spirit__ [@http://spirit.sourceforge.net Spirit]]
|
||
</pre>
|
||
<p>
|
||
(See <a class="link" href="phrase.html#quickbook.ref.images">Images</a> and <a class="link" href="phrase.html#quickbook.ref.links">Links</a>)
|
||
</p>
|
||
<p>
|
||
Invoking these macros:
|
||
</p>
|
||
<pre class="programlisting">Hi __spirit__ :-)
|
||
</pre>
|
||
<p>
|
||
will generate this:
|
||
</p>
|
||
<p>
|
||
Hi <a href="http://spirit.sourceforge.net" target="_top">Spirit</a> <span class="inlinemediaobject"><img src="../../../src/images/smiley.png"></span>
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="quickbook.syntax.block.predefined_macros"></a><a name="quickbook.ref.predefined_macros"></a><a class="link" href="block.html#quickbook.syntax.block.predefined_macros" title="Predefined Macros">Predefined
|
||
Macros</a>
|
||
</h3></div></div></div>
|
||
<p>
|
||
Quickbook has some predefined macros that you can already use.
|
||
</p>
|
||
<div class="table">
|
||
<a name="quickbook.syntax.block.predefined_macros.predefined_macros"></a><p class="title"><b>Table 51.3. Predefined Macros</b></p>
|
||
<div class="table-contents"><table class="table" summary="Predefined Macros">
|
||
<colgroup>
|
||
<col>
|
||
<col>
|
||
<col>
|
||
</colgroup>
|
||
<thead><tr>
|
||
<th>
|
||
<p>
|
||
Macro
|
||
</p>
|
||
</th>
|
||
<th>
|
||
<p>
|
||
Meaning
|
||
</p>
|
||
</th>
|
||
<th>
|
||
<p>
|
||
Example
|
||
</p>
|
||
</th>
|
||
</tr></thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>
|
||
<p>
|
||
<code class="literal">__DATE__</code>
|
||
</p>
|
||
</td>
|
||
<td>
|
||
<p>
|
||
Today's date
|
||
</p>
|
||
</td>
|
||
<td>
|
||
<p>
|
||
2021-Apr-13
|
||
</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<p>
|
||
<code class="literal">__TIME__</code>
|
||
</p>
|
||
</td>
|
||
<td>
|
||
<p>
|
||
The current time
|
||
</p>
|
||
</td>
|
||
<td>
|
||
<p>
|
||
04:33:32 PM
|
||
</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<p>
|
||
<code class="literal">__FILENAME__</code>
|
||
</p>
|
||
</td>
|
||
<td>
|
||
<p>
|
||
Quickbook source filename
|
||
</p>
|
||
</td>
|
||
<td>
|
||
<p>
|
||
block.qbk
|
||
</p>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table></div>
|
||
</div>
|
||
<br class="table-break">
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="quickbook.syntax.block.templates"></a><a name="quickbook.ref.templates"></a><a class="link" href="block.html#quickbook.syntax.block.templates" title="Templates">Templates</a>
|
||
</h3></div></div></div>
|
||
<p>
|
||
Templates provide a more versatile text substitution mechanism. Templates
|
||
come in handy when you need to create parameterizable, multi-line, boilerplate
|
||
text that you specify once and expand many times. Templates accept one or
|
||
more arguments. These arguments act like place-holders for text replacement.
|
||
Unlike simple macros, which are limited to phrase level markup, templates
|
||
can contain block level markup (e.g. paragraphs, code blocks and tables).
|
||
</p>
|
||
<p>
|
||
Example template:
|
||
</p>
|
||
<pre class="programlisting">[template person[name age what]
|
||
|
||
Hi, my name is [name]. I am [age] years old. I am a [what].
|
||
|
||
]
|
||
</pre>
|
||
<a name="quickbook.ref.template_identifier"></a><h4>
|
||
<a name="quickbook.syntax.block.templates.h0"></a>
|
||
<span class="phrase"><a name="quickbook.syntax.block.templates.template_identifier"></a></span><a class="link" href="block.html#quickbook.syntax.block.templates.template_identifier">Template Identifier</a>
|
||
</h4>
|
||
<p>
|
||
Template identifiers can either consist of:
|
||
</p>
|
||
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
|
||
<li class="listitem">
|
||
An initial alphabetic character or the underscore, followed by zero or
|
||
more alphanumeric characters or the underscore. This is similar to your
|
||
typical C/C++ identifier.
|
||
</li>
|
||
<li class="listitem">
|
||
A single character punctuation (a non-alphanumeric printable character)
|
||
</li>
|
||
</ul></div>
|
||
<h4>
|
||
<a name="quickbook.syntax.block.templates.h1"></a>
|
||
<span class="phrase"><a name="quickbook.syntax.block.templates.formal_template_arguments"></a></span><a class="link" href="block.html#quickbook.syntax.block.templates.formal_template_arguments">Formal
|
||
Template Arguments</a>
|
||
</h4>
|
||
<p>
|
||
Template formal arguments are identifiers consisting of an initial alphabetic
|
||
character or the underscore, followed by zero or more alphanumeric characters
|
||
or the underscore. This is similar to your typical C/C++ identifier.
|
||
</p>
|
||
<p>
|
||
A template formal argument temporarily hides a template of the same name
|
||
at the point where the <a class="link" href="phrase.html#quickbook.ref.template_expansion">template
|
||
is expanded</a>. Note that the body of the <code class="literal">person</code> template
|
||
above refers to <code class="literal">name</code> <code class="literal">age</code> and <code class="literal">what</code>
|
||
as <code class="literal">[name]</code> <code class="literal">[age]</code> and <code class="literal">[what]</code>.
|
||
<code class="literal">name</code> <code class="literal">age</code> and <code class="literal">what</code>
|
||
are actually templates that exist in the duration of the template call.
|
||
</p>
|
||
<h4>
|
||
<a name="quickbook.syntax.block.templates.h2"></a>
|
||
<span class="phrase"><a name="quickbook.syntax.block.templates.template_body"></a></span><a class="link" href="block.html#quickbook.syntax.block.templates.template_body">Template
|
||
Body</a>
|
||
</h4>
|
||
<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>
|
||
<h4>
|
||
<a name="quickbook.syntax.block.templates.h3"></a>
|
||
<span class="phrase"><a name="quickbook.syntax.block.templates.template_expansion"></a></span><a class="link" href="block.html#quickbook.syntax.block.templates.template_expansion">Template
|
||
Expansion</a>
|
||
</h4>
|
||
<p>
|
||
You expand a template this way:
|
||
</p>
|
||
<pre class="programlisting">[template_identifier arg1..arg2..arg3]
|
||
</pre>
|
||
<p>
|
||
At template expansion, you supply the actual arguments. The template will
|
||
be expanded with your supplied arguments. Example:
|
||
</p>
|
||
<pre class="programlisting">[person James Bond..39..Spy]
|
||
[person Santa Clause..87..Big Red Fatso]
|
||
</pre>
|
||
<p>
|
||
Which will expand to:
|
||
</p>
|
||
<p>
|
||
Hi, my name is James Bond. I am 39 years old. I am a Spy.
|
||
</p>
|
||
<p>
|
||
Hi, my name is Santa Clause. I am 87 years old. I am a Big Red Fatso.
|
||
</p>
|
||
<div class="caution"><table border="0" summary="Caution">
|
||
<tr>
|
||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../doc/src/images/caution.png"></td>
|
||
<th align="left">Caution</th>
|
||
</tr>
|
||
<tr><td align="left" valign="top"><p>
|
||
A word of caution: Templates are recursive. A template can call another
|
||
template or even itself, directly or indirectly. There are no control structures
|
||
in QuickBook (yet) so this will always mean infinite recursion. QuickBook
|
||
can detect this situation and report an error if recursion exceeds a certain
|
||
limit.
|
||
</p></td></tr>
|
||
</table></div>
|
||
<p>
|
||
Each actual argument can be a word, a text fragment or just about any <a class="link" href="phrase.html" title="Phrase Level Elements">QuickBook phrase</a>. Arguments are
|
||
separated by the double dot <code class="literal">".."</code> and terminated
|
||
by the close parenthesis.
|
||
</p>
|
||
<p>
|
||
Note that templates and template parameters can't be expanded everywhere,
|
||
only where text is interpreted as a phrase. So they can't be expanded in
|
||
places such as table titles and link's urls. If you want to use a template
|
||
to generate a link based of the template parameter, you can't use a normal
|
||
link and will need to use escaped docbook instead. Example:
|
||
</p>
|
||
<pre class="programlisting">[template boost_ticket[key] '''<ulink url="https://svn.boost.org/trac/boost/ticket/'''[key]'''">#'''[key]'''</ulink>''']
|
||
|
||
[boost_ticket 2035]
|
||
</pre>
|
||
<p>
|
||
will expand to:
|
||
</p>
|
||
<p>
|
||
<a href="https://svn.boost.org/trac/boost/ticket/2035" target="_top">#2035</a>
|
||
</p>
|
||
<div class="caution"><table border="0" summary="Caution">
|
||
<tr>
|
||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../doc/src/images/caution.png"></td>
|
||
<th align="left">Caution</th>
|
||
</tr>
|
||
<tr><td align="left" valign="top"><p>
|
||
Since quickbook doesn't understand the context where the parameter is being
|
||
used, it will interpret it as quickbook markup, so when writing a template
|
||
like this, you'll need to escape any meaningful punctuation.
|
||
</p></td></tr>
|
||
</table></div>
|
||
<h4>
|
||
<a name="quickbook.syntax.block.templates.h4"></a>
|
||
<span class="phrase"><a name="quickbook.syntax.block.templates.nullary_templates"></a></span><a class="link" href="block.html#quickbook.syntax.block.templates.nullary_templates">Nullary
|
||
Templates</a>
|
||
</h4>
|
||
<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>αβ</strong></span>
|
||
</p>
|
||
<p>
|
||
The difference with macros are
|
||
</p>
|
||
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
|
||
<li class="listitem">
|
||
The explicit <a class="link" href="phrase.html#quickbook.ref.template_expansion">template
|
||
expansion syntax</a>. This is an advantage because, now, we don't
|
||
have to use obscure naming conventions like double underscores (e.g.
|
||
__alpha__) to avoid unwanted macro replacement.
|
||
</li>
|
||
<li class="listitem">
|
||
The template is expanded at the point where it is invoked. A macro is
|
||
expanded immediately at its point of declaration. This is subtle and
|
||
can cause a slight difference in behavior especially if you refer to
|
||
other macros and templates in the body.
|
||
</li>
|
||
</ul></div>
|
||
<p>
|
||
The empty brackets after the template identifier (<code class="literal">alpha[]</code>)
|
||
indicates no arguments. If the template body does not look like a template
|
||
argument list, we can elide the empty brackets. Example:
|
||
</p>
|
||
<pre class="programlisting">[template aristotle_quote Aristotle: [*['Education is the best provision
|
||
for the journey to old age.]]]
|
||
</pre>
|
||
<p>
|
||
Expanding:
|
||
</p>
|
||
<pre class="programlisting">Here's a quote from [aristotle_quote].
|
||
</pre>
|
||
<p>
|
||
We have:
|
||
</p>
|
||
<p>
|
||
Here's a quote from Aristotle: <span class="bold"><strong><span class="emphasis"><em>Education
|
||
is the best provision for the journey to old age.</em></span></strong></span>.
|
||
</p>
|
||
<p>
|
||
The disadvantage is that you can't avoid the space between the template identifier,
|
||
<code class="computeroutput">aristotle_quote</code>, and the template body "Aristotle...".
|
||
This space will be part of the template body. If that space is unwanted,
|
||
use empty brackets or use the space escape: "<code class="computeroutput">\ </code>".
|
||
Example:
|
||
</p>
|
||
<pre class="programlisting">[template tag\ _tag]
|
||
</pre>
|
||
<p>
|
||
Then expanding:
|
||
</p>
|
||
<pre class="programlisting">`struct` x[tag];
|
||
</pre>
|
||
<p>
|
||
We have:
|
||
</p>
|
||
<p>
|
||
<code class="computeroutput">struct</code> x_tag;
|
||
</p>
|
||
<p>
|
||
You have a couple of ways to do it. I personally prefer the explicit empty
|
||
brackets, though.
|
||
</p>
|
||
<h4>
|
||
<a name="quickbook.syntax.block.templates.h5"></a>
|
||
<span class="phrase"><a name="quickbook.syntax.block.templates.simple_arguments"></a></span><a class="link" href="block.html#quickbook.syntax.block.templates.simple_arguments">Simple
|
||
Arguments</a>
|
||
</h4>
|
||
<p>
|
||
As mentioned, arguments are separated by the double dot <code class="literal">".."</code>.
|
||
Alternatively, if the double dot isn't used and more than one argument is
|
||
expected, QuickBook uses whitespace to separate the arguments, following
|
||
this logic:
|
||
</p>
|
||
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
|
||
<li class="listitem">
|
||
Break the last argument into two, at the first space found (<code class="literal">'',
|
||
'\n', \t' or '\r'</code>).
|
||
</li>
|
||
<li class="listitem">
|
||
Repeat until there are enough arguments or if there are no more spaces
|
||
found (in which case, an error is reported).
|
||
</li>
|
||
</ul></div>
|
||
<p>
|
||
For example:
|
||
</p>
|
||
<pre class="programlisting">[template simple[a b c d] [a][b][c][d]]
|
||
[simple w x y z]
|
||
</pre>
|
||
<p>
|
||
will produce:
|
||
</p>
|
||
<p>
|
||
wxyz
|
||
</p>
|
||
<p>
|
||
"w x y z" is initially treated as a single argument because we
|
||
didn't supply any <code class="literal">".."</code> separators. However,
|
||
since <code class="literal">simple</code> expects 4 arguments, "w x y z"
|
||
is broken down iteratively (applying the logic above) until we have "w",
|
||
"x", "y" and "z".
|
||
</p>
|
||
<p>
|
||
QuickBook only tries to get the arguments it needs. For example:
|
||
</p>
|
||
<pre class="programlisting">[simple w x y z trail]
|
||
</pre>
|
||
<p>
|
||
will produce:
|
||
</p>
|
||
<p>
|
||
wxyz trail
|
||
</p>
|
||
<p>
|
||
The arguments being: "w", "x", "y" and "z
|
||
trail".
|
||
</p>
|
||
<div class="caution"><table border="0" summary="Caution">
|
||
<tr>
|
||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../doc/src/images/caution.png"></td>
|
||
<th align="left">Caution</th>
|
||
</tr>
|
||
<tr><td align="left" valign="top"><p>
|
||
The behavior described here is for QuickBook 1.5. In older versions you
|
||
could use both the double dot and whitespace as separators in the same
|
||
template call. If your document is marked up as an older version, it will
|
||
use the old behavior, which is described in the <a href="http://www.boost.org/doc/libs/1_40_0/doc/html/quickbook/syntax.html#quickbook.syntax.block.templates.simple_arguments" target="_top">QuickBook
|
||
1.4 documentation</a>.
|
||
</p></td></tr>
|
||
</table></div>
|
||
<h4>
|
||
<a name="quickbook.syntax.block.templates.h6"></a>
|
||
<span class="phrase"><a name="quickbook.syntax.block.templates.punctuation_templates"></a></span><a class="link" href="block.html#quickbook.syntax.block.templates.punctuation_templates">Punctuation
|
||
Templates</a>
|
||
</h4>
|
||
<p>
|
||
With templates, one of our objectives is to allow us to rewrite QuickBook
|
||
in QuickBook (as a qbk library). For that to happen, we need to accommodate
|
||
single character punctuation templates which are fairly common in QuickBook.
|
||
You might have noticed that single character punctuations are allowed as
|
||
<a class="link" href="block.html#quickbook.ref.template_identifier">template identifiers</a>.
|
||
Example:
|
||
</p>
|
||
<pre class="programlisting">[template ![bar] <hey>[bar]</hey>]
|
||
</pre>
|
||
<p>
|
||
Now, expanding this:
|
||
</p>
|
||
<pre class="programlisting">[!baz]
|
||
</pre>
|
||
<p>
|
||
We will have:
|
||
</p>
|
||
<pre class="programlisting"><hey>baz</hey>
|
||
</pre>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="quickbook.syntax.block.blurbs"></a><a name="quickbook.ref.blurbs"></a><a class="link" href="block.html#quickbook.syntax.block.blurbs" title="Blurbs">Blurbs</a>
|
||
</h3></div></div></div>
|
||
<pre class="programlisting">[blurb :-) [*An eye catching advertisement or note...]
|
||
|
||
<a href="http://spirit.sourceforge.net" target="_top">Spirit</a> is an object-oriented recursive-descent parser generator framework
|
||
implemented using template meta-programming techniques. Expression templates
|
||
allow us to approximate the syntax of Extended Backus-Normal Form (EBNF)
|
||
completely in C++.
|
||
]
|
||
</pre>
|
||
<p>
|
||
will generate this:
|
||
</p>
|
||
<div class="blurb">
|
||
<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div>
|
||
<p>
|
||
<span class="inlinemediaobject"><img src="../../../src/images/smiley.png"></span>
|
||
<span class="bold"><strong>An eye catching advertisement or note...</strong></span>
|
||
</p>
|
||
<p>
|
||
<a href="http://spirit.sourceforge.net" target="_top">Spirit</a> is an object-oriented
|
||
recursive-descent parser generator framework implemented using template meta-programming
|
||
techniques. Expression templates allow us to approximate the syntax of Extended
|
||
Backus-Normal Form (EBNF) completely in C++.
|
||
</p>
|
||
</div>
|
||
<div class="note"><table border="0" summary="Note">
|
||
<tr>
|
||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../doc/src/images/note.png"></td>
|
||
<th align="left">Note</th>
|
||
</tr>
|
||
<tr><td align="left" valign="top"><p>
|
||
Prefer <a class="link" href="block.html#quickbook.ref.admonitions">admonitions</a> wherever
|
||
appropriate.
|
||
</p></td></tr>
|
||
</table></div>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="quickbook.syntax.block.tables"></a><a name="quickbook.ref.tables"></a><a class="link" href="block.html#quickbook.syntax.block.tables" title="Tables">Tables</a>
|
||
</h3></div></div></div>
|
||
<pre class="programlisting">[table:id A Simple Table
|
||
[[Heading 1] [Heading 2] [Heading 3]]
|
||
[[R0-C0] [R0-C1] [R0-C2]]
|
||
[[R1-C0] [R1-C1] [R1-C2]]
|
||
[[R2-C0] [R2-C1] [R2-C2]]
|
||
]
|
||
</pre>
|
||
<p>
|
||
will generate:
|
||
</p>
|
||
<div class="table">
|
||
<a name="quickbook.syntax.block.tables.id"></a><p class="title"><b>Table 51.4. A Simple Table</b></p>
|
||
<div class="table-contents"><table class="table" summary="A Simple Table">
|
||
<colgroup>
|
||
<col>
|
||
<col>
|
||
<col>
|
||
</colgroup>
|
||
<thead><tr>
|
||
<th>
|
||
<p>
|
||
Heading 1
|
||
</p>
|
||
</th>
|
||
<th>
|
||
<p>
|
||
Heading 2
|
||
</p>
|
||
</th>
|
||
<th>
|
||
<p>
|
||
Heading 3
|
||
</p>
|
||
</th>
|
||
</tr></thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>
|
||
<p>
|
||
R0-C0
|
||
</p>
|
||
</td>
|
||
<td>
|
||
<p>
|
||
R0-C1
|
||
</p>
|
||
</td>
|
||
<td>
|
||
<p>
|
||
R0-C2
|
||
</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<p>
|
||
R1-C0
|
||
</p>
|
||
</td>
|
||
<td>
|
||
<p>
|
||
R1-C1
|
||
</p>
|
||
</td>
|
||
<td>
|
||
<p>
|
||
R1-C2
|
||
</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<p>
|
||
R2-C0
|
||
</p>
|
||
</td>
|
||
<td>
|
||
<p>
|
||
R2-C1
|
||
</p>
|
||
</td>
|
||
<td>
|
||
<p>
|
||
R2-C2
|
||
</p>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table></div>
|
||
</div>
|
||
<br class="table-break"><p>
|
||
The table title is optional. The first row of the table is automatically
|
||
treated as the table header; that is, it is wrapped in <code class="literal"><thead>...</thead></code>
|
||
XML tags. Note that unlike the original QuickDoc, the columns are nested
|
||
in [cells... ].
|
||
</p>
|
||
<p>
|
||
Giving tables an id is a new feature for quickbook 1.5 onwards. As with sections,
|
||
the id is optional. If the table has a title but no id, an id will be generated
|
||
from the title. The table above can be linked to using:
|
||
</p>
|
||
<pre class="programlisting">[link quickbook.syntax.block.tables.id link to table]
|
||
</pre>
|
||
<p>
|
||
which will generate:
|
||
</p>
|
||
<p>
|
||
<a class="link" href="block.html#quickbook.syntax.block.tables.id" title="Table 51.4. A Simple Table">link to table</a>
|
||
</p>
|
||
<p>
|
||
The syntax is free-format and allows big cells to be formatted nicely. Example:
|
||
</p>
|
||
<pre class="programlisting">[table Table with fat cells
|
||
[[Heading 1] [Heading 2]]
|
||
[
|
||
[Row 0, Col 0: a small cell]
|
||
[
|
||
Row 0, Col 1: a big fat cell with paragraphs
|
||
|
||
Boost provides free peer-reviewed portable C++ source libraries.
|
||
|
||
We emphasize libraries that work well with the C++ Standard Library.
|
||
Boost libraries are intended to be widely useful, and usable across
|
||
a broad spectrum of applications. The Boost license encourages both
|
||
commercial and non-commercial use.
|
||
]
|
||
]
|
||
[
|
||
[Row 1, Col 0: a small cell]
|
||
[Row 1, Col 1: a small cell]
|
||
]
|
||
]
|
||
</pre>
|
||
<p>
|
||
and thus:
|
||
</p>
|
||
<div class="table">
|
||
<a name="quickbook.syntax.block.tables.table_with_fat_cells"></a><p class="title"><b>Table 51.5. Table with fat cells</b></p>
|
||
<div class="table-contents"><table class="table" summary="Table with fat cells">
|
||
<colgroup>
|
||
<col>
|
||
<col>
|
||
</colgroup>
|
||
<thead><tr>
|
||
<th>
|
||
<p>
|
||
Heading 1
|
||
</p>
|
||
</th>
|
||
<th>
|
||
<p>
|
||
Heading 2
|
||
</p>
|
||
</th>
|
||
</tr></thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>
|
||
<p>
|
||
Row 0, Col 0: a small cell
|
||
</p>
|
||
</td>
|
||
<td>
|
||
<p>
|
||
Row 0, Col 1: a big fat cell with paragraphs
|
||
</p>
|
||
<p>
|
||
Boost provides free peer-reviewed portable C++ source libraries.
|
||
We emphasize libraries that work well with the C++ Standard Library.
|
||
Boost libraries are intended to be widely useful, and usable across
|
||
a broad spectrum of applications. The Boost license encourages
|
||
both commercial and non-commercial use.
|
||
</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<p>
|
||
Row 1, Col 0: a small cell
|
||
</p>
|
||
</td>
|
||
<td>
|
||
<p>
|
||
Row 1, Col 1: a small cell
|
||
</p>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table></div>
|
||
</div>
|
||
<br class="table-break"><p>
|
||
Here's how to have preformatted blocks of code in a table cell:
|
||
</p>
|
||
<pre class="programlisting">[table Table with code
|
||
[[Comment] [Code]]
|
||
[
|
||
[My first program]
|
||
[``
|
||
#include <iostream>
|
||
|
||
int main()
|
||
{
|
||
std::cout << "Hello, World!" << std::endl;
|
||
return 0;
|
||
}
|
||
``]
|
||
]
|
||
]
|
||
</pre>
|
||
<div class="table">
|
||
<a name="quickbook.syntax.block.tables.table_with_code"></a><p class="title"><b>Table 51.6. Table with code</b></p>
|
||
<div class="table-contents"><table class="table" summary="Table with code">
|
||
<colgroup>
|
||
<col>
|
||
<col>
|
||
</colgroup>
|
||
<thead><tr>
|
||
<th>
|
||
<p>
|
||
Comment
|
||
</p>
|
||
</th>
|
||
<th>
|
||
<p>
|
||
Code
|
||
</p>
|
||
</th>
|
||
</tr></thead>
|
||
<tbody><tr>
|
||
<td>
|
||
<p>
|
||
My first program
|
||
</p>
|
||
</td>
|
||
<td>
|
||
<pre class="programlisting">#include <iostream>
|
||
|
||
int main()
|
||
{
|
||
std::cout << "Hello, World!" << std::endl;
|
||
return 0;
|
||
}
|
||
</pre>
|
||
</td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
</div>
|
||
<br class="table-break">
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="quickbook.syntax.block.variable_lists"></a><a name="quickbook.ref.variable_lists"></a><a class="link" href="block.html#quickbook.syntax.block.variable_lists" title="Variable Lists">Variable
|
||
Lists</a>
|
||
</h3></div></div></div>
|
||
<pre class="programlisting">[variablelist A Variable List
|
||
[[term 1] [The definition of term 1]]
|
||
[[term 2] [The definition of term 2]]
|
||
[[term 3] [
|
||
The definition of term 3.
|
||
|
||
Definitions may contain paragraphs.
|
||
]]
|
||
]
|
||
</pre>
|
||
<p>
|
||
will generate:
|
||
</p>
|
||
<div class="variablelist">
|
||
<p class="title"><b>A Variable List</b></p>
|
||
<dl class="variablelist">
|
||
<dt><span class="term">term 1</span></dt>
|
||
<dd><p>
|
||
The definition of term 1
|
||
</p></dd>
|
||
<dt><span class="term">term 2</span></dt>
|
||
<dd><p>
|
||
The definition of term 2
|
||
</p></dd>
|
||
<dt><span class="term">term 3</span></dt>
|
||
<dd>
|
||
<p>
|
||
The definition of term 3.
|
||
</p>
|
||
<p>
|
||
Definitions may contain paragraphs.
|
||
</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<p>
|
||
The rules for variable lists are the same as for tables, except that only
|
||
2 "columns" are allowed. The first column contains the terms, and
|
||
the second column contains the definitions. Those familiar with HTML will
|
||
recognize this as a "definition list".
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="quickbook.syntax.block.include"></a><a name="quickbook.ref.include"></a><a class="link" href="block.html#quickbook.syntax.block.include" title="Include">Include</a>
|
||
</h3></div></div></div>
|
||
<p>
|
||
You can include one QuickBook file from another. The syntax is simply:
|
||
</p>
|
||
<pre class="programlisting">[include someother.qbk]
|
||
</pre>
|
||
<p>
|
||
In quickbook 1.6 and later, if the included file has a <a class="link" href="structure.html#quickbook.ref.docinfo">docinfo
|
||
block</a> then it will create a nested document. This will be processed
|
||
as a standalone document, although any macros or templates from the enclosing
|
||
file will still be defined.
|
||
</p>
|
||
<p>
|
||
Otherwise the included file will be processed as if it had been cut and pasted
|
||
into the current document, with the following exceptions:
|
||
</p>
|
||
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
|
||
<li class="listitem">
|
||
The __FILENAME__ predefined macro will reflect the name of the file currently being
|
||
processed.
|
||
</li>
|
||
<li class="listitem">
|
||
Any macros or templates defined in the included file are scoped to that
|
||
file, i.e. they are not added to the enclosing file.
|
||
</li>
|
||
</ul></div>
|
||
<div class="note"><table border="0" summary="Note">
|
||
<tr>
|
||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../doc/src/images/note.png"></td>
|
||
<th align="left">Note</th>
|
||
</tr>
|
||
<tr><td align="left" valign="top"><p>
|
||
In quickbook 1.5 and earlier templates weren't scoped in included files.
|
||
If you want to use templates or macros from a file in quickbook 1.6, use
|
||
<a class="link" href="block.html#quickbook.ref.import">import</a> instead.
|
||
</p></td></tr>
|
||
</table></div>
|
||
<p>
|
||
The <code class="literal">[include]</code> directive lets you specify a document id
|
||
to use for the included file. You can specify the id like this:
|
||
</p>
|
||
<pre class="programlisting">[include:someid someother.qbk]
|
||
</pre>
|
||
<p>
|
||
All auto-generated anchors will use the document id as a unique prefix. So
|
||
for instance, if there is a top section in someother.qbk named "Intro",
|
||
the named anchor for that section will be "someid.intro", and you
|
||
can link to it with <code class="literal">[link someid.intro The Intro]</code>.
|
||
</p>
|
||
<p>
|
||
If the included file has a docinfo block, an id specified in an <code class="literal">[include]</code>
|
||
directive will overwrite it.
|
||
</p>
|
||
<p>
|
||
You can also include C, C++ and python source files. This will include any
|
||
quickbook blocks in the file that aren't inside of named code snippets. See
|
||
the <a class="link" href="block.html#quickbook.ref.import">Import section</a> for syntax
|
||
details. For example, say you included this file:
|
||
</p>
|
||
<pre class="programlisting">/**
|
||
* Hello world example
|
||
*/
|
||
|
||
// In this comment, the backtick indicates that this is a
|
||
// quickbook source block that will be included.
|
||
|
||
/*`
|
||
First include the appropriate header: [hello_includes]
|
||
Then write your main function: [hello_main]
|
||
*/
|
||
|
||
// This defines a code snippet, the syntax is
|
||
// described in the import section. It's available
|
||
// in the whole of this source file, not just after
|
||
// its definition.
|
||
|
||
//[hello_includes
|
||
#include <iostream>
|
||
//]
|
||
|
||
//[hello_main
|
||
int main() {
|
||
std::cout << "Hello, trivial example" << std::endl;
|
||
}
|
||
//]
|
||
</pre>
|
||
<p>
|
||
It will generate:
|
||
</p>
|
||
<pre class="programlisting">First include the appropriate header:
|
||
|
||
#include <iostream>
|
||
|
||
Then write your main function:
|
||
|
||
int main() {
|
||
std::cout << "Hello, trivial example" << std::endl;
|
||
}
|
||
</pre>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="quickbook.syntax.block.import"></a><a name="quickbook.ref.import"></a><a class="link" href="block.html#quickbook.syntax.block.import" title="Import">Import</a>
|
||
</h3></div></div></div>
|
||
<p>
|
||
In quickbook 1.6 and later if you wish to use a template, macro or code snippet
|
||
from a file, you need to import it. This will not include any of the content
|
||
from that file, but will pull templates, macros and code snippets into the
|
||
current file's scope.
|
||
</p>
|
||
<p>
|
||
With quickbook files, this allows you to create template and macro libraries.
|
||
For python (indicated by the <code class="computeroutput">.py</code> extension), C or C++ files
|
||
this allows you to include code snippets from source files, so that your
|
||
code examples can be kept up to date and fully tested.
|
||
</p>
|
||
<h4>
|
||
<a name="quickbook.syntax.block.import.h0"></a>
|
||
<span class="phrase"><a name="quickbook.syntax.block.import.example"></a></span><a class="link" href="block.html#quickbook.syntax.block.import.example">Example</a>
|
||
</h4>
|
||
<p>
|
||
You can effortlessly import code snippets from source code into your QuickBook.
|
||
The following illustrates how this is done:
|
||
</p>
|
||
<pre class="programlisting">[import ../test/stub.cpp]
|
||
[foo]
|
||
[bar]
|
||
</pre>
|
||
<p>
|
||
The first line:
|
||
</p>
|
||
<pre class="programlisting">[import ../test/stub.cpp]
|
||
</pre>
|
||
<p>
|
||
collects specially marked-up code snippets from <a href="../../../../tools/quickbook/test/stub.cpp" target="_top">stub.cpp</a>
|
||
and places them in your QuickBook file as virtual templates. Each of the
|
||
specially marked-up code snippets has a name (e.g. <code class="computeroutput">foo</code> and
|
||
<code class="computeroutput">bar</code> in the example above). This shall be the template identifier
|
||
for that particular code snippet. The second and third line above does the
|
||
actual template expansion:
|
||
</p>
|
||
<pre class="programlisting">[foo]
|
||
[bar]
|
||
</pre>
|
||
<p>
|
||
And the result is:
|
||
</p>
|
||
<p>
|
||
This is the <span class="bold"><strong><span class="emphasis"><em>foo</em></span></strong></span> function.
|
||
</p>
|
||
<p>
|
||
This description can have paragraphs...
|
||
</p>
|
||
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
|
||
<li class="listitem">
|
||
lists
|
||
</li>
|
||
<li class="listitem">
|
||
etc.
|
||
</li>
|
||
</ul></div>
|
||
<p>
|
||
And any quickbook block markup.
|
||
</p>
|
||
<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">foo</span><span class="special">()</span>
|
||
<span class="special">{</span>
|
||
<span class="comment">// return 'em, foo man!</span>
|
||
<span class="keyword">return</span> <span class="string">"foo"</span><span class="special">;</span>
|
||
<span class="special">}</span>
|
||
</pre>
|
||
<p>
|
||
This is the <span class="bold"><strong><span class="emphasis"><em>bar</em></span></strong></span> function
|
||
</p>
|
||
<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">bar</span><span class="special">()</span>
|
||
<span class="special">{</span>
|
||
<span class="comment">// return 'em, bar man!</span>
|
||
<span class="keyword">return</span> <span class="string">"bar"</span><span class="special">;</span>
|
||
<span class="special">}</span>
|
||
</pre>
|
||
<p>
|
||
Some trailing text here
|
||
</p>
|
||
<h4>
|
||
<a name="quickbook.syntax.block.import.h1"></a>
|
||
<span class="phrase"><a name="quickbook.syntax.block.import.code_snippet_markup"></a></span><a class="link" href="block.html#quickbook.syntax.block.import.code_snippet_markup">Code
|
||
Snippet Markup</a>
|
||
</h4>
|
||
<p>
|
||
Note how the code snippets in <a href="../../../../tools/quickbook/test/stub.cpp" target="_top">stub.cpp</a>
|
||
get marked up. We use distinguishable comments following the form:
|
||
</p>
|
||
<pre class="programlisting">//[id
|
||
some code here
|
||
//]
|
||
</pre>
|
||
<p>
|
||
The first comment line above initiates a named code-snippet. This prefix
|
||
will not be visible in quickbook. The entire code-snippet in between <code class="computeroutput">//[id</code>
|
||
and <code class="computeroutput">//]</code> will be inserted as a template in quickbook with name
|
||
<span class="emphasis"><em><span class="emphasis"><em>id</em></span></em></span>. The comment <code class="computeroutput">//]</code>
|
||
ends a code-snippet This too will not be visible in quickbook.
|
||
</p>
|
||
<a name="quickbook.ref.callouts"></a><h4>
|
||
<a name="quickbook.syntax.block.import.h2"></a>
|
||
<span class="phrase"><a name="quickbook.syntax.block.import.special_comments"></a></span><a class="link" href="block.html#quickbook.syntax.block.import.special_comments">Special
|
||
Comments</a>
|
||
</h4>
|
||
<p>
|
||
Special comments of the form:
|
||
</p>
|
||
<pre class="programlisting">//` some [*quickbook] markup here
|
||
</pre>
|
||
<p>
|
||
and:
|
||
</p>
|
||
<pre class="programlisting">/*` some [*quickbook] markup here */
|
||
</pre>
|
||
<p>
|
||
will be parsed by QuickBook. This can contain quickbook <span class="emphasis"><em>blocks</em></span>
|
||
(e.g. sections, paragraphs, tables, etc). In the first case, the initial
|
||
slash-slash, tick and white-space shall be ignored. In the second, the initial
|
||
slash-star-tick and the final star-slash shall be ignored.
|
||
</p>
|
||
<p>
|
||
Special comments of the form:
|
||
</p>
|
||
<pre class="programlisting">/*<- this C++ comment will be ignored ->*/
|
||
</pre>
|
||
<p>
|
||
or
|
||
</p>
|
||
<pre class="programlisting">/*<-*/ "this c++ code will be ignored" /*->*/
|
||
</pre>
|
||
<p>
|
||
or
|
||
</p>
|
||
<pre class="programlisting">//<-
|
||
private:
|
||
int some_member;
|
||
//->
|
||
</pre>
|
||
<p>
|
||
can be used to inhibit code from passing through to quickbook. All text between
|
||
the delimeters will simply be ignored.
|
||
</p>
|
||
<p>
|
||
Comments of this form:
|
||
</p>
|
||
<pre class="programlisting">//=int main() {}
|
||
</pre>
|
||
<p>
|
||
or
|
||
</p>
|
||
<pre class="programlisting">/*=foo()*/
|
||
</pre>
|
||
<p>
|
||
will be displayed as code that isn't in comments. This allows you to include
|
||
some code in the snippet but not actually use it when compiling your example.
|
||
</p>
|
||
<h4>
|
||
<a name="quickbook.syntax.block.import.h3"></a>
|
||
<span class="phrase"><a name="quickbook.syntax.block.import.callouts"></a></span><a class="link" href="block.html#quickbook.syntax.block.import.callouts">Callouts</a>
|
||
</h4>
|
||
<p>
|
||
Special comments of the form:
|
||
</p>
|
||
<pre class="programlisting">/*< some [*quickbook] markup here >*/
|
||
</pre>
|
||
<p>
|
||
will be regarded as callouts. These will be collected, numbered and rendered
|
||
as a "callout bug" (a small icon with a number). After the whole
|
||
snippet is parsed, the callout list is generated. See <a href="http://www.docbook.org/tdg/en/html/callout.html" target="_top">Callouts</a>
|
||
for details. Example:
|
||
</p>
|
||
<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">foo_bar</span><span class="special">()</span> <a class="co" name="quickbook.syntax.block.import.c0" href="block.html#quickbook.syntax.block.import.c1"><img src="../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a>
|
||
<span class="special">{</span>
|
||
<span class="keyword">return</span> <span class="string">"foo-bar"</span><span class="special">;</span> <a class="co" name="quickbook.syntax.block.import.c2" href="block.html#quickbook.syntax.block.import.c3"><img src="../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a>
|
||
<span class="special">}</span>
|
||
</pre>
|
||
<div class="calloutlist"><table border="0" summary="Callout list">
|
||
<tr>
|
||
<td width="5%" valign="top" align="left"><p><a name="quickbook.syntax.block.import.c1"></a><a href="#quickbook.syntax.block.import.c0"><img src="../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a> </p></td>
|
||
<td valign="top" align="left"><p>
|
||
The <span class="emphasis"><em>Mythical</em></span> FooBar. See <a href="http://en.wikipedia.org/wiki/Foobar" target="_top">Foobar
|
||
for details</a>
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td width="5%" valign="top" align="left"><p><a name="quickbook.syntax.block.import.c3"></a><a href="#quickbook.syntax.block.import.c2"><img src="../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a> </p></td>
|
||
<td valign="top" align="left"><p>
|
||
return 'em, foo-bar man!
|
||
</p></td>
|
||
</tr>
|
||
</table></div>
|
||
<p>
|
||
This is the actual code:
|
||
</p>
|
||
<pre class="programlisting">//[ foo_bar
|
||
std::string foo_bar() /*< The /Mythical/ FooBar.
|
||
See [@http://en.wikipedia.org/wiki/Foobar Foobar for details] >*/
|
||
{
|
||
return "foo-bar"; /*< return 'em, foo-bar man! >*/
|
||
}
|
||
//]
|
||
</pre>
|
||
<p>
|
||
The callouts bugs are placed exactly where the special callout comment is
|
||
situated. It can be anywhere in the code. The bugs can be rather obtrusive,
|
||
however. They get in the way of the clarity of the code. Another special
|
||
callout comment style is available:
|
||
</p>
|
||
<pre class="programlisting">/*<< some [*quickbook] markup here >>*/
|
||
</pre>
|
||
<p>
|
||
This is the line-oriented version of the callout. With this, the "bug"
|
||
is placed at the very left of the code block, away from the actual code.
|
||
By placing it at the far left, the code is rendered un-obscured. Example:
|
||
</p>
|
||
<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">x</span>
|
||
<span class="special">{</span>
|
||
<span class="keyword">public</span><span class="special">:</span>
|
||
|
||
<a class="co" name="quickbook.syntax.block.import.c4" href="block.html#quickbook.syntax.block.import.c5"><img src="../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a><span class="identifier">x</span><span class="special">()</span> <span class="special">:</span> <span class="identifier">n</span><span class="special">(</span><span class="number">0</span><span class="special">)</span>
|
||
<span class="special">{</span>
|
||
<span class="special">}</span>
|
||
|
||
<a class="co" name="quickbook.syntax.block.import.c6" href="block.html#quickbook.syntax.block.import.c7"><img src="../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a><span class="special">~</span><span class="identifier">x</span><span class="special">()</span>
|
||
<span class="special">{</span>
|
||
<span class="special">}</span>
|
||
|
||
<a class="co" name="quickbook.syntax.block.import.c8" href="block.html#quickbook.syntax.block.import.c9"><img src="../../../../doc/src/images/callouts/3.png" alt="3" border="0"></a><span class="keyword">int</span> <span class="identifier">get</span><span class="special">()</span> <span class="keyword">const</span>
|
||
<span class="special">{</span>
|
||
<span class="keyword">return</span> <span class="identifier">n</span><span class="special">;</span>
|
||
<span class="special">}</span>
|
||
|
||
<a class="co" name="quickbook.syntax.block.import.c10" href="block.html#quickbook.syntax.block.import.c11"><img src="../../../../doc/src/images/callouts/4.png" alt="4" border="0"></a><span class="keyword">void</span> <span class="identifier">set</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">n_</span><span class="special">)</span>
|
||
<span class="special">{</span>
|
||
<span class="identifier">n</span> <span class="special">=</span> <span class="identifier">n_</span><span class="special">;</span>
|
||
<span class="special">}</span>
|
||
<span class="special">};</span>
|
||
</pre>
|
||
<div class="calloutlist"><table border="0" summary="Callout list">
|
||
<tr>
|
||
<td width="5%" valign="top" align="left"><p><a name="quickbook.syntax.block.import.c5"></a><a href="#quickbook.syntax.block.import.c4"><img src="../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a> </p></td>
|
||
<td valign="top" align="left"><p>
|
||
Constructor
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td width="5%" valign="top" align="left"><p><a name="quickbook.syntax.block.import.c7"></a><a href="#quickbook.syntax.block.import.c6"><img src="../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a> </p></td>
|
||
<td valign="top" align="left"><p>
|
||
Destructor
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td width="5%" valign="top" align="left"><p><a name="quickbook.syntax.block.import.c9"></a><a href="#quickbook.syntax.block.import.c8"><img src="../../../../doc/src/images/callouts/3.png" alt="3" border="0"></a> </p></td>
|
||
<td valign="top" align="left"><p>
|
||
Get the <code class="computeroutput">n</code> member variable
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td width="5%" valign="top" align="left"><p><a name="quickbook.syntax.block.import.c11"></a><a href="#quickbook.syntax.block.import.c10"><img src="../../../../doc/src/images/callouts/4.png" alt="4" border="0"></a> </p></td>
|
||
<td valign="top" align="left"><p>
|
||
Set the <code class="computeroutput">n</code> member variable
|
||
</p></td>
|
||
</tr>
|
||
</table></div>
|
||
<p>
|
||
See the actual code here: <a href="../../../../tools/quickbook/test/stub.cpp" target="_top">tools/quickbook/test/stub.cpp</a>
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="quickbook.syntax.block.block"></a><a name="quickbook.ref.block"></a><a class="link" href="block.html#quickbook.syntax.block.block" title="Plain blocks">Plain
|
||
blocks</a>
|
||
</h3></div></div></div>
|
||
<p>
|
||
<code class="computeroutput">block</code> is a plain block element, that doesn't wrap its contents
|
||
in any docbook or boostbook tags. This can be useful when using escaped docbook
|
||
block tags, such as:
|
||
</p>
|
||
<pre class="programlisting">[template chapter[title]
|
||
[block'''<chapter><title>'''[title]'''</title>''']
|
||
]
|
||
|
||
[template chapterend
|
||
[block'''</chapter>''']
|
||
]
|
||
|
||
[chapter An example chapter]
|
||
|
||
Content
|
||
|
||
[chapterend]
|
||
</pre>
|
||
<p>
|
||
Without the <code class="computeroutput">block</code> element, the <code class="computeroutput">chapter</code> and <code class="computeroutput">chapterend</code>
|
||
templates would be wrapped in paragraph tags.
|
||
</p>
|
||
<div class="note"><table border="0" summary="Note">
|
||
<tr>
|
||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../doc/src/images/note.png"></td>
|
||
<th align="left">Note</th>
|
||
</tr>
|
||
<tr><td align="left" valign="top"><p>
|
||
In this example, the template body has to start with a newline so that
|
||
the template will be interpreted in block mode.
|
||
</p></td></tr>
|
||
</table></div>
|
||
</div>
|
||
</div>
|
||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||
<td align="left"></td>
|
||
<td align="right"><div class="copyright-footer">Copyright © 2002, 2004, 2006 Joel de Guzman,
|
||
Eric Niebler<br>Copyright © 2010-2017 Daniel James<p>
|
||
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
|
||
</p>
|
||
</div></td>
|
||
</tr></table>
|
||
<hr>
|
||
<div class="spirit-nav">
|
||
<a accesskey="p" href="phrase.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../quickbook.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../versions.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a>
|
||
</div>
|
||
</body>
|
||
</html>
|