152fe4fa5d
- More consistent names. - Not using `.` in basename. - Run the quickbook manual test last (as when there's an error, the more specific tests are more informative). - Combine some of the code tests. [SVN r75235]
1982 lines
58 KiB
Plaintext
1982 lines
58 KiB
Plaintext
[article Quickbook
|
|
[quickbook 1.4]
|
|
[version 1.4]
|
|
[authors [de Guzman, Joel], [Niebler, Eric]]
|
|
[copyright 2002 2004 2006 Joel de Guzman, Eric Niebler]
|
|
[purpose /WikiWiki/ style documentation tool]
|
|
[license
|
|
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])
|
|
]
|
|
]
|
|
|
|
[/ QuickBook Document version 1.3 ]
|
|
[/ Sept 24, 2002 ]
|
|
[/ Sept 2, 2004 ]
|
|
[/ Feb 14, 2005 ]
|
|
[/ Sept 13, 2005 ]
|
|
|
|
[/ Some links]
|
|
|
|
[def __note__ [$images/note.png]]
|
|
[def __alert__ [$images/alert.png]]
|
|
[def __tip__ [$images/tip.png]]
|
|
[def :-) [$images/smiley.png]]
|
|
[def __spirit__ [@http://spirit.sourceforge.net Spirit]]
|
|
[def __boostbook__ [@http://www.boost.org/doc/html/boostbook.html BoostBook]]
|
|
[def __docbook__ [@http://www.docbook.org/ DocBook]]
|
|
|
|
[def __comments__ [link quickbook.syntax.comments Comments]]
|
|
|
|
[def __font_styles__ [link quickbook.syntax.phrase.font_styles Font Styles]]
|
|
[def __quotations__ [link quickbook.syntax.phrase.quotations Quotations]]
|
|
[def __replaceable__ [link quickbook.syntax.phrase.replaceable Replaceble]]
|
|
[def __simple_formatting__ [link quickbook.syntax.phrase.simple_formatting Simple formatting]]
|
|
[def __inline_code__ [link quickbook.syntax.phrase.inline_code Inline code]]
|
|
[def __code_blocks__ [link quickbook.syntax.phrase.code_blocks Code blocks]]
|
|
[def __source_mode__ [link quickbook.syntax.phrase.source_mode Source Mode]]
|
|
[def __line_break__ [link quickbook.syntax.phrase.line_break line-break]]
|
|
[def __anchors__ [link quickbook.syntax.phrase.anchors Anchors]]
|
|
[def __links__ [link quickbook.syntax.phrase.links Links]]
|
|
[def __anchor_links__ [link quickbook.syntax.phrase.anchor_links Anchor links]]
|
|
[def __refentry_links__ [link quickbook.syntax.phrase.refentry_links refentry links]]
|
|
[def __code_links__ [link quickbook.syntax.phrase.code_links function, class, member, enum, macro, concept or header links]]
|
|
[def __escape__ [link quickbook.syntax.phrase.escape Escape]]
|
|
[def __single_char_escape__ [link quickbook.syntax.phrase.single_char_escape Single char escape]]
|
|
[def __images__ [link quickbook.syntax.phrase.images Images]]
|
|
|
|
[def __document__ [link quickbook.syntax.block.document Document]]
|
|
[def __section__ [link quickbook.syntax.block.section Section]]
|
|
[def __xinclude__ [link quickbook.syntax.block.xinclude xinclude]]
|
|
[def __paragraphs__ [link quickbook.syntax.block.paragraphs Paragraphs]]
|
|
[def __ordered_lists__ [link quickbook.syntax.block.lists.ordered_lists Ordered lists]]
|
|
[def __list_hierarchies__ [link quickbook.syntax.block.lists.list_hierarchies List Hierarchies]]
|
|
[def __long_list_lines__ [link quickbook.syntax.block.lists.long_list_lines Long List Lines]]
|
|
[def __unordered_lists__ [link quickbook.syntax.block.lists.unordered_lists Unordered lists]]
|
|
[def __mixed_lists__ [link quickbook.syntax.block.lists.mixed_lists Mixed lists]]
|
|
[def __code__ [link quickbook.syntax.block.code Code]]
|
|
[def __escape_back__ [link quickbook.syntax.block.escape_back Escaping Back To QuickBook]]
|
|
[def __preformatted__ [link quickbook.syntax.block.preformatted Preformatted]]
|
|
[def __blockquote__ [link quickbook.syntax.block.blockquote Blockquote]]
|
|
[def __heading__ [link quickbook.syntax.block.headings Heading]]
|
|
[def __macros__ [link quickbook.syntax.block.macros Macros]]
|
|
[def __templates__ [link quickbook.syntax.block.templates Templates]]
|
|
[def __predefined_macros__ [link quickbook.syntax.block.predefined_macros Predefined Macros]]
|
|
[def __blurbs__ [link quickbook.syntax.block.blurbs Blurbs]]
|
|
[def __admonitions__ [link quickbook.syntax.block.admonitions Admonitions]]
|
|
[def __tables__ [link quickbook.syntax.block.tables Tables]]
|
|
[def __variable_lists__ [link quickbook.syntax.block.variable_lists Variable Lists]]
|
|
[def __include__ [link quickbook.syntax.block.include Include]]
|
|
[def __import__ [link quickbook.syntax.block.import Import]]
|
|
|
|
[section:intro Introduction]
|
|
|
|
[:[*['["Why program by hand in five days what you can spend five years of your
|
|
life automating?]]]
|
|
|
|
-- Terrence Parr, author ANTLR/PCCTS
|
|
]
|
|
|
|
Well, QuickBook started as a weekend hack. It was originally intended to be a
|
|
sample application using __spirit__. What is it? What you are viewing now, this
|
|
documentation, is autogenerated by QuickBook. These files were generated from
|
|
one master:
|
|
|
|
[:[@../quickbook.qbk quickbook.qbk]]
|
|
|
|
Originally named QuickDoc, this funky tool that never dies evolved into a
|
|
funkier tool thanks to Eric Niebler who resurrected the project making it
|
|
generate __boostbook__ instead of HTML. The __boostbook__ documentation format
|
|
is an extension of __docbook__, an SGML or XML based format for describing
|
|
documentation.
|
|
|
|
QuickBook is a WikiWiki style documentation tool geared towards C++
|
|
documentation using simple rules and markup for simple formatting tasks.
|
|
QuickBook extends the WikiWiki concept. Like the WikiWiki, QuickBook documents are
|
|
simple text files. A single QuickBook document can generate a fully linked set
|
|
of nice HTML and PostScript/PDF documents complete with images and syntax-
|
|
colorized source code.
|
|
|
|
Features include:
|
|
|
|
* generate __boostbook__ xml, to generate HTML, PostScript and PDF
|
|
* simple markup to link to Doxygen-generated entities
|
|
* macro system for simple text substitution
|
|
* simple markup for italics, bold, preformatted, blurbs, code samples,
|
|
tables, URLs, anchors, images, etc.
|
|
* automatic syntax coloring of code samples
|
|
* CSS support
|
|
|
|
[endsect]
|
|
|
|
[section:change_log Change Log]
|
|
|
|
[h3 Version 1.3]
|
|
|
|
* Quickbook file inclusion \[include\].
|
|
* Better xml output (pretty layout). Check out the generated XML.
|
|
* Regression testing facility: to make sure your document will always be
|
|
compatible (full backward compatibility) regardless of changes to
|
|
QuickBook.
|
|
* Code cleanup and refactoring.
|
|
* Allow phrase markup in the doc-info.
|
|
* Preformatted code blocks via \`\`code\`\` (double ticks) allows code in tables
|
|
and lists, for example.
|
|
* Quickbook versioning; allows full backward compatibility. You have to add
|
|
\[quickbook 1.3\] to the doc-info header to enable the new features. Without
|
|
this, QuickBook will assume that the document is a pre-1.3 document.
|
|
* Better (intuitive) paragraph termination. Some markups may terminate a paragraph.
|
|
Example:``
|
|
[section x]
|
|
blah...
|
|
[endsect]``
|
|
* Fully qualified section and headers. Subsection names are concatenated to the
|
|
ID to avoid clashing. Example: `doc_name.sect_name.sub_sect_name.sub_sub_sect_name`
|
|
* Better and whitespace handling in code snippets.
|
|
* \[xinclude\] fixes up the relative path to the target XML file when
|
|
input_directory is not the same as the output_directory.
|
|
* Allow untitled tables.
|
|
* Allow phrase markups in section titles.
|
|
* Allow escaping back to QuickBook from code, code blocks and inline code.
|
|
* Footnotes, with the \[footnote This is the footnote\] syntax.
|
|
* Post-processor bug fix for escaped XML code that it does not recognize.
|
|
* Replaceable, with the \[~replacement\] syntax.
|
|
* Generic Headers
|
|
* Code changes to allow full recursion (i.e. Collectors and push/pop functions)
|
|
* Various code cleanup/maintenance
|
|
* Templates!
|
|
* \[conceptref\] for referencing BoostBook <concept> entities.
|
|
* Allow escape of spaces. The escaped space is removed from the output. Syntax:
|
|
`\ `.
|
|
* Nested comments are now allowed.
|
|
* Quickbook blocks can nest inside comments.
|
|
* __import__ facility.
|
|
* Callouts on imported code
|
|
* Simple markups can now span a whole block.
|
|
* __blurbs__, __admonitions__ and table cells (see __tables__) may now
|
|
contain paragraphs.
|
|
* `\n` and `[br]` are now deprecated.
|
|
|
|
[endsect]
|
|
|
|
[section:syntax Syntax Summary]
|
|
|
|
A QuickBook document is composed of one or more blocks. An example of
|
|
a block is the paragraph or a C++ code snippet. Some blocks have
|
|
special mark-ups. Blocks, except code snippets which have their own
|
|
grammar (C++ or Python), are composed of one or more phrases. A phrase
|
|
can be a simple contiguous run of characters. Phrases can have special
|
|
mark-ups. Marked up phrases can recursively contain other phrases, but
|
|
cannot contain blocks. A terminal is a self contained block-level or
|
|
phrase-level element that does not nest anything.
|
|
|
|
Blocks, in general, are delimited by two end-of-lines (the block terminator).
|
|
Phrases in each block cannot contain a block terminator. This way, syntax errors
|
|
such as un-matched closing brackets do not go haywire and corrupt anything past
|
|
a single block.
|
|
|
|
[section Comments]
|
|
|
|
Can be placed anywhere.
|
|
|
|
[pre
|
|
'''[/ comment (no output generated) ]'''
|
|
]
|
|
|
|
[/ for testing only... ]
|
|
|
|
[pre
|
|
'''[/ comments can be nested [/ some more here] ]'''
|
|
]
|
|
|
|
[/ for testing [/ only ] ]
|
|
|
|
[pre
|
|
'''[/ Quickbook blocks can nest inside comments. [*Comment this out too!] ]'''
|
|
]
|
|
|
|
[/ for testing [*only ] ]
|
|
|
|
[endsect]
|
|
|
|
[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]
|
|
|
|
[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]
|
|
|
|
[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]
|
|
[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]
|
|
[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]
|
|
[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]
|
|
[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`.
|
|
|
|
[table Supported Source Modes
|
|
[[Mode] [Source Mode Markup]]
|
|
[[C++] [[^\[c++\]]]]
|
|
[[Python] [[^\[python\]]]]
|
|
]
|
|
|
|
[note The source mode strings are lowercase.]
|
|
|
|
[endsect]
|
|
[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__.
|
|
|
|
[endsect]
|
|
[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/]
|
|
|
|
[endsect]
|
|
[section Anchor links]
|
|
|
|
You can link within a document using:
|
|
|
|
[pre'''
|
|
[link section_id.normalized_header_text The link text]
|
|
''']
|
|
|
|
See sections __section__ and __heading__ for more info.
|
|
|
|
[endsect]
|
|
[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]
|
|
[section:code_links Code Links]
|
|
|
|
If you want to link to a function, class, member, enum, concept 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]
|
|
''']
|
|
|
|
Again, the link text is optional. If this is not present, the link text will
|
|
automatically be the function, class, member, enum, macro, concept or header. Example:
|
|
|
|
[pre'''
|
|
[classref boost::bar::baz]
|
|
''']
|
|
|
|
would have "boost::bar::baz" as the link text.
|
|
|
|
[endsect]
|
|
[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]
|
|
[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]
|
|
[section Images]
|
|
|
|
[pre'''
|
|
[$image.jpg]
|
|
''']
|
|
|
|
[endsect]
|
|
[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].
|
|
|
|
[section Macro Expansion]
|
|
|
|
[pre'''
|
|
__a_macro_identifier__
|
|
''']
|
|
|
|
See __macros__ for details.
|
|
|
|
[endsect]
|
|
|
|
[section Template Expansion]
|
|
|
|
[pre'''
|
|
[a_template_identifier]
|
|
''']
|
|
|
|
See __templates__ for details.
|
|
|
|
[endsect]
|
|
|
|
[endsect]
|
|
[endsect]
|
|
[section:block Block Level Elements]
|
|
|
|
[section Document]
|
|
|
|
Every document must begin with a Document Info section, which should look
|
|
like this:
|
|
|
|
[pre'''
|
|
[document-type The Document Title
|
|
[quickbook 1.3]
|
|
[version 1.0]
|
|
[id the_document_name]
|
|
[dirname the_document_dir]
|
|
[copyright 2000 2002 2003 Joe Blow, Jane Doe]
|
|
[purpose The document's reason for being]
|
|
[category The document's category]
|
|
[authors [Blow, Joe], [Doe, Jane]]
|
|
[license The document's license]
|
|
[source-mode source-type]
|
|
]
|
|
''']
|
|
|
|
Where document-type is one of:
|
|
|
|
* book
|
|
* article
|
|
* library
|
|
* chapter
|
|
* part
|
|
* appendix
|
|
* preface
|
|
* qandadiv
|
|
* qandaset
|
|
* reference
|
|
* set
|
|
|
|
quickbook 1.3 declares the version of quickbook the document is written for.
|
|
In its absence, version 1.1 is assumed.
|
|
|
|
=version=, =id=, =dirname=, =copyright=, =purpose=, =category=, =authors=,
|
|
=license=, =last-revision= and =source-mode= are optional information.
|
|
|
|
=source-type= is a lowercase string setting the initial __source_mode__. If
|
|
the =source-mode= field is omitted, a default value of =c++= will be used.
|
|
|
|
[endsect]
|
|
[section Section]
|
|
|
|
Starting a new section is accomplished with:
|
|
|
|
[pre'''
|
|
[section:id The Section Title]
|
|
''']
|
|
|
|
where /id/ is optional. id will be the filename of the generated section.
|
|
If it is not present, "The Section Title" will be normalized and become the id.
|
|
Valid characters are =a-Z=, =A-Z=, =0-9= and =_=. All non-valid characters are
|
|
converted to underscore and all upper-case are converted to lower case.
|
|
Thus: "The Section Title" will be normalized to "the_section_title".
|
|
|
|
End a section with:
|
|
|
|
[pre'''
|
|
[endsect]
|
|
''']
|
|
|
|
Sections can nest, and that results in a hierarchy in the table of contents.
|
|
|
|
[endsect]
|
|
[section xinclude]
|
|
|
|
You can include another XML file with:
|
|
|
|
[pre'''
|
|
[xinclude file.xml]
|
|
''']
|
|
|
|
This is useful when file.xml has been generated by Doxygen and contains your
|
|
reference section.
|
|
|
|
[endsect]
|
|
[section Paragraphs]
|
|
|
|
Paragraphs start left-flushed and are terminated by two or more newlines. No
|
|
markup is needed for paragraphs. QuickBook automatically detects paragraphs from
|
|
the context. Block markups \[section, endsect, h1, h2, h3, h4, h5, h6, blurb,
|
|
(block-quote) ':', pre, def, table and include \] may also terminate a paragraph.
|
|
|
|
[endsect]
|
|
|
|
[section Lists]
|
|
[section Ordered lists]
|
|
|
|
[pre
|
|
# One
|
|
# Two
|
|
# Three
|
|
]
|
|
|
|
will generate:
|
|
|
|
# One
|
|
# Two
|
|
# Three
|
|
|
|
[endsect]
|
|
[section List Hierarchies]
|
|
|
|
List hierarchies are supported. Example:
|
|
|
|
[pre
|
|
# One
|
|
# Two
|
|
# Three
|
|
# Three.a
|
|
# Three.b
|
|
# Three.c
|
|
# Four
|
|
# Four.a
|
|
# Four.a.i
|
|
# Four.a.ii
|
|
# Five
|
|
]
|
|
|
|
will generate:
|
|
|
|
# One
|
|
# Two
|
|
# Three
|
|
# Three.a
|
|
# Three.b
|
|
# Three.c
|
|
# Fourth
|
|
# Four.a
|
|
# Four.a.i
|
|
# Four.a.ii
|
|
# Five
|
|
|
|
[endsect]
|
|
[section Long List Lines]
|
|
|
|
Long lines will be wrapped appropriately. Example:
|
|
|
|
[pre
|
|
# A short item.
|
|
# A very long item. A very long item. A very long item.
|
|
A very long item. A very long item. A very long item.
|
|
A very long item. A very long item. A very long item.
|
|
A very long item. A very long item. A very long item.
|
|
A very long item. A very long item. A very long item.
|
|
# A short item.
|
|
]
|
|
|
|
# A short item.
|
|
# A very long item. A very long item. A very long item.
|
|
A very long item. A very long item. A very long item.
|
|
A very long item. A very long item. A very long item.
|
|
A very long item. A very long item. A very long item.
|
|
A very long item. A very long item. A very long item.
|
|
# A short item.
|
|
|
|
[endsect]
|
|
[section Unordered lists]
|
|
|
|
[pre'''
|
|
* First
|
|
* Second
|
|
* Third
|
|
''']
|
|
|
|
will generate:
|
|
|
|
* First
|
|
* Second
|
|
* Third
|
|
|
|
[endsect]
|
|
[section Mixed lists]
|
|
|
|
Mixed lists (ordered and unordered) are supported. Example:
|
|
|
|
[pre'''
|
|
# One
|
|
# Two
|
|
# Three
|
|
* Three.a
|
|
* Three.b
|
|
* Three.c
|
|
# Four
|
|
''']
|
|
|
|
will generate:
|
|
|
|
# One
|
|
# Two
|
|
# Three
|
|
* Three.a
|
|
* Three.b
|
|
* Three.c
|
|
# Four
|
|
|
|
And...
|
|
|
|
[pre'''
|
|
# 1
|
|
* 1.a
|
|
# 1.a.1
|
|
# 1.a.2
|
|
* 1.b
|
|
# 2
|
|
* 2.a
|
|
* 2.b
|
|
# 2.b.1
|
|
# 2.b.2
|
|
* 2.b.2.a
|
|
* 2.b.2.b
|
|
''']
|
|
|
|
will generate:
|
|
|
|
# 1
|
|
* 1.a
|
|
# 1.a.1
|
|
# 1.a.2
|
|
* 1.b
|
|
# 2
|
|
* 2.a
|
|
* 2.b
|
|
# 2.b.1
|
|
# 2.b.2
|
|
* 2.b.2.a
|
|
* 2.b.2.b
|
|
|
|
[endsect]
|
|
[endsect]
|
|
|
|
[section Code]
|
|
|
|
Preformatted code starts with a space or a tab. The code will be
|
|
syntax highlighted according to the current __source_mode__:
|
|
|
|
[c++]
|
|
|
|
#include <iostream>
|
|
|
|
int main()
|
|
{
|
|
// Sample code
|
|
std::cout << "Hello, World\n";
|
|
return 0;
|
|
}
|
|
|
|
[python]
|
|
|
|
import cgi
|
|
|
|
def cookForHtml(text):
|
|
'''"Cooks" the input text for HTML.'''
|
|
|
|
return cgi.escape(text)
|
|
|
|
[c++]
|
|
|
|
Macros that are already defined are expanded in source code. Example:
|
|
|
|
[pre'''
|
|
[def __array__ [@http://www.boost.org/doc/html/array/reference.html array]]
|
|
[def __boost__ [@http://www.boost.org/libs/libraries.htm boost]]
|
|
|
|
using __boost__::__array__;
|
|
''']
|
|
|
|
Generates:
|
|
|
|
[def __array__ [@http://www.boost.org/doc/html/array/reference.html array]]
|
|
[def __boost__ [@http://www.boost.org/libs/libraries.htm boost]]
|
|
|
|
using __boost__::__array__;
|
|
|
|
[endsect]
|
|
[section:escape_back Escaping Back To QuickBook]
|
|
|
|
Inside code, code blocks and inline code, QuickBook does not allow any
|
|
markup to avoid conflicts with the target syntax (e.g. c++). In case you
|
|
need to switch back to QuickBook markup inside code, you can do so using a
|
|
language specific /escape-back/ delimiter. In C++ and Python, the delimiter
|
|
is the double tick (back-quote): "\`\`" and "\`\`". Example:
|
|
|
|
[pre'''
|
|
void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``()
|
|
{
|
|
}
|
|
''']
|
|
|
|
Will generate:
|
|
|
|
void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``()
|
|
{
|
|
}
|
|
|
|
When escaping from code to QuickBook, only phrase level markups are
|
|
allowed. Block level markups like lists, tables etc. are not allowed.
|
|
|
|
[endsect]
|
|
[section Preformatted]
|
|
|
|
Sometimes, you don't want some preformatted text to be parsed as C++. In such
|
|
cases, use the [^[pre ... \]] markup block.
|
|
|
|
[pre'''
|
|
[pre
|
|
|
|
Some *preformatted* text Some *preformatted* text
|
|
|
|
Some *preformatted* text Some *preformatted* text
|
|
|
|
Some *preformatted* text Some *preformatted* text
|
|
|
|
]
|
|
''']
|
|
|
|
Spaces, tabs and newlines are rendered as-is. Unlike all quickbook block level
|
|
markup, pre (and Code) are the only ones that allow multiple newlines. The
|
|
markup above will generate:
|
|
|
|
[pre
|
|
|
|
Some *preformatted* text Some *preformatted* text
|
|
|
|
Some *preformatted* text Some *preformatted* text
|
|
|
|
Some *preformatted* text Some *preformatted* text
|
|
|
|
]
|
|
|
|
Notice that unlike Code, phrase markup such as font style is still permitted
|
|
inside =pre= blocks.
|
|
|
|
[endsect]
|
|
[section Blockquote]
|
|
|
|
[pre
|
|
'''[:sometext...]'''
|
|
]
|
|
|
|
[:Indents the paragraph. This applies to one paragraph only.]
|
|
|
|
[endsect]
|
|
[section Admonitions]
|
|
|
|
[pre'''
|
|
[note This is a note]
|
|
[tip This is a tip]
|
|
[important This is important]
|
|
[caution This is a caution]
|
|
[warning This is a warning]
|
|
''']
|
|
|
|
generates __docbook__ admonitions:
|
|
|
|
[note This is a note]
|
|
[tip This is a tip]
|
|
[important This is important]
|
|
[caution This is a caution]
|
|
[warning This is a warning]
|
|
|
|
These are the only admonitions supported by __docbook__. So,
|
|
for example [^\[information This is some information\]] is unlikely
|
|
to produce the desired effect.
|
|
|
|
[endsect]
|
|
[section Headings]
|
|
|
|
[pre'''
|
|
[h1 Heading 1]
|
|
[h2 Heading 2]
|
|
[h3 Heading 3]
|
|
[h4 Heading 4]
|
|
[h5 Heading 5]
|
|
[h6 Heading 6]
|
|
''']
|
|
|
|
[h1 Heading 1]
|
|
[h2 Heading 2]
|
|
[h3 Heading 3]
|
|
[h4 Heading 4]
|
|
[h5 Heading 5]
|
|
[h6 Heading 6]
|
|
|
|
Headings 1-3 \[h1 h2 and h3\] will automatically have anchors with normalized
|
|
names with [^name="section_id.normalized_header_text"] (i.e. valid characters are
|
|
=a-z=, =A-Z=, =0-9= and =_=. All non-valid characters are converted to underscore
|
|
and all upper-case are converted to lower-case. For example: Heading
|
|
1 in section Section 2 will be normalized to [^section_2.heading_1]). You can use:
|
|
|
|
[pre'''
|
|
[link section_id.normalized_header_text The link text]
|
|
''']
|
|
|
|
to link to them. See __anchor_links__ and __section__ for more info.
|
|
|
|
[endsect]
|
|
[section Generic Heading]
|
|
|
|
In cases when you don't want to care about the heading level (1 to 6), you
|
|
can use the /Generic Heading/:
|
|
|
|
[pre'''
|
|
[heading Heading]
|
|
''']
|
|
|
|
The /Generic Heading/ assumes the level, plus one, of the innermost section
|
|
where it is placed. For example, if it is placed in the outermost section,
|
|
then, it assumes /h2/.
|
|
|
|
Headings are often used as an alternative to sections. It is used
|
|
particularly if you do not want to start a new section. In many cases,
|
|
however, headings in a particular section is just flat. Example:
|
|
|
|
[pre'''
|
|
[section A]
|
|
[h2 X]
|
|
[h2 Y]
|
|
[h2 Z]
|
|
[endsect]
|
|
''']
|
|
|
|
Here we use h2 assuming that section A is the outermost level. If it is
|
|
placed in an inner level, you'll have to use h3, h4, etc. depending on
|
|
where the section is. In general, it is the section level plus one. It is
|
|
rather tedious, however, to scan the section level everytime. If you
|
|
rewrite the example above as shown below, this will be automatic:
|
|
|
|
[pre'''
|
|
[section A]
|
|
[heading X]
|
|
[heading Y]
|
|
[heading Z]
|
|
[endsect]
|
|
''']
|
|
|
|
They work well regardless where you place them. You can rearrange sections
|
|
at will without any extra work to ensure correct heading levels. In fact,
|
|
with /section/ and /heading/, you have all you need. /h1/../h6/ becomes
|
|
redundant. /h1/../h6/ might be deprecated in the future.
|
|
|
|
[endsect]
|
|
[section Macros]
|
|
|
|
[pre'''
|
|
[def macro_identifier some text]
|
|
''']
|
|
|
|
When a macro is defined, the identifier replaces the text anywhere in the
|
|
file, in paragraphs, in markups, etc. macro_identifier is a string of non-
|
|
white space characters except '\]'. A macro may not follow an alphabetic
|
|
character or the underscore. The replacement text can be any phrase (even
|
|
marked up). Example:
|
|
|
|
[pre'''
|
|
[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&type=1]]
|
|
sf_logo
|
|
''']
|
|
|
|
Now everywhere the sf_logo is placed, the picture will be inlined.
|
|
|
|
[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&type=1]]
|
|
sf_logo
|
|
|
|
[tip It's a good idea to use macro identifiers that are distinguishable.
|
|
For instance, in this document, macro identifiers have two leading and
|
|
trailing underscores (e.g. [^'''__spirit__''']). The reason is to avoid
|
|
unwanted macro replacement.]
|
|
|
|
Links (URLS) and images are good candidates for macros. *1*) They tend to
|
|
change a lot. It is a good idea to place all links and images in one place near the top
|
|
to make it easy to make changes. *2*) The syntax is not pretty. It's easier to read and
|
|
write, e.g. [^'''__spirit__'''] than [^'''[@http://spirit.sourceforge.net Spirit]'''].
|
|
|
|
Some more examples:
|
|
|
|
[pre'''
|
|
[def :-) [$theme/smiley.png]]
|
|
[def __spirit__ [@http://spirit.sourceforge.net Spirit]]
|
|
''']
|
|
|
|
(See __images__ and __links__)
|
|
|
|
Invoking these macros:
|
|
|
|
[pre'''
|
|
Hi __spirit__ :-)
|
|
''']
|
|
|
|
will generate this:
|
|
|
|
Hi __spirit__ :-)
|
|
|
|
[endsect]
|
|
[section Predefined Macros]
|
|
|
|
Quickbook has some predefined macros that you can already use.
|
|
|
|
[table Predefined Macros
|
|
[[Macro] [Meaning] [Example]]
|
|
[['''__DATE__'''] [Today's date] [__DATE__]]
|
|
[['''__TIME__'''] [The current time] [__TIME__]]
|
|
[['''__FILENAME__'''] [Quickbook source filename] [__FILENAME__]]
|
|
]
|
|
|
|
[endsect]
|
|
[section Templates]
|
|
|
|
Templates provide a more versatile text substitution mechanism. Templates
|
|
come in handy when you need to create parameterizable, multi-line,
|
|
boilerplate text that you specify once and expand many times. Templates
|
|
accept one or more arguments. These arguments act like place-holders for
|
|
text replacement. Unlike simple macros, which are limited to phrase level
|
|
markup, templates can contain block level markup (e.g. paragraphs, code
|
|
blocks and tables).
|
|
|
|
Example template:
|
|
|
|
[pre'''
|
|
[template person[name age what]
|
|
|
|
Hi, my name is [name]. I am [age] years old. I am a [what].
|
|
|
|
]
|
|
''']
|
|
|
|
[template person[name age what]
|
|
|
|
Hi, my name is [name]. I am [age] years old. I am a [what].
|
|
|
|
]
|
|
|
|
[heading Template Identifier]
|
|
|
|
Template identifiers can either consist of:
|
|
|
|
* An initial alphabetic character or the underscore, followed by
|
|
zero or more alphanumeric characters or the underscore. This is
|
|
similar to your typical C/C++ identifier.
|
|
* A single character punctuation (a non-alphanumeric printable character)
|
|
|
|
[heading Formal Template Arguments]
|
|
|
|
Template formal arguments are identifiers consisting of an initial
|
|
alphabetic character or the underscore, followed by zero or more
|
|
alphanumeric characters or the underscore. This is similar to your typical
|
|
C/C++ identifier.
|
|
|
|
A template formal argument temporarily hides a template of the same name at
|
|
the point where the [link quickbook.syntax.block.templates.template_expansion
|
|
template is expanded]. Note that the body of the [^person] template above
|
|
refers to [^name] [^age] and [^what] as [^\[name\]] [^\[age\]] and
|
|
[^\[what\]]. [^name] [^age] and [^what] are actually templates that exist
|
|
in the duration of the template call.
|
|
|
|
[heading Template Body]
|
|
|
|
The template body can be just about any QuickBook block or phrase. There
|
|
are actually two forms. Templates may be phrase or block level. Phrase
|
|
templates are of the form:
|
|
|
|
[pre'''
|
|
[template sample[arg1 arg2...argN] replacement text... ]
|
|
''']
|
|
|
|
Block templates are of the form:
|
|
|
|
[pre'''
|
|
[template sample[arg1 arg2...argN]
|
|
replacement text...
|
|
]
|
|
''']
|
|
|
|
The basic rule is as follows: if a newline immediately follows the argument
|
|
list, then it is a block template, otherwise, it is a phrase template.
|
|
Phrase templates are typically expanded as part of phrases. Like macros,
|
|
block level elements are not allowed in phrase templates.
|
|
|
|
[heading Template Expansion]
|
|
|
|
You expand a template this way:
|
|
|
|
[pre'''
|
|
[template_identifier arg1..arg2..arg3]
|
|
''']
|
|
|
|
At template expansion, you supply the actual arguments. The template will
|
|
be expanded with your supplied arguments. Example:
|
|
|
|
[pre'''
|
|
[person James Bond..39..Spy]
|
|
[person Santa Clause..87..Big Red Fatso]
|
|
''']
|
|
|
|
Which will expand to:
|
|
|
|
[person James Bond..39..Spy]
|
|
[person Santa Clause..87..Big Red Fatso]
|
|
|
|
[caution A word of caution: Templates are recursive. A template can call
|
|
another template or even itself, directly or indirectly. There are no
|
|
control structures in QuickBook (yet) so this will always mean infinite
|
|
recursion. QuickBook can detect this situation and report an error if
|
|
recursion exceeds a certain limit.]
|
|
|
|
Each actual argument can be a word, a text fragment or just about any [link
|
|
quickbook.syntax.phrase QuickBook phrase]. Arguments are separated by the
|
|
double dot [^".."] and terminated by the close parenthesis.
|
|
|
|
[heading Nullary Templates]
|
|
|
|
Nullary templates look and act like simple macros. Example:
|
|
|
|
[pre'''
|
|
[template alpha[]'''&#945;''']
|
|
[template beta[]'''&#946;''']
|
|
''']
|
|
|
|
[template alpha[]'''α''']
|
|
[template beta[]'''β''']
|
|
|
|
Expanding:
|
|
|
|
[pre'''Some squigles...[*[alpha][beta]]''']
|
|
|
|
We have:
|
|
|
|
Some squiggles...[*[alpha][beta]]
|
|
|
|
The difference with macros are
|
|
|
|
* The explicit [link quickbook.syntax.block.templates.template_expansion
|
|
template expansion syntax]. This is an advantage because, now, we don't
|
|
have to use obscure naming conventions like double underscores (e.g.
|
|
\_\_alpha\_\_) to avoid unwanted
|
|
macro replacement.
|
|
* The template is expanded at the point where it is invoked. A macro is
|
|
expanded immediately at its point of declaration. This is subtle and
|
|
can cause a slight difference in behavior especially if you refer to
|
|
other macros and templates in the body.
|
|
|
|
The empty brackets after the template identifier ([^alpha\[\]]) indicates no
|
|
arguments. If the template body does not look like a template argument list, we
|
|
can elide the empty brackets. Example:
|
|
|
|
[pre'''
|
|
[template aristotle_quote Aristotle: [*['Education is the best provision
|
|
for the journey to old age.]]]
|
|
''']
|
|
|
|
[template aristotle_quote\ Aristotle: [*['Education is the best provision
|
|
for the journey to old age.]]]
|
|
|
|
Expanding:
|
|
|
|
[pre'''
|
|
Here's a quote from [aristotle_quote].
|
|
''']
|
|
|
|
We have:
|
|
|
|
Here's a quote from [aristotle_quote].
|
|
|
|
The disadvantage is that you can't avoid the space between the template
|
|
identifier, `aristotle_quote`, and the template body "Aristotle...". This space
|
|
will be part of the template body. If that space is unwanted, use empty
|
|
brackets or use the space escape: "`\ `". Example:
|
|
|
|
[pre'''
|
|
[template tag\ _tag]
|
|
''']
|
|
|
|
[template tag\ _tag]
|
|
|
|
Then expanding:
|
|
|
|
[pre'''
|
|
`struct` x[tag];
|
|
''']
|
|
|
|
We have:
|
|
|
|
`struct` x[tag];
|
|
|
|
You have a couple of ways to do it. I personally prefer the explicit empty
|
|
brackets, though.
|
|
|
|
[heading Simple Arguments]
|
|
|
|
As mentioned, arguments are separated by the double dot [^".."]. If there
|
|
are less arguments passed than expected, QuickBook attempts to break the
|
|
last argument into two or more arguments following this logic:
|
|
|
|
* Break the last argument into two, at the first space found ([^'', '\\n',
|
|
\\t' or '\\r']).
|
|
* Repeat until there are enough arguments or if there are no more spaces
|
|
found (in which case, an error is reported).
|
|
|
|
For example:
|
|
|
|
[pre'''
|
|
[template simple[a b c d] [a][b][c][d]]
|
|
[simple w x y z]
|
|
''']
|
|
|
|
will produce:
|
|
|
|
[template simple[a b c d] [a][b][c][d]]
|
|
[simple w x y z]
|
|
|
|
"w x y z" is initially treated as a single argument because we didn't
|
|
supply any [^".."] separators. However, since [^simple] expects 4
|
|
arguments, "w x y z" is broken down iteratively (applying the logic above)
|
|
until we have "w", "x", "y" and "z".
|
|
|
|
QuickBook only tries to get the arguments it needs. For example:
|
|
|
|
[pre'''
|
|
[simple w x y z trail]
|
|
''']
|
|
|
|
will produce:
|
|
|
|
[simple w x y z trail]
|
|
|
|
The arguments being: "w", "x", "y" and "z trail".
|
|
|
|
It should be obvious now that for simple arguments with no spaces, we can
|
|
get by without separating the arguments with [^".."] separators. It is
|
|
possible to combine [^".."] separators with the argument passing
|
|
simplification presented above. Example:
|
|
|
|
[pre'''
|
|
[simple what do you think ..m a n?]
|
|
''']
|
|
|
|
will produce:
|
|
|
|
[simple what do you think ..m a n?]
|
|
|
|
[heading Punctuation Templates]
|
|
|
|
With templates, one of our objectives is to allow us to rewrite QuickBook
|
|
in QuickBook (as a qbk library). For that to happen, we need to accommodate
|
|
single character punctuation templates which are fairly common in
|
|
QuickBook. You might have noticed that single character punctuations are
|
|
allowed as [link quickbook.syntax.block.templates.template_identifier
|
|
template identifiers]. Example:
|
|
|
|
[pre'''
|
|
[template ![bar] '''<hey>'''[bar]'''</hey>''']
|
|
''']
|
|
|
|
Now, expanding this:
|
|
|
|
[pre'''
|
|
[!baz]
|
|
''']
|
|
|
|
We will have:
|
|
|
|
[pre
|
|
<hey>baz</hey>
|
|
]
|
|
|
|
[endsect]
|
|
[section Blurbs]
|
|
|
|
[pre'''
|
|
[blurb :-) [*An eye catching advertisement or note...]
|
|
|
|
__spirit__ is an object-oriented recursive-descent parser generator framework
|
|
implemented using template meta-programming techniques. Expression templates
|
|
allow us to approximate the syntax of Extended Backus-Normal Form (EBNF)
|
|
completely in C++.
|
|
]
|
|
''']
|
|
|
|
will generate this:
|
|
|
|
[blurb :-) [*An eye catching advertisement or note...]
|
|
|
|
__spirit__ is an object-oriented recursive-descent parser generator
|
|
framework implemented using template meta-programming techniques. Expression
|
|
templates allow us to approximate the syntax of Extended Backus-Normal Form
|
|
(EBNF) completely in C++.
|
|
]
|
|
|
|
[note Prefer [link quickbook.syntax.block.admonitions admonitions] wherever
|
|
appropriate.]
|
|
|
|
[endsect]
|
|
[section Tables]
|
|
|
|
[pre'''
|
|
[table A Simple Table
|
|
[[Heading 1] [Heading 2] [Heading 3]]
|
|
[[R0-C0] [R0-C1] [R0-C2]]
|
|
[[R1-C0] [R1-C1] [R1-C2]]
|
|
[[R2-C0] [R2-C1] [R2-C2]]
|
|
]
|
|
''']
|
|
|
|
will generate:
|
|
|
|
[table A Simple Table
|
|
[[Heading 1] [Heading 2] [Heading 3]]
|
|
[[R0-C0] [R0-C1] [R0-C2]]
|
|
[[R2-C0] [R2-C1] [R2-C2]]
|
|
[[R3-C0] [R3-C1] [R3-C2]]
|
|
]
|
|
|
|
The table title is optional. The first row of the table is automatically
|
|
treated as the table header; that is, it is wrapped in
|
|
[^<thead>...</thead>] XML tags. Note that unlike the original QuickDoc, the
|
|
columns are nested in [ cells... ]. The syntax is free-format and allows
|
|
big cells to be formatted nicely. Example:
|
|
|
|
[pre'''
|
|
[table Table with fat cells
|
|
[[Heading 1] [Heading 2]]
|
|
[
|
|
[Row 0, Col 0: a small cell]
|
|
[
|
|
Row 0, Col 1: a big fat cell with paragraphs
|
|
|
|
Boost provides free peer-reviewed portable C++ source libraries.
|
|
|
|
We emphasize libraries that work well with the C++ Standard Library.
|
|
Boost libraries are intended to be widely useful, and usable across
|
|
a broad spectrum of applications. The Boost license encourages both
|
|
commercial and non-commercial use.
|
|
]
|
|
]
|
|
[
|
|
[Row 1, Col 0: a small cell]
|
|
[Row 1, Col 1: a small cell]
|
|
]
|
|
]
|
|
''']
|
|
|
|
and thus:
|
|
|
|
[table Table with fat cells
|
|
[[Heading 1] [Heading 2]]
|
|
[
|
|
[Row 0, Col 0: a small cell]
|
|
[
|
|
Row 0, Col 1: a big fat cell with paragraphs
|
|
|
|
Boost provides free peer-reviewed portable C++ source libraries.
|
|
|
|
We emphasize libraries that work well with the C++ Standard Library.
|
|
Boost libraries are intended to be widely useful, and usable across
|
|
a broad spectrum of applications. The Boost license encourages both
|
|
commercial and non-commercial use.
|
|
]
|
|
]
|
|
[
|
|
[Row 1, Col 0: a small cell]
|
|
[Row 1, Col 1: a small cell]
|
|
]
|
|
]
|
|
|
|
Here's how to have preformatted blocks of code in a table cell:
|
|
|
|
[pre'''
|
|
[table Table with code
|
|
[[Comment] [Code]]
|
|
[
|
|
[My first program]
|
|
['''\`\`
|
|
#include <iostream>
|
|
|
|
int main()
|
|
{
|
|
std::cout << "Hello, World!" << std::endl;
|
|
return 0;
|
|
}
|
|
\`\`''']
|
|
]
|
|
]
|
|
''']
|
|
|
|
[table Table with code
|
|
[[Comment] [Code]]
|
|
[
|
|
[My first program]
|
|
[``
|
|
#include <iostream>
|
|
|
|
int main()
|
|
{
|
|
std::cout << "Hello, World!" << std::endl;
|
|
return 0;
|
|
}
|
|
``]
|
|
]
|
|
]
|
|
|
|
[endsect]
|
|
[section Variable Lists]
|
|
|
|
[pre'''
|
|
[variablelist A Variable List
|
|
[[term 1] [The definition of term 1]]
|
|
[[term 2] [The definition of term 2]]
|
|
[[term 3] [The definition of term 3]]
|
|
]
|
|
''']
|
|
|
|
will generate:
|
|
|
|
[variablelist A Variable List
|
|
[[term 1] [The definition of term 1]]
|
|
[[term 2] [The definition of term 2]]
|
|
[[term 3] [The definition of term 3]]
|
|
]
|
|
|
|
The rules for variable lists are the same as for tables, except that
|
|
only 2 "columns" are allowed. The first column contains the terms, and
|
|
the second column contains the definitions. Those familiar with HTML
|
|
will recognize this as a "definition list".
|
|
|
|
[endsect]
|
|
[section Include]
|
|
|
|
You can include one QuickBook file from another. The syntax is simply:
|
|
|
|
[pre'''
|
|
[include someother.qbk]
|
|
''']
|
|
|
|
The included file will be processed as if it had been cut and pasted
|
|
into the current document, with the following exceptions:
|
|
|
|
* The '''__FILENAME__''' predefined macro will reflect the name of the
|
|
file currently being processed.
|
|
* Any macros defined in the included file are scoped to that file.
|
|
|
|
The [^\[include\]] directive lets you specify a document id to use for the
|
|
included file. When this id is not explicitly specified, the id defaults to
|
|
the filename ("someother", in the example above). You can specify the id
|
|
like this:
|
|
|
|
[pre'''
|
|
[include:someid someother.qbk]
|
|
''']
|
|
|
|
All auto-generated anchors will use the document id as a unique prefix. So
|
|
for instance, if there is a top section in someother.qbk named "Intro", the
|
|
named anchor for that section will be "someid.intro", and you can link to
|
|
it with [^\[link someid.intro The Intro\]].
|
|
|
|
[endsect]
|
|
|
|
[section Import]
|
|
|
|
When documenting code, you'd surely need to present code from actual source
|
|
files. While it is possible to copy some code and paste them in your QuickBook
|
|
file, doing so is error prone and the extracted code in the documentation tends
|
|
to get out of sync with the actual code as the code evolves. The problem, as
|
|
always, is that once documentation is written, the tendency is for the docs to
|
|
languish in the archives without maintenance.
|
|
|
|
QuickBook's import facility provides a nice solution.
|
|
|
|
[heading Example]
|
|
|
|
You can effortlessly import code snippets from source code into your QuickBook.
|
|
The following illustrates how this is done:
|
|
|
|
[pre'''
|
|
[import ../test/stub.cpp]
|
|
[foo]
|
|
[bar]
|
|
''']
|
|
|
|
The first line:
|
|
|
|
[pre'''
|
|
[import ../test/stub.cpp]
|
|
''']
|
|
|
|
collects specially marked-up code snippets from [@../../test/stub.cpp stub.cpp]
|
|
and places them in your QuickBook file as virtual templates. Each of the
|
|
specially marked-up code snippets has a name (e.g. `foo` and `bar` in the
|
|
example above). This shall be the template identifier for that particular code
|
|
snippet. The second and third line above does the actual template expansion:
|
|
|
|
[pre'''
|
|
[foo]
|
|
[bar]
|
|
''']
|
|
|
|
And the result is:
|
|
|
|
[import ../test/stub.cpp]
|
|
[foo]
|
|
[bar]
|
|
|
|
[heading Code Snippet Markup]
|
|
|
|
Note how the code snippets in [@../../test/stub.cpp stub.cpp] get marked up. We
|
|
use distinguishable comments following the form:
|
|
|
|
//[id
|
|
some code here
|
|
//]
|
|
|
|
The first comment line above initiates a named code-snippet. This prefix will
|
|
not be visible in quickbook. The entire code-snippet in between `//[id` and
|
|
`//]` will be inserted as a template in quickbook with name ['/id/]. The comment
|
|
`//]` ends a code-snippet This too will not be visible in quickbook.
|
|
|
|
[heading Special Comments]
|
|
|
|
Special comments of the form:
|
|
|
|
//` some [*quickbook] markup here
|
|
|
|
and:
|
|
|
|
/*` some [*quickbook] markup here */
|
|
|
|
will be parsed by QuickBook. This can contain quickbook /blocks/ (e.g. sections,
|
|
paragraphs, tables, etc). In the first case, the initial slash-slash, tick and
|
|
white-space shall be ignored. In the second, the initial slash-star-tick and the
|
|
final star-slash shall be ignored.
|
|
|
|
[heading Callouts]
|
|
|
|
Special comments of the form:
|
|
|
|
/*< some [*quickbook] markup here >*/
|
|
|
|
will be regarded as callouts. These will be collected, numbered and
|
|
rendered as a "callout bug" (a small icon with a number). After the
|
|
whole snippet is parsed, the callout list is generated. See
|
|
[@http://www.docbook.org/tdg/en/html/callout.html Callouts] for details.
|
|
Example:
|
|
|
|
[foo_bar]
|
|
|
|
Checkout [@../../test/stub.cpp stub.cpp] to see the actual code.
|
|
|
|
[endsect]
|
|
|
|
[endsect]
|
|
[endsect]
|
|
|
|
[section:install Installation and configuration]
|
|
|
|
This section provides some guidelines on how to install and configure
|
|
BoostBook and Quickbook under several operating systems.
|
|
|
|
Before continuing, it is very important that you keep this in mind: if you
|
|
try to build some documents and the process breaks due to misconfiguration,
|
|
be absolutely sure to delete any `bin` and `bin.v2` directories generated
|
|
by the build before trying again. Otherwise your configuration fixes will
|
|
not take any effect.
|
|
|
|
[section:windows Windows 2000, XP, 2003, Vista]
|
|
|
|
[python]
|
|
|
|
[:['Section contributed by Julio M. Merino Vidal]]
|
|
|
|
The following instructions apply to any Windows system based on Windows
|
|
2000, including Windows XP, Windows 2003 Server and Windows Vista. The
|
|
paths shown below are taken from a Windows Vista machine; you will need to
|
|
adjust them to match your system in case you are running an older version.
|
|
|
|
# First of all you need to have a copy of `xsltproc` for Windows. There
|
|
are many ways to get this tool, but to keep things simple, use the
|
|
[@http://www.zlatkovic.com/pub/libxml/ binary packages] made by Igor
|
|
Zlatkovic. At the very least, you need to download the following
|
|
packages: `iconv`, `zlib`, `libxml2` and `libxslt`.
|
|
|
|
# Unpack all these packages in the same directory so that you get unique
|
|
`bin`, `include` and `lib` directories within the hierarchy. These
|
|
instructions use `C:\Users\example\Documents\boost\xml` as the root for
|
|
all files.
|
|
|
|
# From the command line, go to the `bin` directory and launch
|
|
`xsltproc.exe` to ensure it works. You should get usage information on
|
|
screen.
|
|
|
|
# Download [@http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip Docbook XML
|
|
4.2] and unpack it in the same directory used above. That is:
|
|
`C:\Users\example\Documents\boost\xml\docbook-xml`.
|
|
|
|
# Download the latest
|
|
[@http://sourceforge.net/project/showfiles.php?group_id=21935&package_id=16608
|
|
Docbook XSL] version and unpack it, again in the same directory
|
|
used before. To make things easier, rename the directory created
|
|
during the extraction to `docbook-xsl` (bypassing the version name):
|
|
`C:\Users\example\Documents\boost\xml\docbook-xsl`.
|
|
|
|
# Add the following to your `user-config.jam` file, which should live in
|
|
your home directory (`%HOMEDRIVE%%HOMEPATH%`). You must already have it
|
|
somewhere or otherwise you could not be building Boost (i.e. missing
|
|
tools configuration).
|
|
|
|
using xsltproc
|
|
: "C:/Users/example/Documents/boost/xml/bin/xsltproc.exe"
|
|
;
|
|
|
|
using boostbook
|
|
: "C:/Users/example/Documents/boost/xml/docbook-xsl"
|
|
: "C:/Users/example/Documents/boost/xml/docbook-xml"
|
|
;
|
|
|
|
The above steps are enough to get a functional BoostBook setup. Quickbook
|
|
will be automatically built when needed. If you want to avoid these
|
|
rebuilds:
|
|
|
|
# Go to Quickbook's source directory (`BOOST_ROOT\tools\quickbook`).
|
|
|
|
# Build the utility by issuing `bjam --v2`.
|
|
|
|
# Copy the resulting `quickbook.exe` binary (located under the
|
|
`BOOST_ROOT\bin.v2` hierarchy) to a safe place. Following our previous
|
|
example, you can install it into:
|
|
`C:\Users\example\Documents\boost\xml\bin`.
|
|
|
|
# Add the following to your `user-config.jam` file:
|
|
|
|
using quickbook
|
|
: "C:/Users/example/Documents/boost/xml/bin/quickbook.exe"
|
|
;
|
|
|
|
[endsect]
|
|
|
|
[section:linux Debian, Ubuntu]
|
|
|
|
The following instructions apply to Debian and its derivatives. They are based
|
|
on a Ubuntu Edgy install but should work on other Debian based systems.
|
|
|
|
First install the `bjam`, `xsltproc`, `docbook-xsl` and `docbook-xml` packages.
|
|
For example, using `apt-get`:
|
|
|
|
sudo apt-get install xsltprc docbook-xsl docbook-xml
|
|
|
|
If you're planning on building boost's documentation, you'll also need to
|
|
install the `doxygen` package as well.
|
|
|
|
Next, we need to configure Boost Build to compile BoostBook files. Add the
|
|
following to your `user-config.jam` file, which should be in your home
|
|
directory. If you don't have one, create a file containing this text. For more
|
|
information on setting up `user-config.jam`, see the
|
|
[@http://boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html Boost
|
|
Build documentation].
|
|
|
|
using xsltproc ;
|
|
|
|
using boostbook
|
|
: /usr/share/xml/docbook/stylesheet/nwalsh
|
|
: /usr/share/xml/docbook/schema/dtd/4.2
|
|
;
|
|
|
|
# Remove this line if you're not using doxygen
|
|
using doxygen ;
|
|
|
|
The above steps are enough to get a functional BoostBook setup. Quickbook
|
|
will be automatically built when needed. If you want to avoid these
|
|
rebuilds:
|
|
|
|
# Go to Quickbook's source directory (`BOOST_ROOT/tools/quickbook`).
|
|
|
|
# Build the utility by issuing `bjam --v2`.
|
|
|
|
# Copy the resulting `quickbook` binary (located under the
|
|
`BOOST_ROOT/bin.v2` hierarchy) to a safe place. The traditional location is
|
|
`/usr/local/bin`.
|
|
|
|
# Add the following to your `user-config.jam` file, using the full path of the
|
|
quickbook executable:
|
|
|
|
using quickbook
|
|
: /usr/local/bin/quickbook
|
|
;
|
|
|
|
[endsect]
|
|
[endsect] [/Installation and configuration]
|
|
|
|
[section:editors Editor Support]
|
|
|
|
Editing quickbook files is usually done with text editors both simple and
|
|
powerful. The following sections list the settings for some editors which can
|
|
help make editing quickbook files a bit easier.
|
|
|
|
[blurb __note__ You may submit your settings, tips, and suggestions to the
|
|
authors, or through the [@https://lists.sourceforge.net/lists/listinfo/boost-
|
|
docs Boost Docs mailing list].]
|
|
|
|
[section:scite Scintilla Text Editor]
|
|
|
|
[:['Section contributed by Dean Michael Berris]]
|
|
|
|
The Scintilla Text Editor (SciTE) is a free source code editor for Win32 and X.
|
|
It uses the SCIntilla source code editing component.
|
|
|
|
[blurb __tip__ SciTE can be downloaded from [@http://www.scintilla.org/SciTE.html]]
|
|
|
|
You can use the following settings to highlight quickbook tags when
|
|
editing quickbook files.
|
|
|
|
[pre'''
|
|
qbk=*.qbk
|
|
lexer.*.qbk=props
|
|
use.tabs.$(qbk)=0
|
|
tab.size.$(qbk)=4
|
|
indent.size.$(qbk)=4
|
|
style.props.32=$(font.base)
|
|
comment.stream.start.props=[/
|
|
comment.stream.end.props=]
|
|
comment.box.start.props=[/
|
|
comment.box.middle.props=
|
|
comment.box.end.props=]
|
|
''']
|
|
|
|
[blurb __note__ Thanks to Rene Rivera for the above SciTE settings.]
|
|
|
|
[endsect] [/scite]
|
|
[endsect] [/editors]
|
|
|
|
[section:faq Frequently Asked Questions]
|
|
|
|
[heading Can I use QuickBook for non-Boost documentation?]
|
|
|
|
QuickBook can be used for non-Boost documentation with a little extra work.
|
|
|
|
[:['Faq contributed by Michael Marcin]]
|
|
|
|
When building HTML documentation with BoostBook a Boost C++ Libraries header
|
|
is added to the files. When using QuickBook to document projects outside of
|
|
Boost this is not desirable. This behavior can be overridden at the BoostBook
|
|
level by specifying some XSLT options. When using Boost Build version 2 (BBv2)
|
|
this can be achieved by adding parameters to the BoostBook target declaration.
|
|
|
|
For example:
|
|
[pre
|
|
using quickbook ;
|
|
|
|
xml my_doc : my_doc.qbk ;
|
|
|
|
boostbook standalone
|
|
:
|
|
my_doc
|
|
:
|
|
<xsl:param>boost.image.src=images/my_project_logo.png
|
|
<xsl:param>boost.image.alt="\\"My Project\\""
|
|
<xsl:param>boost.image.w=100
|
|
<xsl:param>boost.image.h=50
|
|
<xsl:param>nav.layout=none
|
|
;
|
|
]
|
|
|
|
[endsect] [/faq]
|
|
|
|
[section:ref Quick Reference]
|
|
|
|
[cpp]
|
|
|
|
[template ordered_list_sample[]
|
|
[pre'''
|
|
# one
|
|
# two
|
|
# three
|
|
''']
|
|
]
|
|
|
|
[template unordered_list_sample[]
|
|
[pre'''
|
|
* one
|
|
* two
|
|
* three
|
|
''']
|
|
]
|
|
|
|
[template table_sample[]
|
|
[pre'''
|
|
[table Title
|
|
[[a][b][c]]
|
|
[[a][b][c]]
|
|
]
|
|
''']
|
|
]
|
|
|
|
[template var_list_sample[]
|
|
[pre'''
|
|
[variablelist Title
|
|
[[a][b]]
|
|
[[a][b]]
|
|
]
|
|
''']
|
|
]
|
|
|
|
|
|
[table Syntax Compendium
|
|
[[To do this...] [Use this...] [See this...]]
|
|
[[comment] [[^'''[/ some comment]''']] [__comments__]]
|
|
[[['italics]] [[^'''['italics] or /italics/''']] [__font_styles__ and __simple_formatting__]]
|
|
[[[*bold]] [[^'''[*bold] or *bold*''']] [__font_styles__ and __simple_formatting__]]
|
|
[[[_underline]] [[^'''[_underline] or _underline_''']] [__font_styles__ and __simple_formatting__]]
|
|
[[[^teletype]] [[^'''[^teletype] or =teletype=''']] [__font_styles__ and __simple_formatting__]]
|
|
[[[-strikethrough]] [[^'''[-strikethrough]''']] [__font_styles__ and __simple_formatting__]]
|
|
[[[~replaceable]] [[^'''[~replaceable]''']] [__replaceable__]]
|
|
[[source mode] [[^\[c++\]] or [^\[python\]]] [__source_mode__]]
|
|
[[inline code] [[^'''`int main();`''']] [__inline_code__]]
|
|
[[code block] [[^'''``int main();``''']] [__code__]]
|
|
[[code escape] [[^'''``from c++ to QuickBook``''']] [__escape_back__]]
|
|
[[line break] [[^'''[br] or \n''']] [__line_break__ *DEPRECATED*]]
|
|
[[anchor] [[^'''[#anchor]''']] [__anchors__]]
|
|
[[link] [[^'''[@http://www.boost.org Boost]''']] [__links__]]
|
|
[[anchor link] [[^'''[link section.anchor Link text]''']] [__anchor_links__]]
|
|
[[refentry link] [[^'''[link xml.refentry Link text]''']] [__refentry_links__]]
|
|
[[function link] [[^'''[funcref fully::qualified::function_name Link text]''']] [__code_links__]]
|
|
[[class link] [[^'''[classref fully::qualified::class_name Link text]''']] [__code_links__]]
|
|
[[member link] [[^'''[memberref fully::qualified::member_name Link text]''']] [__code_links__]]
|
|
[[enum link] [[^'''[enumref fully::qualified::enum_name Link text]''']] [__code_links__]]
|
|
[[macro link] [[^'''[macroref MACRO_NAME Link text]''']] [__code_links__]]
|
|
[[concept link] [[^'''[conceptref ConceptName Link text]''']] [__code_links__]]
|
|
[[header link] [[^'''[headerref path/to/header.hpp Link text]''']] [__code_links__]]
|
|
[[escape] [[^\'\'\'escaped text (no processing/formatting)\'\'\']] [__escape__]]
|
|
[[single char escape] [[^\\c]] [__single_char_escape__]]
|
|
[[images] [[^'''[$image.jpg]''']] [__images__]]
|
|
[[begin section] [[^'''[section The Section Title]''']] [__section__]]
|
|
[[end section] [[^'''[endsect]''']] [__section__]]
|
|
[[paragraph] [No markup. Paragraphs start left-flushed and are terminated by two or more newlines.] [__paragraphs__]]
|
|
[[ordered list] [[ordered_list_sample]] [__ordered_lists__]]
|
|
[[unordered list] [[unordered_list_sample]] [__unordered_lists__]]
|
|
[[code] [No markup. Preformatted code starts with a space or a tab.] [__code__]]
|
|
[[preformatted] [[^'''[pre preformatted]''']] [__preformatted__]]
|
|
[[block quote] [[^'''[:sometext...]''']] [__blockquote__]]
|
|
[[heading 1] [[^'''[h1 Heading 1]''']] [__heading__]]
|
|
[[heading 2] [[^'''[h2 Heading 2]''']] [__heading__]]
|
|
[[heading 3] [[^'''[h3 Heading 3]''']] [__heading__]]
|
|
[[heading 4] [[^'''[h4 Heading 4]''']] [__heading__]]
|
|
[[heading 5] [[^'''[h5 Heading 5]''']] [__heading__]]
|
|
[[heading 6] [[^'''[h6 Heading 6]''']] [__heading__]]
|
|
[[macro] [[^'''[def macro_identifier some text]''']] [__macros__]]
|
|
[[template] [[^'''[template[a b] [a] body [b]]''']] [__templates__]]
|
|
[[blurb] [[^'''[blurb advertisement or note...]''']] [__blurbs__]]
|
|
[[admonition] [[^'''[warning Warning text...]''']] [__admonitions__]]
|
|
[[table] [[table_sample]] [__tables__]]
|
|
[[variablelist] [[var_list_sample]] [__variable_lists__]]
|
|
[[include] [[^'''[include someother.qbk]''']] [__include__]]
|
|
]
|
|
|
|
[endsect]
|