...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
['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
When you want content that may or must be replaced by the user, use the syntax:
[~replacement]
This will generate:
replacement
["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 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[36].
Table 50.1. More Formatting Samples
Markup |
Result |
---|---|
|
|
|
|
|
|
|
This*Isn't*Bold (no bold) |
|
(Bold Inside) (parenthesis not bold) |
|
|
|
3*4*5 = 60 (no bold) |
|
3 * 4 * 5 = 60 (no bold) |
|
3 4 5 = 60 (4 is bold) |
|
|
|
|
|
|
|
Bold-Italic |
|
|
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:
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:
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.
This generates a docbook phrase with a role
attribute, which
can be used to classify the phrase. This can be used to mark text for a use
that isn't covered elsewhere. The docbook role
will generate
a html class, which can be used to style text. And the xsl stylesheets can
be customized to treat certain roles specially when generating pdfs.
The boostbook css stylesheets, and xsl stylesheets contain support for a
limited number of colours that can be used with role
. For example
if you write:
[role red Text content]
You'll get red text if you're using the boostbook css (for html) or the boostbook xsl for generating pdfs.
The full list of colours that will be available is:
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 | |
---|---|
We simply enclose the code with the tick: |
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 or triple-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; } ``
or:
``` #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; }
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
.
Quickbook 1.7 introduced the !
element which can be used to
set the source mode of the following element:
[teletype] Example in C++: [!c++] `int main() {}`, example with no highlighting: `int main() {}`.
will generate:
Example in C++: int main() {}
, example
with no highlighting: int main() {}
.
In order to change the source mode for a whole paragraph, put the !
element on a separate line before the paragraph:
[!c++] `int main() {}` is highlighted as C++, as is `//example`. [!c++] `int main() {}` is also highlighted as C++, but `//example` isn't.
generates:
int main() {}
is highlighted
as C++, as is //example
.
int main() {}
is also
highlighted as C++, but //example
isn't.
The !
element can also be used to set the source mode for blocks
and sections. For example:
[!python] [section:python Section in which all code samples use python] [/...] [endsect:python] [!c++] [section:cpp Section in which all code samples use C++] [/...] [endsect:cpp]
Or to set the source mode for a table:
[!teletype] [table [[code][meaning]] [[`+`][addition]] ]
Table 50.2. Supported Source Modes
Mode |
Source Mode Markup |
---|---|
C++ |
|
Python |
|
Plain Text |
|
Note | |
---|---|
The source mode strings are lowercase. |
[br]
Warning | |
---|---|
|
[#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.
[@http://www.boost.org this is [*boost's] website....]
will generate:
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/
Boostbook also support a custom url schema for linking to files within the boost distribution:
[@boost:/libs/spirit/index.html the Boost.Spirit documentation]
will generate: the Boost.Spirit documentation
Note that this is only available when using BoostBook, and only for links - it can't be used for images.
You can link within a document using:
[link document_id.section_id.normalized_header_text The link text]
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>
.
If you want to link to a function, class, member, enum, concept, global, 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] [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:
[classref boost::bar::baz]
would have "boost::bar::baz" as the link text.
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
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 | |
---|---|
|
The escaped space: \
also has a special meaning. The escaped
space is removed from the output.
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.
\u03B1 + \u03B2
will generate:
α + β
[$image.jpg]
From version 1.5, you can also use DocBook imagedata attributes:
[$image.jpg [width 200in] [height 200in]]
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[37].
Like C++ #ifdef
, you can generate phrases depending on the presence
of a macro. Example:
[? __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:
[def __to_be__] [? __to_be__ To be or not to be]
Which results in:
To be or not to be
In quickbook 1.7, you can generate output when a macro isn't defined:
[?! __to_be__ Not to be]