Annotation of gforth/makedoc.fs, revision 1.1
1.1 ! anton 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.
! 4:
! 5: \ the forth source must have the following format:
! 6: \ .... name ( stack-effect ) \ wordset [pronounciation]
! 7: \ \G description ...
! 8:
! 9: \ The output is a Forth source file that looks like this:
! 10: \ doc-entry name stack-effect ) wordset [pronountiation]
! 11: \ description
! 12: \
! 13: \ (i.e., the entry is terminated by an empty line or the end-of-file)
! 14:
! 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.
! 18:
! 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.
! 23:
! 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.
! 28:
! 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.
! 33:
! 34:
! 35: r/w create-file throw value doc-file-id
! 36: \ contains the file-id of the documentation file
! 37:
! 38: s" \ automatically generated by makedoc.fs" doc-file-id write-line throw
! 39:
! 40: : \G ( -- )
! 41: source >in @ /string doc-file-id write-line throw
! 42: source >in ! drop ; immediate
! 43:
! 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
! 47: if
! 48: 0 0 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 ;
! 59:
! 60: : (doc-header) ( -- )
! 61: defers header
! 62: put-doc-entry ;
! 63:
! 64: ' (doc-header) IS header
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>