[/ 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 ornote...]
[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 - ']'))
;
