quickbook.qbk

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

syntax highlighted according to the current [link syntax.source_mode 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)

Macros that are already defined are expanded in source code. Example:

[pre'''
[def __syntax_highlight__ [@quickbook/highlight.html syntax_highlight]]
[def __quickbook__ [@index.html quickbook]]

    using __quickbook__::__syntax_highlight__;
''']

Generates:

[def __syntax_highlight__ [@quickbook/highlight.html syntax_highlight]]
[def __quickbook__ [@index.html quickbook]]

    using __quickbook__::__syntax_highlight__;

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

[h3 Blockquote]

[pre
'''[:sometext...]'''
]

[:Indents the paragraph. This applies to one paragraph only.]

[h3 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 [link syntax.anchor_links Anchor links] and
[link syntax.section Section] for more info.

[h3 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 '\]' while the replacement text can be any phrase (even
marked up). Example:

[pre'''
[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&amp;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

[blurb __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 [link syntax.images__terminal_ Images]
and [link syntax.links Links])

Invoking these macros:

[pre'''
Hi __spirit__  :-)
''']

will generate this:

Hi __spirit__ :-)

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

[h3 Blurbs]

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

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

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

[h3 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:ref Quick Reference]

[table Syntax Compendium
    [[To do this...]        [Use this...]]
    [[comment]              [[^'''[/ some comment]''']]]
    [[['italics]]           [[^'''['italics] or /italics/''']]]
    [[[*bold]]              [[^'''[*bold] or *bold*''']]]
    [[[_underline]]         [[^'''[_underline] or _underline_''']]]
    [[[^teletype]]          [[^'''[^teletype] or =teletype=''']]]
    [[source mode]          [[^\[c++\]] or [^\[python\]]]]
    [[inline code]          [[^'''`int main();`''']]]
    [[line break]           [[^'''[br]''']]]
    [[line break]           [[^'''\n''']]]
    [[anchor]               [[^'''[#anchor]''']]]
    [[link]                 [[^'''[@http://www.boost.org Boost]''']]]
    [[anchor link]          [[^'''[link section.anchor Link text]''']]]
    [[refentry link]        [[^'''[link xml.refentry Link text]''']]]
    [[function link]        [[^'''[funcref fully::qualified::function_name Link text]''']]]
    [[class link]           [[^'''[classref fully::qualified::class_name Link text]''']]]
    [[member link]          [[^'''[memberref fully::qualified::member_name Link text]''']]]
    [[enum link]            [[^'''[enumref fully::qualified::enum_name Link text]''']]]
    [[header link]          [[^'''[headerref path/to/header.hpp Link text]''']]]
    [[escape]               [[^\'\'\'escaped text (no processing/formatting)\'\'\']]]
    [[single char escape]   [[^\\c]]]
    [[images]               [[^'''[$image.jpg]''']]]
    [[begin section]        [[^'''[section The Section Title]''']]]
    [[end section]          [[^'''[endsect]''']]]
    [[paragraph]            [No markup. Paragraphs start left-flushed and are terminated by two or more newlines.]]
    [[ordered list]         [[^# one\n# two\n# three\n]]]
    [[unordered list]       [[^\* one\n\* two\n\* three\n]]]
    [[code]                 [No markup. Preformatted code starts with a space or a tab.]]
    [[preformatted]         [[^'''[pre preformatted]''']]]
    [[block quote]          [[^'''[:sometext...]''']]]
    [[heading 1]            [[^'''[h1 Heading 1]''']]]
    [[heading 2]            [[^'''[h2 Heading 2]''']]]
    [[heading 3]            [[^'''[h3 Heading 3]''']]]
    [[heading 4]            [[^'''[h4 Heading 4]''']]]
    [[heading 5]            [[^'''[h5 Heading 5]''']]]
    [[heading 6]            [[^'''[h6 Heading 6]''']]]
    [[macro]                [[^'''[def macro_identifier some text]''']]]
    [[blurb]                [[^'''[blurb advertisement or note...]''']]]
    [[table]                [[^[table Title\n \[\[a\]\[b\]\[c\]\]\n    \[\[a\]\[b\]\[c\]\]\n\]]]]
    [[variablelist]         [[^[variablelist Title\n \[\[a\]\[b\]\]\n    \[\[a\]\[b\]\]\n\]]]]
]

[endsect]
[section:docinfo Library Document Grammar]

[c++]

    doc_info =
            space
        >>  '['
        >>  (   str_p("book")
            |   "article"
            |   "library"
            |   "chapter"
            |   "part"
            )
        >> hard_space
        >>  (  *(anychar_p -
                (ch_p('[') | ']' | eol_p)
                )
            )
        >> *( doc_version
            | doc_id
            | doc_dirname
            | doc_copyright
            | doc_purpose
            | doc_category
            | doc_authors
            | doc_license
            | doc_last_revision
            )
        >> ']' >> +eol_p
        ;

    doc_version =
            space
        >> "[version" >> hard_space
        >> (*(anychar_p - ']'))
        >> ']' >> +eol_p
        ;

    doc_id =
            space
        >> "[id" >> hard_space
        >> (*(anychar_p - ']'))
        >> ']' >> +eol_p
        ;

    doc_dirname =
            space
        >> "[dirname" >> hard_space
        >> (*(anychar_p - ']'))
        >> ']' >> +eol_p
        ;

    doc_copyright =
            space
        >> "[copyright" >> hard_space
        >> +( repeat_p(4)[digit_p]
              >> space
            )
        >> space
        >> (*(anychar_p - ']'))
        >> ']' >> +eol_p
        ;

    doc_purpose =
            space
        >> "[purpose" >> hard_space
        >> (*(anychar_p - ']'))
        >> ']' >> +eol_p
        ;

    doc_category =
            space
        >> "[category" >> hard_space
        >> (*(anychar_p - ']'))
        >> ']' >> +eol_p
        ;

    doc_author =
            space
        >>  '[' >> space
        >>  (*(anychar_p - ','))
        >>  ',' >> space
        >>  (*(anychar_p - ']'))
        >>  ']'
        ;

    doc_authors =
            space
        >> "[authors" >> hard_space
        >> doc_author
        >> *(   ','
                >>  doc_author
            )
        >> ']' >> +eol_p
        ;

    doc_license =
            space
        >> "[license" >> hard_space
        >> (*(anychar_p - ']'))
        >> ']' >> +eol_p
        ;

    doc_last_revision =
            space
        >> "[last-revision" >> hard_space
        >> (*(anychar_p - ']'))
        >> ']' >> +eol_p
        ;

    doc_source_mode =
        space
        >> "[source-mode" >> hard_space
        >> (
              str_p("c++") 
           |  "python"
           )
        >> space >> ']' >> +eol_p
        ;

    comment =
        "[/" >> *(anychar_p - ']') >> ']'
        ;

    space =
        *(space_p | comment)
        ;

    hard_space =
        (eps_p - (alnum_p | '_')) >> space  // must not be followed by
        ;                                   // alpha-numeric or underscore

[endsect]
[section:quickbook QuickBook Grammar]

    library =
        *(space_p | comment) >> blocks >> blank
        ;

    blocks =
       +(   block_markup
        |   code
        |   list
        |   hr
        |   comment >> *eol
        |   paragraph
        |   eol
        )
        ;

    space =
        *(space_p | comment)
        ;

    blank =
        *(blank_p | comment)
        ;

    eol = blank >> eol_p
        ;

    close_bracket =
        ']' |
        if_p(var(is_not_preformatted))
        [
            eol_p >> eol_p                  // Make sure that we don't go
        ]                                   // past a single block, except
        ;                                   // when preformatted.

    hard_space =
        (eps_p - (alnum_p | '_')) >> space  // must not be followed by
        ;                                   // alpha-numeric or underscore

    comment =
        "[/" >> *(anychar_p - ']') >> ']'
        ;

    hr =
        str_p("----")
        >> *(anychar_p - eol)
        >> +eol
        ;

    block_markup =
            '['
        >>  (   begin_section
            |   end_section
            |   headings
            |   blurb
            |   blockquote
            |   preformatted
            |   def_macro
            |   table
            |   variablelist
            |   xinclude
            )
        >>  (   (']' >> +eol)
            |   eps_p
            )
        ;

    begin_section =
           "section"
        >> hard_space
        >>  (':' >> (*(alnum_p | '_'))
            | eps_p
            )
        >> (*(anychar_p -
                close_bracket))
        ;

    end_section =
        str_p("endsect")
        ;

    headings =
        h1 | h2 | h3 | h4 | h5 | h6
        ;

    h1 = "h1" >> hard_space >> phrase
    h2 = "h2" >> hard_space >> phrase
    h3 = "h3" >> hard_space >> phrase
    h4 = "h4" >> hard_space >> phrase
    h5 = "h5" >> hard_space >> phrase
    h6 = "h6" >> hard_space >> phrase

    blurb =
        "blurb" >> hard_space
        >> phrase
        ;

    blockquote =
        ':' >> blank >>
        phrase
        ;

    preformatted =
        "pre" >> hard_space
        >> !eol >> phrase
        >> eps_p
        ;