source: project/wiki/mole @ 9471

Last change on this file since 9471 was 9471, checked in by sjamaan, 12 years ago

Add wikified docs for 'mole'

File size: 3.6 KB
Line 
1[[tags: egg]]
2
3== mole
4
5[[toc:]]
6
7=== Description
8
9A literate programming tool for Scheme.
10
11=== Author
12
13[[Kirill Lisovsky]]
14
15=== Requirements
16
17None
18
19=== Download
20
21[[http://www.call-with-current-continuation.org/eggs/mole.egg|mole.egg]]
22
23=== Documentation
24
25The mole homepage is located at [[http://www196.pair.com/lisovsky/ad/mole]].
26
27Mole reads the Scheme source code and parse it to the structural
28elements using {{";===="}} as chapter separator, {{";----"}} as
29section start, {{";^^^^"}} as section end (if necessary) and {{"; "}}
30or {{"("}} at the beginning of the "chunk".  Chunk may be a function,
31macro, binding, etc. More documentation on the source code formatted
32style may be found in mole.txt file.
33
34Parsed data is represented as the SXML tree. A number of useful
35reports may be generated querying this data. For example, Mole may be
36used as a tool for automated documentation generation. For such a
37purpose it works as a filter that reads documented Scheme code from
38the standard input and produces some kind of hypertext documentation
39in the HTML format to the standard output.
40
41Use the command "{{mole -h}}" for usage instructions.
42
43==== Test cases
44
45Since version 3.4 Mole has an ability to attach a test suite to every
46function in documentation which has a test case in a test fixture file
47specified with {{--tf=<file>}} option.  If the file name is omitted
48(an option {{--tf}} ), then file {{xtest-fixture.scm}} in subdirectory
49test is used.
50
51Test cases are XTester-compatible they has to be formatted as follows:
52
53  ;@ name (optional)
54  ; description (optional)
55  (xtest-assert
56  ...
57  )
58
59Please note the closing {{")"}} in first position (It's used to detect
60end of test case).  If the name of the function tested may be not
61detected automatically, it has to be specified explicitly using ;@
62{{<some-name>}} comment before the test case.
63
64Processing of test fixture file may be controlled using {{;$}} comment
65as an explicit end of file. The rest of test fixture will be not
66processed by Mole.
67
68For every function with test suite a clickable {{[+]}} is included in
69table of content.
70
71==== Mole Source Code Formating Style
72
73The syntax accepted by Mole is described by the following grammar:
74
75  <module>  ::= ( <chapter> | <section> | <chunk> | <comment> )*
76   <chapter> ::= ( <section> | <chunk> | <comment>)*
77   <section> ::= ( <chunk> | <comment> )*
78   <chunk> :== "(" <chunk-type> <name> <description>? <code> ")"
79   <chunk-type> :== function | macro | app
80   <name> ::= "(" name STRING ")"
81   <description> ::= "(" description STRING ")"
82   <code> ::= "(" code STRING ")"
83   <comment> ::= "(" comment STRING ")"
84
85===== Chapter
86 
87  ;=============================================================
88  ; <Chapter name>
89  ; Description
90  ;  of the
91  ; module 
92 
93Any number of sections or chunks may follow
94
95End of chapter is {{";="}} in the first position
96
97===== Section
98
99  ;-----------------------------
100  ; <Section name>
101  ; Description
102  ;  of the
103  ; section
104
105End of section is {{";="}} or {{";-"}}  in the first position
106
107'''NOTE:''' in chapter and section separators just two first characters
108are important: {{";="}} or {{";-"}} respectively.
109
110===== Unit
111
112  ; Description
113  ;  of the
114  ; chunk
115  (chunk-code
116    ...
117   ...)
118
119End of chunk is one of: {{";="}} {{";-"}} {{";*"}} or {{"; "}} in the
120first position.
121
122Chunk descriptions are of optional.
123Description-less chunks have to be nested in section or chapter.
124If they are nested in module they are ignored by parser.
125
126===== Head comment
127
128  <Comment-block> ::= (^;;\S+$)+  ; Semicolons in the first and second pos
129
130=== Changelog
131
132* 3.4
133
134=== License
135
136Public Domain
Note: See TracBrowser for help on using the repository browser.