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>