File:  [gforth] / gforth / Attic / makedoc.fs
Revision 1.2: download - view: text, annotated - select for diffs
Thu Jul 6 15:57:28 1995 UTC (27 years, 1 month ago) by pazsan
Branches: MAIN
CVS tags: HEAD
Added makedoc facility to cross compiler.
Now most doc-* reverences are resolved.

    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: 	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 ;
   59: 
   60: : (doc-header) ( -- )
   61:     defers header
   62:     put-doc-entry ;
   63: 
   64: ' (doc-header) IS header

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>