HomeAboutCodePastes
summaryrefslogtreecommitdiff
path: root/chalk.svnwiki
blob: be4c7b4a62a4f86d7c42268804ba287a6f8122ed (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
[[tags: egg]]
[[toc:]]
== chalk
Simple hahn-style in-source documentation

=== Introduction
Chalk attempts to be a simpler alternative to Chicken 4's
[[https://wiki.call-cc.org/eggref/4/hahn|hahn]] +
[[https://wiki.call-cc.org/eggref/4/hahn-utils|hahn-utils]], generating wiki
output with support for procedure, variables, syntax, modules, include files,
and egg files. It tries to be as basic as possible, performing almost no code
analysis and no evaluation, while making it easy to generate documentation from
one or more files.

The following is hahn's fibonacci example, rewritten for chalk. Note key
differences: The example is simply a string (and therefore not evaluated),
whith the option of a {{@pre}} or {{@post}} caption. Additionally, the
docstring must be contained within a single string and a heading is not
generated for the procedure name.

<enscript highlight="scheme">
(define (fibonacci n)
  @("Computes the nth [[http://en.wikipedia.org/wiki/Fibonacci_number|Fibonacci]].
This naïve algorithm runs in ''O(2^n)''; using e.g. memoization, we could bring
it down to ''O(n)''."
    (n "The nth number to calculate")
    (@to "integer")
    (@example
     (@pre "For example, computing the 6th Fibonnaci number (starting from 0)")
     "(fibonacci 6) ; => 8"))
  (case n
    ((0) 0)
    ((1) 1)
    (else (+ (fibonacci (- n 1))
             (fibonacci (- n 2))))))
</enscript>

Which produces the following wiki output:

<procedure>(fibonacci n) → integer</procedure>
Computes the nth [[http://en.wikipedia.org/wiki/Fibonacci_number|Fibonacci]].
This naïve algorithm runs in ''O(2^n)''; using e.g. memoization, we could bring
it down to ''O(n)''.

; n : The nth number to calculate

For example, computing the 6th Fibonnaci number (starting from 0)
<enscript highlight="scheme">
(fibonacci 6) ; => 8
</enscript>

=== Syntax

Most expressions of the following form can be documented to varying degrees of
automation, where {{SIGNATURE}} can be a pair (as in a procedure definition).

<enscript>
(DEFINE SIGNATURE BODY ...)
</enscript>

Documentation entails inserting a docexpr of the following form before the
{{BODY}}.

<enscript>
@("Description" [OPTION] ...)
</enscript>

==== Variables
Variables are documented as follows, ignoring potentially disastrous rounding practices:
<enscript highlight="scheme">
(define pi @("The ratio of a circle's circumference to its diameter.") 3.14)
</enscript>

The special tag {{@internal}} can be used to suppress output, and is useful for
documenting unexported variables internally:

<enscript highlight="scheme">
(define counter
  @("How many times thing has happened."
    (@internal)))
</enscript>

==== Procedures

Procedures are documented similarly, but can contain the tags, {{@to}}, and
{{@example}}, as well as listing function parameters:

<enscript highlight="scheme">
(define (foobar a b)
  @("Does baz."
    (a "An input")
    (b "Another input")
    (@to integer)
    (@example
     (@pre "For example, to do baz with foobar:")
     "(foobar blarg arg) ; => 4"))
  (baz))
</enscript>

In the case of procedures defined as variables, chalk considers it a variable
by default, using the function name as a signature. In either case, you can
override the default signature with the tag {{@sig}}, and you can specify that
it is indeed a procedure as follows:

<enscript highlight="scheme">
(define function?
  @(fn "This is definitely a function"
       (@sig (function? a b c)))
  (lambda () (print "bar")))
</enscript>

You can specify that a variable definition is a procedure with any of {{fn}},
{{proc}}, {{function}}, or {{procedure}} in the first position of the docexpr.

Tags behave as follows:

; @to : A string or expression to be inserted as {{→ expr}}
; @example : A string to be enscripted with scheme highlighting, with optional {{@pre}} or {{@post}} caption.
; @sig : A string or expression that override the procedure signature
; @internal : Suppress output, documented for internal use.

==== Syntax definitions

Syntax definitions accept the same tags and is defined equivalently to
procedures, provided that it is is defined using {{define-syntax}}. The
{{@sig}} tag is especially useful for specifying syntax usage, since chalk
won't automatically detect the signature. Here's a rather silly example:

<enscript highlight="scheme">
(define-syntax hello
  @("Hello there!"
    (@sig (hello a b c)))
  (syntax-rules ()
    ((_ a b c)
     "Hello there!")))
</enscript>

For syntax defined otherwise, you can specify that it is syntax like so:

<enscript highlight="scheme">
(define-syntax-rule (hello a b c)
  @(syntax "Hello")
  "Hello there")
</enscript>

You can specify that a definition is syntax with either {{syntax}} or {{macro}}
in the first position of the docexpr.

==== Records

Currently, two types of record definitions are supported - {{define-record}}
and {{define-record-type}} from {{chicken.base}}. Records can be documented
internally by specifying a {{@internal}} file, and they accept one more tag
{{@full}}. When specified, it generates a list of all of the procedures
associated with that record definition. Otherwise, only the record name is
documented, and procedure documentation can be added manually.

For example:

<enscript highlight="scheme">
(define-record point
  @("A point"
    (@full))
  x y)
</enscript>

Produces the following output:

<record>point</record>
<procedure>(make-point x y)</procedure>
<procedure>point?</procedure>
<procedure>point-x</procedure>
<procedure>point-y</procedure>
A point

==== Top-level documentation

A docexpr outside of a definition can be used to insert arbitrary text.
Additionally, the following top-level tags are supported:

; script : Generate an enscript segment, with optional highlight tag. Can contain multiple strings.

<enscript highlight="scheme">
@(script
  (@highlight "scheme")
  "(print \"hello\")"
  "(print 4)")
</enscript>

In addition to the {{@highlight}} tag, a caption can be inserted before or
after a script using the tags {{@pre}} and {{@post}}.

; heading, title, == : A title

<enscript highlight="scheme">
@(== "My egg")
</enscript>

Various subheadings:

; subheading, subtitle, === :
; subsubheading, subsubtitle, ==== :
; subsubsubsubheading, subsubsubsubtitle, ===== :

; deflist : A definition list such as this one

<enscript highlight="scheme">
@(deflist
   (key "value")
   (definitionless-term)
   (term "definition"))
</enscript>

Lists and tables are not currently supported, but are planned for the future.
In the meantime, unsupported forms of wiki syntax can be inserted literally
using a top-level docexpr.

=== Compiling and running programs

To compile a scheme file containing chalk special syntax, you can use {{-X
chalk}}. For script usage (e.g. with {{csi -s}}), you can use {{import chalk}}.

=== Chalk program usage

The chalk program generates output to stdout or a specified output file based
on the given input file(s), and optionally: a {{.egg}} file, a
{{.release-info}} file, and/or a {{LICENSE}} file. For more info, see {{chalk --help}}:

<enscript>
Usage: chalk [OPTION]... [FILE]...
 -h, --help               Print usage
 -o, --output=FILE        Write to file
 -i, --ignore-egg         Ignore .egg file
 -r, --ignore-release     Ignore .release-info file
 -n, --no-toc             Don't add a toc
 -e, --email=EMAIL        Include EMAIL with author
 -H, --head=FILE          File to add to beginning of documentation
 -P, --prologue=FILE      File to add after synopsis
 -E, --epilogue=FILE      File to add before maintainer info
 -T, --tail=FILE          File to add to end of documentation
 -L, --no-license         Don't insert a license file
 -l, --license=FILE       File to use as license (defaults to LICENSE if unspecified)
 -m, --module-headers     Create === Module-name headers
 </enscript>

A {{.release-info}} file can contain optional comments following {{release}}
expressions (on the same line), which are used as version descriptions when
generating a version history section of the documentation, for example:

<enscript highlight="scheme">
(uri targz "https://example-url.com")
(release "0.3.1") ; Fixes bug
(release "0.3.0") ; Adds feature
(release "0.2.0")
(release "0.1.0") ; Initial version
</enscript>

=== Full Example

See the [[https://code.dieggsy.com/icu/tree/|ICU egg source code]] and
[[https://wiki.call-cc.org/eggref/5/icu|documentation]] for a full example of a
project using chalk.

=== Author
Diego A. Mundo

=== Version History

; 0.3.3 : Reduce line spacing, change license options
; 0.3.2 : Add multi-line script support
; 0.3.1 : Fix bug: release-info not ignored on ignore-egg
; 0.3.0 : Add support for records and syntax
; 0.2.0 : Add @example, listed function parameters, script caption
; 0.1.0 : Initial version