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

- First
- Second
- Third

#### 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-C0 | R0-C1 | R0-C2
| R2-C0 | R2-C1 | R2-C2 | R3-C0 | R3-C1 | R3-C2

Copyright © 2001-2002 Joel de Guzman
Permission to copy, use, modify, sell and distribute this document is granted provided this copyright notice appears in all copies. This document is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose.