doc/html/quickbook/syntax/block.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   5 <title>Block Level Elements</title>
   6 <link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css">
   7 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   8 <link rel="home" href="../../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
   9 <link rel="up" href="../../quickbook.html" title="Chapter&#160;50.&#160;Quickbook 1.7">
  10 <link rel="prev" href="phrase.html" title="Phrase Level Elements">
  11 <link rel="next" href="../versions.html" title="Language Versions">
  12 </head>
  13 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  14 <table cellpadding="2" width="100%"><tr>
  15 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td>
  16 <td align="center"><a href="../../../../index.html">Home</a></td>
  17 <td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  19 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  20 <td align="center"><a href="../../../../more/index.htm">More</a></td>
  21 </tr></table>
  22 <hr>
  23 <div class="spirit-nav">
  24 <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>
  25 </div>
  26 <div class="section">
  27 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  28 <a name="quickbook.syntax.block"></a>Block Level Elements</h2></div></div></div>
  29 <div class="toc"><dl class="toc">
  30 <dt><span class="section"><a href="block.html#quickbook.syntax.block.xinclude">xinclude</a></span></dt>
  31 <dt><span class="section"><a href="block.html#quickbook.syntax.block.paragraphs">Paragraphs</a></span></dt>
  32 <dt><span class="section"><a href="block.html#quickbook.syntax.block.lists">Lists</a></span></dt>
  33 <dt><span class="section"><a href="block.html#quickbook.syntax.block.code">Code</a></span></dt>
  34 <dt><span class="section"><a href="block.html#quickbook.syntax.block.escape_back">Escaping
  35       Back To QuickBook</a></span></dt>
  36 <dt><span class="section"><a href="block.html#quickbook.syntax.block.preformatted">Preformatted</a></span></dt>
  37 <dt><span class="section"><a href="block.html#quickbook.syntax.block.blockquote">Blockquote</a></span></dt>
  38 <dt><span class="section"><a href="block.html#quickbook.syntax.block.admonitions">Admonitions</a></span></dt>
  39 <dt><span class="section"><a href="block.html#quickbook.syntax.block.headings">Headings</a></span></dt>
  40 <dt><span class="section"><a href="block.html#quickbook.syntax.block.generic_heading">Generic
  41       Heading</a></span></dt>
  42 <dt><span class="section"><a href="block.html#quickbook.syntax.block.macros">Macros</a></span></dt>
  43 <dt><span class="section"><a href="block.html#quickbook.syntax.block.predefined_macros">Predefined
  44       Macros</a></span></dt>
  45 <dt><span class="section"><a href="block.html#quickbook.syntax.block.templates">Templates</a></span></dt>
  46 <dt><span class="section"><a href="block.html#quickbook.syntax.block.blurbs">Blurbs</a></span></dt>
  47 <dt><span class="section"><a href="block.html#quickbook.syntax.block.tables">Tables</a></span></dt>
  48 <dt><span class="section"><a href="block.html#quickbook.syntax.block.variable_lists">Variable
  49       Lists</a></span></dt>
  50 <dt><span class="section"><a href="block.html#quickbook.syntax.block.include">Include</a></span></dt>
  51 <dt><span class="section"><a href="block.html#quickbook.syntax.block.import">Import</a></span></dt>
  52 <dt><span class="section"><a href="block.html#quickbook.syntax.block.block">Plain
  53       blocks</a></span></dt>
  54 </dl></div>
  55 <div class="section">
  56 <div class="titlepage"><div><div><h3 class="title">
  57 <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>
  58 </h3></div></div></div>
  59 <p>
  60         You can include another XML file with:
  61       </p>
  62 <pre class="programlisting">[xinclude file.xml]
  63 </pre>
  64 <p>
  65         This is useful when file.xml has been generated by Doxygen and contains your
  66         reference section.
  67       </p>
  68 <p>
  69         <code class="literal">xinclude</code> paths are normally used unchanged in the generated
  70         documentation, which will not work if you wish them to be relative to the
  71         current quickbook file. Quickbook can add a <code class="literal">xml:base</code> attribute
  72         to the boostbook documentation to specify where <code class="literal">xinclude</code>
  73         files should be found. For example, if you wish them to be relative to the
  74         current quickbook file:
  75       </p>
  76 <pre class="programlisting">[article Article with xincludes
  77 [quickbook 1.7]
  78 [xmlbase .]
  79 ]
  80
  81 [xinclude file.xml]
  82 </pre>
  83 <p>
  84         Now the xinclude should work if <code class="literal">file.xml</code> is in the same
  85         directory as the quickbook file. Although it might not work if you distribute
  86         the generated files (as their relative directories can change).
  87       </p>
  88 <p>
  89         Say the article is generated in a sub-directory, by running something like:
  90       </p>
  91 <pre class="programlisting">quickbook article.qbk --output-file=output/article.xml
  92 </pre>
  93 <p>
  94         This will generate a boostbook root tag:
  95       </p>
  96 <pre class="programlisting">&lt;article id="article_with_xincludes"
  97     last-revision="$Date: 2013/08/20 08:26:48 $"
  98     xml:base=".."
  99     xmlns:xi="http://www.w3.org/2001/XInclude"&gt;
 100 </pre>
 101 <p>
 102         Because <code class="literal">xml:base</code> is set to <code class="literal">..</code>, the
 103         xml processor will know to look in the parent directory to find <code class="literal">file.xml</code>,
 104         which it comes across the <code class="literal">xi:include</code> tag.
 105       </p>
 106 </div>
 107 <div class="section">
 108 <div class="titlepage"><div><div><h3 class="title">
 109 <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>
 110 </h3></div></div></div>
 111 <p>
 112         Paragraphs start left-flushed and are terminated by two or more newlines.
 113         No markup is needed for paragraphs. QuickBook automatically detects paragraphs
 114         from the context. Block markups [section, endsect, h1, h2, h3, h4, h5, h6,
 115         blurb, (block-quote) ':', pre, def, table and include ] may also terminate
 116         a paragraph. This is a new paragraph...
 117       </p>
 118 </div>
 119 <div class="section">
 120 <div class="titlepage"><div><div><h3 class="title">
 121 <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>
 122 </h3></div></div></div>
 123 <div class="toc"><dl class="toc">
 124 <dt><span class="section"><a href="block.html#quickbook.syntax.block.lists.ordered_lists">Ordered
 125         lists</a></span></dt>
 126 <dt><span class="section"><a href="block.html#quickbook.syntax.block.lists.list_hierarchies">List
 127         Hierarchies</a></span></dt>
 128 <dt><span class="section"><a href="block.html#quickbook.syntax.block.lists.long_list_lines">Long
 129         List Lines</a></span></dt>
 130 <dt><span class="section"><a href="block.html#quickbook.syntax.block.lists.unordered_lists">Unordered
 131         lists</a></span></dt>
 132 <dt><span class="section"><a href="block.html#quickbook.syntax.block.lists.mixed_lists">Mixed
 133         lists</a></span></dt>
 134 <dt><span class="section"><a href="block.html#quickbook.syntax.block.lists.list_paragraphs">Paragraphs
 135         in lists</a></span></dt>
 136 <dt><span class="section"><a href="block.html#quickbook.syntax.block.lists.list_tags">Explicit
 137         list tags</a></span></dt>
 138 </dl></div>
 139 <div class="section">
 140 <div class="titlepage"><div><div><h4 class="title">
 141 <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
 142         lists</a>
 143 </h4></div></div></div>
 144 <pre class="programlisting"># One
 145 # Two
 146 # Three
 147 </pre>
 148 <p>
 149           will generate:
 150         </p>
 151 <div class="orderedlist"><ol class="orderedlist" type="1">
 152 <li class="listitem">
 153               One
 154             </li>
 155 <li class="listitem">
 156               Two
 157             </li>
 158 <li class="listitem">
 159               Three
 160             </li>
 161 </ol></div>
 162 </div>
 163 <div class="section">
 164 <div class="titlepage"><div><div><h4 class="title">
 165 <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
 166         Hierarchies</a>
 167 </h4></div></div></div>
 168 <p>
 169           List hierarchies are supported. Example:
 170         </p>
 171 <pre class="programlisting"># One
 172 # Two
 173 # Three
 174     # Three.a
 175     # Three.b
 176     # Three.c
 177 # Four
 178     # Four.a
 179         # Four.a.i
 180         # Four.a.ii
 181 # Five
 182 </pre>
 183 <p>
 184           will generate:
 185         </p>
 186 <div class="orderedlist"><ol class="orderedlist" type="1">
 187 <li class="listitem">
 188               One
 189             </li>
 190 <li class="listitem">
 191               Two
 192             </li>
 193 <li class="listitem">
 194               Three
 195               <div class="orderedlist"><ol class="orderedlist" type="a">
 196 <li class="listitem">
 197                     Three.a
 198                   </li>
 199 <li class="listitem">
 200                     Three.b
 201                   </li>
 202 <li class="listitem">
 203                     Three.c
 204                   </li>
 205 </ol></div>
 206             </li>
 207 <li class="listitem">
 208               Fourth
 209               <div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem">
 210                     Four.a
 211                     <div class="orderedlist"><ol class="orderedlist" type="i">
 212 <li class="listitem">
 213                           Four.a.i
 214                         </li>
 215 <li class="listitem">
 216                           Four.a.ii
 217                         </li>
 218 </ol></div>
 219                   </li></ol></div>
 220             </li>
 221 <li class="listitem">
 222               Five
 223             </li>
 224 </ol></div>
 225 </div>
 226 <div class="section">
 227 <div class="titlepage"><div><div><h4 class="title">
 228 <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
 229         List Lines</a>
 230 </h4></div></div></div>
 231 <p>
 232           Long lines will be wrapped appropriately. Example:
 233         </p>
 234 <pre class="programlisting"># A short item.
 235 # A very long item. A very long item. A very long item.
 236   A very long item. A very long item. A very long item.
 237   A very long item. A very long item. A very long item.
 238   A very long item. A very long item. A very long item.
 239   A very long item. A very long item. A very long item.
 240 # A short item.
 241 </pre>
 242 <div class="orderedlist"><ol class="orderedlist" type="1">
 243 <li class="listitem">
 244               A short item.
 245             </li>
 246 <li class="listitem">
 247               A very long item. A very long item. A very long item. A very long item.
 248               A very long item. A very long item. A very long item. A very long item.
 249               A very long item. A very long item. A very long item. A very long item.
 250               A very long item. A very long item. A very long item.
 251             </li>
 252 <li class="listitem">
 253               A short item.
 254             </li>
 255 </ol></div>
 256 </div>
 257 <div class="section">
 258 <div class="titlepage"><div><div><h4 class="title">
 259 <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
 260         lists</a>
 261 </h4></div></div></div>
 262 <pre class="programlisting">* First
 263 * Second
 264 * Third
 265 </pre>
 266 <p>
 267           will generate:
 268         </p>
 269 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 270 <li class="listitem">
 271               First
 272             </li>
 273 <li class="listitem">
 274               Second
 275             </li>
 276 <li class="listitem">
 277               Third
 278             </li>
 279 </ul></div>
 280 </div>
 281 <div class="section">
 282 <div class="titlepage"><div><div><h4 class="title">
 283 <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
 284         lists</a>
 285 </h4></div></div></div>
 286 <p>
 287           Mixed lists (ordered and unordered) are supported. Example:
 288         </p>
 289 <pre class="programlisting"># One
 290 # Two
 291 # Three
 292     * Three.a
 293     * Three.b
 294     * Three.c
 295 # Four
 296 </pre>
 297 <p>
 298           will generate:
 299         </p>
 300 <div class="orderedlist"><ol class="orderedlist" type="1">
 301 <li class="listitem">
 302               One
 303             </li>
 304 <li class="listitem">
 305               Two
 306             </li>
 307 <li class="listitem">
 308               Three
 309               <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 310 <li class="listitem">
 311                     Three.a
 312                   </li>
 313 <li class="listitem">
 314                     Three.b
 315                   </li>
 316 <li class="listitem">
 317                     Three.c
 318                   </li>
 319 </ul></div>
 320             </li>
 321 <li class="listitem">
 322               Four
 323             </li>
 324 </ol></div>
 325 <p>
 326           And...
 327         </p>
 328 <pre class="programlisting"># 1
 329     * 1.a
 330         # 1.a.1
 331         # 1.a.2
 332     * 1.b
 333 # 2
 334     * 2.a
 335     * 2.b
 336         # 2.b.1
 337         # 2.b.2
 338             * 2.b.2.a
 339             * 2.b.2.b
 340 </pre>
 341 <p>
 342           will generate:
 343         </p>
 344 <div class="orderedlist"><ol class="orderedlist" type="1">
 345 <li class="listitem">
 346               1
 347               <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 348 <li class="listitem">
 349                     1.a
 350                     <div class="orderedlist"><ol class="orderedlist" type="a">
 351 <li class="listitem">
 352                           1.a.1
 353                         </li>
 354 <li class="listitem">
 355                           1.a.2
 356                         </li>
 357 </ol></div>
 358                   </li>
 359 <li class="listitem">
 360                     1.b
 361                   </li>
 362 </ul></div>
 363             </li>
 364 <li class="listitem">
 365               2
 366               <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 367 <li class="listitem">
 368                     2.a
 369                   </li>
 370 <li class="listitem">
 371                     2.b
 372                     <div class="orderedlist"><ol class="orderedlist" type="a">
 373 <li class="listitem">
 374                           2.b.1
 375                         </li>
 376 <li class="listitem">
 377                           2.b.2
 378                           <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; ">
 379 <li class="listitem">
 380                                 2.b.2.a
 381                               </li>
 382 <li class="listitem">
 383                                 2.b.2.b
 384                               </li>
 385 </ul></div>
 386                         </li>
 387 </ol></div>
 388                   </li>
 389 </ul></div>
 390             </li>
 391 </ol></div>
 392 </div>
 393 <div class="section">
 394 <div class="titlepage"><div><div><h4 class="title">
 395 <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
 396         in lists</a>
 397 </h4></div></div></div>
 398 <p>
 399           In quickbook 1.7 onwards, you can nest paragraphs in lists by separating
 400           them with blank lines:
 401         </p>
 402 <pre class="programlisting">* List item 1, paragraph 1
 403
 404   List item 1, paragraph 2
 405
 406 * List item 2, paragraph 1
 407
 408   List item 2, paragraph 2
 409 </pre>
 410 <p>
 411           will generate:
 412         </p>
 413 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 414 <li class="listitem">
 415 <p class="simpara">
 416               List item 1, paragraph 1
 417             </p>
 418 <p class="simpara">
 419               List item 1, paragraph 2
 420             </p>
 421 </li>
 422 <li class="listitem">
 423 <p class="simpara">
 424               List item 2, paragraph 1
 425             </p>
 426 <p class="simpara">
 427               List item 2, paragraph 2
 428             </p>
 429 </li>
 430 </ul></div>
 431 </div>
 432 <div class="section">
 433 <div class="titlepage"><div><div><h4 class="title">
 434 <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
 435         list tags</a>
 436 </h4></div></div></div>
 437 <p>
 438           Sometimes the wiki-style list markup can be tricky to use, especially if
 439           you wish to include more complicated markup with the list. So in quickbook
 440           1.6, an alternative way to mark up lists introduced:
 441         </p>
 442 <pre class="programlisting">[ordered_list [item1][item2]]
 443 </pre>
 444 <p>
 445           is equivalent to:
 446         </p>
 447 <pre class="programlisting"># item1
 448 # item2
 449 </pre>
 450 <p>
 451           And:
 452         </p>
 453 <pre class="programlisting">[itemized_list [item1][item2]]
 454 </pre>
 455 <p>
 456           is equivalent to:
 457         </p>
 458 <pre class="programlisting">* item1
 459 * item2
 460 </pre>
 461 </div>
 462 </div>
 463 <div class="section">
 464 <div class="titlepage"><div><div><h3 class="title">
 465 <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>
 466 </h3></div></div></div>
 467 <p>
 468         Preformatted code starts with a space or a tab. The code will be syntax highlighted
 469         according to the current <a class="link" href="phrase.html#quickbook.ref.source_mode">Source
 470         Mode</a>:
 471       </p>
 472 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
 473
 474 <span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
 475 <span class="special">{</span>
 476     <span class="comment">// Sample code</span>
 477     <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>
 478     <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
 479 <span class="special">}</span>
 480 </pre>
 481 <pre class="programlisting"><span class="keyword">import</span> <span class="identifier">cgi</span>
 482
 483 <span class="keyword">def</span> <span class="identifier">cookForHtml</span><span class="special">(</span><span class="identifier">text</span><span class="special">):</span>
 484     <span class="string">'''"Cooks" the input text for HTML.'''</span>
 485
 486     <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>
 487 </pre>
 488 <p>
 489         Macros that are already defined are expanded in source code. Example:
 490       </p>
 491 <pre class="programlisting">[def __array__ [@http://www.boost.org/doc/html/array/reference.html array]]
 492 [def __boost__ [@http://www.boost.org/libs/libraries.htm boost]]
 493
 494     using __boost__::__array__;
 495 </pre>
 496 <p>
 497         Generates:
 498       </p>
 499 <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>;
 500 </pre>
 501 <p>
 502         In quickbook 1.7 and later, you can include <a class="link" href="block.html#quickbook.ref.callouts">callouts</a>
 503         in code blocks, like so:
 504       </p>
 505 <pre class="programlisting">[!c++]
 506     std::string foo_bar() /*&lt; The /Mythical/ FooBar.
 507                           See [@http://en.wikipedia.org/wiki/Foobar Foobar for details] &gt;*/
 508     {
 509         return "foo-bar"; /*&lt; return 'em, foo-bar man! &gt;*/
 510     }
 511 </pre>
 512 <p>
 513         Which will generate:
 514       </p>
 515 <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>
 516 <span class="special">{</span>
 517     <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>
 518 <span class="special">}</span>
 519 </pre>
 520 <div class="calloutlist"><table border="0" summary="Callout list">
 521 <tr>
 522 <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>
 523 <td valign="top" align="left"><p>
 524             The <span class="emphasis"><em>Mythical</em></span> FooBar. See <a href="http://en.wikipedia.org/wiki/Foobar" target="_top">Foobar
 525             for details</a>
 526           </p></td>
 527 </tr>
 528 <tr>
 529 <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>
 530 <td valign="top" align="left"><p>
 531             return 'em, foo-bar man!
 532           </p></td>
 533 </tr>
 534 </table></div>
 535 </div>
 536 <div class="section">
 537 <div class="titlepage"><div><div><h3 class="title">
 538 <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
 539       Back To QuickBook</a>
 540 </h3></div></div></div>
 541 <p>
 542         Inside code, code blocks and inline code, QuickBook does not allow any markup
 543         to avoid conflicts with the target syntax (e.g. c++). In case you need to
 544         switch back to QuickBook markup inside code, you can do so using a language
 545         specific <span class="emphasis"><em>escape-back</em></span> delimiter. In C++ and Python, the
 546         delimiter is the double tick (back-quote): "``" and "``".
 547         Example:
 548       </p>
 549 <pre class="programlisting">void <a href="http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz" target="_top">foo</a>()
 550 {
 551 }
 552 </pre>
 553 <p>
 554         Will generate:
 555       </p>
 556 <pre class="programlisting">void <a href="http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz" target="_top">foo</a>()
 557 {
 558 }
 559 </pre>
 560 <p>
 561         When escaping from code to QuickBook, only phrase level markups are allowed.
 562         Block level markups like lists, tables etc. are not allowed.
 563       </p>
 564 </div>
 565 <div class="section">
 566 <div class="titlepage"><div><div><h3 class="title">
 567 <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>
 568 </h3></div></div></div>
 569 <p>
 570         Sometimes, you don't want some preformatted text to be parsed as source code.
 571         In such cases, use the <code class="literal">[pre ... ]</code> markup block.
 572       </p>
 573 <pre class="programlisting">[pre
 574
 575     Some *preformatted* text                    Some *preformatted* text
 576
 577         Some *preformatted* text            Some *preformatted* text
 578
 579             Some *preformatted* text    Some *preformatted* text
 580
 581 ]
 582 </pre>
 583 <p>
 584         Spaces, tabs and newlines are rendered as-is. Unlike all quickbook block
 585         level markup, pre (and Code) are the only ones that allow multiple newlines.
 586         The markup above will generate:
 587       </p>
 588 <pre class="programlisting">
 589 Some <span class="bold"><strong>preformatted</strong></span> text                    Some <span class="bold"><strong>preformatted</strong></span> text
 590
 591     Some <span class="bold"><strong>preformatted</strong></span> text            Some <span class="bold"><strong>preformatted</strong></span> text
 592
 593         Some <span class="bold"><strong>preformatted</strong></span> text    Some <span class="bold"><strong>preformatted</strong></span> text
 594
 595 </pre>
 596 <p>
 597         Notice that unlike Code, phrase markup such as font style is still permitted
 598         inside <code class="literal">pre</code> blocks.
 599       </p>
 600 </div>
 601 <div class="section">
 602 <div class="titlepage"><div><div><h3 class="title">
 603 <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>
 604 </h3></div></div></div>
 605 <pre class="programlisting">[:sometext...]
 606 </pre>
 607 <div class="blockquote"><blockquote class="blockquote"><p>
 608           Indents the paragraph. This applies to one paragraph only.
 609         </p></blockquote></div>
 610 </div>
 611 <div class="section">
 612 <div class="titlepage"><div><div><h3 class="title">
 613 <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>
 614 </h3></div></div></div>
 615 <pre class="programlisting">[note This is a note]
 616 [tip This is a tip]
 617 [important This is important]
 618 [caution This is a caution]
 619 [warning This is a warning]
 620 </pre>
 621 <p>
 622         generates <a href="http://www.docbook.org/" target="_top">DocBook</a> admonitions:
 623       </p>
 624 <div class="note"><table border="0" summary="Note">
 625 <tr>
 626 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../doc/src/images/note.png"></td>
 627 <th align="left">Note</th>
 628 </tr>
 629 <tr><td align="left" valign="top"><p>
 630           This is a note
 631         </p></td></tr>
 632 </table></div>
 633 <div class="tip"><table border="0" summary="Tip">
 634 <tr>
 635 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../doc/src/images/tip.png"></td>
 636 <th align="left">Tip</th>
 637 </tr>
 638 <tr><td align="left" valign="top"><p>
 639           This is a tip
 640         </p></td></tr>
 641 </table></div>
 642 <div class="important"><table border="0" summary="Important">
 643 <tr>
 644 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../doc/src/images/important.png"></td>
 645 <th align="left">Important</th>
 646 </tr>
 647 <tr><td align="left" valign="top"><p>
 648           This is important
 649         </p></td></tr>
 650 </table></div>
 651 <div class="caution"><table border="0" summary="Caution">
 652 <tr>
 653 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../doc/src/images/caution.png"></td>
 654 <th align="left">Caution</th>
 655 </tr>
 656 <tr><td align="left" valign="top"><p>
 657           This is a caution
 658         </p></td></tr>
 659 </table></div>
 660 <div class="warning"><table border="0" summary="Warning">
 661 <tr>
 662 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../doc/src/images/warning.png"></td>
 663 <th align="left">Warning</th>
 664 </tr>
 665 <tr><td align="left" valign="top"><p>
 666           This is a warning
 667         </p></td></tr>
 668 </table></div>
 669 <p>
 670         These are the only admonitions supported by <a href="http://www.docbook.org/" target="_top">DocBook</a>.
 671         So, for example <code class="literal">[information This is some information]</code>
 672         is unlikely to produce the desired effect.
 673       </p>
 674 </div>
 675 <div class="section">
 676 <div class="titlepage"><div><div><h3 class="title">
 677 <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>
 678 </h3></div></div></div>
 679 <pre class="programlisting">[h1 Heading 1]
 680 [h2 Heading 2]
 681 [h3 Heading 3]
 682 [h4 Heading 4]
 683 [h5 Heading 5]
 684 [h6 Heading 6]
 685 </pre>
 686 <h2>
 687 <a name="quickbook.syntax.block.headings.h0"></a>
 688         <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
 689         1</a>
 690       </h2>
 691 <h3>
 692 <a name="quickbook.syntax.block.headings.h1"></a>
 693         <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
 694         2</a>
 695       </h3>
 696 <h4>
 697 <a name="quickbook.syntax.block.headings.h2"></a>
 698         <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
 699         3</a>
 700       </h4>
 701 <h5>
 702 <a name="quickbook.syntax.block.headings.h3"></a>
 703         <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
 704         4</a>
 705       </h5>
 706 <h6>
 707 <a name="quickbook.syntax.block.headings.h4"></a>
 708         <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
 709         5</a>
 710       </h6>
 711 <h4>
 712 <a name="quickbook.syntax.block.headings.h5"></a>
 713         <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
 714         6</a>
 715       </h4>
 716 <p>
 717         You can specify an id for a heading:
 718       </p>
 719 <pre class="programlisting">[h1:heading_id A heading to link to]
 720 </pre>
 721 <p>
 722         To link to it, you'll need to include the enclosing section's id:
 723       </p>
 724 <pre class="programlisting">[link document_id.section_id.heading_id The link text]
 725 </pre>
 726 <p>
 727         Although you can preceed a heading by an <a class="link" href="phrase.html#quickbook.ref.anchors">anchor</a>
 728         if you wish to use a location independent link.
 729       </p>
 730 <p>
 731         If a heading doesn't have an id, one will be automatically generated with
 732         a normalized name with <code class="literal">name="document_id.section_id.normalized_header_text"</code>
 733         (i.e. valid characters are <code class="literal">a-z</code>, <code class="literal">A-Z</code>,
 734         <code class="literal">0-9</code> and <code class="literal">_</code>. All non-valid characters
 735         are converted to underscore and all upper-case are converted to lower-case.
 736         For example: Heading 1 in section Section 2 will be normalized to <code class="literal">section_2.heading_1</code>).
 737         You can use:
 738       </p>
 739 <pre class="programlisting">[link document_id.section_id.normalized_header_text The link text]
 740 </pre>
 741 <p>
 742         to link to them. See <a class="link" href="phrase.html#quickbook.ref.anchor_links">Anchor links</a>
 743         and <a class="link" href="structure.html#quickbook.ref.section">Section</a> for more info.
 744       </p>
 745 <div class="note"><table border="0" summary="Note">
 746 <tr>
 747 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../doc/src/images/note.png"></td>
 748 <th align="left">Note</th>
 749 </tr>
 750 <tr><td align="left" valign="top"><p>
 751           Specifying heading ids is a quickbook 1.6 feature, earlier versions don't
 752           support them.
 753         </p></td></tr>
 754 </table></div>
 755 </div>
 756 <div class="section">
 757 <div class="titlepage"><div><div><h3 class="title">
 758 <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
 759       Heading</a>
 760 </h3></div></div></div>
 761 <p>
 762         In cases when you don't want to care about the heading level (1 to 6), you
 763         can use the <span class="emphasis"><em>Generic Heading</em></span>:
 764       </p>
 765 <pre class="programlisting">[heading Heading]
 766 </pre>
 767 <p>
 768         The <span class="emphasis"><em>Generic Heading</em></span> assumes the level, plus one, of
 769         the innermost section where it is placed. For example, if it is placed in
 770         the outermost section, then, it assumes <span class="emphasis"><em>h2</em></span>.
 771       </p>
 772 <p>
 773         Headings are often used as an alternative to sections. It is used particularly
 774         if you do not want to start a new section. In many cases, however, headings
 775         in a particular section is just flat. Example:
 776       </p>
 777 <pre class="programlisting">[section A]
 778 [h2 X]
 779 [h2:link_id Y]
 780 [h2 Z]
 781 [endsect]
 782 </pre>
 783 <p>
 784         Here we use h2 assuming that section A is the outermost level. If it is placed
 785         in an inner level, you'll have to use h3, h4, etc. depending on where the
 786         section is. In general, it is the section level plus one. It is rather tedious,
 787         however, to scan the section level everytime. If you rewrite the example
 788         above as shown below, this will be automatic:
 789       </p>
 790 <pre class="programlisting">[section A]
 791 [heading X]
 792 [heading Y]
 793 [heading Z]
 794 [endsect]
 795 </pre>
 796 <p>
 797         They work well regardless where you place them. You can rearrange sections
 798         at will without any extra work to ensure correct heading levels. In fact,
 799         with <span class="emphasis"><em>section</em></span> and <span class="emphasis"><em>heading</em></span>, you have
 800         all you need. <span class="emphasis"><em>h1</em></span>..<span class="emphasis"><em>h6</em></span> becomes redundant.
 801         <span class="emphasis"><em>h1</em></span>..<span class="emphasis"><em>h6</em></span> might be deprecated in the
 802         future.
 803       </p>
 804 </div>
 805 <div class="section">
 806 <div class="titlepage"><div><div><h3 class="title">
 807 <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>
 808 </h3></div></div></div>
 809 <pre class="programlisting">[def macro_identifier some text]
 810 </pre>
 811 <p>
 812         When a macro is defined, the identifier replaces the text anywhere in the
 813         file, in paragraphs, in markups, etc. macro_identifier is a string of non-
 814         white space characters except ']'. A macro may not follow an alphabetic character
 815         or the underscore. The replacement text can be any phrase (even marked up).
 816         Example:
 817       </p>
 818 <pre class="programlisting">[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&amp;amp;type=1]]
 819 sf_logo
 820 </pre>
 821 <p>
 822         Now everywhere the sf_logo is placed, the picture will be inlined.
 823       </p>
 824 <p>
 825         <span class="inlinemediaobject"><img src="http://sourceforge.net/sflogo.php?group_id=28447&amp;type=1"></span>
 826       </p>
 827 <div class="tip"><table border="0" summary="Tip">
 828 <tr>
 829 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../doc/src/images/tip.png"></td>
 830 <th align="left">Tip</th>
 831 </tr>
 832 <tr><td align="left" valign="top"><p>
 833           It's a good idea to use macro identifiers that are distinguishable. For
 834           instance, in this document, macro identifiers have two leading and trailing
 835           underscores (e.g. <code class="literal">__spirit__</code>). The reason is to avoid
 836           unwanted macro replacement.
 837         </p></td></tr>
 838 </table></div>
 839 <p>
 840         Links (URLS) and images are good candidates for macros. <span class="bold"><strong>1</strong></span>)
 841         They tend to change a lot. It is a good idea to place all links and images
 842         in one place near the top to make it easy to make changes. <span class="bold"><strong>2</strong></span>)
 843         The syntax is not pretty. It's easier to read and write, e.g. <code class="literal">__spirit__</code>
 844         than <code class="computeroutput">[@http://spirit.sourceforge.net Spirit]</code>.
 845       </p>
 846 <p>
 847         Some more examples:
 848       </p>
 849 <pre class="programlisting">[def :-)            [$theme/smiley.png]]
 850 [def __spirit__     [@http://spirit.sourceforge.net Spirit]]
 851 </pre>
 852 <p>
 853         (See <a class="link" href="phrase.html#quickbook.ref.images">Images</a> and <a class="link" href="phrase.html#quickbook.ref.links">Links</a>)
 854       </p>
 855 <p>
 856         Invoking these macros:
 857       </p>
 858 <pre class="programlisting">Hi __spirit__  :-)
 859 </pre>
 860 <p>
 861         will generate this:
 862       </p>
 863 <p>
 864         Hi <a href="http://spirit.sourceforge.net" target="_top">Spirit</a> <span class="inlinemediaobject"><img src="../../../src/images/smiley.png"></span>
 865       </p>
 866 </div>
 867 <div class="section">
 868 <div class="titlepage"><div><div><h3 class="title">
 869 <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
 870       Macros</a>
 871 </h3></div></div></div>
 872 <p>
 873         Quickbook has some predefined macros that you can already use.
 874       </p>
 875 <div class="table">
 876 <a name="quickbook.syntax.block.predefined_macros.predefined_macros"></a><p class="title"><b>Table&#160;50.3.&#160;Predefined Macros</b></p>
 877 <div class="table-contents"><table class="table" summary="Predefined Macros">
 878 <colgroup>
 879 <col>
 880 <col>
 881 <col>
 882 </colgroup>
 883 <thead><tr>
 884 <th>
 885                 <p>
 886                   Macro
 887                 </p>
 888               </th>
 889 <th>
 890                 <p>
 891                   Meaning
 892                 </p>
 893               </th>
 894 <th>
 895                 <p>
 896                   Example
 897                 </p>
 898               </th>
 899 </tr></thead>
 900 <tbody>
 901 <tr>
 902 <td>
 903                 <p>
 904                   <code class="literal">__DATE__</code>
 905                 </p>
 906               </td>
 907 <td>
 908                 <p>
 909                   Today's date
 910                 </p>
 911               </td>
 912 <td>
 913                 <p>
 914                   2019-Dec-10
 915                 </p>
 916               </td>
 917 </tr>
 918 <tr>
 919 <td>
 920                 <p>
 921                   <code class="literal">__TIME__</code>
 922                 </p>
 923               </td>
 924 <td>
 925                 <p>
 926                   The current time
 927                 </p>
 928               </td>
 929 <td>
 930                 <p>
 931                   12:27:07 AM
 932                 </p>
 933               </td>
 934 </tr>
 935 <tr>
 936 <td>
 937                 <p>
 938                   <code class="literal">__FILENAME__</code>
 939                 </p>
 940               </td>
 941 <td>
 942                 <p>
 943                   Quickbook source filename
 944                 </p>
 945               </td>
 946 <td>
 947                 <p>
 948                   block.qbk
 949                 </p>
 950               </td>
 951 </tr>
 952 </tbody>
 953 </table></div>
 954 </div>
 955 <br class="table-break">
 956 </div>
 957 <div class="section">
 958 <div class="titlepage"><div><div><h3 class="title">
 959 <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>
 960 </h3></div></div></div>
 961 <p>
 962         Templates provide a more versatile text substitution mechanism. Templates
 963         come in handy when you need to create parameterizable, multi-line, boilerplate
 964         text that you specify once and expand many times. Templates accept one or
 965         more arguments. These arguments act like place-holders for text replacement.
 966         Unlike simple macros, which are limited to phrase level markup, templates
 967         can contain block level markup (e.g. paragraphs, code blocks and tables).
 968       </p>
 969 <p>
 970         Example template:
 971       </p>
 972 <pre class="programlisting">[template person[name age what]
 973
 974 Hi, my name is [name]. I am [age] years old. I am a [what].
 975
 976 ]
 977 </pre>
 978 <a name="quickbook.ref.template_identifier"></a><h4>
 979 <a name="quickbook.syntax.block.templates.h0"></a>
 980         <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>
 981       </h4>
 982 <p>
 983         Template identifiers can either consist of:
 984       </p>
 985 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 986 <li class="listitem">
 987             An initial alphabetic character or the underscore, followed by zero or
 988             more alphanumeric characters or the underscore. This is similar to your
 989             typical C/C++ identifier.
 990           </li>
 991 <li class="listitem">
 992             A single character punctuation (a non-alphanumeric printable character)
 993           </li>
 994 </ul></div>
 995 <h4>
 996 <a name="quickbook.syntax.block.templates.h1"></a>
 997         <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
 998         Template Arguments</a>
 999       </h4>
1000 <p>
1001         Template formal arguments are identifiers consisting of an initial alphabetic
1002         character or the underscore, followed by zero or more alphanumeric characters
1003         or the underscore. This is similar to your typical C/C++ identifier.
1004       </p>
1005 <p>
1006         A template formal argument temporarily hides a template of the same name
1007         at the point where the <a class="link" href="phrase.html#quickbook.ref.template_expansion">template
1008         is expanded</a>. Note that the body of the <code class="literal">person</code> template
1009         above refers to <code class="literal">name</code> <code class="literal">age</code> and <code class="literal">what</code>
1010         as <code class="literal">[name]</code> <code class="literal">[age]</code> and <code class="literal">[what]</code>.
1011         <code class="literal">name</code> <code class="literal">age</code> and <code class="literal">what</code>
1012         are actually templates that exist in the duration of the template call.
1013       </p>
1014 <h4>
1015 <a name="quickbook.syntax.block.templates.h2"></a>
1016         <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
1017         Body</a>
1018       </h4>
1019 <p>
1020         The template body can be just about any QuickBook block or phrase. There
1021         are actually two forms. Templates may be phrase or block level. Phrase templates
1022         are of the form:
1023       </p>
1024 <pre class="programlisting">[template sample[arg1 arg2...argN] replacement text... ]
1025 </pre>
1026 <p>
1027         Block templates are of the form:
1028       </p>
1029 <pre class="programlisting">[template sample[arg1 arg2...argN]
1030 replacement text...
1031 ]
1032 </pre>
1033 <p>
1034         The basic rule is as follows: if a newline immediately follows the argument
1035         list, then it is a block template, otherwise, it is a phrase template. Phrase
1036         templates are typically expanded as part of phrases. Like macros, block level
1037         elements are not allowed in phrase templates.
1038       </p>
1039 <h4>
1040 <a name="quickbook.syntax.block.templates.h3"></a>
1041         <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
1042         Expansion</a>
1043       </h4>
1044 <p>
1045         You expand a template this way:
1046       </p>
1047 <pre class="programlisting">[template_identifier arg1..arg2..arg3]
1048 </pre>
1049 <p>
1050         At template expansion, you supply the actual arguments. The template will
1051         be expanded with your supplied arguments. Example:
1052       </p>
1053 <pre class="programlisting">[person James Bond..39..Spy]
1054 [person Santa Clause..87..Big Red Fatso]
1055 </pre>
1056 <p>
1057         Which will expand to:
1058       </p>
1059 <p>
1060         Hi, my name is James Bond. I am 39 years old. I am a Spy.
1061       </p>
1062 <p>
1063         Hi, my name is Santa Clause. I am 87 years old. I am a Big Red Fatso.
1064       </p>
1065 <div class="caution"><table border="0" summary="Caution">
1066 <tr>
1067 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../doc/src/images/caution.png"></td>
1068 <th align="left">Caution</th>
1069 </tr>
1070 <tr><td align="left" valign="top"><p>
1071           A word of caution: Templates are recursive. A template can call another
1072           template or even itself, directly or indirectly. There are no control structures
1073           in QuickBook (yet) so this will always mean infinite recursion. QuickBook
1074           can detect this situation and report an error if recursion exceeds a certain
1075           limit.
1076         </p></td></tr>
1077 </table></div>
1078 <p>
1079         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
1080         separated by the double dot <code class="literal">".."</code> and terminated
1081         by the close parenthesis.
1082       </p>
1083 <p>
1084         Note that templates and template parameters can't be expanded everywhere,
1085         only where text is interpreted as a phrase. So they can't be expanded in
1086         places such as table titles and link's urls. If you want to use a template
1087         to generate a link based of the template parameter, you can't use a normal
1088         link and will need to use escaped docbook instead. Example:
1089       </p>
1090 <pre class="programlisting">[template boost_ticket[key] '''&lt;ulink url="https://svn.boost.org/trac/boost/ticket/'''[key]'''"&gt;#'''[key]'''&lt;/ulink&gt;''']
1091
1092 [boost_ticket 2035]
1093 </pre>
1094 <p>
1095         will expand to:
1096       </p>
1097 <p>
1098         <a href="https://svn.boost.org/trac/boost/ticket/2035" target="_top">#2035</a>
1099       </p>
1100 <div class="caution"><table border="0" summary="Caution">
1101 <tr>
1102 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../doc/src/images/caution.png"></td>
1103 <th align="left">Caution</th>
1104 </tr>
1105 <tr><td align="left" valign="top"><p>
1106           Since quickbook doesn't understand the context where the parameter is being
1107           used, it will interpret it as quickbook markup, so when writing a template
1108           like this, you'll need to escape any meaningful punctuation.
1109         </p></td></tr>
1110 </table></div>
1111 <h4>
1112 <a name="quickbook.syntax.block.templates.h4"></a>
1113         <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
1114         Templates</a>
1115       </h4>
1116 <p>
1117         Nullary templates look and act like simple macros. Example:
1118       </p>
1119 <pre class="programlisting">[template alpha[]&amp;apos;&amp;apos;&amp;apos;&amp;amp;#945;&amp;apos;&amp;apos;&amp;apos;]
1120 [template beta[]&amp;apos;&amp;apos;&amp;apos;&amp;amp;#946;&amp;apos;&amp;apos;&amp;apos;]
1121 </pre>
1122 <p>
1123         Expanding:
1124       </p>
1125 <pre class="programlisting">Some squigles...[*[alpha][beta]]</pre>
1126 <p>
1127         We have:
1128       </p>
1129 <p>
1130         Some squiggles...<span class="bold"><strong>&#945;&#946;</strong></span>
1131       </p>
1132 <p>
1133         The difference with macros are
1134       </p>
1135 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1136 <li class="listitem">
1137             The explicit <a class="link" href="phrase.html#quickbook.ref.template_expansion">template
1138             expansion syntax</a>. This is an advantage because, now, we don't
1139             have to use obscure naming conventions like double underscores (e.g.
1140             __alpha__) to avoid unwanted macro replacement.
1141           </li>
1142 <li class="listitem">
1143             The template is expanded at the point where it is invoked. A macro is
1144             expanded immediately at its point of declaration. This is subtle and
1145             can cause a slight difference in behavior especially if you refer to
1146             other macros and templates in the body.
1147           </li>
1148 </ul></div>
1149 <p>
1150         The empty brackets after the template identifier (<code class="literal">alpha[]</code>)
1151         indicates no arguments. If the template body does not look like a template
1152         argument list, we can elide the empty brackets. Example:
1153       </p>
1154 <pre class="programlisting">[template aristotle_quote Aristotle: [*['Education is the best provision
1155 for the journey to old age.]]]
1156 </pre>
1157 <p>
1158         Expanding:
1159       </p>
1160 <pre class="programlisting">Here's a quote from [aristotle_quote].
1161 </pre>
1162 <p>
1163         We have:
1164       </p>
1165 <p>
1166         Here's a quote from Aristotle: <span class="bold"><strong><span class="emphasis"><em>Education
1167         is the best provision for the journey to old age.</em></span></strong></span>.
1168       </p>
1169 <p>
1170         The disadvantage is that you can't avoid the space between the template identifier,
1171         <code class="computeroutput">aristotle_quote</code>, and the template body "Aristotle...".
1172         This space will be part of the template body. If that space is unwanted,
1173         use empty brackets or use the space escape: "<code class="computeroutput">\ </code>".
1174         Example:
1175       </p>
1176 <pre class="programlisting">[template tag\ _tag]
1177 </pre>
1178 <p>
1179         Then expanding:
1180       </p>
1181 <pre class="programlisting">`struct` x[tag];
1182 </pre>
1183 <p>
1184         We have:
1185       </p>
1186 <p>
1187         <code class="computeroutput">struct</code> x_tag;
1188       </p>
1189 <p>
1190         You have a couple of ways to do it. I personally prefer the explicit empty
1191         brackets, though.
1192       </p>
1193 <h4>
1194 <a name="quickbook.syntax.block.templates.h5"></a>
1195         <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
1196         Arguments</a>
1197       </h4>
1198 <p>
1199         As mentioned, arguments are separated by the double dot <code class="literal">".."</code>.
1200         Alternatively, if the double dot isn't used and more than one argument is
1201         expected, QuickBook uses whitespace to separate the arguments, following
1202         this logic:
1203       </p>
1204 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1205 <li class="listitem">
1206             Break the last argument into two, at the first space found (<code class="literal">'',
1207             '\n', \t' or '\r'</code>).
1208           </li>
1209 <li class="listitem">
1210             Repeat until there are enough arguments or if there are no more spaces
1211             found (in which case, an error is reported).
1212           </li>
1213 </ul></div>
1214 <p>
1215         For example:
1216       </p>
1217 <pre class="programlisting">[template simple[a b c d] [a][b][c][d]]
1218 [simple w x y z]
1219 </pre>
1220 <p>
1221         will produce:
1222       </p>
1223 <p>
1224         wxyz
1225       </p>
1226 <p>
1227         "w x y z" is initially treated as a single argument because we
1228         didn't supply any <code class="literal">".."</code> separators. However,
1229         since <code class="literal">simple</code> expects 4 arguments, "w x y z"
1230         is broken down iteratively (applying the logic above) until we have "w",
1231         "x", "y" and "z".
1232       </p>
1233 <p>
1234         QuickBook only tries to get the arguments it needs. For example:
1235       </p>
1236 <pre class="programlisting">[simple w x y z trail]
1237 </pre>
1238 <p>
1239         will produce:
1240       </p>
1241 <p>
1242         wxyz trail
1243       </p>
1244 <p>
1245         The arguments being: "w", "x", "y" and "z
1246         trail".
1247       </p>
1248 <div class="caution"><table border="0" summary="Caution">
1249 <tr>
1250 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../doc/src/images/caution.png"></td>
1251 <th align="left">Caution</th>
1252 </tr>
1253 <tr><td align="left" valign="top"><p>
1254           The behavior described here is for QuickBook 1.5. In older versions you
1255           could use both the double dot and whitespace as separators in the same
1256           template call. If your document is marked up as an older version, it will
1257           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
1258           1.4 documentation</a>.
1259         </p></td></tr>
1260 </table></div>
1261 <h4>
1262 <a name="quickbook.syntax.block.templates.h6"></a>
1263         <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
1264         Templates</a>
1265       </h4>
1266 <p>
1267         With templates, one of our objectives is to allow us to rewrite QuickBook
1268         in QuickBook (as a qbk library). For that to happen, we need to accommodate
1269         single character punctuation templates which are fairly common in QuickBook.
1270         You might have noticed that single character punctuations are allowed as
1271         <a class="link" href="block.html#quickbook.ref.template_identifier">template identifiers</a>.
1272         Example:
1273       </p>
1274 <pre class="programlisting">[template ![bar] &lt;hey&gt;[bar]&lt;/hey&gt;]
1275 </pre>
1276 <p>
1277         Now, expanding this:
1278       </p>
1279 <pre class="programlisting">[!baz]
1280 </pre>
1281 <p>
1282         We will have:
1283       </p>
1284 <pre class="programlisting">&lt;hey&gt;baz&lt;/hey&gt;
1285 </pre>
1286 </div>
1287 <div class="section">
1288 <div class="titlepage"><div><div><h3 class="title">
1289 <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>
1290 </h3></div></div></div>
1291 <pre class="programlisting">[blurb :-) [*An eye catching advertisement or note...]
1292
1293     <a href="http://spirit.sourceforge.net" target="_top">Spirit</a> is an object-oriented recursive-descent parser generator framework
1294     implemented using template meta-programming techniques. Expression templates
1295     allow us to approximate the syntax of Extended Backus-Normal Form (EBNF)
1296     completely in C++.
1297 ]
1298 </pre>
1299 <p>
1300         will generate this:
1301       </p>
1302 <div class="blurb">
1303 <div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div>
1304 <p>
1305         <span class="inlinemediaobject"><img src="../../../src/images/smiley.png"></span>
1306         <span class="bold"><strong>An eye catching advertisement or note...</strong></span>
1307       </p>
1308 <p>
1309         <a href="http://spirit.sourceforge.net" target="_top">Spirit</a> is an object-oriented
1310         recursive-descent parser generator framework implemented using template meta-programming
1311         techniques. Expression templates allow us to approximate the syntax of Extended
1312         Backus-Normal Form (EBNF) completely in C++.
1313       </p>
1314 </div>
1315 <div class="note"><table border="0" summary="Note">
1316 <tr>
1317 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../doc/src/images/note.png"></td>
1318 <th align="left">Note</th>
1319 </tr>
1320 <tr><td align="left" valign="top"><p>
1321           Prefer <a class="link" href="block.html#quickbook.ref.admonitions">admonitions</a> wherever
1322           appropriate.
1323         </p></td></tr>
1324 </table></div>
1325 </div>
1326 <div class="section">
1327 <div class="titlepage"><div><div><h3 class="title">
1328 <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>
1329 </h3></div></div></div>
1330 <pre class="programlisting">[table:id A Simple Table
1331     [[Heading 1] [Heading 2] [Heading 3]]
1332     [[R0-C0]     [R0-C1]     [R0-C2]]
1333     [[R1-C0]     [R1-C1]     [R1-C2]]
1334     [[R2-C0]     [R2-C1]     [R2-C2]]
1335 ]
1336 </pre>
1337 <p>
1338         will generate:
1339       </p>
1340 <div class="table">
1341 <a name="quickbook.syntax.block.tables.id"></a><p class="title"><b>Table&#160;50.4.&#160;A Simple Table</b></p>
1342 <div class="table-contents"><table class="table" summary="A Simple Table">
1343 <colgroup>
1344 <col>
1345 <col>
1346 <col>
1347 </colgroup>
1348 <thead><tr>
1349 <th>
1350                 <p>
1351                   Heading 1
1352                 </p>
1353               </th>
1354 <th>
1355                 <p>
1356                   Heading 2
1357                 </p>
1358               </th>
1359 <th>
1360                 <p>
1361                   Heading 3
1362                 </p>
1363               </th>
1364 </tr></thead>
1365 <tbody>
1366 <tr>
1367 <td>
1368                 <p>
1369                   R0-C0
1370                 </p>
1371               </td>
1372 <td>
1373                 <p>
1374                   R0-C1
1375                 </p>
1376               </td>
1377 <td>
1378                 <p>
1379                   R0-C2
1380                 </p>
1381               </td>
1382 </tr>
1383 <tr>
1384 <td>
1385                 <p>
1386                   R1-C0
1387                 </p>
1388               </td>
1389 <td>
1390                 <p>
1391                   R1-C1
1392                 </p>
1393               </td>
1394 <td>
1395                 <p>
1396                   R1-C2
1397                 </p>
1398               </td>
1399 </tr>
1400 <tr>
1401 <td>
1402                 <p>
1403                   R2-C0
1404                 </p>
1405               </td>
1406 <td>
1407                 <p>
1408                   R2-C1
1409                 </p>
1410               </td>
1411 <td>
1412                 <p>
1413                   R2-C2
1414                 </p>
1415               </td>
1416 </tr>
1417 </tbody>
1418 </table></div>
1419 </div>
1420 <br class="table-break"><p>
1421         The table title is optional. The first row of the table is automatically
1422         treated as the table header; that is, it is wrapped in <code class="literal">&lt;thead&gt;...&lt;/thead&gt;</code>
1423         XML tags. Note that unlike the original QuickDoc, the columns are nested
1424         in [cells... ].
1425       </p>
1426 <p>
1427         Giving tables an id is a new feature for quickbook 1.5 onwards. As with sections,
1428         the id is optional. If the table has a title but no id, an id will be generated
1429         from the title. The table above can be linked to using:
1430       </p>
1431 <pre class="programlisting">[link quickbook.syntax.block.tables.id link to table]
1432 </pre>
1433 <p>
1434         which will generate:
1435       </p>
1436 <p>
1437         <a class="link" href="block.html#quickbook.syntax.block.tables.id" title="Table&#160;50.4.&#160;A Simple Table">link to table</a>
1438       </p>
1439 <p>
1440         The syntax is free-format and allows big cells to be formatted 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: a big fat cell with paragraphs
1448
1449             Boost provides free peer-reviewed portable C++ source libraries.
1450
1451             We emphasize libraries that work well with the C++ Standard Library.
1452             Boost libraries are intended to be widely useful, and usable across
1453             a broad spectrum of applications. The Boost license encourages both
1454             commercial and non-commercial use.
1455         ]
1456     ]
1457     [
1458         [Row 1, Col 0: a small cell]
1459         [Row 1, Col 1: a small cell]
1460     ]
1461 ]
1462 </pre>
1463 <p>
1464         and thus:
1465       </p>
1466 <div class="table">
1467 <a name="quickbook.syntax.block.tables.table_with_fat_cells"></a><p class="title"><b>Table&#160;50.5.&#160;Table with fat cells</b></p>
1468 <div class="table-contents"><table class="table" summary="Table with fat cells">
1469 <colgroup>
1470 <col>
1471 <col>
1472 </colgroup>
1473 <thead><tr>
1474 <th>
1475                 <p>
1476                   Heading 1
1477                 </p>
1478               </th>
1479 <th>
1480                 <p>
1481                   Heading 2
1482                 </p>
1483               </th>
1484 </tr></thead>
1485 <tbody>
1486 <tr>
1487 <td>
1488                 <p>
1489                   Row 0, Col 0: a small cell
1490                 </p>
1491               </td>
1492 <td>
1493                 <p>
1494                   Row 0, Col 1: a big fat cell with paragraphs
1495                 </p>
1496                 <p>
1497                   Boost provides free peer-reviewed portable C++ source libraries.
1498                   We emphasize libraries that work well with the C++ Standard Library.
1499                   Boost libraries are intended to be widely useful, and usable across
1500                   a broad spectrum of applications. The Boost license encourages
1501                   both commercial and non-commercial use.
1502                 </p>
1503               </td>
1504 </tr>
1505 <tr>
1506 <td>
1507                 <p>
1508                   Row 1, Col 0: a small cell
1509                 </p>
1510               </td>
1511 <td>
1512                 <p>
1513                   Row 1, Col 1: a small cell
1514                 </p>
1515               </td>
1516 </tr>
1517 </tbody>
1518 </table></div>
1519 </div>
1520 <br class="table-break"><p>
1521         Here's how to have preformatted blocks of code in a table cell:
1522       </p>
1523 <pre class="programlisting">[table Table with code
1524     [[Comment] [Code]]
1525     [
1526         [My first program]
1527         [``
1528             #include &lt;iostream&gt;
1529
1530             int main()
1531             {
1532                 std::cout &lt;&lt; "Hello, World!" &lt;&lt; std::endl;
1533                 return 0;
1534             }
1535         ``]
1536     ]
1537 ]
1538 </pre>
1539 <div class="table">
1540 <a name="quickbook.syntax.block.tables.table_with_code"></a><p class="title"><b>Table&#160;50.6.&#160;Table with code</b></p>
1541 <div class="table-contents"><table class="table" summary="Table with code">
1542 <colgroup>
1543 <col>
1544 <col>
1545 </colgroup>
1546 <thead><tr>
1547 <th>
1548                 <p>
1549                   Comment
1550                 </p>
1551               </th>
1552 <th>
1553                 <p>
1554                   Code
1555                 </p>
1556               </th>
1557 </tr></thead>
1558 <tbody><tr>
1559 <td>
1560                 <p>
1561                   My first program
1562                 </p>
1563               </td>
1564 <td>
1565 <pre class="programlisting">#include &lt;iostream&gt;
1566
1567 int main()
1568 {
1569     std::cout &lt;&lt; "Hello, World!" &lt;&lt; std::endl;
1570     return 0;
1571 }
1572 </pre>
1573               </td>
1574 </tr></tbody>
1575 </table></div>
1576 </div>
1577 <br class="table-break">
1578 </div>
1579 <div class="section">
1580 <div class="titlepage"><div><div><h3 class="title">
1581 <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
1582       Lists</a>
1583 </h3></div></div></div>
1584 <pre class="programlisting">[variablelist A Variable List
1585     [[term 1] [The definition of term 1]]
1586     [[term 2] [The definition of term 2]]
1587     [[term 3] [
1588     The definition of term 3.
1589
1590     Definitions may contain paragraphs.
1591     ]]
1592 ]
1593 </pre>
1594 <p>
1595         will generate:
1596       </p>
1597 <div class="variablelist">
1598 <p class="title"><b>A Variable List</b></p>
1599 <dl class="variablelist">
1600 <dt><span class="term">term 1</span></dt>
1601 <dd><p>
1602               The definition of term 1
1603             </p></dd>
1604 <dt><span class="term">term 2</span></dt>
1605 <dd><p>
1606               The definition of term 2
1607             </p></dd>
1608 <dt><span class="term">term 3</span></dt>
1609 <dd>
1610 <p>
1611               The definition of term 3.
1612             </p>
1613 <p>
1614               Definitions may contain paragraphs.
1615             </p>
1616 </dd>
1617 </dl>
1618 </div>
1619 <p>
1620         The rules for variable lists are the same as for tables, except that only
1621         2 "columns" are allowed. The first column contains the terms, and
1622         the second column contains the definitions. Those familiar with HTML will
1623         recognize this as a "definition list".
1624       </p>
1625 </div>
1626 <div class="section">
1627 <div class="titlepage"><div><div><h3 class="title">
1628 <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>
1629 </h3></div></div></div>
1630 <p>
1631         You can include one QuickBook file from another. The syntax is simply:
1632       </p>
1633 <pre class="programlisting">[include someother.qbk]
1634 </pre>
1635 <p>
1636         In quickbook 1.6 and later, if the included file has a <a class="link" href="structure.html#quickbook.ref.docinfo">docinfo
1637         block</a> then it will create a nested document. This will be processed
1638         as a standalone document, although any macros or templates from the enclosing
1639         file will still be defined.
1640       </p>
1641 <p>
1642         Otherwise the included file will be processed as if it had been cut and pasted
1643         into the current document, with the following exceptions:
1644       </p>
1645 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1646 <li class="listitem">
1647             The __FILENAME__ predefined macro will reflect the name of the file currently being
1648             processed.
1649           </li>
1650 <li class="listitem">
1651             Any macros or templates defined in the included file are scoped to that
1652             file, i.e. they are not added to the enclosing file.
1653           </li>
1654 </ul></div>
1655 <div class="note"><table border="0" summary="Note">
1656 <tr>
1657 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../doc/src/images/note.png"></td>
1658 <th align="left">Note</th>
1659 </tr>
1660 <tr><td align="left" valign="top"><p>
1661           In quickbook 1.5 and earlier templates weren't scoped in included files.
1662           If you want to use templates or macros from a file in quickbook 1.6, use
1663           <a class="link" href="block.html#quickbook.ref.import">import</a> instead.
1664         </p></td></tr>
1665 </table></div>
1666 <p>
1667         The <code class="literal">[include]</code> directive lets you specify a document id
1668         to use for the included file. You can specify the id like this:
1669       </p>
1670 <pre class="programlisting">[include:someid someother.qbk]
1671 </pre>
1672 <p>
1673         All auto-generated anchors will use the document id as a unique prefix. So
1674         for instance, if there is a top section in someother.qbk named "Intro",
1675         the named anchor for that section will be "someid.intro", and you
1676         can link to it with <code class="literal">[link someid.intro The Intro]</code>.
1677       </p>
1678 <p>
1679         If the included file has a docinfo block, an id specified in an <code class="literal">[include]</code>
1680         directive will overwrite it.
1681       </p>
1682 <p>
1683         You can also include C, C++ and python source files. This will include any
1684         quickbook blocks in the file that aren't inside of named code snippets. See
1685         the <a class="link" href="block.html#quickbook.ref.import">Import section</a> for syntax
1686         details. For example, say you included this file:
1687       </p>
1688 <pre class="programlisting">/**
1689  * Hello world example
1690  */
1691
1692 // In this comment, the backtick indicates that this is a
1693 // quickbook source block that will be included.
1694
1695 /*`
1696 First include the appropriate header: [hello_includes]
1697 Then write your main function: [hello_main]
1698 */
1699
1700 // This defines a code snippet, the syntax is
1701 // described in the import section. It's available
1702 // in the whole of this source file, not just after
1703 // its definition.
1704
1705 //[hello_includes
1706 #include &lt;iostream&gt;
1707 //]
1708
1709 //[hello_main
1710 int main() {
1711     std::cout &lt;&lt; "Hello, trivial example" &lt;&lt; std::endl;
1712 }
1713 //]
1714 </pre>
1715 <p>
1716         It will generate:
1717       </p>
1718 <pre class="programlisting">First include the appropriate header:
1719
1720     #include &lt;iostream&gt;
1721
1722 Then write your main function:
1723
1724     int main() {
1725         std::cout &lt;&lt; "Hello, trivial example" &lt;&lt; std::endl;
1726     }
1727 </pre>
1728 </div>
1729 <div class="section">
1730 <div class="titlepage"><div><div><h3 class="title">
1731 <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>
1732 </h3></div></div></div>
1733 <p>
1734         In quickbook 1.6 and later if you wish to use a template, macro or code snippet
1735         from a file, you need to import it. This will not include any of the content
1736         from that file, but will pull templates, macros and code snippets into the
1737         current file's scope.
1738       </p>
1739 <p>
1740         With quickbook files, this allows you to create template and macro libraries.
1741         For python (indicated by the <code class="computeroutput">.py</code> extension), C or C++ files
1742         this allows you to include code snippets from source files, so that your
1743         code examples can be kept up to date and fully tested.
1744       </p>
1745 <h4>
1746 <a name="quickbook.syntax.block.import.h0"></a>
1747         <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>
1748       </h4>
1749 <p>
1750         You can effortlessly import code snippets from source code into your QuickBook.
1751         The following illustrates how this is done:
1752       </p>
1753 <pre class="programlisting">[import ../test/stub.cpp]
1754 [foo]
1755 [bar]
1756 </pre>
1757 <p>
1758         The first line:
1759       </p>
1760 <pre class="programlisting">[import ../test/stub.cpp]
1761 </pre>
1762 <p>
1763         collects specially marked-up code snippets from <a href="../../../../tools/quickbook/test/stub.cpp" target="_top">stub.cpp</a>
1764         and places them in your QuickBook file as virtual templates. Each of the
1765         specially marked-up code snippets has a name (e.g. <code class="computeroutput">foo</code> and
1766         <code class="computeroutput">bar</code> in the example above). This shall be the template identifier
1767         for that particular code snippet. The second and third line above does the
1768         actual template expansion:
1769       </p>
1770 <pre class="programlisting">[foo]
1771 [bar]
1772 </pre>
1773 <p>
1774         And the result is:
1775       </p>
1776 <p>
1777         This is the <span class="bold"><strong><span class="emphasis"><em>foo</em></span></strong></span> function.
1778       </p>
1779 <p>
1780         This description can have paragraphs...
1781       </p>
1782 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1783 <li class="listitem">
1784             lists
1785           </li>
1786 <li class="listitem">
1787             etc.
1788           </li>
1789 </ul></div>
1790 <p>
1791         And any quickbook block markup.
1792       </p>
1793 <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>
1794 <span class="special">{</span>
1795     <span class="comment">// return 'em, foo man!</span>
1796     <span class="keyword">return</span> <span class="string">"foo"</span><span class="special">;</span>
1797 <span class="special">}</span>
1798 </pre>
1799 <p>
1800         This is the <span class="bold"><strong><span class="emphasis"><em>bar</em></span></strong></span> function
1801       </p>
1802 <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>
1803 <span class="special">{</span>
1804     <span class="comment">// return 'em, bar man!</span>
1805     <span class="keyword">return</span> <span class="string">"bar"</span><span class="special">;</span>
1806 <span class="special">}</span>
1807 </pre>
1808 <p>
1809         Some trailing text here
1810       </p>
1811 <h4>
1812 <a name="quickbook.syntax.block.import.h1"></a>
1813         <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
1814         Snippet Markup</a>
1815       </h4>
1816 <p>
1817         Note how the code snippets in <a href="../../../../tools/quickbook/test/stub.cpp" target="_top">stub.cpp</a>
1818         get marked up. We use distinguishable comments following the form:
1819       </p>
1820 <pre class="programlisting">//[id
1821 some code here
1822 //]
1823 </pre>
1824 <p>
1825         The first comment line above initiates a named code-snippet. This prefix
1826         will not be visible in quickbook. The entire code-snippet in between <code class="computeroutput">//[id</code>
1827         and <code class="computeroutput">//]</code> will be inserted as a template in quickbook with name
1828         <span class="emphasis"><em><span class="emphasis"><em>id</em></span></em></span>. The comment <code class="computeroutput">//]</code>
1829         ends a code-snippet This too will not be visible in quickbook.
1830       </p>
1831 <a name="quickbook.ref.callouts"></a><h4>
1832 <a name="quickbook.syntax.block.import.h2"></a>
1833         <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
1834         Comments</a>
1835       </h4>
1836 <p>
1837         Special comments of the form:
1838       </p>
1839 <pre class="programlisting">//` some [*quickbook] markup here
1840 </pre>
1841 <p>
1842         and:
1843       </p>
1844 <pre class="programlisting">/*` some [*quickbook] markup here */
1845 </pre>
1846 <p>
1847         will be parsed by QuickBook. This can contain quickbook <span class="emphasis"><em>blocks</em></span>
1848         (e.g. sections, paragraphs, tables, etc). In the first case, the initial
1849         slash-slash, tick and white-space shall be ignored. In the second, the initial
1850         slash-star-tick and the final star-slash shall be ignored.
1851       </p>
1852 <p>
1853         Special comments of the form:
1854       </p>
1855 <pre class="programlisting">/*&lt;- this C++ comment will be ignored -&gt;*/
1856 </pre>
1857 <p>
1858         or
1859       </p>
1860 <pre class="programlisting">/*&lt;-*/ "this c++ code  will be ignored" /*-&gt;*/
1861 </pre>
1862 <p>
1863         or
1864       </p>
1865 <pre class="programlisting">//&lt;-
1866 private:
1867     int some_member;
1868 //-&gt;
1869 </pre>
1870 <p>
1871         can be used to inhibit code from passing through to quickbook. All text between
1872         the delimeters will simply be ignored.
1873       </p>
1874 <p>
1875         Comments of this form:
1876       </p>
1877 <pre class="programlisting">//=int main() {}
1878 </pre>
1879 <p>
1880         or
1881       </p>
1882 <pre class="programlisting">/*=foo()*/
1883 </pre>
1884 <p>
1885         will be displayed as code that isn't in comments. This allows you to include
1886         some code in the snippet but not actually use it when compiling your example.
1887       </p>
1888 <h4>
1889 <a name="quickbook.syntax.block.import.h3"></a>
1890         <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>
1891       </h4>
1892 <p>
1893         Special comments of the form:
1894       </p>
1895 <pre class="programlisting">/*&lt; some [*quickbook] markup here &gt;*/
1896 </pre>
1897 <p>
1898         will be regarded as callouts. These will be collected, numbered and rendered
1899         as a "callout bug" (a small icon with a number). After the whole
1900         snippet is parsed, the callout list is generated. See <a href="http://www.docbook.org/tdg/en/html/callout.html" target="_top">Callouts</a>
1901         for details. Example:
1902       </p>
1903 <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>
1904 <span class="special">{</span>
1905     <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>
1906 <span class="special">}</span>
1907 </pre>
1908 <div class="calloutlist"><table border="0" summary="Callout list">
1909 <tr>
1910 <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>
1911 <td valign="top" align="left"><p>
1912             The <span class="emphasis"><em>Mythical</em></span> FooBar. See <a href="http://en.wikipedia.org/wiki/Foobar" target="_top">Foobar
1913             for details</a>
1914           </p></td>
1915 </tr>
1916 <tr>
1917 <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>
1918 <td valign="top" align="left"><p>
1919             return 'em, foo-bar man!
1920           </p></td>
1921 </tr>
1922 </table></div>
1923 <p>
1924         This is the actual code:
1925       </p>
1926 <pre class="programlisting">//[ foo_bar
1927 std::string foo_bar() /*&lt; The /Mythical/ FooBar.
1928                       See [@http://en.wikipedia.org/wiki/Foobar Foobar for details] &gt;*/
1929 {
1930     return "foo-bar"; /*&lt; return 'em, foo-bar man! &gt;*/
1931 }
1932 //]
1933 </pre>
1934 <p>
1935         The callouts bugs are placed exactly where the special callout comment is
1936         situated. It can be anywhere in the code. The bugs can be rather obtrusive,
1937         however. They get in the way of the clarity of the code. Another special
1938         callout comment style is available:
1939       </p>
1940 <pre class="programlisting">/*&lt;&lt; some [*quickbook] markup here &gt;&gt;*/
1941 </pre>
1942 <p>
1943         This is the line-oriented version of the callout. With this, the "bug"
1944         is placed at the very left of the code block, away from the actual code.
1945         By placing it at the far left, the code is rendered un-obscured. Example:
1946       </p>
1947 <pre class="programlisting"><span class="keyword">class</span> <span class="identifier">x</span>
1948 <span class="special">{</span>
1949 <span class="keyword">public</span><span class="special">:</span>
1950
1951     <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>
1952     <span class="special">{</span>
1953     <span class="special">}</span>
1954
1955     <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>
1956     <span class="special">{</span>
1957     <span class="special">}</span>
1958
1959     <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>
1960     <span class="special">{</span>
1961         <span class="keyword">return</span> <span class="identifier">n</span><span class="special">;</span>
1962     <span class="special">}</span>
1963
1964     <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>
1965     <span class="special">{</span>
1966         <span class="identifier">n</span> <span class="special">=</span> <span class="identifier">n_</span><span class="special">;</span>
1967     <span class="special">}</span>
1968 <span class="special">};</span>
1969 </pre>
1970 <div class="calloutlist"><table border="0" summary="Callout list">
1971 <tr>
1972 <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>
1973 <td valign="top" align="left"><p>
1974             Constructor
1975           </p></td>
1976 </tr>
1977 <tr>
1978 <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>
1979 <td valign="top" align="left"><p>
1980             Destructor
1981           </p></td>
1982 </tr>
1983 <tr>
1984 <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>
1985 <td valign="top" align="left"><p>
1986             Get the <code class="computeroutput">n</code> member variable
1987           </p></td>
1988 </tr>
1989 <tr>
1990 <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>
1991 <td valign="top" align="left"><p>
1992             Set the <code class="computeroutput">n</code> member variable
1993           </p></td>
1994 </tr>
1995 </table></div>
1996 <p>
1997         See the actual code here: <a href="../../../../tools/quickbook/test/stub.cpp" target="_top">tools/quickbook/test/stub.cpp</a>
1998       </p>
1999 </div>
2000 <div class="section">
2001 <div class="titlepage"><div><div><h3 class="title">
2002 <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
2003       blocks</a>
2004 </h3></div></div></div>
2005 <p>
2006         <code class="computeroutput">block</code> is a plain block element, that doesn't wrap its contents
2007         in any docbook or boostbook tags. This can be useful when using escaped docbook
2008         block tags, such as:
2009       </p>
2010 <pre class="programlisting">[template chapter[title]
2011 [block'''&lt;chapter&gt;&lt;title&gt;'''[title]'''&lt;/title&gt;''']
2012 ]
2013
2014 [template chapterend
2015 [block'''&lt;/chapter&gt;''']
2016 ]
2017
2018 [chapter An example chapter]
2019
2020 Content
2021
2022 [chapterend]
2023 </pre>
2024 <p>
2025         Without the <code class="computeroutput">block</code> element, the <code class="computeroutput">chapter</code> and <code class="computeroutput">chapterend</code>
2026         templates would be wrapped in paragraph tags.
2027       </p>
2028 <div class="note"><table border="0" summary="Note">
2029 <tr>
2030 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../doc/src/images/note.png"></td>
2031 <th align="left">Note</th>
2032 </tr>
2033 <tr><td align="left" valign="top"><p>
2034           In this example, the template body has to start with a newline so that
2035           the template will be interpreted in block mode.
2036         </p></td></tr>
2037 </table></div>
2038 </div>
2039 </div>
2040 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
2041 <td align="left"></td>
2042 <td align="right"><div class="copyright-footer">Copyright &#169; 2002, 2004, 2006 Joel de Guzman,
2043       Eric Niebler<br>Copyright &#169; 2010-2017 Daniel James<p>
2044         Distributed under the Boost Software License, Version 1.0. (See accompanying
2045         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>)
2046       </p>
2047 </div></td>
2048 </tr></table>
2049 <hr>
2050 <div class="spirit-nav">
2051 <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>
2052 </div>
2053 </body>
2054 </html>