Return to makedoc.fs CVS log

Up to [gforth] / gforth

Annotation of gforth/makedoc.fs, revision 1.2

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
1.2     ! pazsan     48:        s" " doc-file-id write-line throw
1.1       anton      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