doc/html/quickbook/syntax/phrase.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   5 <title>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&#160;50.&#160;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">&#8220;<span class="quote">A question that sometimes drives me hazy: am I or are the others crazy?</span>&#8221;</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. &lt;quote&gt;quoted&lt;/quote&gt;).
 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
 128 the true business precept.]
 129 </pre>
 130 <p>
 131         will generate:
 132       </p>
 133 <p>
 134         <span class="quote">&#8220;<span class="quote">Here's the rule for bargains: <span class="quote">&#8216;<span class="quote">Do other men, for they would
 135         do you.</span>&#8217;</span> That's the true business precept.</span>&#8221;</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&#160;50.1.&#160;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?
 386 Yes sir, yes sir, three bags full!*
 387 One for the master, one for the dame,
 388 And 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?
 399 Yes sir, yes sir, three bags full!
 400 One for the master, one for the dame,
 401 And 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 &lt;iostream&gt;
 527
 528     int main()
 529     {
 530         std::cout &lt;&lt; "Hello, World!" &lt;&lt; std::endl;
 531         return 0;
 532     }
 533 ``
 534 </pre>
 535 <p>
 536         or:
 537       </p>
 538 <pre class="programlisting">```
 539     #include &lt;iostream&gt;
 540
 541     int main()
 542     {
 543         std::cout &lt;&lt; "Hello, World!" &lt;&lt; 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">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</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">&lt;&lt;</span> <span class="string">"Hello, World!"</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 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
 578 C++ 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]
 595 Example in C++: [!c++] `int main() {}`,
 596 example 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++,
 613 but `//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&#160;50.2.&#160;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">&lt;link linkend="xml.refentry"&gt;The
 827         link text&lt;/link&gt;</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">&lt;link linkend="xml.refentry"&gt;xml.refentry&lt;/link&gt;</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">'''
 876 escape (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 &lt;emphasis role="bold"&gt;This is direct XML markup&lt;/emphasis&gt;
 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           &#945; + &#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 &#169; 2002, 2004, 2006 Joel de Guzman,
1048       Eric Niebler<br>Copyright &#169; 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>