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
|
\ create a documentation file
\ Copyright (C) 1995,1999,2000,2003,2004,2007 Free Software Foundation, Inc.
\ This file is part of Gforth.
\ Gforth is free software; you can redistribute it and/or
\ modify it under the terms of the GNU General Public License
\ as published by the Free Software Foundation, either version 3
\ of the License, or (at your option) any later version.
\ This program is distributed in the hope that it will be useful,
\ but WITHOUT ANY WARRANTY; without even the implied warranty of
\ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
\ GNU General Public License for more details.
\ You should have received a copy of the GNU General Public License
\ along with this program. If not, see http://www.gnu.org/licenses/.
\ the stack effect of loading this file is: ( addr u -- )
\ it takes the name of the doc-file to be generated.
\ the forth source must have the following format:
\ .... name ( stack-effect ) \ [prefix-] wordset [pronounciation]
\ \G description ...
\ The output is a file of entries that look like this:
\ make-doc [--prefix]-entry name stack-effect ) wordset [pronounciation]
\ description
\
\ (i.e., the entry is terminated by an empty line or the end-of-file)
\ this stuff uses the same mechanism as etags.fs, i.e., the
\ documentation is generated during compilation using a deferred
\ HEADER. It should be possible to use this togeter with etags.fs.
\ This is not very general. Input should come from stream files,
\ otherwise the results are unpredictable. It also does not detect
\ errors in the input (e.g., if there is something else on the
\ definition line) and reacts strangely to them.
\ possible improvements: we could analyse the defining word and guess
\ the stack effect. This would be handy for variables. Unfortunately,
\ we have to look back in the input buffer; we cannot use the cfa
\ because it does not exist when header is called.
\ This is ANS Forth with the following serious environmental
\ dependences: the variable LAST must contain a pointer to the last
\ header, NAME>STRING must convert that pointer to a string, and
\ HEADER must be a deferred word that is called to create the name.
r/w create-file throw value doc-file-id
\ contains the file-id of the documentation file
s" \ automatically generated by makedoc.fs" doc-file-id write-line throw
: >fileCR ( c-addr u -- )
doc-file-id write-line throw ;
: >file ( c-addr u -- )
doc-file-id write-file throw ;
: \G ( -- )
source >in @ /string >fileCR
source >in ! drop ; immediate
: put-doc-entry ( -- )
dpp @ normal-dp = \ not defining locals
latest 0<> and \ not an anonymous (i.e. noname) header
if
s" " >fileCR
s" make-doc " >file
>in @ >r
parse-name 2dup s" (" str= if
2drop ') parse
else
2dup s" {" str= if
2drop '} parse
else \ no stack comment or locals
2drop
r@ >in ! \ restore "\"
s" unknown " \ default stack comment
endif
endif
[char] \ parse 2drop
>in @
bl word dup c@
IF
dup count 1- chars + c@ [char] - =
IF
s" --" >file
count >file drop
ELSE
drop >in !
THEN
ELSE
drop >in !
THEN
latest name>string >file
s" " >file
>file
s" )" >file
POSTPONE \g
r> >in !
endif ;
: (doc-header) ( -- )
defers header
put-doc-entry ;
' (doc-header) IS header
|
