quickbook.qbk

C++的一个好库。。。现在很流行

[part quickbook
    [version 1.1]
    [authors [de Guzman, Joel], [Niebler, Eric]]
    [copyright 2002 2004 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
        <ulink url="http://www.boost.org/LICENSE_1_0.txt">
            http://www.boost.org/LICENSE_1_0.txt
        </ulink>)
    ]
    [last-revision $Date: 2005/04/30 01:48:44 $]
]

[/ QuickBook Document version 1.1 ]
[/ Sept 24, 2002 ]
[/ Sept 2, 2004 ]
[/ Feb 14, 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]]

[section:intro Introduction]

[:[*['"Why program by hand in five days what you can spend five years of your
life automating?"]]\n\n-- 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: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.

[h2 Comments]

Can be placed anywhere.

[pre
'''[/ comment (no output generated) ]'''
]

[h2 Phrase Level Elements]

[h3 Font Styles]

[pre'''
['italic], [*bold], [_underline], [^teletype]
''']

will generate:

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

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

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

will generate:

[*['bold-italic]]

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

* 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 [link syntax.unordered_lists 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*]]]
]

[blurb __note__ 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.]

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

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

[h3 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 [link syntax.document Document Info] 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\]]]]
]

[blurb __note__ The source mode strings are lowercase.]

[h3 line-break]

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

[blurb __note__ Note that `\n` is now preferred over `[br]`.]

[h3 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]'''].
More on anchors [link syntax.anchor_links here], [link syntax.section here] and
[link syntax.headings here].

[h3 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/]

[h3 Anchor links]

You can link within a document using:

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

See sections [link syntax.section Section] and [link syntax.headings Headings]
for more info.

[h3 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>].

[h3 function, class, member, enum or header links]

If you want to link to a function, class, member, enum 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]
[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:

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

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

[h3 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>
'''

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

[h3 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]`.

[h3 Images (terminal)]

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

[h2 Block Level Elements]

[h3 Document]

Every document must begin with a Document Info section, which should look
like this:

[pre'''
[document-type The Document Title
    [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]
    [last-revision $Date: 2005/04/30 01:48:44 $]
    [source-mode source-type]
]
''']

Where document-type is one of:

* book
* library
* part
* article
* chapter

and =version=, =id=, =dirname=, =copyright=, =purpose=, =category=, =authors=,
=license=, =last-revision= and =source-mode= are optional information.

Here =source-type= is a lowercase string setting the initial 
[link syntax.source_mode source mode]. If the =source-mode= field is omitted, a
default value of =c++= will be used.

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

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

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

[h3 Ordered lists]

[pre
# One
# Two
# Three
]

will generate:

# One
# Two
# Three

[h3 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

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

[h3 Unordered lists]

[pre'''
* First
* Second
* Third
''']

will generate:

* First
* Second
* Third

[h3 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

[h3 Code]

Preformatted code starts with a space or a tab. The code will be