Joelde GuzmanEricNiebler20022004Joel de Guzman, Eric Niebler
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)
WikiWiki style documentation tool
Quickbook 1.3 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
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
Change Log
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:
[sectionx]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.
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.
Comments
Can be placed anywhere.
[/ comment (no output generated) ]
Phrase Level ElementsFont 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-italicReplaceable
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 SamplesMarkupResult
*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-Italicnote 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 intmain(){return0;} 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>intmain(){std::cout<<"Hello, World!"<<std::endl;return0;}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 ModesModeSource Mode MarkupC++[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 markupalert 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
A sample footnote
.
Block Level ElementsDocument
Every document must begin with a Document Info section, which should look
like this:
[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.
Section
Starting a new section is accomplished with:
[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:
[endsect]
Sections can nest, and that results in a hierarchy in the table of contents.
xinclude
You can include another XML file with:
[xinclude file.xml]
This is useful when file.xml has been generated by Doxygen and contains
your reference 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.
ListsOrdered lists# One
# Two
# Three
will generate:
One
Two
Three
List Hierarchies
List hierarchies are supported. Example:
# 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
Long List Lines
Long lines will be wrapped appropriately. Example:
# 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.
Unordered lists* First
* Second
* Third
will generate:
First
Second
Third
Mixed lists
Mixed lists (ordered and unordered) are supported. Example:
# One
# Two
# Three
* Three.a
* Three.b
* Three.c
# Four
will generate:
One
Two
Three
Three.a
Three.b
Three.c
Four
And...
# 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
Code
Preformatted code starts with a space or a tab. The code will be syntax
highlighted according to the current Source
Mode:
#include<iostream>intmain(){// Sample code
std::cout<<"Hello, World\n";return0;}importcgidefcookForHtml(text):'''"Cooks" the input text for HTML.'''returncgi.escape(text)
Macros that are already defined are expanded in source code. Example:
[def __syntax_highlight__ [@quickbook/highlight.html syntax_highlight]]
[def __quickbook__ [@index.html quickbook]]
using __quickbook__::__syntax_highlight__;
Generates:
usingquickbook::syntax_highlight; 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:
void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``()
{
}
Will generate:
voidfoo(){}
When escaping from code to QuickBook, only phrase level markups are allowed.
Block level markups like lists, tables etc. are not allowed.
Preformatted
Sometimes, you don't want some preformatted text to be parsed as C++. In
such cases, use the [pre ... ] markup block.
[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:
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.
Blockquote[:sometext...]
Indents the paragraph. This applies to one paragraph only.
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]
generates DocBook admonitions:
This is a note
This is a tip
This is important
This is a caution
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.
Headings[h1 Heading 1]
[h2 Heading 2]
[h3 Heading 3]
[h4 Heading 4]
[h5 Heading 5]
[h6 Heading 6]
Heading 1
Heading 2
Heading 3
Heading 4
Heading 5
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:
[link section_id.normalized_header_text The link text]
to link to them. See Anchor
links and Section
for more info.
Macros[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 ']' while the replacement text can be any phrase
(even marked up). Example:
[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.
sflogotip 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:
[def :-) [$theme/smiley.png]]
[def __spirit__ [@http://spirit.sourceforge.net Spirit]]
(See Images and
Links)
Invoking these macros:
Hi __spirit__ :-)
will generate this:
Hi SpiritsmileyPredefined Macros
Quickbook has some predefined macros that you can already use.
Predefined MacrosMacroMeaningExample
__DATE__
Today's date2000-Dec-20
__TIME__
The current time12:00:00 PM
__FILENAME__
Quickbook source filenameNO_FILENAME_MACRO_GENERATED_IN_DEBUG_MODEBlurbs[blurb :-) [*An eye catching advertisement or note...]\n\n
__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:
smileyAn 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++. Tables[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:
A Simple TableHeading 1Heading 2Heading 3R0-C0R0-C1R0-C2R2-C0R2-C1R2-C2R3-C0R3-C1R3-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:
[table Table with fat cells
[[Heading 1] [Heading 2]]
[
[Row 0, Col 0: a small cell]
[
Row 0, Col 1:
A very big cell...A very big cell...A very big cell...
A very big cell...A very big cell...A very big cell...
A very big cell...A very big cell...A very big cell...
]
]
[
[Row 1, Col 0: a small cell]
[Row 1, Col 1: a small cell]
]
]
and thus:
Table with fat cellsHeading 1Heading 2Row 0, Col 0: a small cell Row 0, Col 1: A
very big cell...A very big cell...A very big cell... A very big cell...A
very big cell...A very big cell... A very big cell...A very big cell...A
very big cell... Row 1, Col 0: a small cellRow 1, Col 1: a small
cell
Here's how to have preformatted blocks of code in a table cell:
[table Table with code
[[Comment] [Code]]
[
[My first program]
[``
#include <iostream>
int main()
{
std::cout << "Hello, World!" << std::endl;
return 0;
}
``]
]
]
Table with codeCommentCodeMy first program#include <iostream>
intmain(){std::cout<<"Hello, World!"<<std::endl;return0;}Variable Lists[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:
A Variable Listterm 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".
Include
You can include one QuickBook file from another. The syntax is simply:
[include someother.qbk]
The included file will be processed as if it had be 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.
As the number of included QuickBook files grows, so too does the likelihood
of two sections having the same name. Since QuickBook generates an anchor
for each section based on the section name, it is possible to end up with
two identically named anchors, leading to link ambiguities. To resolve
these ambiguities, the [include] directive lets you
specify a document id to use for the included file. You can use it like
this:
[include:someid someother.qbk]
When using this form, all auto-generated anchors will use "someid"
as a unique prefix. So for instance, if there is a 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].
Quick ReferenceSyntax CompendiumTo do this...Use this...See this...comment
[/ some comment]
Commentsitalics
['italics] or /italics/
Font
Styles and formatting
Simple formattingbold
[*bold] or *bold*
Font
Styles and formatting
Simple formattingunderline
[_underline] or _underline_
Font
Styles and formatting
Simple formattingteletype
[^teletype] or =teletype=
Font
Styles and formatting
Simple formattingstrikethrough
[-strikethrough]
Font
Styles and formatting
Simple formatting
replaceable
[~replaceable]
Replaceblesource mode[c++] or [python]Source Modeinline code
`int main();`
Inline
codecode block
``int main();``
Codecode escape
``from c++ to QuickBook``
Escaping
Back To QuickBookline break
[br] or \n
line-breakanchor
[#anchor]
Anchorslink
[@http://www.boost.org Boost]
Linksanchor link
[link section.anchor Link text]
Anchor
linksrefentry link
[link xml.refentry Link text]
refentry
linksfunction link
[funcref fully::qualified::function_name Link text]
function,
class, member, enum or header linksclass link
[classref fully::qualified::class_name Link text]
function,
class, member, enum or header linksmember link
[memberref fully::qualified::member_name Link text]
function,
class, member, enum or header linksenum link
[enumref fully::qualified::enum_name Link text]
function,
class, member, enum or header linksheader link
[headerref path/to/header.hpp Link text]
function,
class, member, enum or header linksescape'''escaped text (no processing/formatting)'''Escapesingle char escape\cSingle char escapeimages
[$image.jpg]
Imagesbegin section
[section The Section Title]
Sectionend section
[endsect]
SectionparagraphNo markup. Paragraphs start left-flushed
and are terminated by two or more newlines.Paragraphsordered list# one # two #
threeOrdered
listsunordered list* one * two
* threeUnordered
listscodeNo markup. Preformatted code starts with a
space or a tab.Codepreformatted
[pre preformatted]
Preformattedblock quote
[:sometext...]
Blockquoteheading 1
[h1 Heading 1]
Headingheading 2
[h2 Heading 2]
Headingheading 3
[h3 Heading 3]
Headingheading 4
[h4 Heading 4]
Headingheading 5
[h5 Heading 5]
Headingheading 6
[h6 Heading 6]
Headingmacro
[def macro_identifier some text]
Macrosblurb
[blurb advertisement or note...]
Blurbsadmonition
[warning Warning text...]
Admonitionstable[table Title [[a][b][c]]
[[a][b][c]] ]Tablesvariablelist[variablelist Title
[[a][b]] [[a][b]] ]Variable
Listsinclude
[include someother.qbk]
Include