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>Phrase 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="structure.html" title="Document Structure"> 11<link rel="next" href="block.html" title="Block Level Elements"> 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="structure.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="block.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.phrase"></a>Phrase Level Elements</h2></div></div></div> 29<div class="toc"><dl class="toc"> 30<dt><span class="section"><a href="phrase.html#quickbook.syntax.phrase.font_styles">Font 31 Styles</a></span></dt> 32<dt><span class="section"><a href="phrase.html#quickbook.syntax.phrase.replaceable">Replaceable</a></span></dt> 33<dt><span class="section"><a href="phrase.html#quickbook.syntax.phrase.quotations">Quotations</a></span></dt> 34<dt><span class="section"><a href="phrase.html#quickbook.syntax.phrase.simple_formatting">Simple 35 formatting</a></span></dt> 36<dt><span class="section"><a href="phrase.html#quickbook.syntax.phrase.role">Role</a></span></dt> 37<dt><span class="section"><a href="phrase.html#quickbook.syntax.phrase.inline_code">Inline 38 code</a></span></dt> 39<dt><span class="section"><a href="phrase.html#quickbook.syntax.phrase.code_blocks">Code 40 blocks</a></span></dt> 41<dt><span class="section"><a href="phrase.html#quickbook.syntax.phrase.source_mode">Source 42 Mode</a></span></dt> 43<dt><span class="section"><a href="phrase.html#quickbook.syntax.phrase.line_break">line-break</a></span></dt> 44<dt><span class="section"><a href="phrase.html#quickbook.syntax.phrase.anchors">Anchors</a></span></dt> 45<dt><span class="section"><a href="phrase.html#quickbook.syntax.phrase.links">Links</a></span></dt> 46<dt><span class="section"><a href="phrase.html#quickbook.syntax.phrase.anchor_links">Anchor 47 links</a></span></dt> 48<dt><span class="section"><a href="phrase.html#quickbook.syntax.phrase.refentry_links">refentry 49 links</a></span></dt> 50<dt><span class="section"><a href="phrase.html#quickbook.syntax.phrase.code_links">Code 51 Links</a></span></dt> 52<dt><span class="section"><a href="phrase.html#quickbook.syntax.phrase.escape">Escape</a></span></dt> 53<dt><span class="section"><a href="phrase.html#quickbook.syntax.phrase.single_char_escape">Single 54 char escape</a></span></dt> 55<dt><span class="section"><a href="phrase.html#quickbook.syntax.phrase.unicode_escape">Unicode 56 escape</a></span></dt> 57<dt><span class="section"><a href="phrase.html#quickbook.syntax.phrase.images">Images</a></span></dt> 58<dt><span class="section"><a href="phrase.html#quickbook.syntax.phrase.footnotes">Footnotes</a></span></dt> 59<dt><span class="section"><a href="phrase.html#quickbook.syntax.phrase.macro_expansion">Macro 60 Expansion</a></span></dt> 61<dt><span class="section"><a href="phrase.html#quickbook.syntax.phrase.template_expansion">Template 62 Expansion</a></span></dt> 63<dt><span class="section"><a href="phrase.html#quickbook.syntax.phrase.cond">Conditional 64 Generation</a></span></dt> 65</dl></div> 66<div class="section"> 67<div class="titlepage"><div><div><h3 class="title"> 68<a name="quickbook.syntax.phrase.font_styles"></a><a name="quickbook.ref.font_styles"></a><a class="link" href="phrase.html#quickbook.syntax.phrase.font_styles" title="Font Styles">Font 69 Styles</a> 70</h3></div></div></div> 71<pre class="programlisting">['italic], [*bold], [_underline], [^teletype], [-strikethrough] 72</pre> 73<p> 74 will generate: 75 </p> 76<p> 77 <span class="emphasis"><em>italic</em></span>, <span class="bold"><strong>bold</strong></span>, <span class="underline">underline</span>, <code class="literal">teletype</code>, <span class="strikethrough">strikethrough</span> 78 </p> 79<p> 80 Like all non-terminal phrase level elements, this can of course be nested: 81 </p> 82<pre class="programlisting">[*['bold-italic]] 83</pre> 84<p> 85 will generate: 86 </p> 87<p> 88 <span class="bold"><strong><span class="emphasis"><em>bold-italic</em></span></strong></span> 89 </p> 90</div> 91<div class="section"> 92<div class="titlepage"><div><div><h3 class="title"> 93<a name="quickbook.syntax.phrase.replaceable"></a><a name="quickbook.ref.replaceable"></a><a class="link" href="phrase.html#quickbook.syntax.phrase.replaceable" title="Replaceable">Replaceable</a> 94</h3></div></div></div> 95<p> 96 When you want content that may or must be replaced by the user, use the syntax: 97 </p> 98<pre class="programlisting">[~replacement] 99</pre> 100<p> 101 This will generate: 102 </p> 103<p> 104 <em class="replaceable"><code>replacement</code></em> 105 </p> 106</div> 107<div class="section"> 108<div class="titlepage"><div><div><h3 class="title"> 109<a name="quickbook.syntax.phrase.quotations"></a><a name="quickbook.ref.quotations"></a><a class="link" href="phrase.html#quickbook.syntax.phrase.quotations" title="Quotations">Quotations</a> 110</h3></div></div></div> 111<pre class="programlisting">["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein 112</pre> 113<p> 114 will generate: 115 </p> 116<p> 117 <span class="quote">“<span class="quote">A question that sometimes drives me hazy: am I or are the others crazy?</span>”</span>--Einstein 118 </p> 119<p> 120 Note the proper left and right quote marks. Also, while you can simply use 121 ordinary quote marks like "quoted", our quotation, above, will 122 generate correct DocBook quotations (e.g. <quote>quoted</quote>). 123 </p> 124<p> 125 Like all phrase elements, quotations may be nested. Example: 126 </p> 127<pre class="programlisting">["Here's the rule for bargains: ["Do other men, for they would do you.] That's 128the true business precept.] 129</pre> 130<p> 131 will generate: 132 </p> 133<p> 134 <span class="quote">“<span class="quote">Here's the rule for bargains: <span class="quote">‘<span class="quote">Do other men, for they would 135 do you.</span>’</span> That's the true business precept.</span>”</span> 136 </p> 137</div> 138<div class="section"> 139<div class="titlepage"><div><div><h3 class="title"> 140<a name="quickbook.syntax.phrase.simple_formatting"></a><a name="quickbook.ref.simple_formatting"></a><a class="link" href="phrase.html#quickbook.syntax.phrase.simple_formatting" title="Simple formatting">Simple 141 formatting</a> 142</h3></div></div></div> 143<p> 144 Simple markup for formatting text, common in many applications, is now supported: 145 </p> 146<pre class="programlisting">/italic/, *bold*, _underline_, =teletype= 147</pre> 148<p> 149 will generate: 150 </p> 151<p> 152 <span class="emphasis"><em>italic</em></span>, <span class="bold"><strong>bold</strong></span>, <span class="underline">underline</span>, <code class="literal">teletype</code> 153 </p> 154<p> 155 Unlike QuickBook's standard formatting scheme, the rules for simpler alternatives 156 are much stricter<a href="#ftn.quickbook.syntax.phrase.simple_formatting.f0" class="footnote" name="quickbook.syntax.phrase.simple_formatting.f0"><sup class="footnote">[38]</sup></a>. 157 </p> 158<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 159<li class="listitem"> 160 Simple markups cannot nest. You can combine a simple markup with a nestable 161 markup. 162 </li> 163<li class="listitem"> 164 Simple markups cannot contain any other form of quickbook markup. 165 </li> 166<li class="listitem"> 167 A non-space character must follow the leading markup 168 </li> 169<li class="listitem"> 170 A non-space character must precede the trailing markup 171 </li> 172<li class="listitem"> 173 A space or a punctuation must follow the trailing markup 174 </li> 175<li class="listitem"> 176 If the matching markup cannot be found within a block, the formatting 177 will not be applied. This is to ensure that un-matched formatting markups, 178 which can be a common mistake, does not corrupt anything past a single 179 block. We do not want the rest of the document to be rendered bold just 180 because we forgot a trailing '*'. A single block is terminated by two 181 end of lines or the close bracket: ']'. 182 </li> 183<li class="listitem"> 184 A line starting with the star will be interpreted as an unordered list. 185 See <a class="link" href="block.html#quickbook.ref.unordered_lists">Unordered lists</a>. 186 </li> 187</ul></div> 188<div class="table"> 189<a name="quickbook.syntax.phrase.simple_formatting.more_formatting_samples"></a><p class="title"><b>Table 50.1. More Formatting Samples</b></p> 190<div class="table-contents"><table class="table" summary="More Formatting Samples"> 191<colgroup> 192<col> 193<col> 194</colgroup> 195<thead><tr> 196<th> 197 <p> 198 Markup 199 </p> 200 </th> 201<th> 202 <p> 203 Result 204 </p> 205 </th> 206</tr></thead> 207<tbody> 208<tr> 209<td> 210 <p> 211 <code class="computeroutput">*Bold*</code> 212 </p> 213 </td> 214<td> 215 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 216 Bold* 217 </li></ul></div> 218 </td> 219</tr> 220<tr> 221<td> 222 <p> 223 <code class="computeroutput">*Is bold*</code> 224 </p> 225 </td> 226<td> 227 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 228 Is bold* 229 </li></ul></div> 230 </td> 231</tr> 232<tr> 233<td> 234 <p> 235 <code class="computeroutput">* Not bold* *Not bold * * Not bold *</code> 236 </p> 237 </td> 238<td> 239 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 240 Not bold* *Not bold * * Not bold * 241 </li></ul></div> 242 </td> 243</tr> 244<tr> 245<td> 246 <p> 247 <code class="computeroutput">This*Isn't*Bold (no bold)</code> 248 </p> 249 </td> 250<td> 251 <p> 252 This*Isn't*Bold (no bold) 253 </p> 254 </td> 255</tr> 256<tr> 257<td> 258 <p> 259 <code class="computeroutput">(*Bold Inside*) (parenthesis not bold)</code> 260 </p> 261 </td> 262<td> 263 <p> 264 (<span class="bold"><strong>Bold Inside</strong></span>) (parenthesis not 265 bold) 266 </p> 267 </td> 268</tr> 269<tr> 270<td> 271 <p> 272 <code class="computeroutput">*(Bold Outside)* (parenthesis bold)</code> 273 </p> 274 </td> 275<td> 276 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 277 (Bold Outside)* (parenthesis bold) 278 </li></ul></div> 279 </td> 280</tr> 281<tr> 282<td> 283 <p> 284 <code class="computeroutput">3*4*5 = 60 (no bold)</code> 285 </p> 286 </td> 287<td> 288 <p> 289 3*4*5 = 60 (no bold) 290 </p> 291 </td> 292</tr> 293<tr> 294<td> 295 <p> 296 <code class="computeroutput">3 * 4 * 5 = 60 (no bold)</code> 297 </p> 298 </td> 299<td> 300 <p> 301 3 * 4 * 5 = 60 (no bold) 302 </p> 303 </td> 304</tr> 305<tr> 306<td> 307 <p> 308 <code class="computeroutput">3 *4* 5 = 60 (4 is bold)</code> 309 </p> 310 </td> 311<td> 312 <p> 313 3 <span class="bold"><strong>4</strong></span> 5 = 60 (4 is bold) 314 </p> 315 </td> 316</tr> 317<tr> 318<td> 319 <p> 320 <code class="computeroutput">*This is bold* this is not *but this is*</code> 321 </p> 322 </td> 323<td> 324 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 325 This is bold* this is not <span class="bold"><strong>but this is</strong></span> 326 </li></ul></div> 327 </td> 328</tr> 329<tr> 330<td> 331 <p> 332 <code class="computeroutput">*This is bold*.</code> 333 </p> 334 </td> 335<td> 336 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 337 This is bold*. 338 </li></ul></div> 339 </td> 340</tr> 341<tr> 342<td> 343 <p> 344 <code class="computeroutput">*B*. (bold B)</code> 345 </p> 346 </td> 347<td> 348 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 349 B*. (bold B) 350 </li></ul></div> 351 </td> 352</tr> 353<tr> 354<td> 355 <p> 356 <code class="computeroutput">['*Bold-Italic*]</code> 357 </p> 358 </td> 359<td> 360 <p> 361 <span class="emphasis"><em><span class="bold"><strong>Bold-Italic</strong></span></em></span> 362 </p> 363 </td> 364</tr> 365<tr> 366<td> 367 <p> 368 <code class="computeroutput">*side-by*/-side/</code> 369 </p> 370 </td> 371<td> 372 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 373 side-by*<span class="emphasis"><em>-side</em></span> 374 </li></ul></div> 375 </td> 376</tr> 377</tbody> 378</table></div> 379</div> 380<br class="table-break"><p> 381 As mentioned, simple markups cannot go past a single block. The text from 382 "have" to "full" in the following paragraph will be rendered 383 as bold: 384 </p> 385<pre class="programlisting">Baa baa black sheep, *have you any wool? 386Yes sir, yes sir, three bags full!* 387One for the master, one for the dame, 388And one for the little boy who lives down the lane. 389</pre> 390<p> 391 Baa baa black sheep, <span class="bold"><strong>have you any wool? Yes sir, yes 392 sir, three bags full!</strong></span> One for the master, one for the dame, And 393 one for the little boy who lives down the lane. 394 </p> 395<p> 396 But in the following paragraph, bold is not applied: 397 </p> 398<pre class="programlisting">Baa baa black sheep, *have you any wool? 399Yes sir, yes sir, three bags full! 400One for the master, one for the dame, 401And one for the little boy who lives down the lane. 402</pre> 403<p> 404 Baa baa black sheep, *have you any wool? Yes sir, yes sir, three bags full! 405 One for the master, one for the dame, And one for the little boy who lives 406 down the lane. 407 </p> 408</div> 409<div class="section"> 410<div class="titlepage"><div><div><h3 class="title"> 411<a name="quickbook.syntax.phrase.role"></a><a name="quickbook.ref.role"></a><a class="link" href="phrase.html#quickbook.syntax.phrase.role" title="Role">Role</a> 412</h3></div></div></div> 413<p> 414 This generates a docbook phrase with a <code class="computeroutput">role</code> attribute, which 415 can be used to classify the phrase. This can be used to mark text for a use 416 that isn't covered elsewhere. The docbook <code class="computeroutput">role</code> will generate 417 a html class, which can be used to style text. And the xsl stylesheets can 418 be customized to treat certain roles specially when generating pdfs. 419 </p> 420<p> 421 The boostbook css stylesheets, and xsl stylesheets contain support for a 422 limited number of colours that can be used with <code class="computeroutput">role</code>. For example 423 if you write: 424 </p> 425<pre class="programlisting">[role red Text content] 426</pre> 427<p> 428 You'll get red text if you're using the boostbook css (for html) or the boostbook 429 xsl for generating pdfs. 430 </p> 431<p> 432 The full list of colours that will be available is: 433 </p> 434<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 435<li class="listitem"> 436 <span class="red">red</span> 437 </li> 438<li class="listitem"> 439 <span class="green">green</span> 440 </li> 441<li class="listitem"> 442 <span class="lime">lime</span> 443 </li> 444<li class="listitem"> 445 <span class="blue">blue</span> 446 </li> 447<li class="listitem"> 448 <span class="navy">navy</span> 449 </li> 450<li class="listitem"> 451 <span class="yellow">yellow</span> 452 </li> 453<li class="listitem"> 454 <span class="magenta">magenta</span> 455 </li> 456<li class="listitem"> 457 <span class="indigo">indigo</span> 458 </li> 459<li class="listitem"> 460 <span class="cyan">cyan</span> 461 </li> 462<li class="listitem"> 463 <span class="purple">purple</span> 464 </li> 465<li class="listitem"> 466 <span class="gold">gold</span> 467 </li> 468<li class="listitem"> 469 <span class="silver">silver</span> 470 </li> 471<li class="listitem"> 472 <span class="gray">gray</span> 473 </li> 474</ul></div> 475</div> 476<div class="section"> 477<div class="titlepage"><div><div><h3 class="title"> 478<a name="quickbook.syntax.phrase.inline_code"></a><a name="quickbook.ref.inline_code"></a><a class="link" href="phrase.html#quickbook.syntax.phrase.inline_code" title="Inline code">Inline 479 code</a> 480</h3></div></div></div> 481<p> 482 Inlining code in paragraphs is quite common when writing C++ documentation. 483 We provide a very simple markup for this. For example, this: 484 </p> 485<pre class="programlisting">This text has inlined code `int main() { return 0; }` in it. 486</pre> 487<p> 488 will generate: 489 </p> 490<p> 491 This text has inlined code <code class="computeroutput">int main() { return 0; }</code> in it. The 492 code will be syntax highlighted. 493 </p> 494<div class="note"><table border="0" summary="Note"> 495<tr> 496<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../doc/src/images/note.png"></td> 497<th align="left">Note</th> 498</tr> 499<tr><td align="left" valign="top"><p> 500 We simply enclose the code with the tick: <code class="literal">"`"</code>, 501 not the single quote: <code class="computeroutput">"'"</code>. Note too that <code class="literal">`some 502 code`</code> is preferred over <code class="computeroutput">[^some code]</code>. 503 </p></td></tr> 504</table></div> 505</div> 506<div class="section"> 507<div class="titlepage"><div><div><h3 class="title"> 508<a name="quickbook.syntax.phrase.code_blocks"></a><a name="quickbook.ref.code_blocks"></a><a class="link" href="phrase.html#quickbook.syntax.phrase.code_blocks" title="Code blocks">Code 509 blocks</a> 510</h3></div></div></div> 511<p> 512 Preformatted code simply starts with a space or a tab (See <a class="link" href="block.html#quickbook.ref.code">Code</a>). 513 However, such a simple syntax cannot be used as phrase elements in lists 514 (See <a class="link" href="block.html#quickbook.ref.ordered_lists">Ordered lists</a> and 515 <a class="link" href="block.html#quickbook.ref.unordered_lists">Unordered lists</a>), tables 516 (See <a class="link" href="block.html#quickbook.ref.tables">Tables</a>), etc. Inline code 517 (see above) can. The problem is, inline code does not allow formatting with 518 newlines, spaces, and tabs. These are lost. 519 </p> 520<p> 521 We provide a phrase level markup that is a mix between the two. By using 522 the double-tick or triple-tick, instead of the single-tick, we are telling 523 QuickBook to use preformatted blocks of code. Example: 524 </p> 525<pre class="programlisting">`` 526 #include <iostream> 527 528 int main() 529 { 530 std::cout << "Hello, World!" << std::endl; 531 return 0; 532 } 533`` 534</pre> 535<p> 536 or: 537 </p> 538<pre class="programlisting">``` 539 #include <iostream> 540 541 int main() 542 { 543 std::cout << "Hello, World!" << std::endl; 544 return 0; 545 } 546``` 547</pre> 548<p> 549 will generate: 550 </p> 551<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span> 552 553<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> 554<span class="special">{</span> 555 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Hello, World!"</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> 556 <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> 557<span class="special">}</span> 558</pre> 559</div> 560<div class="section"> 561<div class="titlepage"><div><div><h3 class="title"> 562<a name="quickbook.syntax.phrase.source_mode"></a><a name="quickbook.ref.source_mode"></a><a class="link" href="phrase.html#quickbook.syntax.phrase.source_mode" title="Source Mode">Source 563 Mode</a> 564</h3></div></div></div> 565<p> 566 If a document contains more than one type of source code then the source 567 mode may be changed dynamically as the document is processed. All QuickBook 568 documents are initially in C++ mode by default, though an alternative initial 569 value may be set in the <a class="link" href="structure.html#quickbook.ref.docinfo">Document</a> 570 section. 571 </p> 572<p> 573 To change the source mode, use the <code class="literal">[source-mode]</code> markup, 574 where <code class="literal">source-mode</code> is one of the supported modes. For example, 575 this: 576 </p> 577<pre class="programlisting">Python's [python] `import` is rather like C++'s [c++] `#include`. A 578C++ comment `// looks like this` whereas a Python comment [python] 579`# looks like this`. 580</pre> 581<p> 582 will generate: 583 </p> 584<p> 585 Python's <code class="computeroutput"><span class="keyword">import</span></code> is rather like 586 C++'s <code class="computeroutput"><span class="preprocessor">#include</span></code>. A C++ comment 587 <code class="computeroutput"><span class="comment">// looks like this</span></code> whereas a 588 Python comment <code class="computeroutput"><span class="comment">#looks like this</span></code>. 589 </p> 590<p> 591 Quickbook 1.7 introduced the <code class="computeroutput">!</code> element which can be used to 592 set the source mode of the following element: 593 </p> 594<pre class="programlisting">[teletype] 595Example in C++: [!c++] `int main() {}`, 596example with no highlighting: `int main() {}`. 597</pre> 598<p> 599 will generate: 600 </p> 601<p> 602 Example in C++: <code class="computeroutput"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> <span class="special">{}</span></code>, example 603 with no highlighting: <code class="computeroutput">int main() {}</code>. 604 </p> 605<p> 606 In order to change the source mode for a whole paragraph, put the <code class="computeroutput">!</code> 607 element on a separate line before the paragraph: 608 </p> 609<pre class="programlisting">[!c++] 610`int main() {}` is highlighted as C++, as is `//example`. 611 612[!c++] `int main() {}` is also highlighted as C++, 613but `//example` isn't. 614</pre> 615<p> 616 generates: 617 </p> 618<p> 619 <code class="computeroutput"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> <span class="special">{}</span></code> is highlighted 620 as C++, as is <code class="computeroutput"><span class="comment">//example</span></code>. 621 </p> 622<p> 623 <code class="computeroutput"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> <span class="special">{}</span></code> is also 624 highlighted as C++, but <code class="computeroutput">//example</code> isn't. 625 </p> 626<p> 627 The <code class="computeroutput">!</code> element can also be used to set the source mode for blocks 628 and sections. For example: 629 </p> 630<pre class="programlisting">[!python] 631[section:python Section in which all code samples use python] 632 633[/...] 634 635[endsect:python] 636 637[!c++] 638[section:cpp Section in which all code samples use C++] 639 640[/...] 641 642[endsect:cpp] 643</pre> 644<p> 645 Or to set the source mode for a table: 646 </p> 647<pre class="programlisting">[!teletype] 648[table 649 [[code][meaning]] 650 [[`+`][addition]] 651] 652</pre> 653<div class="table"> 654<a name="quickbook.syntax.phrase.source_mode.supported_source_modes"></a><p class="title"><b>Table 50.2. Supported Source Modes</b></p> 655<div class="table-contents"><table class="table" summary="Supported Source Modes"> 656<colgroup> 657<col> 658<col> 659</colgroup> 660<thead><tr> 661<th> 662 <p> 663 Mode 664 </p> 665 </th> 666<th> 667 <p> 668 Source Mode Markup 669 </p> 670 </th> 671</tr></thead> 672<tbody> 673<tr> 674<td> 675 <p> 676 C++ 677 </p> 678 </td> 679<td> 680 <p> 681 <code class="literal">[c++]</code> 682 </p> 683 </td> 684</tr> 685<tr> 686<td> 687 <p> 688 Python 689 </p> 690 </td> 691<td> 692 <p> 693 <code class="literal">[python]</code> 694 </p> 695 </td> 696</tr> 697<tr> 698<td> 699 <p> 700 Plain Text 701 </p> 702 </td> 703<td> 704 <p> 705 <code class="literal">[teletype]</code> 706 </p> 707 </td> 708</tr> 709</tbody> 710</table></div> 711</div> 712<br class="table-break"><div class="note"><table border="0" summary="Note"> 713<tr> 714<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../doc/src/images/note.png"></td> 715<th align="left">Note</th> 716</tr> 717<tr><td align="left" valign="top"><p> 718 The source mode strings are lowercase. 719 </p></td></tr> 720</table></div> 721</div> 722<div class="section"> 723<div class="titlepage"><div><div><h3 class="title"> 724<a name="quickbook.syntax.phrase.line_break"></a><a name="quickbook.ref.line_break"></a><a class="link" href="phrase.html#quickbook.syntax.phrase.line_break" title="line-break">line-break</a> 725</h3></div></div></div> 726<pre class="programlisting">[br] 727</pre> 728<div class="warning"><table border="0" summary="Warning"> 729<tr> 730<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../doc/src/images/warning.png"></td> 731<th align="left">Warning</th> 732</tr> 733<tr><td align="left" valign="top"><p> 734 <code class="computeroutput">[br]</code> generates invalid docbook. It seems to mostly work okay 735 but there might be problems, especially when using an alternative docbook 736 processor. 737 </p></td></tr> 738</table></div> 739</div> 740<div class="section"> 741<div class="titlepage"><div><div><h3 class="title"> 742<a name="quickbook.syntax.phrase.anchors"></a><a name="quickbook.ref.anchors"></a><a class="link" href="phrase.html#quickbook.syntax.phrase.anchors" title="Anchors">Anchors</a> 743</h3></div></div></div> 744<pre class="programlisting">[#named_anchor] 745</pre> 746<p> 747 A named anchor is a hook that can be referenced by a link elsewhere in the 748 document. You can then reference an anchor with <code class="computeroutput">[link named_anchor 749 Some link text]</code>. See <a class="link" href="phrase.html#quickbook.ref.anchor_links">Anchor 750 links</a>, <a class="link" href="structure.html#quickbook.ref.section">Section</a> and <a class="link" href="block.html#quickbook.ref.headings">Heading</a>. 751 </p> 752<p> 753 These anchors are global and can be accessed from anywhere in the quickbook 754 documentation. Be careful to avoid clashes with anchors in other sections. 755 </p> 756</div> 757<div class="section"> 758<div class="titlepage"><div><div><h3 class="title"> 759<a name="quickbook.syntax.phrase.links"></a><a name="quickbook.ref.links"></a><a class="link" href="phrase.html#quickbook.syntax.phrase.links" title="Links">Links</a> 760</h3></div></div></div> 761<pre class="programlisting">[@http://www.boost.org this is [*boost's] website....] 762</pre> 763<p> 764 will generate: 765 </p> 766<p> 767 <a href="http://www.boost.org" target="_top">this is <span class="bold"><strong>boost's</strong></span> 768 website....</a> 769 </p> 770<p> 771 URL links where the link text is the link itself is common. Example: 772 </p> 773<pre class="programlisting">see http://spirit.sourceforge.net/ 774</pre> 775<p> 776 so, when the text is absent in a link markup, the URL is assumed. Example: 777 </p> 778<pre class="programlisting">see [@http://spirit.sourceforge.net/] 779</pre> 780<p> 781 will generate: 782 </p> 783<p> 784 see <a href="http://spirit.sourceforge.net/" target="_top">http://spirit.sourceforge.net/</a> 785 </p> 786<p> 787 Boostbook also support a custom url schema for linking to files within the 788 boost distribution: 789 </p> 790<pre class="programlisting">[@boost:/libs/spirit/index.html the Boost.Spirit documentation] 791</pre> 792<p> 793 will generate: <a href="../../../../libs/spirit/index.html" target="_top">the Boost.Spirit 794 documentation</a> 795 </p> 796<p> 797 Note that this is only available when using BoostBook, and only for links 798 - it can't be used for images. 799 </p> 800</div> 801<div class="section"> 802<div class="titlepage"><div><div><h3 class="title"> 803<a name="quickbook.syntax.phrase.anchor_links"></a><a name="quickbook.ref.anchor_links"></a><a class="link" href="phrase.html#quickbook.syntax.phrase.anchor_links" title="Anchor links">Anchor 804 links</a> 805</h3></div></div></div> 806<p> 807 You can link within a document using: 808 </p> 809<pre class="programlisting">[link document_id.section_id.normalized_header_text The link text] 810</pre> 811<p> 812 See sections <a class="link" href="structure.html#quickbook.ref.section">Section</a> and <a class="link" href="block.html#quickbook.ref.headings">Heading</a> for more info. 813 </p> 814</div> 815<div class="section"> 816<div class="titlepage"><div><div><h3 class="title"> 817<a name="quickbook.syntax.phrase.refentry_links"></a><a name="quickbook.ref.refentry_links"></a><a class="link" href="phrase.html#quickbook.syntax.phrase.refentry_links" title="refentry links">refentry 818 links</a> 819</h3></div></div></div> 820<p> 821 In addition, you can link internally to an XML refentry like: 822 </p> 823<pre class="programlisting">[link xml.refentry The link text] 824</pre> 825<p> 826 This gets converted into <code class="literal"><link linkend="xml.refentry">The 827 link text</link></code>. 828 </p> 829<p> 830 Like URLs, the link text is optional. If this is not present, the link text 831 will automatically be the refentry. Example: 832 </p> 833<pre class="programlisting">[link xml.refentry] 834</pre> 835<p> 836 This gets converted into <code class="literal"><link linkend="xml.refentry">xml.refentry</link></code>. 837 </p> 838</div> 839<div class="section"> 840<div class="titlepage"><div><div><h3 class="title"> 841<a name="quickbook.syntax.phrase.code_links"></a><a name="quickbook.ref.code_links"></a><a class="link" href="phrase.html#quickbook.syntax.phrase.code_links" title="Code Links">Code 842 Links</a> 843</h3></div></div></div> 844<p> 845 If you want to link to a function, class, member, enum, concept, global, 846 or header in the reference section, you can use: 847 </p> 848<pre class="programlisting">[funcref fully::qualified::function_name The link text] 849[classref fully::qualified::class_name The link text] 850[memberref fully::qualified::member_name The link text] 851[enumref fully::qualified::enum_name The link text] 852[macroref MACRO_NAME The link text] 853[conceptref ConceptName The link text] 854[headerref path/to/header.hpp The link text] 855[globalref fully::qualified::global The link text] 856</pre> 857<p> 858 Again, the link text is optional. If this is not present, the link text will 859 automatically be the function, class, member, enum, macro, concept, global, 860 or header name. Example: 861 </p> 862<pre class="programlisting">[classref boost::bar::baz] 863</pre> 864<p> 865 would have "boost::bar::baz" as the link text. 866 </p> 867</div> 868<div class="section"> 869<div class="titlepage"><div><div><h3 class="title"> 870<a name="quickbook.syntax.phrase.escape"></a><a name="quickbook.ref.escape"></a><a class="link" href="phrase.html#quickbook.syntax.phrase.escape" title="Escape">Escape</a> 871</h3></div></div></div> 872<p> 873 The escape mark-up is used when we don't want to do any processing. 874 </p> 875<pre class="programlisting">''' 876escape (no processing/formatting) 877''' 878</pre> 879<p> 880 Escaping allows us to pass XML markup to <a href="http://www.boost.org/doc/html/boostbook.html" target="_top">BoostBook</a> 881 or <a href="http://www.docbook.org/" target="_top">DocBook</a>. For example: 882 </p> 883<pre class="programlisting">''' 884<emphasis role="bold">This is direct XML markup</emphasis> 885''' 886</pre> 887<p> 888 <span class="bold"><strong>This is direct XML markup</strong></span> 889 </p> 890<div class="important"><table border="0" summary="Important"> 891<tr> 892<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../doc/src/images/important.png"></td> 893<th align="left">Important</th> 894</tr> 895<tr><td align="left" valign="top"><p> 896 Be careful when using the escape. The text must conform to <a href="http://www.boost.org/doc/html/boostbook.html" target="_top">BoostBook</a>/<a href="http://www.docbook.org/" target="_top">DocBook</a> syntax. 897 </p></td></tr> 898</table></div> 899</div> 900<div class="section"> 901<div class="titlepage"><div><div><h3 class="title"> 902<a name="quickbook.syntax.phrase.single_char_escape"></a><a name="quickbook.ref.single_char_escape"></a><a class="link" href="phrase.html#quickbook.syntax.phrase.single_char_escape" title="Single char escape">Single 903 char escape</a> 904</h3></div></div></div> 905<p> 906 The backslash may be used to escape a single punctuation character. The punctuation 907 immediately after the backslash is passed without any processing. This is 908 useful when we need to escape QuickBook punctuations such as <code class="computeroutput">[</code> 909 and <code class="computeroutput">]</code>. For example, how do you escape the triple quote? Simple: 910 <code class="literal">\'\'\'</code> 911 </p> 912<p> 913 <code class="computeroutput">\n</code> has a special meaning. It is used to generate line breaks. 914 </p> 915<div class="warning"><table border="0" summary="Warning"> 916<tr> 917<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../doc/src/images/warning.png"></td> 918<th align="left">Warning</th> 919</tr> 920<tr><td align="left" valign="top"><p> 921 <code class="computeroutput">\n</code> is now deprecated, use <a class="link" href="phrase.html#quickbook.ref.line_break"><code class="computeroutput">[br]</code></a> 922 instead. Although, use it sparingly as it can generated invalid docbook 923 </p></td></tr> 924</table></div> 925<p> 926 The escaped space: <code class="computeroutput">\ </code> also has a special meaning. The escaped 927 space is removed from the output. 928 </p> 929</div> 930<div class="section"> 931<div class="titlepage"><div><div><h3 class="title"> 932<a name="quickbook.syntax.phrase.unicode_escape"></a><a name="quickbook.ref.unicode_escape"></a><a class="link" href="phrase.html#quickbook.syntax.phrase.unicode_escape" title="Unicode escape">Unicode 933 escape</a> 934</h3></div></div></div> 935<p> 936 You can enter any 16-bit unicode character by using <code class="computeroutput">\u</code> followed 937 by its 4 digit hexadecimal code, or a 32-bit character by using <code class="computeroutput">\U</code> 938 followed by an 8 digit hexadecimal code. eg. 939 </p> 940<pre class="programlisting">\u03B1 + \u03B2 941</pre> 942<p> 943 will generate: 944 </p> 945<div class="blockquote"><blockquote class="blockquote"><p> 946 α + β 947 </p></blockquote></div> 948</div> 949<div class="section"> 950<div class="titlepage"><div><div><h3 class="title"> 951<a name="quickbook.syntax.phrase.images"></a><a name="quickbook.ref.images"></a><a class="link" href="phrase.html#quickbook.syntax.phrase.images" title="Images">Images</a> 952</h3></div></div></div> 953<pre class="programlisting">[$image.jpg] 954</pre> 955<p> 956 From version 1.5, you can also use <a href="http://www.docbook.org/tdg/en/html/imagedata.html" target="_top">DocBook 957 imagedata attributes</a>: 958 </p> 959<pre class="programlisting">[$image.jpg [width 200in] [height 200in]] 960</pre> 961</div> 962<div class="section"> 963<div class="titlepage"><div><div><h3 class="title"> 964<a name="quickbook.syntax.phrase.footnotes"></a><a name="quickbook.ref.footnotes"></a><a class="link" href="phrase.html#quickbook.syntax.phrase.footnotes" title="Footnotes">Footnotes</a> 965</h3></div></div></div> 966<p> 967 As of version 1.3, QuickBook supports footnotes. Just put the text of the 968 footnote in a <code class="computeroutput">[footnote]</code> block, and the text will be put at 969 the bottom of the current page. For example, this: 970 </p> 971<pre class="programlisting">[footnote A sample footnote] 972</pre> 973<p> 974 will generate this<a href="#ftn.quickbook.syntax.phrase.footnotes.f0" class="footnote" name="quickbook.syntax.phrase.footnotes.f0"><sup class="footnote">[39]</sup></a>. 975 </p> 976</div> 977<div class="section"> 978<div class="titlepage"><div><div><h3 class="title"> 979<a name="quickbook.syntax.phrase.macro_expansion"></a><a name="quickbook.ref.macro_expansion"></a><a class="link" href="phrase.html#quickbook.syntax.phrase.macro_expansion" title="Macro Expansion">Macro 980 Expansion</a> 981</h3></div></div></div> 982<pre class="programlisting">__a_macro_identifier__ 983</pre> 984<p> 985 See <a class="link" href="block.html#quickbook.ref.macros">Macros</a> for details. 986 </p> 987</div> 988<div class="section"> 989<div class="titlepage"><div><div><h3 class="title"> 990<a name="quickbook.syntax.phrase.template_expansion"></a><a name="quickbook.ref.template_expansion"></a><a class="link" href="phrase.html#quickbook.syntax.phrase.template_expansion" title="Template Expansion">Template 991 Expansion</a> 992</h3></div></div></div> 993<pre class="programlisting">[a_template_identifier] 994</pre> 995<p> 996 See <a class="link" href="block.html#quickbook.ref.templates">Templates</a> for details. 997 </p> 998</div> 999<div class="section"> 1000<div class="titlepage"><div><div><h3 class="title"> 1001<a name="quickbook.syntax.phrase.cond"></a><a name="quickbook.ref.cond"></a><a class="link" href="phrase.html#quickbook.syntax.phrase.cond" title="Conditional Generation">Conditional 1002 Generation</a> 1003</h3></div></div></div> 1004<p> 1005 Like C++ <code class="computeroutput">#ifdef</code>, you can generate phrases depending on the presence 1006 of a macro. Example: 1007 </p> 1008<pre class="programlisting">[? __to_be__ To be or not to be] 1009</pre> 1010<p> 1011 Here, the phrase "To be or not to be" will only be generated if 1012 the macro symbol <code class="computeroutput">__to_be__</code> has been previously defined. The 1013 phrase above will not do anything since we haven't defined <code class="computeroutput">__to_be__</code>. 1014 Now, let's define the symbol: 1015 </p> 1016<pre class="programlisting">[def __to_be__] 1017 1018[? __to_be__ To be or not to be] 1019</pre> 1020<p> 1021 Which results in: 1022 </p> 1023<pre class="programlisting">To be or not to be 1024</pre> 1025<p> 1026 In quickbook 1.7, you can generate output when a macro isn't defined: 1027 </p> 1028<pre class="programlisting">[?! __to_be__ Not to be] 1029</pre> 1030</div> 1031<div class="footnotes"> 1032<br><hr style="width:100; text-align:left;margin-left: 0"> 1033<div id="ftn.quickbook.syntax.phrase.simple_formatting.f0" class="footnote"><p><a href="#quickbook.syntax.phrase.simple_formatting.f0" class="para"><sup class="para">[38] </sup></a> 1034 Thanks to David Barrett, author of <a href="http://quinthar.com/qwikiwiki/index.php?page=Home" target="_top">Qwiki</a>, 1035 for sharing these samples and teaching me these obscure formatting rules. 1036 I wasn't sure at all if <a href="http://spirit.sourceforge.net" target="_top">Spirit</a>, 1037 being more or less a formal EBNF parser, can handle the context sensitivity 1038 and ambiguity. 1039 </p></div> 1040<div id="ftn.quickbook.syntax.phrase.footnotes.f0" class="footnote"><p><a href="#quickbook.syntax.phrase.footnotes.f0" class="para"><sup class="para">[39] </sup></a> 1041 A sample footnote 1042 </p></div> 1043</div> 1044</div> 1045<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 1046<td align="left"></td> 1047<td align="right"><div class="copyright-footer">Copyright © 2002, 2004, 2006 Joel de Guzman, 1048 Eric Niebler<br>Copyright © 2010-2017 Daniel James<p> 1049 Distributed under the Boost Software License, Version 1.0. (See accompanying 1050 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>) 1051 </p> 1052</div></td> 1053</tr></table> 1054<hr> 1055<div class="spirit-nav"> 1056<a accesskey="p" href="structure.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="block.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> 1057</div> 1058</body> 1059</html> 1060
