quickbook/doc/phrase.qbk

[/
    Copyright 2002,2004,2006 Joel de Guzman, Eric Niebler
    Copyright 2010-2011 Daniel James

    Distributed under 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])
]

[section:phrase Phrase Level Elements]

[section Font Styles]

[pre'''
['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:

[pre'''
[*['bold-italic]]
''']

will generate:

[*['bold-italic]]

[endsect] [/Font Styles]

[section Replaceable]

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

[pre'''
[~replacement]
''']

This will generate:

[~replacement]

[endsect] [/Replaceable]

[section Quotations]

[pre'''
["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:

[pre'''
["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.]

[endsect] [/Quotations]

[section Simple formatting]

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

[pre'''
/italic/, *bold*, _underline_, =teletype=
''']

will generate:

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

Unlike QuickBook's standard formatting scheme, the rules for simpler
alternatives are much stricter[footnote Thanks to David Barrett, author of
[@http://quinthar.com/qwikiwiki/index.php?page=Home 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.].

* Simple markups cannot nest. You can combine a simple markup with a nestable markup.
* Simple markups cannot contain any other form of quickbook 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 block, 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 block.
  We do not want the rest of the document to be rendered bold just because we
  forgot a trailing '*'. A single block is terminated by two end of lines or
  the close bracket: ']'.
* A line starting with the star will be interpreted as an unordered list.
  See __unordered_lists__.

[table 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*]]]
    [[[^'''*side-by*/-side/''']]                        [*side-by*/-side/]]
]

As mentioned, simple markups cannot go past a single block. The text
from "have" to "full" in the following paragraph will be rendered as
bold:

[pre'''
Baa baa black sheep, *have you any wool?
Yes sir, yes sir, three bags full!*
One for the master, one for the dame,
And one for the little boy who lives down the lane.
''']

Baa baa black sheep, *have you any wool?
Yes sir, yes sir, three bags full!*
One for the master, one for the dame,
And one for the little boy who lives down the lane.

But in the following paragraph, bold is not applied:

[pre'''
Baa baa black sheep, *have you any wool?
Yes sir, yes sir, three bags full!
One for the master, one for the dame,
And one for the little boy who lives down the lane.
''']

Baa baa black sheep, *have you any wool?
Yes sir, yes sir, three bags full!
One for the master, one for the dame,
And one for the little boy who lives down the lane.

[endsect] [/Simple Formatting]

[section Inline code]

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

[pre'''
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 We simply enclose the code with the tick: [^'''"`"'''], not the
single quote: `"'"`. Note too that [^'''`some code`'''] is preferred over
[^'''[^some code]''']. ]

[endsect] [/Inline Code]

[section 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:

[pre
\`\`
    #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;
    }
``

[endsect] [/Code blocks]

[section 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:

[pre'''
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 [python] `import` is rather like C++'s [c++] `#include`. A
C++ comment `// looks like this` whereas a Python comment [python]
`#looks like this`.

[teletype]

[table Supported Source Modes
    [[Mode]                 [Source Mode Markup]]
    [[C++]                  [[^\[c++\]]]]
    [[Python]               [[^\[python\]]]]
    [[Plain Text]           [[^\[teletype\]]]]
]

[note The source mode strings are lowercase.]

[endsect] [/Source Mode]

[section line-break]

[pre'''
[br]
''']

[warning `[br]` is now deprecated. __blurbs__, __admonitions__ and
table cells (see __tables__) may now contain paragraphs.]

[endsect]
[section Anchors]

[pre'''
[#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__.

These anchors are global and can be accessed from anywhere in the
quickbook documentation. Be careful to avoid clashes with anchors in
other sections.

[endsect] [/Line break]

[section Links]

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

will generate:

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

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

[pre'''
see http://spirit.sourceforge.net/
''']

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

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

will generate:

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

Boostbook also support a custom url schema for linking to files within
the boost distribution:

[pre
'''[@boost:/libs/spirit/index.html the Boost.Spirit documentation]'''
]

will generate: [@boost:/libs/spirit/index.html the Boost.Spirit documentation]

Note that this is only available when using BoostBook, and only for links
- it can't be used for images.

[endsect] [/Links]

[section Anchor links]

You can link within a document using:

[pre'''
[link document_id.section_id.normalized_header_text The link text]
''']

See sections __section__ and __heading__ for more info.

[endsect] [/Anchor links]

[section refentry links]

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

[pre'''
[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:

[pre'''
[link xml.refentry]
''']

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

[endsect] [/refentry links]

[section:code_links Code Links]

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

[pre'''
[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]
[macroref MACRO_NAME The link text]
[conceptref ConceptName The link text]
[headerref path/to/header.hpp The link text]
[globalref fully::qualified::global The link text]
''']

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

[pre'''
[classref boost::bar::baz]
''']

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

[endsect] [/Code Links]

[section Escape]

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

[pre
\'\'\'
escape (no processing/formatting)
\'\'\'
]

Escaping allows us to pass XML markup to __boostbook__ or __docbook__. For example:

[pre
\'\'\'
<emphasis role="bold">This is direct XML markup</emphasis>
\'\'\'
]

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

[important Be careful when using the escape. The text must conform to
__boostbook__/__docbook__ syntax.]

[endsect] [/Escape]

[section 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.

[warning `\n` and `[br]` are now deprecated. __blurbs__, __admonitions__
and table cells (see __tables__) may now contain paragraphs.]

The escaped space: `\ ` also has a special meaning. The escaped space is removed
from the output.

[endsect] [/Single char escape]

[section Unicode escape]

You can enter any 16-bit unicode character by using `\u` followed by its 4 digit
hexadecimal code, or a 32-bit character by using `\U` followed by an 8 digit
hexadecimal code. eg.

[pre'''
\u03B1 + \u03B2
''']

will generate:

[:
\u03B1 + \u03B2
]

[endsect] [/Unicode escape]

[section Images]

[pre'''
[$image.jpg]
''']

From version 1.5, you can also use
[@http://www.docbook.org/tdg/en/html/imagedata.html
DocBook imagedata attributes]:

[pre'''
[$image.jpg [width 200in] [height 200in]]
''']

[endsect] [/Images]

[section 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:

[pre'''
[footnote A sample footnote]
''']

will generate this[footnote A sample footnote].

[endsect] [/Footnotes]

[section Macro Expansion]

[pre'''
__a_macro_identifier__
''']

See __macros__ for details.

[endsect] [/Macro Expansion]

[section Template Expansion]

[pre'''
[a_template_identifier]
''']

See __templates__ for details.

[endsect] [/Template Expansion]

[section:cond Conditional Generation]

Like C++ `#ifdef`, you can generate phrases depending on the presence of
a macro. Example:

[pre'''
[? __to_be__ To be or not to be]
''']

[? __to_be__ To be or not to be]

Here, the phrase "To be or not to be" will only be generated if the
macro symbol '''__to_be__''' has been previously defined. The phrase
above will not do anything since we haven't defined '''__to_be__'''.
Now, let's define the symbol:

[pre'''
[def __to_be__]
''']

[def __to_be__]

And try again:

[? __to_be__ To be or not to be]

Yes![footnote Conditional Generation makes quickbook turing complete.]

[endsect] [/Condition Generation]

[endsect] [/Phrase Level Elements]