1: \ create a documentation file
3: \ Copyright (C) 1995 Free Software Foundation, Inc.
5: \ This file is part of Gforth.
7: \ Gforth is free software; you can redistribute it and/or
8: \ modify it under the terms of the GNU General Public License
9: \ as published by the Free Software Foundation; either version 2
10: \ of the License, or (at your option) any later version.
12: \ This program is distributed in the hope that it will be useful,
13: \ but WITHOUT ANY WARRANTY; without even the implied warranty of
14: \ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15: \ GNU General Public License for more details.
17: \ You should have received a copy of the GNU General Public License
18: \ along with this program; if not, write to the Free Software
19: \ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
22: \ the stack effect of loading this file is: ( addr u -- )
23: \ it takes the name of the doc-file to be generated.
25: \ the forth source must have the following format:
26: \ .... name ( stack-effect ) \ wordset [pronounciation]
27: \ \G description ...
29: \ The output is a Forth source file that looks like this:
30: \ doc-entry name stack-effect ) wordset [pronountiation]
31: \ description
33: \ (i.e., the entry is terminated by an empty line or the end-of-file)
35: \ this stuff uses the same mechanism as etags.fs, i.e., the
36: \ documentation is generated during compilation using a deferred
37: \ HEADER. It should be possible to use this togeter with etags.fs.
39: \ This is not very general. Input should come from stream files,
40: \ otherwise the results are unpredictable. It also does not detect
41: \ errors in the input (e.g., if there is something else on the
42: \ definition line) and reacts strangely to them.
44: \ possible improvements: we could analyse the defining word and guess
45: \ the stack effect. This would be handy for variables. Unfortunately,
46: \ we have to look back in the input buffer; we cannot use the cfa
47: \ because it does not exist when header is called.
49: \ This is ANS Forth with the following serious environmental
50: \ dependences: the variable LAST must contain a pointer to the last
51: \ header, NAME>STRING must convert that pointer to a string, and
52: \ HEADER must be a deferred word that is called to create the name.
55: r/w create-file throw value doc-file-id
56: \ contains the file-id of the documentation file
58: s" \ automatically generated by makedoc.fs" doc-file-id write-line throw
60: : \G ( -- )
61: source >in @ /string doc-file-id write-line throw
62: source >in ! drop ; immediate
64: : put-doc-entry ( -- )
65: locals-list @ 0= \ not in a colon def, i.e., not a local name
66: last @ 0<> and \ not an anonymous (i.e. noname) header
68: s" " doc-file-id write-line throw
69: s" make-doc " doc-file-id write-file throw
70: last @ name>string doc-file-id write-file throw
71: >in @
72: [char] ( parse 2drop
73: [char] ) parse doc-file-id write-file throw
74: s" )" doc-file-id write-file throw
75: [char] \ parse 2drop
76: POSTPONE \g
77: >in !
78: endif ;
80: : (doc-header) ( -- )
81: defers header
82: put-doc-entry ;
84: ' (doc-header) IS header