<-- Copyright (c) 2002 2004 Joel de Guzman Copyright (c) 2004 Eric Niebler http://spirit.sourceforge.net/ Use, modification and distribution is subject to the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> Phrase Level Elements - 1.34.0

Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of boost. Click here for the latest Boost documentation.
PrevUpHomeNext

Phrase Level Elements

Font Styles
Replaceable
Quotations
Simple formatting
Inline code
Code blocks
Source Mode
line-break
Anchors
Links
Anchor links
refentry links
Code Links
Escape
Single char escape
Images
Footnotes

Font Styles

['italic], [*bold], [_underline], [^teletype], [-strikethrough]

will generate:

italic, bold, underline, teletype, strikethrough

Like all non-terminal phrase level elements, this can of course be nested:

[*['bold-italic]]

will generate:

bold-italic

Replaceable

When you want content that may or must be replaced by the user, use the syntax:

[~replacement]

This will generate:

replacement

Quotations

["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein

will generate:

A question that sometimes drives me hazy: am I or are the others crazy?”--Einstein

Note the proper left and right quote marks. Also, while you can simply use ordinary quote marks like "quoted", our quotation, above, will generate correct DocBook quotations (e.g. <quote>quoted</quote>).

Like all phrase elements, quotations may be nested. Example:

["Here's the rule for bargains: ["Do other men, for they would do you.] That's
the true business precept.]

will generate:

Here's the rule for bargains: ‘Do other men, for they would do you.’ That's the true business precept.

Simple formatting

Simple markup for formatting text, common in many applications, is now supported:

/italic/, *bold*, _underline_, =teletype=

will generate:

italic, bold, underline, teletype

Unlike QuickBook's standard formatting scheme, the rules for simpler alternatives are much stricter.

  • Simple markups cannot nest. You can combine a simple markup with a nestable markup.
  • A non-space character must follow the leading markup
  • A non-space character must precede the trailing markup
  • A space or a punctuation must follow the trailing markup
  • If the matching markup cannot be found within a line, the formatting will not be applied. This is to ensure that un-matched formatting markups, which can be a common mistake, does not corrupt anything past a single line. We do not want the rest of the document to be rendered bold just because we forgot a trailing '*'.
  • A line starting with the star will be interpreted as an unordered list. See Unordered lists.

More Formatting Samples

Markup Result
*Bold* Bold
*Is bold* Is bold
* Not bold* *Not bold * * Not bold * * Not bold* *Not bold * * Not bold *
This*Isn't*Bold (no bold) This*Isn't*Bold (no bold)
(*Bold Inside*) (parenthesis not bold) (Bold Inside) (parenthesis not bold)
*(Bold Outside)* (parenthesis bold) (Bold Outside) (parenthesis bold)
3*4*5 = 60 (no bold) 3*4*5 = 60 (no bold)
3 * 4 * 5 = 60 (no bold) 3 * 4 * 5 = 60 (no bold)
3 *4* 5 = 60 (4 is bold) 3 4 5 = 60 (4 is bold)
*This is bold* this is not *but this is* This is bold this is not but this is
*This is bold*. This is bold.
*B*. (bold B) B. (bold B)
['*Bold-Italic*] Bold-Italic
note Thanks to David Barrett, author of Qwiki, for sharing these samples and teaching me these obscure formatting rules. I wasn't sure at all if Spirit, being more or less a formal EBNF parser, can handle the context sensitivity and ambiguity.

Inline code

Inlining code in paragraphs is quite common when writing C++ documentation. We provide a very simple markup for this. For example, this:

This text has inlined code `int main() { return 0; }` in it.

will generate:

This text has inlined code int main() { return 0; } in it. The code will be syntax highlighted.

note Note that we simply enclose the code with the tick: "`" , not the single quote: "'". Note too that `some code` is preferred over [^some code] .

Code blocks

Preformatted code simply starts with a space or a tab (See Code). However, such a simple syntax cannot be used as phrase elements in lists (See Ordered lists and Unordered lists), tables (See Tables), etc. Inline code (see above) can. The problem is, inline code does not allow formatting with newlines, spaces, and tabs. These are lost.

We provide a phrase level markup that is a mix between the two. By using the double-tick, instead of the single-tick, we are telling QuickBook to use preformatted blocks of code. Example:

``
    #include <iostream>

    int main()
    {
        std::cout << "Hello, World!" << std::endl;
        return 0;
    }
``

will generate:

#include <iostream>

int main()
{
    std::cout << "Hello, World!" << std::endl;
    return 0;
}

Source Mode

If a document contains more than one type of source code then the source mode may be changed dynamically as the document is processed. All QuickBook documents are initially in C++ mode by default, though an alternative initial value may be set in the Document section.

To change the source mode, use the [source-mode] markup, where source-mode is one of the supported modes. For example, this:

Python's [python] `import` is rather like C++'s [c++] `#include`. A
C++ comment `// looks like this` whereas a Python comment [python]
`# looks like this`.

will generate:

Python's import is rather like C++'s #include. A C++ comment // looks like this whereas a Python comment #looks like this.

Supported Source Modes

Mode Source Mode Markup
C++ [c++]
Python [python]
note The source mode strings are lowercase.

line-break

[br]
note Note that \n is now preferred over [br].

Anchors

[#named_anchor]

A named anchor is a hook that can be referenced by a link elsewhere in the document. You can then reference an anchor with [link named_anchor Some link text] . See Anchor links, Section and Heading.

Links

[@http://www.boost.org this is [*boost's] website....]

will generate:

this is boost's website....

URL links where the link text is the link itself is common. Example:

see http://spirit.sourceforge.net/

so, when the text is absent in a link markup, the URL is assumed. Example:

see [@http://spirit.sourceforge.net/]

will generate:

see http://spirit.sourceforge.net/

Anchor links

You can link within a document using:

[link section_id.normalized_header_text The link text]

See sections Section and Heading for more info.

refentry links

In addition, you can link internally to an XML refentry like:

[link xml.refentry The link text]

This gets converted into <link linkend="xml.refentry">The link text</link>.

Like URLs, the link text is optional. If this is not present, the link text will automatically be the refentry. Example:

[link xml.refentry]

This gets converted into <link linkend="xml.refentry">xml.refentry</link>.

Code Links

If you want to link to a function, class, member, enum or header in the reference section, you can use:

[funcref fully::qualified::function_name The link text]
[classref fully::qualified::class_name The link text]
[memberref fully::qualified::member_name The link text]
[enumref fully::qualified::enum_name The link text]
[headerref path/to/header.hpp The link text]

Again, the link text is optional. If this is not present, the link text will automatically be the function, class, member or enum. Example:

[classref boost::bar::baz]

would have "boost::bar::baz" as the link text.

Escape

The escape mark-up is used when we don't want to do any processing.

'''
escape (no processing/formatting)
'''

Escaping allows us to pass XML markup to BoostBook or DocBook. For example:

'''
<emphasis role="bold">This is direct XML markup</emphasis>
'''

This is direct XML markup

alert Be careful when using the escape. The text must conform to BoostBook/DocBook syntax.

Single char escape

The backslash may be used to escape a single punctuation character. The punctuation immediately after the backslash is passed without any processing. This is useful when we need to escape QuickBook punctuations such as [ and ]. For example, how do you escape the triple quote? Simple: \'\'\'

\n has a special meaning. It is used to generate line breaks. Note that \n is now preferred over [br].

Images

[$image.jpg]

Footnotes

As of version 1.3, QuickBook supports footnotes. Just put the text of the footnote in a [footnote] block, and the text will be put at the bottom of the current page. For example, this:

[footnote A sample footnote]

will generate this [1] .



[1] A sample footnote

Copyright © 2002, 2004 Joel de Guzman, Eric Niebler

PrevUpHomeNext