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=UTF-8"> 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 50. 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"><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"> 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"><</span><span class="identifier">iostream</span><span class="special">></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"><<</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() /*< The /Mythical/ FooBar. 507 See [@http://en.wikipedia.org/wiki/Foobar Foobar for details] >*/ 508 { 509 return "foo-bar"; /*< return 'em, foo-bar man! >*/ 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"> 589Some <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;type=1]] 819sf_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&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 50.3. 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 2020-Aug-11 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 03:04:03 PM 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 974Hi, 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] 1030replacement 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] '''<ulink url="https://svn.boost.org/trac/boost/ticket/'''[key]'''">#'''[key]'''</ulink>'''] 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[]&apos;&apos;&apos;&amp;#945;&apos;&apos;&apos;] 1120[template beta[]&apos;&apos;&apos;&amp;#946;&apos;&apos;&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>αβ</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 1155for 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] <hey>[bar]</hey>] 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"><hey>baz</hey> 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 50.4. 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"><thead>...</thead></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 50.4. 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 50.5. 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 <iostream> 1529 1530 int main() 1531 { 1532 std::cout << "Hello, World!" << 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 50.6. 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 <iostream> 1566 1567int main() 1568{ 1569 std::cout << "Hello, World!" << 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/*` 1696First include the appropriate header: [hello_includes] 1697Then 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 <iostream> 1707//] 1708 1709//[hello_main 1710int main() { 1711 std::cout << "Hello, trivial example" << 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 <iostream> 1721 1722Then write your main function: 1723 1724 int main() { 1725 std::cout << "Hello, trivial example" << 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 1821some 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">/*<- this C++ comment will be ignored ->*/ 1856</pre> 1857<p> 1858 or 1859 </p> 1860<pre class="programlisting">/*<-*/ "this c++ code will be ignored" /*->*/ 1861</pre> 1862<p> 1863 or 1864 </p> 1865<pre class="programlisting">//<- 1866private: 1867 int some_member; 1868//-> 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">/*< some [*quickbook] markup here >*/ 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 1927std::string foo_bar() /*< The /Mythical/ FooBar. 1928 See [@http://en.wikipedia.org/wiki/Foobar Foobar for details] >*/ 1929{ 1930 return "foo-bar"; /*< return 'em, foo-bar man! >*/ 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">/*<< some [*quickbook] markup here >>*/ 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'''<chapter><title>'''[title]'''</title>'''] 2012] 2013 2014[template chapterend 2015[block'''</chapter>'''] 2016] 2017 2018[chapter An example chapter] 2019 2020Content 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 © 2002, 2004, 2006 Joel de Guzman, 2043 Eric Niebler<br>Copyright © 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> 2055
