Annotation of gforth/doc/makedoc.fs, revision 1.1
1.1 ! anton 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
! 32: \
! 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
! 67: if
! 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