[/ QuickDoc Document version 0.5 ]
[doc Spirit QuickDoc v.05]
[/ Sept 24, 2002 ]

[def :-)            [$theme/smiley.gif]]
[def Spirit         [@http://spirit.sourceforge.net Spirit]]

[page Introduction]

[:[*['"Why program by hand in five days what you can spend five years of
your life automating?"]][br][br]-- Terrence Parr, author ANTLR/PCCTS]

Well, QuickDoc was done over the weekend, thanks to Spirit, which is just
over a year old... What is it? What you are viewing now, this
documentation, is autogenerated by QuickDoc. These files were generated
from one master:

[:[@quickdoc.txt quickdoc.txt]]

QuickDoc is a WikiWiki style documentation tool geared towards C++
documentation using simple rules and markup for simple formatting tasks.
QuickDoc extends the Wiki concept. Like the Wiki, QuickDoc documents are
simple text files. A single QuickDoc document can generate a fully linked
set of nice HTML documents complete with images and syntax-colorized C++
code.

[page Syntax Summary]

A QuickDoc 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 its own grammar, 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.

[h2 Comments]

Can be placed anywhere.

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

[h2 Phrase Level Elements]

[h4 Font Styles]

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

Will generate:

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

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

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

Will generate:

[*['bold-italic]]

[h4 line-break]

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

[h4 Anchors]

[pre
    '''[#named_anchor]'''
]

[h4 Links]

[pre
    '''[@http"//www.boost.org this is [*boost's] website....]'''
]

Will generate:

[@http"//www.boost.org this is [*boost's] website....]

[h4 Escape]

The escape mark-up is used when we don't want to do any processing.

[pre
"'    '''
    escape (no processing/formatting)
    '''"'
]

In rare occasions (such as when writing this document :-)) when the triple-
quote [^"''''"'] is needed, a double-quote followed by a single-quote
[^'''"''''] may be used as the escape delimiter.

[h4 Images (terminal)]

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

[h2 Block Level Elements]

[h4 Document]

[pre
    '''[doc Document Title]'''
]

Should be at the very top

[h4 Page]

[pre
    '''[page:level Page Title]'''
]

"Page Title" will be the html's title, a corresponding filename will be
created with the same name appended with ".html", 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:
"page_title.html"

A quickdoc document is basically a flat list of pages. However, the
generated table of contents may be formatted to reflect a certain
hierarchy. Example:

[pre
    intro
    basics
        pizza flavors
        pizza toppings
    crust
        size
        ingredients
]

Here, intro, basics and crust are at level 0 while pizza flavors, pizza
toppings, size and ingredients are level 1. level is optional (defaults to
zero) and will be page's hierarchical level from the top. Up to 5 levels
(0..5) are currently supported.

[h4 Paragraphs]

Paragraphs start left-flushed and are terminated by two or more newlines.
No markup is needed for paragraphs. QuickDoc automatically detects
paragraphs from the context.

[h4 Bulleted lists]

[pre
    * First
    * Second
    * Third
]

Will generate:

* First
* Second
* Third

[h4 Ordered lists]

[pre
    # First
    # Second
    # Third
]

Will generate:

# First
# Second
# Third

[h4 Code]

    #include <iostream>

    int main()
    {
        std::cout << "Hello World\n";
    }

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

[h4 Preformatted]

Sometimes, you don't want some preformatted code to be parsed as C++. In
such cases, use the '''[pre ... ]''' markup block.

[pre
    This should not be taken in as C++
]

[h4 Horizontal rule (terminal)]

[pre
    '''----------------- 4 or more dashes (text after the dashes are ignored)'''
]

The above will generate this:

----------------- 4 or more dashes (text after the dashes are ignored)

[h4 blockquote]

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

Applies to one paragraph only.

[h4 Headings]

[pre
'''
    [h1 Heading 1]
    [h2 Heading 2]
    [h4 Heading 3]
    [h4 Heading 4]
    [h5 Heading 5]
    [h6 Heading 6]
'''
]

[h1 Heading 1]
[h2 Heading 2]
[h4 Heading 3]
[h4 Heading 4]
[h5 Heading 5]
[h6 Heading 6]

All headings will have anchors with the same name, 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. Example:
heading_1

[h4 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&type=1]]'''
    '''sf_logo'''
]

Now everytime sf_logo is seen, the picture will be inlined.

[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&type=1]]
sf_logo

Some more examples:

[pre
'''    [def :-)            [$theme/smiley.gif]]
    [def Spirit         [@http://spirit.sourceforge.net Spirit]]'''
]

(See [@syntax_summary.html#images__terminal_ Images] and [@syntax_summary.html#links Links])

Invoking these macros:

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

Will generate this:

Hi Spirit :-)

[h4 Blurbs]

[pre
    '''
    [blurb :-) [*An eye catching advertisement or note...]
    [br][br]

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

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

[h4 Tables]

[pre
'''    [table Title

        [R0-C0]     [R0-C1]     [R0-C2]
        [R1-C0]     [R1-C1]     [R1-C2]
        [R2-C0]     [R2-C1]     [R2-C2]
    ]'''
]

Will generate:

[table Title
    [R0-C0]     [R0-C1]     [R0-C2]
    [R2-C0]     [R2-C1]     [R2-C2]
    [R3-C0]     [R3-C1]     [R3-C2]
]

[page Grammar]

    document =
        doc_info >> blocks >> space
        ;

    blocks =
       +(   block_markup
        |   code
        |   unordered_list
        |   ordered_list
        |   hr
        |   comment >> *eol_p
        |   paragraph
        |   eol_p
        )
        ;

    space =
        *(blank_p | comment)
        ;

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

    doc_info =
            *(space_p | comment)
        >> "[doc" >> space
        >> (*(anychar_p - ']'))
        >> ']' >> +eol_p
        ;

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

    block_markup =
            '['
        >>  (   page
            |   headings
            |   blurb
            |   blockquote
            |   preformatted
            |   def_macro
            |   table
            )
        >>  ']'
        >> +eol_p
        ;

    page =
            "page"
        >>  !(':' >> uint_p)
        >>  space
        >>  (*(anychar_p - ']'))
        ;

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

    h1 = "h1" >> space >> phrase;
    h2 = "h2" >> space >> phrase;
    h3 = "h3" >> space >> phrase;
    h4 = "h4" >> space >> phrase;
    h5 = "h5" >> space >> phrase;
    h6 = "h6" >> space >> phrase;

    blurb =
        "blurb" >> space
        >> phrase
        ;

    blockquote =
        ':' >> space >>
        phrase
        ;

    preformatted =
        "pre" >> space >>
        phrase
        ;

    def_macro =
        "def" >> space >> identifier
         >> space >> phrase
        ;

    table =
        "table" >> space
        >>  (*(anychar_p - eol_p))
        >>  +eol_p
        >> *(   table_row
                >> +eol_p
            )
        >>  eps_p
        ;

    table_row =
       *(       space
            >>  ch_p('[')
            >>  phrase
            >>  ch_p(']')
            >>  space
        )
        ;

    identifier =
        *(anychar_p - (space_p | ']'))
        ;

    code =
        code_line >> *(*eol_p >> code_line)
        ;

    code_line =
        ((ch_p(' ') | '\t'))
        >> *(anychar_p - eol_p) >> eol_p
        ;

    unordered_list =
        +('*' >> space >> line)
        ;

    ordered_list =
        +('#' >> space >> line)
        ;

    common =
            self.actions.macro
        |   phrase_markup
        |   escape
        |   comment
        ;

    line =
       *(   common
        |   (anychar_p - eol_p)
        )
        >> +eol_p
        ;

    paragraph =
       *(   common
        |   (   anychar_p
                - (eol_p >> eol_p)
            )
        )
        >> +eol_p
        ;

    phrase =
       *(   common
        |   comment
        |   (anychar_p - ']')
        )
        ;

    phrase_markup =
            '['
        >>  (   image
            |   link
            |   bold
            |   italic
            |   underline
            |   teletype
            |   str_p("br")
            |   unexpected
            )
        >>  ']'
        ;

    escape =
            (
                "'''"
            >>  *(anychar_p - "'''")
            >>  "'''"
            )
        |   (
                "\"'"
            >>  *(anychar_p - "\"'")
            >>  "\"'"
            )
        ;

    image =
            '$' >> space
        >> (*(anychar_p - ']'))
        ;

    link =
            '@'
        >>  (*(anychar_p - space))
        >>  space >> phrase
        ;

    bold =
            ch_p('*')
        >>  space >> phrase
        ;

    italic =
            ch_p('\'')
        >>  space >> phrase
        ;

    underline =
            ch_p('_')
        >>  space >> phrase
        ;

    teletype =
            ch_p('^')
        >>  space >> phrase
        ;

    unexpected =
        (*(anychar_p - ']'))
        ;
