Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/doc/html/quickbook/syntax.html @ 46

Last change on this file since 46 was 29, checked in by landauf, 17 years ago

updated boost from 1_33_1 to 1_34_1
File size: 60.3 KB
Line 
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title> Syntax Summary</title>
5<link rel="stylesheet" href="../boostbook.css" type="text/css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.68.1">
7<link rel="start" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
8<link rel="up" href="../quickbook.html" title="Chapter 23. Quickbook 1.3">
9<link rel="prev" href="change_log.html" title=" Change Log">
10<link rel="next" href="ref.html" title=" Quick Reference">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
13<table cellpadding="2" width="100%">
14<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
15<td align="center"><a href="../../../index.htm">Home</a></td>
16<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
17<td align="center"><a href="../../../people/people.htm">People</a></td>
18<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
19<td align="center"><a href="../../../more/index.htm">More</a></td>
20</table>
21<hr>
22<div class="spirit-nav">
23<a accesskey="p" href="change_log.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../quickbook.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="ref.html"><img src="../images/next.png" alt="Next"></a>
24</div>
25<div class="section" lang="en">
26<div class="titlepage"><div><div><h2 class="title" style="clear: both">
27<a name="quickbook.syntax"></a> Syntax Summary</h2></div></div></div>
28<div class="toc"><dl>
29<dt><span class="section"><a href="syntax.html#quickbook.syntax.comments">Comments</a></span></dt>
30<dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase"> Phrase Level Elements</a></span></dt>
31<dt><span class="section"><a href="syntax.html#quickbook.syntax.block"> Block Level Elements</a></span></dt>
32</dl></div>
33<p>
34      A QuickBook document is composed of one or more blocks. An example of a block
35      is the paragraph or a C++ code snippet. Some blocks have special mark-ups.
36      Blocks, except code snippets which have their own grammar (C++ or Python),
37      are composed of one or more phrases. A phrase can be a simple contiguous run
38      of characters. Phrases can have special mark-ups. Marked up phrases can recursively
39      contain other phrases, but cannot contain blocks. A terminal is a self contained
40      block-level or phrase-level element that does not nest anything.
41    </p>
42<p>
43      Blocks, in general, are delimited by two end-of-lines (the block terminator).
44      Phrases in each block cannot contain a block terminator. This way, syntax errors
45      such as un-matched closing brackets do not go haywire and corrupt anything
46      past a single block.
47    </p>
48<div class="section" lang="en">
49<div class="titlepage"><div><div><h3 class="title">
50<a name="quickbook.syntax.comments"></a>Comments</h3></div></div></div>
51<p>
52        Can be placed anywhere.
53      </p>
54<pre class="programlisting">[/ comment (no output generated) ]
55</pre>
56</div>
57<div class="section" lang="en">
58<div class="titlepage"><div><div><h3 class="title">
59<a name="quickbook.syntax.phrase"></a> Phrase Level Elements</h3></div></div></div>
60<div class="toc"><dl>
61<dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.font_styles">Font Styles</a></span></dt>
62<dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.replaceable">Replaceable</a></span></dt>
63<dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.quotations">Quotations</a></span></dt>
64<dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.simple_formatting">Simple formatting</a></span></dt>
65<dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.inline_code">Inline code</a></span></dt>
66<dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.code_blocks">Code blocks</a></span></dt>
67<dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.source_mode">Source Mode</a></span></dt>
68<dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.line_break">line-break</a></span></dt>
69<dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.anchors">Anchors</a></span></dt>
70<dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.links">Links</a></span></dt>
71<dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.anchor_links">Anchor links</a></span></dt>
72<dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.refentry_links">refentry links</a></span></dt>
73<dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.code_links"> Code Links</a></span></dt>
74<dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.escape">Escape</a></span></dt>
75<dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.single_char_escape">Single char escape</a></span></dt>
76<dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.images">Images</a></span></dt>
77<dt><span class="section"><a href="syntax.html#quickbook.syntax.phrase.footnotes">Footnotes</a></span></dt>
78</dl></div>
79<div class="section" lang="en">
80<div class="titlepage"><div><div><h4 class="title">
81<a name="quickbook.syntax.phrase.font_styles"></a>Font Styles</h4></div></div></div>
82<pre class="programlisting">['italic], [*bold], [_underline], [^teletype], [-strikethrough]
83</pre>
84<p>
85          will generate:
86        </p>
87<p>
88          <span class="emphasis"><em>italic</em></span>, <span class="bold"><strong>bold</strong></span>, <span class="underline">underline</span>, <code class="literal">teletype</code>, <span class="strikethrough">strikethrough</span>
89        </p>
90<p>
91          Like all non-terminal phrase level elements, this can of course be nested:
92        </p>
93<pre class="programlisting">[*['bold-italic]]
94</pre>
95<p>
96          will generate:
97        </p>
98<p>
99          <span class="bold"><strong><span class="emphasis"><em>bold-italic</em></span></strong></span>
100        </p>
101</div>
102<div class="section" lang="en">
103<div class="titlepage"><div><div><h4 class="title">
104<a name="quickbook.syntax.phrase.replaceable"></a>Replaceable</h4></div></div></div>
105<p>
106          When you want content that may or must be replaced by the user, use the
107          syntax:
108        </p>
109<pre class="programlisting">[~replacement]
110</pre>
111<p>
112          This will generate:
113        </p>
114<p>
115          <em class="replaceable"><code>
116            replacement
117          </code></em>
118        </p>
119</div>
120<div class="section" lang="en">
121<div class="titlepage"><div><div><h4 class="title">
122<a name="quickbook.syntax.phrase.quotations"></a>Quotations</h4></div></div></div>
123<pre class="programlisting">["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein
124</pre>
125<p>
126          will generate:
127        </p>
128<p>
129          &#8220;<span class="quote">A question that sometimes drives me hazy: am I or are the others
130          crazy?</span>&#8221;--Einstein
131        </p>
132<p>
133          Note the proper left and right quote marks. Also, while you can simply
134          use ordinary quote marks like "quoted", our quotation, above,
135          will generate correct DocBook quotations (e.g. &lt;quote&gt;quoted&lt;/quote&gt;).
136        </p>
137<p>
138          Like all phrase elements, quotations may be nested. Example:
139        </p>
140<pre class="programlisting">["Here's the rule for bargains: ["Do other men, for they would do you.] That's
141the true business precept.]
142</pre>
143<p>
144          will generate:
145        </p>
146<p>
147          &#8220;<span class="quote">Here's the rule for bargains: &#8216;<span class="quote">Do other men, for they would
148          do you.</span>&#8217; That's the true business precept.</span>&#8221;
149        </p>
150</div>
151<div class="section" lang="en">
152<div class="titlepage"><div><div><h4 class="title">
153<a name="quickbook.syntax.phrase.simple_formatting"></a>Simple formatting</h4></div></div></div>
154<p>
155          Simple markup for formatting text, common in many applications, is now
156          supported:
157        </p>
158<pre class="programlisting">/italic/, *bold*, _underline_, =teletype=
159</pre>
160<p>
161          will generate:
162        </p>
163<p>
164          <span class="emphasis"><em>italic</em></span>, <span class="bold"><strong>bold</strong></span>, <span class="underline">underline</span>, <code class="literal">teletype</code>
165        </p>
166<p>
167          Unlike QuickBook's standard formatting scheme, the rules for simpler alternatives
168          are much stricter.
169        </p>
170<div class="itemizedlist"><ul type="disc">
171<li>
172            Simple markups cannot nest. You can combine a simple markup with a nestable
173            markup.
174          </li>
175<li>
176            A non-space character must follow the leading markup
177          </li>
178<li>
179            A non-space character must precede the trailing markup
180          </li>
181<li>
182            A space or a punctuation must follow the trailing markup
183          </li>
184<li>
185            If the matching markup cannot be found within a line, the formatting
186            will not be applied. This is to ensure that un-matched formatting markups,
187            which can be a common mistake, does not corrupt anything past a single
188            line. We do not want the rest of the document to be rendered bold just
189            because we forgot a trailing '*'.
190          </li>
191<li>
192            A line starting with the star will be interpreted as an unordered list.
193            See <a href="syntax.html#quickbook.syntax.block.lists.unordered_lists" title="Unordered lists">Unordered
194            lists</a>.
195          </li>
196</ul></div>
197<div class="informaltable">
198<h4>
199<a name="id2086955"></a>
200            <span class="table-title">More Formatting Samples</span>
201          </h4>
202<table class="table">
203<colgroup>
204<col>
205<col>
206</colgroup>
207<thead><tr>
208<th>Markup</th>
209<th>Result</th>
210</tr></thead>
211<tbody>
212<tr>
213<td><code class="literal">
214*Bold*
215                </code></td>
216<td><span class="bold"><strong>Bold</strong></span></td>
217</tr>
218<tr>
219<td><code class="literal">
220*Is bold*
221                </code></td>
222<td><span class="bold"><strong>Is bold</strong></span></td>
223</tr>
224<tr>
225<td><code class="literal">
226* Not bold* *Not bold * * Not bold *
227                </code></td>
228<td>* Not bold* *Not bold * * Not bold *</td>
229</tr>
230<tr>
231<td><code class="literal">
232This*Isn't*Bold (no bold)
233                </code></td>
234<td>This*Isn't*Bold (no bold)</td>
235</tr>
236<tr>
237<td><code class="literal">
238(*Bold Inside*) (parenthesis not bold)
239                </code></td>
240<td>(<span class="bold"><strong>Bold Inside</strong></span>)
241                (parenthesis not bold)</td>
242</tr>
243<tr>
244<td><code class="literal">
245*(Bold Outside)* (parenthesis bold)
246                </code></td>
247<td>
248<span class="bold"><strong>(Bold Outside)</strong></span>
249                (parenthesis bold)</td>
250</tr>
251<tr>
252<td><code class="literal">
2533*4*5 = 60 (no bold)
254                </code></td>
255<td>3*4*5 = 60 (no bold)</td>
256</tr>
257<tr>
258<td><code class="literal">
2593 * 4 * 5 = 60 (no bold)
260                </code></td>
261<td>3 * 4 * 5 = 60 (no bold)</td>
262</tr>
263<tr>
264<td><code class="literal">
2653 *4* 5 = 60 (4 is bold)
266                </code></td>
267<td>3 <span class="bold"><strong>4</strong></span> 5 =
268                60 (4 is bold)</td>
269</tr>
270<tr>
271<td><code class="literal">
272*This is bold* this is not *but this is*
273                </code></td>
274<td>
275<span class="bold"><strong>This is bold</strong></span>
276                this is not <span class="bold"><strong>but this is</strong></span>
277</td>
278</tr>
279<tr>
280<td><code class="literal">
281*This is bold*.
282                </code></td>
283<td>
284<span class="bold"><strong>This is bold</strong></span>.</td>
285</tr>
286<tr>
287<td><code class="literal">
288*B*. (bold B)
289                </code></td>
290<td>
291<span class="bold"><strong>B</strong></span>. (bold
292                B)</td>
293</tr>
294<tr>
295<td><code class="literal">
296['*Bold-Italic*]
297                </code></td>
298<td><span class="emphasis"><em><span class="bold"><strong>Bold-Italic</strong></span></em></span></td>
299</tr>
300</tbody>
301</table>
302</div>
303<div class="informaltable"><table class="table">
304<colgroup><col></colgroup>
305<tbody><tr><td class="blurb"> <span class="inlinemediaobject"><img src="../images/note.png" alt="note"></span> Thanks to David Barrett, author of <a href="http://quinthar.com/qwikiwiki/index.php?page=Home" target="_top">Qwiki</a>,
306                for sharing these samples and teaching me these obscure formatting
307                rules. I wasn't sure at all if <a href="http://spirit.sourceforge.net" target="_top">Spirit</a>,
308                being more or less a formal EBNF parser, can handle the context sensitivity
309                and ambiguity.</td></tr></tbody>
310</table></div>
311</div>
312<div class="section" lang="en">
313<div class="titlepage"><div><div><h4 class="title">
314<a name="quickbook.syntax.phrase.inline_code"></a>Inline code</h4></div></div></div>
315<p>
316          Inlining code in paragraphs is quite common when writing C++ documentation.
317          We provide a very simple markup for this. For example, this:
318        </p>
319<pre class="programlisting">This text has inlined code `int main() { return 0; }` in it.
320</pre>
321<p>
322          will generate:
323        </p>
324<p>
325          This text has inlined code <code class="computeroutput"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> <span class="special">}</span></code> in it. The code will be syntax highlighted.
326        </p>
327<div class="informaltable"><table class="table">
328<colgroup><col></colgroup>
329<tbody><tr><td class="blurb"> <span class="inlinemediaobject"><img src="../images/note.png" alt="note"></span> Note that we simply enclose the code with the
330                tick: <code class="literal">
331"`"
332                </code>, not the single quote: <code class="computeroutput"><span class="string">"'"</span></code>.
333                Note too that <code class="literal">
334`some code`
335                </code> is preferred over <code class="literal">
336[^some code]
337                </code>. </td></tr></tbody>
338</table></div>
339</div>
340<div class="section" lang="en">
341<div class="titlepage"><div><div><h4 class="title">
342<a name="quickbook.syntax.phrase.code_blocks"></a>Code blocks</h4></div></div></div>
343<p>
344          Preformatted code simply starts with a space or a tab (See <a href="syntax.html#quickbook.syntax.block.code" title="Code">Code</a>).
345          However, such a simple syntax cannot be used as phrase elements in lists
346          (See <a href="syntax.html#quickbook.syntax.block.lists.ordered_lists" title="Ordered lists">Ordered
347          lists</a> and <a href="syntax.html#quickbook.syntax.block.lists.unordered_lists" title="Unordered lists">Unordered
348          lists</a>), tables (See <a href="syntax.html#quickbook.syntax.block.tables" title="Tables">Tables</a>),
349          etc. Inline code (see above) can. The problem is, inline code does not
350          allow formatting with newlines, spaces, and tabs. These are lost.
351        </p>
352<p>
353          We provide a phrase level markup that is a mix between the two. By using
354          the double-tick, instead of the single-tick, we are telling QuickBook to
355          use preformatted blocks of code. Example:
356        </p>
357<pre class="programlisting">``
358    #include &lt;iostream&gt;
359
360    int main()
361    {
362        std::cout &lt;&lt; "Hello, World!" &lt;&lt; std::endl;
363        return 0;
364    }
365``
366</pre>
367<p>
368          will generate:
369        </p>
370<p>
371         
372</p>
373<pre class="programlisting">
374<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
375
376<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
377<span class="special">{</span>
378    <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Hello, World!"</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>
379    <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
380<span class="special">}</span>
381</pre>
382<p>
383        </p>
384</div>
385<div class="section" lang="en">
386<div class="titlepage"><div><div><h4 class="title">
387<a name="quickbook.syntax.phrase.source_mode"></a>Source Mode</h4></div></div></div>
388<p>
389          If a document contains more than one type of source code then the source
390          mode may be changed dynamically as the document is processed. All QuickBook
391          documents are initially in C++ mode by default, though an alternative initial
392          value may be set in the <a href="syntax.html#quickbook.syntax.block.document" title="Document">Document</a>
393          section.
394        </p>
395<p>
396          To change the source mode, use the <code class="literal">[source-mode]</code> markup,
397          where <code class="literal">source-mode</code> is one of the supported modes. For
398          example, this:
399        </p>
400<pre class="programlisting">Python's [python] `import` is rather like C++'s [c++] `#include`. A
401C++ comment `// looks like this` whereas a Python comment [python]
402`# looks like this`.
403</pre>
404<p>
405          will generate:
406        </p>
407<p>
408          Python's <code class="computeroutput"><span class="keyword">import</span></code> is rather
409          like C++'s <code class="computeroutput"><span class="preprocessor">#include</span></code>.
410          A C++ comment <code class="computeroutput"><span class="comment">// looks like this</span></code>
411          whereas a Python comment <code class="computeroutput"><span class="comment">#looks like this</span></code>.
412        </p>
413<div class="informaltable">
414<h4>
415<a name="id2087699"></a>
416            <span class="table-title">Supported Source Modes</span>
417          </h4>
418<table class="table">
419<colgroup>
420<col>
421<col>
422</colgroup>
423<thead><tr>
424<th>Mode</th>
425<th>Source Mode Markup</th>
426</tr></thead>
427<tbody>
428<tr>
429<td>C++</td>
430<td><code class="literal">[c++]</code></td>
431</tr>
432<tr>
433<td>Python</td>
434<td><code class="literal">[python]</code></td>
435</tr>
436</tbody>
437</table>
438</div>
439<div class="informaltable"><table class="table">
440<colgroup><col></colgroup>
441<tbody><tr><td class="blurb"> <span class="inlinemediaobject"><img src="../images/note.png" alt="note"></span> The source mode strings are lowercase.</td></tr></tbody>
442</table></div>
443</div>
444<div class="section" lang="en">
445<div class="titlepage"><div><div><h4 class="title">
446<a name="quickbook.syntax.phrase.line_break"></a>line-break</h4></div></div></div>
447<pre class="programlisting">[br]
448</pre>
449<div class="informaltable"><table class="table">
450<colgroup><col></colgroup>
451<tbody><tr><td class="blurb"> <span class="inlinemediaobject"><img src="../images/note.png" alt="note"></span> Note that <code class="computeroutput"><span class="special">\</span><span class="identifier">n</span></code> is now preferred over <code class="computeroutput"><span class="special">[</span><span class="identifier">br</span><span class="special">]</span></code>.</td></tr></tbody>
452</table></div>
453</div>
454<div class="section" lang="en">
455<div class="titlepage"><div><div><h4 class="title">
456<a name="quickbook.syntax.phrase.anchors"></a>Anchors</h4></div></div></div>
457<pre class="programlisting">[#named_anchor]
458</pre>
459<p>
460          A named anchor is a hook that can be referenced by a link elsewhere in
461          the document. You can then reference an anchor with <code class="literal">
462[link named_anchor
463Some link text]
464          </code>. See <a href="syntax.html#quickbook.syntax.phrase.anchor_links" title="Anchor links">Anchor
465          links</a>, <a href="syntax.html#quickbook.syntax.block.section" title="Section">Section</a>
466          and <a href="syntax.html#quickbook.syntax.block.headings" title="Headings">Heading</a>.
467        </p>
468</div>
469<div class="section" lang="en">
470<div class="titlepage"><div><div><h4 class="title">
471<a name="quickbook.syntax.phrase.links"></a>Links</h4></div></div></div>
472<pre class="programlisting">[@http://www.boost.org this is [*boost's] website....]
473</pre>
474<p>
475          will generate:
476        </p>
477<p>
478          <a href="http://www.boost.org" target="_top">this is <span class="bold"><strong>boost's</strong></span>
479          website....</a>
480        </p>
481<p>
482          URL links where the link text is the link itself is common. Example:
483        </p>
484<pre class="programlisting">see http://spirit.sourceforge.net/
485</pre>
486<p>
487          so, when the text is absent in a link markup, the URL is assumed. Example:
488        </p>
489<pre class="programlisting">see [@http://spirit.sourceforge.net/]
490</pre>
491<p>
492          will generate:
493        </p>
494<p>
495          see <a href="http://spirit.sourceforge.net/" target="_top">http://spirit.sourceforge.net/</a>
496        </p>
497</div>
498<div class="section" lang="en">
499<div class="titlepage"><div><div><h4 class="title">
500<a name="quickbook.syntax.phrase.anchor_links"></a>Anchor links</h4></div></div></div>
501<p>
502          You can link within a document using:
503        </p>
504<pre class="programlisting">[link section_id.normalized_header_text The link text]
505</pre>
506<p>
507          See sections <a href="syntax.html#quickbook.syntax.block.section" title="Section">Section</a>
508          and <a href="syntax.html#quickbook.syntax.block.headings" title="Headings">Heading</a> for
509          more info.
510        </p>
511</div>
512<div class="section" lang="en">
513<div class="titlepage"><div><div><h4 class="title">
514<a name="quickbook.syntax.phrase.refentry_links"></a>refentry links</h4></div></div></div>
515<p>
516          In addition, you can link internally to an XML refentry like:
517        </p>
518<pre class="programlisting">[link xml.refentry The link text]
519</pre>
520<p>
521          This gets converted into <code class="literal">&lt;link linkend="xml.refentry"&gt;The
522          link text&lt;/link&gt;</code>.
523        </p>
524<p>
525          Like URLs, the link text is optional. If this is not present, the link
526          text will automatically be the refentry. Example:
527        </p>
528<pre class="programlisting">[link xml.refentry]
529</pre>
530<p>
531          This gets converted into <code class="literal">&lt;link linkend="xml.refentry"&gt;xml.refentry&lt;/link&gt;</code>.
532        </p>
533</div>
534<div class="section" lang="en">
535<div class="titlepage"><div><div><h4 class="title">
536<a name="quickbook.syntax.phrase.code_links"></a> Code Links</h4></div></div></div>
537<p>
538          If you want to link to a function, class, member, enum or header in the
539          reference section, you can use:
540        </p>
541<pre class="programlisting">[funcref fully::qualified::function_name The link text]
542[classref fully::qualified::class_name The link text]
543[memberref fully::qualified::member_name The link text]
544[enumref fully::qualified::enum_name The link text]
545[headerref path/to/header.hpp The link text]
546</pre>
547<p>
548          Again, the link text is optional. If this is not present, the link text
549          will automatically be the function, class, member or enum. Example:
550        </p>
551<pre class="programlisting">[classref boost::bar::baz]
552</pre>
553<p>
554          would have "boost::bar::baz" as the link text.
555        </p>
556</div>
557<div class="section" lang="en">
558<div class="titlepage"><div><div><h4 class="title">
559<a name="quickbook.syntax.phrase.escape"></a>Escape</h4></div></div></div>
560<p>
561          The escape mark-up is used when we don't want to do any processing.
562        </p>
563<pre class="programlisting">'''
564escape (no processing/formatting)
565'''
566</pre>
567<p>
568          Escaping allows us to pass XML markup to <a href="http://www.boost.org/doc/html/boostbook.html" target="_top">BoostBook</a>
569          or <a href="http://www.docbook.org/" target="_top">DocBook</a>. For example:
570        </p>
571<pre class="programlisting">'''
572&lt;emphasis role="bold"&gt;This is direct XML markup&lt;/emphasis&gt;
573'''
574</pre>
575<p>
576         
577<span class="bold"><strong>This is direct XML markup</strong></span>
578
579        </p>
580<div class="informaltable"><table class="table">
581<colgroup><col></colgroup>
582<tbody><tr><td class="blurb"> <span class="inlinemediaobject"><img src="../images/alert.png" alt="alert"></span> Be careful when using the escape. The text must
583                conform to <a href="http://www.boost.org/doc/html/boostbook.html" target="_top">BoostBook</a>/<a href="http://www.docbook.org/" target="_top">DocBook</a> syntax.</td></tr></tbody>
584</table></div>
585</div>
586<div class="section" lang="en">
587<div class="titlepage"><div><div><h4 class="title">
588<a name="quickbook.syntax.phrase.single_char_escape"></a>Single char escape</h4></div></div></div>
589<p>
590          The backslash may be used to escape a single punctuation character. The
591          punctuation immediately after the backslash is passed without any processing.
592          This is useful when we need to escape QuickBook punctuations such as <code class="computeroutput"><span class="special">[</span></code> and <code class="computeroutput"><span class="special">]</span></code>.
593          For example, how do you escape the triple quote? Simple: <code class="literal">\'\'\'</code>
594        </p>
595<p>
596          <code class="computeroutput"><span class="special">\</span><span class="identifier">n</span></code>
597          has a special meaning. It is used to generate line breaks. Note that <code class="computeroutput"><span class="special">\</span><span class="identifier">n</span></code> is
598          now preferred over <code class="computeroutput"><span class="special">[</span><span class="identifier">br</span><span class="special">]</span></code>.
599        </p>
600</div>
601<div class="section" lang="en">
602<div class="titlepage"><div><div><h4 class="title">
603<a name="quickbook.syntax.phrase.images"></a>Images</h4></div></div></div>
604<pre class="programlisting">[$image.jpg]
605</pre>
606</div>
607<div class="section" lang="en">
608<div class="titlepage"><div><div><h4 class="title">
609<a name="quickbook.syntax.phrase.footnotes"></a>Footnotes</h4></div></div></div>
610<p>
611          As of version 1.3, QuickBook supports footnotes. Just put the text of the
612          footnote in a <code class="computeroutput"><span class="special">[</span><span class="identifier">footnote</span><span class="special">]</span></code> block, and the text will be put at the
613          bottom of the current page. For example, this:
614        </p>
615<pre class="programlisting">[footnote A sample footnote]
616</pre>
617<p>
618          will generate this
619          <sup>[<a name="id2088405" href="#ftn.id2088405">2</a>]</sup>
620          .
621        </p>
622</div>
623</div>
624<div class="section" lang="en">
625<div class="titlepage"><div><div><h3 class="title">
626<a name="quickbook.syntax.block"></a> Block Level Elements</h3></div></div></div>
627<div class="toc"><dl>
628<dt><span class="section"><a href="syntax.html#quickbook.syntax.block.document">Document</a></span></dt>
629<dt><span class="section"><a href="syntax.html#quickbook.syntax.block.section">Section</a></span></dt>
630<dt><span class="section"><a href="syntax.html#quickbook.syntax.block.xinclude">xinclude</a></span></dt>
631<dt><span class="section"><a href="syntax.html#quickbook.syntax.block.paragraphs">Paragraphs</a></span></dt>
632<dt><span class="section"><a href="syntax.html#quickbook.syntax.block.lists">Lists</a></span></dt>
633<dt><span class="section"><a href="syntax.html#quickbook.syntax.block.code">Code</a></span></dt>
634<dt><span class="section"><a href="syntax.html#quickbook.syntax.block.escape_back"> Escaping Back To QuickBook</a></span></dt>
635<dt><span class="section"><a href="syntax.html#quickbook.syntax.block.preformatted">Preformatted</a></span></dt>
636<dt><span class="section"><a href="syntax.html#quickbook.syntax.block.blockquote">Blockquote</a></span></dt>
637<dt><span class="section"><a href="syntax.html#quickbook.syntax.block.admonitions">Admonitions</a></span></dt>
638<dt><span class="section"><a href="syntax.html#quickbook.syntax.block.headings">Headings</a></span></dt>
639<dt><span class="section"><a href="syntax.html#quickbook.syntax.block.macros">Macros</a></span></dt>
640<dt><span class="section"><a href="syntax.html#quickbook.syntax.block.predefined_macros">Predefined Macros</a></span></dt>
641<dt><span class="section"><a href="syntax.html#quickbook.syntax.block.blurbs">Blurbs</a></span></dt>
642<dt><span class="section"><a href="syntax.html#quickbook.syntax.block.tables">Tables</a></span></dt>
643<dt><span class="section"><a href="syntax.html#quickbook.syntax.block.variable_lists">Variable Lists</a></span></dt>
644<dt><span class="section"><a href="syntax.html#quickbook.syntax.block.include">Include</a></span></dt>
645</dl></div>
646<div class="section" lang="en">
647<div class="titlepage"><div><div><h4 class="title">
648<a name="quickbook.syntax.block.document"></a>Document</h4></div></div></div>
649<p>
650          Every document must begin with a Document Info section, which should look
651          like this:
652        </p>
653<pre class="programlisting">[document-type The Document Title
654    [quickbook 1.3]
655    [version 1.0]
656    [id the_document_name]
657    [dirname the_document_dir]
658    [copyright 2000 2002 2003 Joe Blow, Jane Doe]
659    [purpose The document's reason for being]
660    [category The document's category]
661    [authors [Blow, Joe], [Doe, Jane]]
662    [license The document's license]
663    [source-mode source-type]
664]
665</pre>
666<p>
667          Where document-type is one of:
668        </p>
669<div class="itemizedlist"><ul type="disc">
670<li>
671            book
672          </li>
673<li>
674            article
675          </li>
676<li>
677            library
678          </li>
679<li>
680            chapter
681          </li>
682<li>
683            part
684          </li>
685<li>
686            appendix
687          </li>
688<li>
689            preface
690          </li>
691<li>
692            qandadiv
693          </li>
694<li>
695            qandaset
696          </li>
697<li>
698            reference
699          </li>
700<li>
701            set
702          </li>
703</ul></div>
704<p>
705          quickbook 1.3 declares the version of quickbook the document is written
706          for. In its absence, version 1.1 is assumed.
707        </p>
708<p>
709          <code class="literal">version</code>, <code class="literal">id</code>, <code class="literal">dirname</code>,
710          <code class="literal">copyright</code>, <code class="literal">purpose</code>, <code class="literal">category</code>,
711          <code class="literal">authors</code>, <code class="literal">license</code>, <code class="literal">last-revision</code>
712          and <code class="literal">source-mode</code> are optional information.
713        </p>
714<p>
715          <code class="literal">source-type</code> is a lowercase string setting the initial
716          <a href="syntax.html#quickbook.syntax.phrase.source_mode" title="Source Mode">Source Mode</a>.
717          If the <code class="literal">source-mode</code> field is omitted, a default value
718          of <code class="literal">c++</code> will be used.
719        </p>
720</div>
721<div class="section" lang="en">
722<div class="titlepage"><div><div><h4 class="title">
723<a name="quickbook.syntax.block.section"></a>Section</h4></div></div></div>
724<p>
725          Starting a new section is accomplished with:
726        </p>
727<pre class="programlisting">[section:id The Section Title]
728</pre>
729<p>
730          where <span class="emphasis"><em>id</em></span> is optional. id will be the filename of the
731          generated section. If it is not present, "The Section Title"
732          will be normalized and become the id. Valid characters are <code class="literal">a-Z</code>,
733          <code class="literal">A-Z</code>, <code class="literal">0-9</code> and <code class="literal">_</code>.
734          All non-valid characters are converted to underscore and all upper-case
735          are converted to lower case. Thus: "The Section Title" will be
736          normalized to "the_section_title".
737        </p>
738<p>
739          End a section with:
740        </p>
741<pre class="programlisting">[endsect]
742</pre>
743<p>
744          Sections can nest, and that results in a hierarchy in the table of contents.
745        </p>
746</div>
747<div class="section" lang="en">
748<div class="titlepage"><div><div><h4 class="title">
749<a name="quickbook.syntax.block.xinclude"></a>xinclude</h4></div></div></div>
750<p>
751          You can include another XML file with:
752        </p>
753<pre class="programlisting">[xinclude file.xml]
754</pre>
755<p>
756          This is useful when file.xml has been generated by Doxygen and contains
757          your reference section.
758        </p>
759</div>
760<div class="section" lang="en">
761<div class="titlepage"><div><div><h4 class="title">
762<a name="quickbook.syntax.block.paragraphs"></a>Paragraphs</h4></div></div></div>
763<p>
764          Paragraphs start left-flushed and are terminated by two or more newlines.
765          No markup is needed for paragraphs. QuickBook automatically detects paragraphs
766          from the context. Block markups [section, endsect, h1, h2, h3, h4, h5,
767          h6, blurb, (block-quote) ':', pre, def, table and include ] may also terminate
768          a paragraph.
769        </p>
770</div>
771<div class="section" lang="en">
772<div class="titlepage"><div><div><h4 class="title">
773<a name="quickbook.syntax.block.lists"></a>Lists</h4></div></div></div>
774<div class="toc"><dl>
775<dt><span class="section"><a href="syntax.html#quickbook.syntax.block.lists.ordered_lists">Ordered lists</a></span></dt>
776<dt><span class="section"><a href="syntax.html#quickbook.syntax.block.lists.list_hierarchies">List Hierarchies</a></span></dt>
777<dt><span class="section"><a href="syntax.html#quickbook.syntax.block.lists.long_list_lines">Long List Lines</a></span></dt>
778<dt><span class="section"><a href="syntax.html#quickbook.syntax.block.lists.unordered_lists">Unordered lists</a></span></dt>
779<dt><span class="section"><a href="syntax.html#quickbook.syntax.block.lists.mixed_lists">Mixed lists</a></span></dt>
780</dl></div>
781<div class="section" lang="en">
782<div class="titlepage"><div><div><h5 class="title">
783<a name="quickbook.syntax.block.lists.ordered_lists"></a>Ordered lists</h5></div></div></div>
784<pre class="programlisting"># One
785# Two
786# Three
787</pre>
788<p>
789            will generate:
790          </p>
791<div class="orderedlist"><ol type="1">
792<li>
793              One
794            </li>
795<li>
796              Two
797            </li>
798<li>
799              Three
800            </li>
801</ol></div>
802</div>
803<div class="section" lang="en">
804<div class="titlepage"><div><div><h5 class="title">
805<a name="quickbook.syntax.block.lists.list_hierarchies"></a>List Hierarchies</h5></div></div></div>
806<p>
807            List hierarchies are supported. Example:
808          </p>
809<pre class="programlisting"># One
810# Two
811# Three
812    # Three.a
813    # Three.b
814    # Three.c
815# Four
816    # Four.a
817        # Four.a.i
818        # Four.a.ii
819# Five
820</pre>
821<p>
822            will generate:
823          </p>
824<div class="orderedlist"><ol type="1">
825<li>
826              One
827            </li>
828<li>
829              Two
830            </li>
831<li>
832              Three
833              <div class="orderedlist"><ol type="a">
834<li>
835                  Three.a
836                </li>
837<li>
838                  Three.b
839                </li>
840<li>
841                  Three.c
842                </li>
843</ol></div>
844</li>
845<li>
846              Fourth
847              <div class="orderedlist"><ol type="a"><li>
848                  Four.a
849                  <div class="orderedlist"><ol type="i">
850<li>
851                      Four.a.i
852                    </li>
853<li>
854                      Four.a.ii
855                    </li>
856</ol></div>
857</li></ol></div>
858</li>
859<li>
860              Five
861            </li>
862</ol></div>
863</div>
864<div class="section" lang="en">
865<div class="titlepage"><div><div><h5 class="title">
866<a name="quickbook.syntax.block.lists.long_list_lines"></a>Long List Lines</h5></div></div></div>
867<p>
868            Long lines will be wrapped appropriately. Example:
869          </p>
870<pre class="programlisting"># A short item.
871# A very long item. A very long item. A very long item.
872  A very long item. A very long item. A very long item.
873  A very long item. A very long item. A very long item.
874  A very long item. A very long item. A very long item.
875  A very long item. A very long item. A very long item.
876# A short item.
877</pre>
878<div class="orderedlist"><ol type="1">
879<li>
880              A short item.
881            </li>
882<li>
883              A very long item. A very long item. A very long item. A very long item.
884              A very long item. A very long item. A very long item. A very long item.
885              A very long item. A very long item. A very long item. A very long item.
886              A very long item. A very long item. A very long item.
887            </li>
888<li>
889              A short item.
890            </li>
891</ol></div>
892</div>
893<div class="section" lang="en">
894<div class="titlepage"><div><div><h5 class="title">
895<a name="quickbook.syntax.block.lists.unordered_lists"></a>Unordered lists</h5></div></div></div>
896<pre class="programlisting">* First
897* Second
898* Third
899</pre>
900<p>
901            will generate:
902          </p>
903<div class="itemizedlist"><ul type="disc">
904<li>
905              First
906            </li>
907<li>
908              Second
909            </li>
910<li>
911              Third
912            </li>
913</ul></div>
914</div>
915<div class="section" lang="en">
916<div class="titlepage"><div><div><h5 class="title">
917<a name="quickbook.syntax.block.lists.mixed_lists"></a>Mixed lists</h5></div></div></div>
918<p>
919            Mixed lists (ordered and unordered) are supported. Example:
920          </p>
921<pre class="programlisting"># One
922# Two
923# Three
924    * Three.a
925    * Three.b
926    * Three.c
927# Four
928</pre>
929<p>
930            will generate:
931          </p>
932<div class="orderedlist"><ol type="1">
933<li>
934              One
935            </li>
936<li>
937              Two
938            </li>
939<li>
940              Three
941              <div class="itemizedlist"><ul type="disc">
942<li>
943                  Three.a
944                </li>
945<li>
946                  Three.b
947                </li>
948<li>
949                  Three.c
950                </li>
951</ul></div>
952</li>
953<li>
954              Four
955            </li>
956</ol></div>
957<p>
958            And...
959          </p>
960<pre class="programlisting"># 1
961    * 1.a
962        # 1.a.1
963        # 1.a.2
964    * 1.b
965# 2
966    * 2.a
967    * 2.b
968        # 2.b.1
969        # 2.b.2
970            * 2.b.2.a
971            * 2.b.2.b
972</pre>
973<p>
974            will generate:
975          </p>
976<div class="orderedlist"><ol type="1">
977<li>
978              1
979              <div class="itemizedlist"><ul type="disc">
980<li>
981                  1.a
982                  <div class="orderedlist"><ol type="a">
983<li>
984                      1.a.1
985                    </li>
986<li>
987                      1.a.2
988                    </li>
989</ol></div>
990</li>
991<li>
992                  1.b
993                </li>
994</ul></div>
995</li>
996<li>
997              2
998              <div class="itemizedlist"><ul type="disc">
999<li>
1000                  2.a
1001                </li>
1002<li>
1003                  2.b
1004                  <div class="orderedlist"><ol type="a">
1005<li>
1006                      2.b.1
1007                    </li>
1008<li>
1009                      2.b.2
1010                      <div class="itemizedlist"><ul type="circle">
1011<li>
1012                          2.b.2.a
1013                        </li>
1014<li>
1015                          2.b.2.b
1016                        </li>
1017</ul></div>
1018</li>
1019</ol></div>
1020</li>
1021</ul></div>
1022</li>
1023</ol></div>
1024</div>
1025</div>
1026<div class="section" lang="en">
1027<div class="titlepage"><div><div><h4 class="title">
1028<a name="quickbook.syntax.block.code"></a>Code</h4></div></div></div>
1029<p>
1030          Preformatted code starts with a space or a tab. The code will be syntax
1031          highlighted according to the current <a href="syntax.html#quickbook.syntax.phrase.source_mode" title="Source Mode">Source
1032          Mode</a>:
1033        </p>
1034<p>
1035        </p>
1036<pre class="programlisting">
1037<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
1038
1039<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
1040<span class="special">{</span>
1041    <span class="comment">// Sample code
1042</span>    <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Hello, World\n"</span><span class="special">;</span>
1043    <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
1044<span class="special">}</span>
1045</pre>
1046<p>
1047        </p>
1048<pre class="programlisting">
1049<span class="keyword">import</span> <span class="identifier">cgi</span>
1050
1051<span class="keyword">def</span> <span class="identifier">cookForHtml</span><span class="special">(</span><span class="identifier">text</span><span class="special">):</span>
1052    <span class="string">'''"Cooks" the input text for HTML.'''</span>
1053
1054    <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>
1055</pre>
1056<p>
1057          Macros that are already defined are expanded in source code. Example:
1058        </p>
1059<pre class="programlisting">[def __array__ [@http://www.boost.org/doc/html/array/reference.html array]]
1060[def __boost__ [@http://www.boost.org/libs/libraries.htm boost]]
1061
1062    using __boost__::__array__;
1063</pre>
1064<p>
1065          Generates:
1066        </p>
1067<pre class="programlisting">
1068<span class="identifier">using</span> <a href="http://www.boost.org/libs/libraries.htm" target="_top">boost</a><span class="special">::</span><a href="http://www.boost.org/doc/html/array/reference.html" target="_top">array</a><span class="special">;</span>
1069</pre>
1070</div>
1071<div class="section" lang="en">
1072<div class="titlepage"><div><div><h4 class="title">
1073<a name="quickbook.syntax.block.escape_back"></a> Escaping Back To QuickBook</h4></div></div></div>
1074<p>
1075          Inside code, code blocks and inline code, QuickBook does not allow any
1076          markup to avoid conflicts with the target syntax (e.g. c++). In case you
1077          need to switch back to QuickBook markup inside code, you can do so using
1078          a language specific <span class="emphasis"><em>escape-back</em></span> delimiter. In C++
1079          and Python, the delimiter is the double tick (back-quote): "``"
1080          and "``". Example:
1081        </p>
1082<pre class="programlisting">void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``()
1083{
1084}
1085</pre>
1086<p>
1087          Will generate:
1088        </p>
1089<pre class="programlisting">
1090<span class="identifier">void</span> <a href="http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz" target="_top">foo</a><span class="special">()</span>
1091<span class="special">{</span>
1092<span class="special">}</span>
1093</pre>
1094<p>
1095          When escaping from code to QuickBook, only phrase level markups are allowed.
1096          Block level markups like lists, tables etc. are not allowed.
1097        </p>
1098</div>
1099<div class="section" lang="en">
1100<div class="titlepage"><div><div><h4 class="title">
1101<a name="quickbook.syntax.block.preformatted"></a>Preformatted</h4></div></div></div>
1102<p>
1103          Sometimes, you don't want some preformatted text to be parsed as C++. In
1104          such cases, use the <code class="literal">[pre ... ]</code> markup block.
1105        </p>
1106<pre class="programlisting">[pre
1107
1108    Some *preformatted* text                    Some *preformatted* text
1109
1110        Some *preformatted* text            Some *preformatted* text
1111
1112            Some *preformatted* text    Some *preformatted* text
1113
1114]
1115</pre>
1116<p>
1117          Spaces, tabs and newlines are rendered as-is. Unlike all quickbook block
1118          level markup, pre (and Code) are the only ones that allow multiple newlines.
1119          The markup above will generate:
1120        </p>
1121<pre class="programlisting">Some <span class="bold"><strong>preformatted</strong></span> text                    Some <span class="bold"><strong>preformatted</strong></span> text
1122
1123    Some <span class="bold"><strong>preformatted</strong></span> text            Some <span class="bold"><strong>preformatted</strong></span> text
1124
1125        Some <span class="bold"><strong>preformatted</strong></span> text    Some <span class="bold"><strong>preformatted</strong></span> text
1126
1127</pre>
1128<p>
1129          Notice that unlike Code, phrase markup such as font style is still permitted
1130          inside <code class="literal">pre</code> blocks.
1131        </p>
1132</div>
1133<div class="section" lang="en">
1134<div class="titlepage"><div><div><h4 class="title">
1135<a name="quickbook.syntax.block.blockquote"></a>Blockquote</h4></div></div></div>
1136<pre class="programlisting">[:sometext...]
1137</pre>
1138<div class="blockquote"><blockquote class="blockquote"><p>
1139            Indents the paragraph. This applies to one paragraph only.
1140          </p></blockquote></div>
1141</div>
1142<div class="section" lang="en">
1143<div class="titlepage"><div><div><h4 class="title">
1144<a name="quickbook.syntax.block.admonitions"></a>Admonitions</h4></div></div></div>
1145<pre class="programlisting">[note This is a note]
1146[tip This is a tip]
1147[important This is important]
1148[caution This is a caution]
1149[warning This is a warning]
1150</pre>
1151<p>
1152          generates <a href="http://www.docbook.org/" target="_top">DocBook</a> admonitions:
1153        </p>
1154<div class="note"><table border="0" summary="Note">
1155<tr>
1156<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
1157<th align="left">Note</th>
1158</tr>
1159<tr><td align="left" valign="top"><p>
1160            This is a note
1161          </p></td></tr>
1162</table></div>
1163<div class="tip"><table border="0" summary="Tip">
1164<tr>
1165<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../images/tip.png"></td>
1166<th align="left">Tip</th>
1167</tr>
1168<tr><td align="left" valign="top"><p>
1169            This is a tip
1170          </p></td></tr>
1171</table></div>
1172<div class="important"><table border="0" summary="Important">
1173<tr>
1174<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../images/important.png"></td>
1175<th align="left">Important</th>
1176</tr>
1177<tr><td align="left" valign="top"><p>
1178            This is important
1179          </p></td></tr>
1180</table></div>
1181<div class="caution"><table border="0" summary="Caution">
1182<tr>
1183<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../images/caution.png"></td>
1184<th align="left">Caution</th>
1185</tr>
1186<tr><td align="left" valign="top"><p>
1187            This is a caution
1188          </p></td></tr>
1189</table></div>
1190<div class="warning"><table border="0" summary="Warning">
1191<tr>
1192<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../images/warning.png"></td>
1193<th align="left">Warning</th>
1194</tr>
1195<tr><td align="left" valign="top"><p>
1196            This is a warning
1197          </p></td></tr>
1198</table></div>
1199<p>
1200          These are the only admonitions supported by <a href="http://www.docbook.org/" target="_top">DocBook</a>.
1201          So, for example <code class="literal">[information This is some information]</code>
1202          is unlikely to produce the desired effect.
1203        </p>
1204</div>
1205<div class="section" lang="en">
1206<div class="titlepage"><div><div><h4 class="title">
1207<a name="quickbook.syntax.block.headings"></a>Headings</h4></div></div></div>
1208<pre class="programlisting">[h1 Heading 1]
1209[h2 Heading 2]
1210[h3 Heading 3]
1211[h4 Heading 4]
1212[h5 Heading 5]
1213[h6 Heading 6]
1214</pre>
1215<a name="quickbook.syntax.block.headings.heading_1"></a><h1>
1216<a name="id2089682"></a>
1217          Heading 1
1218        </h1>
1219<a name="quickbook.syntax.block.headings.heading_2"></a><h2>
1220<a name="id2089694"></a>
1221          Heading 2
1222        </h2>
1223<a name="quickbook.syntax.block.headings.heading_3"></a><h3>
1224<a name="id2089707"></a>
1225          Heading 3
1226        </h3>
1227<a name="quickbook.syntax.block.headings.heading_4"></a><h4>
1228<a name="id2089720"></a>
1229          Heading 4
1230        </h4>
1231<a name="quickbook.syntax.block.headings.heading_5"></a><h5>
1232<a name="id2089733"></a>
1233          Heading 5
1234        </h5>
1235<a name="quickbook.syntax.block.headings.heading_6"></a><h5>
1236<a name="id2089745"></a>
1237          Heading 6
1238        </h5>
1239<p>
1240          Headings 1-3 [h1 h2 and h3] will automatically have anchors with normalized
1241          names with <code class="literal">name="section_id.normalized_header_text"</code>
1242          (i.e. valid characters are <code class="literal">a-z</code>, <code class="literal">A-Z</code>,
1243          <code class="literal">0-9</code> and <code class="literal">_</code>. All non-valid characters
1244          are converted to underscore and all upper-case are converted to lower-case.
1245          For example: Heading 1 in section Section 2 will be normalized to <code class="literal">section_2.heading_1</code>).
1246          You can use:
1247        </p>
1248<pre class="programlisting">[link section_id.normalized_header_text The link text]
1249</pre>
1250<p>
1251          to link to them. See <a href="syntax.html#quickbook.syntax.phrase.anchor_links" title="Anchor links">Anchor
1252          links</a> and <a href="syntax.html#quickbook.syntax.block.section" title="Section">Section</a>
1253          for more info.
1254        </p>
1255</div>
1256<div class="section" lang="en">
1257<div class="titlepage"><div><div><h4 class="title">
1258<a name="quickbook.syntax.block.macros"></a>Macros</h4></div></div></div>
1259<pre class="programlisting">[def macro_identifier some text]
1260</pre>
1261<p>
1262          When a macro is defined, the identifier replaces the text anywhere in the
1263          file, in paragraphs, in markups, etc. macro_identifier is a string of non-white
1264          space characters except ']' while the replacement text can be any phrase
1265          (even marked up). Example:
1266        </p>
1267<pre class="programlisting">[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&amp;type=1]]
1268sf_logo
1269</pre>
1270<p>
1271          Now everywhere the sf_logo is placed, the picture will be inlined.
1272        </p>
1273<p>
1274          <span class="inlinemediaobject"></span>
1275        </p>
1276<div class="informaltable"><table class="table">
1277<colgroup><col></colgroup>
1278<tbody><tr><td class="blurb"> <span class="inlinemediaobject"><img src="../images/tip.png" alt="tip"></span> It's a good idea to use macro identifiers that
1279                are distinguishable. For instance, in this document, macro identifiers
1280                have two leading and trailing underscores (e.g. <code class="literal">
1281__spirit__
1282                </code>). The reason is to avoid unwanted macro replacement.</td></tr></tbody>
1283</table></div>
1284<p>
1285          Links (URLS) and images are good candidates for macros. <span class="bold"><strong>1</strong></span>)
1286          They tend to change a lot. It is a good idea to place all links and images
1287          in one place near the top to make it easy to make changes. <span class="bold"><strong>2</strong></span>)
1288          The syntax is not pretty. It's easier to read and write, e.g. <code class="literal">
1289__spirit__
1290          </code> than <code class="literal">
1291[@http://spirit.sourceforge.net Spirit]
1292          </code>.
1293        </p>
1294<p>
1295          Some more examples:
1296        </p>
1297<pre class="programlisting">[def :-)            [$theme/smiley.png]]
1298[def __spirit__     [@http://spirit.sourceforge.net Spirit]]
1299</pre>
1300<p>
1301          (See <a href="syntax.html#quickbook.syntax.phrase.images" title="Images">Images</a> and
1302          <a href="syntax.html#quickbook.syntax.phrase.links" title="Links">Links</a>)
1303        </p>
1304<p>
1305          Invoking these macros:
1306        </p>
1307<pre class="programlisting">Hi __spirit__  :-)
1308</pre>
1309<p>
1310          will generate this:
1311        </p>
1312<p>
1313          Hi <a href="http://spirit.sourceforge.net" target="_top">Spirit</a> <span class="inlinemediaobject"><img src="../images/smiley.png" alt="smiley"></span>
1314        </p>
1315</div>
1316<div class="section" lang="en">
1317<div class="titlepage"><div><div><h4 class="title">
1318<a name="quickbook.syntax.block.predefined_macros"></a>Predefined Macros</h4></div></div></div>
1319<p>
1320          Quickbook has some predefined macros that you can already use.
1321        </p>
1322<div class="informaltable">
1323<h4>
1324<a name="id2090046"></a>
1325            <span class="table-title">Predefined Macros</span>
1326          </h4>
1327<table class="table">
1328<colgroup>
1329<col>
1330<col>
1331<col>
1332</colgroup>
1333<thead><tr>
1334<th>Macro</th>
1335<th>Meaning</th>
1336<th>Example</th>
1337</tr></thead>
1338<tbody>
1339<tr>
1340<td>
1341__DATE__
1342                </td>
1343<td>Today's date</td>
1344<td>2007-Jul-16</td>
1345</tr>
1346<tr>
1347<td>
1348__TIME__
1349                </td>
1350<td>The current time</td>
1351<td>01:52:26 PM</td>
1352</tr>
1353<tr>
1354<td>
1355__FILENAME__
1356                </td>
1357<td>Quickbook source filename</td>
1358<td>/Users/witt/Documents/Project/BoostRelease/doc/boost/doc/../tools/quickbook/doc/quickbook.qbk</td>
1359</tr>
1360</tbody>
1361</table>
1362</div>
1363</div>
1364<div class="section" lang="en">
1365<div class="titlepage"><div><div><h4 class="title">
1366<a name="quickbook.syntax.block.blurbs"></a>Blurbs</h4></div></div></div>
1367<pre class="programlisting">[blurb :-) [*An eye catching advertisement or note...]\n\n
1368    __spirit__ is an object-oriented recursive-descent parser generator framework
1369    implemented using template meta-programming techniques. Expression templates
1370    allow us to approximate the syntax of Extended Backus-Normal Form (EBNF)
1371    completely in C++.
1372]
1373</pre>
1374<p>
1375          will generate this:
1376        </p>
1377<div class="informaltable"><table class="table">
1378<colgroup><col></colgroup>
1379<tbody><tr><td class="blurb"> <span class="inlinemediaobject"><img src="../images/smiley.png" alt="smiley"></span> <span class="bold"><strong>An eye catching advertisement
1380                or note...</strong></span><br> <br> <a href="http://spirit.sourceforge.net" target="_top">Spirit</a>
1381                is an object-oriented recursive-descent parser generator framework
1382                implemented using template meta-programming techniques. Expression
1383                templates allow us to approximate the syntax of Extended Backus-Normal
1384                Form (EBNF) completely in C++. </td></tr></tbody>
1385</table></div>
1386</div>
1387<div class="section" lang="en">
1388<div class="titlepage"><div><div><h4 class="title">
1389<a name="quickbook.syntax.block.tables"></a>Tables</h4></div></div></div>
1390<pre class="programlisting">[table A Simple Table
1391    [[Heading 1] [Heading 2] [Heading 3]]
1392    [[R0-C0]     [R0-C1]     [R0-C2]]
1393    [[R1-C0]     [R1-C1]     [R1-C2]]
1394    [[R2-C0]     [R2-C1]     [R2-C2]]
1395]
1396</pre>
1397<p>
1398          will generate:
1399        </p>
1400<div class="informaltable">
1401<h4>
1402<a name="id2090229"></a>
1403            <span class="table-title">A Simple Table</span>
1404          </h4>
1405<table class="table">
1406<colgroup>
1407<col>
1408<col>
1409<col>
1410</colgroup>
1411<thead><tr>
1412<th>Heading 1</th>
1413<th>Heading 2</th>
1414<th>Heading 3</th>
1415</tr></thead>
1416<tbody>
1417<tr>
1418<td>R0-C0</td>
1419<td>R0-C1</td>
1420<td>R0-C2</td>
1421</tr>
1422<tr>
1423<td>R2-C0</td>
1424<td>R2-C1</td>
1425<td>R2-C2</td>
1426</tr>
1427<tr>
1428<td>R3-C0</td>
1429<td>R3-C1</td>
1430<td>R3-C2</td>
1431</tr>
1432</tbody>
1433</table>
1434</div>
1435<p>
1436          The table title is optional. The first row of the table is automatically
1437          treated as the table header; that is, it is wrapped in <code class="literal">&lt;thead&gt;...&lt;/thead&gt;</code>
1438          XML tags. Note that unlike the original QuickDoc, the columns are nested
1439          in [ cells... ]. The syntax is free-format and allows big cells to be formatted
1440          nicely. Example:
1441        </p>
1442<pre class="programlisting">[table Table with fat cells
1443    [[Heading 1] [Heading 2]]
1444    [
1445        [Row 0, Col 0: a small cell]
1446        [
1447            Row 0, Col 1:
1448            A very big cell...A very big cell...A very big cell...
1449            A very big cell...A very big cell...A very big cell...
1450            A very big cell...A very big cell...A very big cell...
1451        ]
1452    ]
1453    [
1454        [Row 1, Col 0: a small cell]
1455        [Row 1, Col 1: a small cell]
1456    ]
1457]
1458</pre>
1459<p>
1460          and thus:
1461        </p>
1462<div class="informaltable">
1463<h4>
1464<a name="id2090334"></a>
1465            <span class="table-title">Table with fat cells</span>
1466          </h4>
1467<table class="table">
1468<colgroup>
1469<col>
1470<col>
1471</colgroup>
1472<thead><tr>
1473<th>Heading 1</th>
1474<th>Heading 2</th>
1475</tr></thead>
1476<tbody>
1477<tr>
1478<td>Row 0, Col 0: a small cell</td>
1479<td> Row 0, Col 1: A
1480                very big cell...A very big cell...A very big cell... A very big cell...A
1481                very big cell...A very big cell... A very big cell...A very big cell...A
1482                very big cell... </td>
1483</tr>
1484<tr>
1485<td>Row 1, Col 0: a small cell</td>
1486<td>Row 1, Col 1: a small
1487                cell</td>
1488</tr>
1489</tbody>
1490</table>
1491</div>
1492<p>
1493          Here's how to have preformatted blocks of code in a table cell:
1494        </p>
1495<pre class="programlisting">[table Table with code
1496    [[Comment] [Code]]
1497    [
1498        [My first program]
1499        [``
1500            #include &lt;iostream&gt;
1501
1502            int main()
1503            {
1504                std::cout &lt;&lt; "Hello, World!" &lt;&lt; std::endl;
1505                return 0;
1506            }
1507        ``]
1508    ]
1509]
1510</pre>
1511<div class="informaltable">
1512<h4>
1513<a name="id2090408"></a>
1514            <span class="table-title">Table with code</span>
1515          </h4>
1516<table class="table">
1517<colgroup>
1518<col>
1519<col>
1520</colgroup>
1521<thead><tr>
1522<th>Comment</th>
1523<th>Code</th>
1524</tr></thead>
1525<tbody><tr>
1526<td>My first program</td>
1527<td>
1528<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">
1529<span class="comment">#include &lt;iostream&gt;
1530</span>
1531<span class="identifier">int</span> <span class="identifier">main</span><span class="special">()</span>
1532<span class="special">{</span>
1533    <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Hello, World!"</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>
1534    <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
1535<span class="special">}</span>
1536</pre>
1537                </td>
1538</tr></tbody>
1539</table>
1540</div>
1541</div>
1542<div class="section" lang="en">
1543<div class="titlepage"><div><div><h4 class="title">
1544<a name="quickbook.syntax.block.variable_lists"></a>Variable Lists</h4></div></div></div>
1545<pre class="programlisting">[variablelist A Variable List
1546    [[term 1] [The definition of term 1]]
1547    [[term 2] [The definition of term 2]]
1548    [[term 3] [The definition of term 3]]
1549]
1550</pre>
1551<p>
1552          will generate:
1553        </p>
1554<div class="variablelist">
1555<p class="title"><b>A Variable List</b></p>
1556<dl>
1557<dt><span class="term">term 1</span></dt>
1558<dd>
1559            The definition of term 1
1560          </dd>
1561<dt><span class="term">term 2</span></dt>
1562<dd>
1563            The definition of term 2
1564          </dd>
1565<dt><span class="term">term 3</span></dt>
1566<dd>
1567            The definition of term 3
1568          </dd>
1569</dl>
1570</div>
1571<p>
1572          The rules for variable lists are the same as for tables, except that only
1573          2 "columns" are allowed. The first column contains the terms,
1574          and the second column contains the definitions. Those familiar with HTML
1575          will recognize this as a "definition list".
1576        </p>
1577</div>
1578<div class="section" lang="en">
1579<div class="titlepage"><div><div><h4 class="title">
1580<a name="quickbook.syntax.block.include"></a>Include</h4></div></div></div>
1581<p>
1582          You can include one QuickBook file from another. The syntax is simply:
1583        </p>
1584<pre class="programlisting">[include someother.qbk]
1585</pre>
1586<p>
1587          The included file will be processed as if it had be cut and pasted into
1588          the current document, with the following exceptions:
1589        </p>
1590<div class="itemizedlist"><ul type="disc">
1591<li>
1592            The
1593__FILENAME__
1594            predefined macro will reflect the name of the file currently being processed.
1595          </li>
1596<li>
1597            Any macros defined in the included file are scoped to that file.
1598          </li>
1599</ul></div>
1600<p>
1601          As the number of included QuickBook files grows, so too does the likelihood
1602          of two sections having the same name. Since QuickBook generates an anchor
1603          for each section based on the section name, it is possible to end up with
1604          two identically named anchors, leading to link ambiguities. To resolve
1605          these ambiguities, the <code class="literal">[include]</code> directive lets you
1606          specify a document id to use for the included file. You can use it like
1607          this:
1608        </p>
1609<pre class="programlisting">[include:someid someother.qbk]
1610</pre>
1611<p>
1612          When using this form, all auto-generated anchors will use "someid"
1613          as a unique prefix. So for instance, if there is a section in someother.qbk
1614          named "Intro", the named anchor for that section will be "someid.intro",
1615          and you can link to it with <code class="literal">[link someid.intro The Intro]</code>.
1616        </p>
1617</div>
1618</div>
1619<div class="footnotes">
1620<br><hr width="100" align="left">
1621<div class="footnote"><p><sup>[<a name="ftn.id2088405" href="#id2088405">2</a>] </sup>
1622              A sample footnote
1623            </p></div>
1624</div>
1625</div>
1626<table width="100%"><tr>
1627<td align="left"></td>
1628<td align="right"><small>Copyright © 2002, 2004 Joel de Guzman, Eric Niebler</small></td>
1629</tr></table>
1630<hr>
1631<div class="spirit-nav">
1632<a accesskey="p" href="change_log.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../quickbook.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="ref.html"><img src="../images/next.png" alt="Next"></a>
1633</div>
1634</body>
1635</html>
Note: See TracBrowser for help on using the repository browser.