source: project/wiki/eggref/5/scm2wiki @ 39262

Last change on this file since 39262 was 39262, checked in by svnwiki, 2 months ago

Anonymous wiki edit for IP [62.44.134.200]: Add initial egg documentation.

File size: 11.6 KB
Line 
1[[tags: egg]]
2
3== scm2wiki
4
5[[toc:]]
6
7=== Description
8
9scm2wiki is an in-source documentation tool. It uses stand-alone comment blocks and commented definitions in Scheme source code to generate documentation in Markdown or Chicken-flavored svnwiki format. scm2wiki supports Markdown in comments.
10
11scm2wiki can generate documentation for the following definition types:
12
13* variable and procedure definitions using {{define}}
14* constant definitions using {{define-constant}}
15* macro definitions using {{define-syntax}} (limited support, see [example](#example))
16* record type definitions using {{define-record}}, {{define-record-type}}, and {{defstruct}}
17* coops class definitions using {{define-class}}
18* coops generic procedure specializations using {{define-method}}
19
20scm2wiki understands Chicken Scheme's native {{module}} declarations. By default, it will only generate documentation for symbols that are exported.
21
22There is also some limited support for simple type annotations, including [[typed-records]]. However, this feature is not yet complete.
23
24For svnwiki output, scm2wiki translates Markdown text. However, translation is limited and does not yet support lists, plain hyperlinks, inline images, and formatting in tables.
25
26
27=== Repository
28
29[[https://github.com/utz82/scm2wiki]]
30
31
32=== Requirements
33
34* [[args]]
35* [[comparse]]
36=== Usage
37
38This egg provides the {{scm2wiki}} command line utility, which can be used as follows:
39
40{{$ scm2wiki [options...]}}
41
42By default, scm2wiki reads from STDIN and outputs Markdown to STDOUT. The following options are available:
43
44<table>
45<tr><th>Option</th><th>Function</th></tr>
46<tr><td>-i, --infile=FILENAME</td><td>specify an input file</td></tr>
47<tr><td>-o, --outfile=FILENAME</td><td>specify an output file</td></tr>
48<tr><td>-p, --prefix=STRING</td><td>change the comment prefix (default ";;;")</td></tr>
49<tr><td>--svn</td><td>output to svnwiki instead of Markdown</td></tr>
50<tr><td>-a</td><td>create anchor links (Markdown only)</td></tr>
51<tr><td>--document-internals</td><td>emit documentation for non-exported definitions</td></tr>
52
53</table>
54
55scm2wiki will only consider code comments with a specific, user-defined prefix. By default, the prefix is ";;;". See the following example for a complete list of supported source code elements.
56
57If the {{-a}} flag is specified, anchor links will be created for each defined binding. This allows for easy cross-referencing of definitions. The anchor id is the name of the binding, prefixed by {{def-}}. Characters not allowed in URLs are stripped. This feature works only in Markdown mode.
58
59
60=== Example
61
62The following source file demonstrates the various types of in-source documentation currently supported by scm2wiki. See below for the resulting output in Markdown and svnwiki formats.
63
64<enscript highlight="scheme">
65;; this comment will be ignored
66
67;;; # A Test Heading
68
69(module foo
70    *
71
72  (import scheme (chicken base) srfi-9 coops defstruct)
73
74  ;;; A stand-alone comment stretching multiple lines
75  ;;; *with* `formatting` **and** a [named link](https://call-cc.org)
76
77  ;;; ```Scheme
78  ;;; ;; A fenced code block
79  ;;; (+ 1 2 3)
80  ;;; ```
81
82  ;;; an   | interesting | table
83  ;;; ---- | ----------- | -----
84  ;;; with | actual      | content
85
86  ;; An undocumented variable definition
87  (define bar 0)
88
89  ;;; A documented variable
90  (define baz 0)
91
92  ;;; (procedure (foo X))
93  ;;; A manual annotation in the first line of a comment overrides any auto-
94  ;;; detected definition type. This is useful to mark closures, which scm2wiki
95  ;;; would class as variable definitions otherwise.
96  (define foo
97    (let ((z #t))
98      (lambda (x)
99        (set! z x))))
100
101  ;;; Since constants are not visible outside a translation unit, this constant
102  ;;; is not included in the documentation.
103  ;;; Override this behavior with the `--doc-internals` command line argument.
104  (define-constant bar1 0)
105
106  ;; An undocumented procedure
107  (define (fooproc x)
108    x)
109
110  ;;; A documented procedure
111  (define (bazproc y)
112    (+ y y))
113
114  ;;; (footax arg1 ...)
115  ;;; A list expression at the start of a syntax comment is interpreted as
116  ;;; the syntax' signature. scm2wiki does not auto-detect syntax signatures.
117  (define-syntax footax
118    (syntax-rules ()
119      ((_ a ...) (list a ...))))
120
121  ;;; A record type definition using defstruct
122  (defstruct bla
123    x ;;; a field comment
124    y
125    (z 1) ;;; another field comment
126    )
127
128  ;;; A record type definition using chicken/define-record
129  (define-record blu x y)
130
131  ;;; A record type definition using srfi-9
132  (define-record-type blorb
133    (make-blorb x y)
134    blorb?
135    (x blorb-x blorb-x-set!)
136    (y blorb-y))
137
138  ;;; A very simple coops class type defintion.
139  (define-class <myclass> ()
140    (foobar))
141
142  ;;; A slightly more complex coops class definition derived from `<myclass>`.
143  (define-class <mysubclass> (<myclass>)
144    (foo
145     (bar 0)
146     (baz initform: 0 accessor: myclass-baz)))
147
148  ;;; A procedure specialization on <mysubclass>.
149  (define-method (do-foo primary: (baz <mysubclass>) another-arg)
150    42)
151
152  ) ;; end module foo
153</enscript>
154
155The resulting Markdown output:
156
157<enscript>
158# A Test Heading
159## [module] foo
160
161A stand-alone comment stretching multiple lines
162*with* `formatting` **and** a [named link](https://call-cc.org)
163
164` ` `Scheme
165;; A fenced code block
166(+ 1 2 3)
167` ` `
168
169an   | interesting | table
170---- | ----------- | -----
171with | actual      | content
172
173#### [variable] `bar`
174**default:** `0`
175
176
177#### [variable] `baz`
178**default:** `0`
179A documented variable
180
181
182#### [procedure] `(foo X)`
183A manual annotation in the first line of a comment overrides any auto-
184detected definition type. This is useful to mark closures, which scm2wiki
185would class as variable definitions otherwise.
186
187
188#### [procedure] `(fooproc X)`
189
190
191
192#### [procedure] `(bazproc Y)`
193
194A documented procedure
195
196
197#### [syntax] `(footax ARG1 ...)`
198
199A procedure signature at the start of a syntax comment is interpreted as
200the syntax' signature. scm2wiki does not auto-detect syntax signatures.
201
202
203### [record] `bla`
204**[constructor] `(make-bla #!key X (Y 1) (Z 1))`**
205**[predicate] `bla?`**
206**implementation:** `defstruct`
207
208field | getter  | setter       | default | type     | comment
209----- | ------- | ------------ | ------- | -------- | ------------------------------
210`x`   | `bla-x` | `bla-x-set!` |         |          | `a field comment`
211`y`   | `bla-y` | `bla-y-set!` | `1`     |          |
212`z`   | `bla-z` | `bla-z-set!` | `1`     | `number` | `a field with type annotation`
213
214A record type definition using defstruct
215
216
217### [record] `blu`
218**[constructor] `(make-blu X Y)`**
219**[predicate] `blu?`**
220**implementation:** `define-record`
221
222field | getter  | setter
223----- | ------- | ------------
224`x`   | `blu-x` | `blu-x-set!`
225`y`   | `blu-y` | `blu-y-set!`
226
227A record type definition using chicken/define-record
228
229
230### [record] `blorb`
231**[constructor] `(make-blorb X Y)`**
232**[predicate] `blorb?`**
233**implementation:** `srfi-9`
234
235field | getter    | setter
236----- | --------- | --------------
237`x`   | `blorb-x` | `blorb-x-set!`
238`y`   | `blorb-y` |
239
240A record type definition using srfi-9
241
242
243### [class] `<myclass>`
244slot: `foobar`
245
246
247A very simple coops class type defintion.
248
249
250### [class] `<mysubclass>`
251**inherits from:** [`<myclass>`](#class-ltmyclassgt)
252
253slot  | initform | accessor
254----- | -------- | -------------
255`foo` |          |
256`bar` | `0`      |
257`baz` | `0`      | `myclass-baz`
258
259A slightly more complex coops class definition derived from `<myclass>`.
260
261
262**[method] `(do-foo primary: (BAZ <mysubclass>) ANOTHER-ARG)`**
263A procedure specialization on <mysubclass>.
264</enscript>
265
266The resulting svnwiki output:
267
268 == A Test Heading
269 == Module foo
270 
271 A stand-alone comment stretching multiple lines
272 ''with'' {{formatting}} '''and''' a [[https://call-cc.org|named link]]
273 
274 <enscript highlight=#"scheme#">;; A fenced code block
275 (+ 1 2 3)</enscript>
276 
277 
278 
279 <table><tr><th>an   </th><th>interesting</th><th>table</th></tr>
280 <tr><td>with </td><td>actual</td><td>content</td></tr>
281 
282 </table>
283 
284 <constant>bar</constant>
285 ; default : {{0}}
286 
287 
288 <constant>baz</constant>
289 ; default : {{0}}
290 A documented variable
291 
292 
293 <procedure>(foo X)</procedure>
294 
295 A manual annotation in the first line of a comment overrides any auto-
296 detected definition type. This is useful to mark closures, which scm2wiki
297 would class as variable definitions otherwise.
298 
299 
300 <procedure>(fooproc X)</procedure>
301 
302 
303 
304 <procedure>(bazproc Y)</procedure>
305 
306 A documented procedure
307 
308 
309 <syntax>(footax ARG1 ...)</syntax>
310 
311 A procedure signature at the start of a syntax comment is interpreted as
312 the syntax' signature. scm2wiki does not auto-detect syntax signatures.
313 
314 
315 <record>bla</record>
316 ; constructor : {{(make-bla #!key X (Y 1) (Z 1))}}
317 ; predicate : {{bla?}}
318 ; implementation : {{defstruct}}
319 
320 <table><tr><th>field</th> <th>getter</th> <th>setter</th> <th>default</th> <th>type</th> <th>comment</th></tr><tr><td>{{x}}</td> <td>{{bla-x}}</td> <td>{{bla-x-set!}}</td> <td></td> <td></td> <td>{{a field comment}}</td></tr>
321 <tr><td>{{y}}</td> <td>{{bla-y}}</td> <td>{{bla-y-set!}}</td> <td>{{1}}</td> <td></td> <td></td></tr>
322 <tr><td>{{z}}</td> <td>{{bla-z}}</td> <td>{{bla-z-set!}}</td> <td>{{1}}</td> <td>{{number}}</td> <td>{{a field with type annotation}}</td></tr></table>
323 
324 A record type definition using defstruct
325 
326 
327 <record>blu</record>
328 ; constructor : {{(make-blu X Y)}}
329 ; predicate : {{blu?}}
330 ; implementation : {{define-record}}
331 
332 <table><tr><th>field</th> <th>getter</th> <th>setter</th></tr><tr><td>{{x}}</td> <td>{{blu-x}}</td> <td>{{blu-x-set!}}</td></tr>
333 <tr><td>{{y}}</td> <td>{{blu-y}}</td> <td>{{blu-y-set!}}</td></tr></table>
334 
335 A record type definition using chicken/define-record
336 
337 
338 <record>blorb</record>
339 ; constructor : {{(make-blorb X Y)}}
340 ; predicate : {{blorb?}}
341 ; implementation : {{srfi-9}}
342 
343 <table><tr><th>field</th> <th>getter</th> <th>setter</th></tr><tr><td>{{x}}</td> <td>{{blorb-x}}</td> <td>{{blorb-x-set!}}</td></tr>
344 <tr><td>{{y}}</td> <td>{{blorb-y}}</td> <td></td></tr></table>
345 
346 A record type definition using srfi-9
347 
348 
349 === Class <myclass>
350 <class><myclass></class>
351 
352 
353 ; slot : {{foobar}}
354 
355 
356 A very simple coops class type defintion.
357 
358 
359 
360 === Class <mysubclass>
361 <class><mysubclass></class>
362 
363 ; inherits from : [[#Class-<myclass>|<myclass>]]
364 
365 <table><tr><th>slot</th> <th>initform</th> <th>accessor</th></tr><tr><td>{{foo}}</td> <td></td> <td></td></tr>
366 <tr><td>{{bar}}</td> <td>{{0}}</td> <td></td></tr>
367 <tr><td>{{baz}}</td> <td>{{0}}</td> <td>{{myclass-baz}}</td></tr></table>
368 
369 A slightly more complex coops class definition derived from {{<myclass>}}.
370 
371 
372 <method>(do-foo primary: (BAZ <mysubclass>) ANOTHER-ARG)</method>
373 A procedure specialization on <mysubclass>.
374 
375 
376=== License
377
378 Copyright (c) 2019-2020, Michael Neidel
379 
380 Permission is hereby granted, free of charge, to any person obtaining a copy
381 of this software and associated documentation files (the "Software"), to deal
382 in the Software without restriction, including without limitation the rights
383 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
384 copies of the Software, and to permit persons to whom the Software is
385 furnished to do so, subject to the following conditions:
386 
387 The above copyright notice and this permission notice shall be included in all
388 copies or substantial portions of the Software.
389 
390 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
391 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
392 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
393 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
394 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
395 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
396 SOFTWARE.
Note: See TracBrowser for help on using the repository browser.