Spirit QuickDoc C++ documentation tool
"Why program by hand in five days what you can spend five years of your life
automating?"
-- 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? Here's a sample set of HTML documents autogenerated by
QuickDoc:
http://spirit.sf.net/dl_more/phoenix_v1_0_docs/index.html
These files were generated from one master:
http://spirit.sf.net/dl_more/phoenix_v1_0_docs/doc/phoenix_users_manual.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.
QuickDoc v0.5 Syntax Summary
*** See phoenix_users_manual.txt for an example of a document
*** using the quickdoc format. Compile the quickdoc.exe application
*** and feed phoenix_users_manual.txt. The output is a fully linked
*** set of html pages. Have fun with documentation :-)!
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 one or more newlines.
Bulleted lists
* First
* Second
* Third
Ordered lists
# First
# Second
# Third
Code
int main()
{
}
Preformatted code starts with a space or a tab. The code will be syntax
highlighted.
Formatting
['italic]
[*bold]
[_underline]
[^teletype]
horizontal rule
----------------- 4 or more dashes (text after the 4 dashes are ignored)
line-break
[br]
blockquote
[: sometext...]
Applies to one paragraph only.
Anchors
[#named_anchor]
Headings
[h1 Heading 1]
[h2 Heading 2]
[h3 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
Blurbs
[blurb an eye catching advertisement or note]
comment
[/ comment (no html generated) ]
Escape
'''
escape (no processing/formatting)
'''
image
[$image.jpg]
Macros (Powerful!)
[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 my_picture [$http://www.pixels.com/my_picture.jpg]]
Now everytime my_picture is seen, the picture will be inlined.
Links
[@url some possibly [*marked up] text....]
Tables
[table Title
[R0-C0] [R0-C1] [R0-C2]
[R2-C0] [R2-C1] [R2-C2]
[R3-C0] [R3-C1] [R3-C2]
]
Cheers,
--Joel [Sept 24, 2002]
Grammar:
document =
doc_info >> blocks >> space
;
blocks =
+( block_markup
| code
| unordered_list
| ordered_list
| hr
| comment >> *eol_p
| paragraph
)
;
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
| 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
;
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 >> paragraph)
;
ordered_list =
+('#' >> space >> paragraph)
;
paragraph =
*( self.actions.macro
| phrase_markup
| escape
| comment
| (anychar_p - eol_p)
)
>> +eol_p
;
phrase =
*( self.actions.macro
| phrase_markup
| escape
| comment
| (anychar_p - ']')
)
;
phrase_markup =
'['
>> ( image
| link
| bold
| italic
| underline
| teletype
| str_p("br")
| unexpected
)
>> ']'
;
escape =
"'''"
>> *(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 - ']'))
;
