1: \ create a documentation file
2: \ the stack effect of loading this file is: ( addr u -- )
3: \ it takes the name of the doc-file to be generated.
5: \ the forth source must have the following format:
6: \ .... name ( stack-effect ) \ wordset [pronounciation]
7: \ \G description ...
9: \ The output is a Forth source file that looks like this:
10: \ doc-entry name stack-effect ) wordset [pronountiation]
11: \ description
13: \ (i.e., the entry is terminated by an empty line or the end-of-file)
15: \ this stuff uses the same mechanism as etags.fs, i.e., the
16: \ documentation is generated during compilation using a deferred
17: \ HEADER. It should be possible to use this togeter with etags.fs.
19: \ This is not very general. Input should come from stream files,
20: \ otherwise the results are unpredictable. It also does not detect
21: \ errors in the input (e.g., if there is something else on the
22: \ definition line) and reacts strangely to them.
24: \ possible improvements: we could analyse the defining word and guess
25: \ the stack effect. This would be handy for variables. Unfortunately,
26: \ we have to look back in the input buffer; we cannot use the cfa
27: \ because it does not exist when header is called.
29: \ This is ANS Forth with the following serious environmental
30: \ dependences: the variable LAST must contain a pointer to the last
31: \ header, NAME>STRING must convert that pointer to a string, and
32: \ HEADER must be a deferred word that is called to create the name.
35: r/w create-file throw value doc-file-id
36: \ contains the file-id of the documentation file
38: s" \ automatically generated by makedoc.fs" doc-file-id write-line throw
40: : \G ( -- )
41: source >in @ /string doc-file-id write-line throw
42: source >in ! drop ; immediate
44: : put-doc-entry ( -- )
45: locals-list @ 0= \ not in a colon def, i.e., not a local name
46: last @ 0<> and \ not an anonymous (i.e. noname) header
48: s" " doc-file-id write-line throw
49: s" make-doc " doc-file-id write-file throw
50: last @ name>string doc-file-id write-file throw
51: >in @
52: [char] ( parse 2drop
53: [char] ) parse doc-file-id write-file throw
54: s" )" doc-file-id write-file throw
55: [char] \ parse 2drop
56: POSTPONE \g
57: >in !
58: endif ;
60: : (doc-header) ( -- )
61: defers header
62: put-doc-entry ;
64: ' (doc-header) IS header