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.

Comments

Can be placed anywhere.

    [/ comment (no html generated) ]

Phrase Level Elements

Font Styles


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

Will generate:

italic
bold
underline
teletype

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

    [*['bold-italic]]

Will generate:

bold-italic

line-break

    [br]

Anchors

    [#named_anchor]

Links

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

Will generate:

this is boost's website....

Escape

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

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

Images (terminal)

    [$image.jpg]

Block Level Elements

Document

    [doc Document Title]

Should be at the very top

Page

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

    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.

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.

Bulleted lists

    * First
    * Second
    * Third

Will generate:

Ordered lists

    # First
    # Second
    # Third

Will generate:

  1. First
  2. Second
  3. Third

Code

    #include <iostream>

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

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

Preformatted

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

    This should not be taken in as C++

Horizontal rule (terminal)

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

The above will generate this:


blockquote

    [:sometext...]

Applies to one paragraph only.

Headings


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

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5
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

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 everytime sf_logo is seen, the picture will be inlined.

Some more examples:

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

(See Images and Links)

Invoking these macros:

    Hi Spirit :-)

Will generate this:

Hi Spirit

Blurbs

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

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

Tables

    [table Title

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

Will generate:

Title
R0-C0R0-C1R0-C2
R2-C0R2-C1R2-C2
R3-C0R3-C1R3-C2