Annotation of gforth/doc/makedoc.fs, revision 1.14

1.1       anton       1: \ create a documentation file
                      2: 
1.12      anton       3: \ Copyright (C) 1995,1999,2000,2003,2004,2007 Free Software Foundation, Inc.
1.1       anton       4: 
                      5: \ This file is part of Gforth.
                      6: 
                      7: \ Gforth is free software; you can redistribute it and/or
                      8: \ modify it under the terms of the GNU General Public License
1.13      anton       9: \ as published by the Free Software Foundation, either version 3
1.1       anton      10: \ of the License, or (at your option) any later version.
                     11: 
                     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.
                     16: 
                     17: \ You should have received a copy of the GNU General Public License
1.13      anton      18: \ along with this program. If not, see http://www.gnu.org/licenses/.
1.1       anton      19: 
                     20: 
                     21: \ the stack effect of loading this file is: ( addr u -- )
                     22: \ it takes the name of the doc-file to be generated.
                     23: 
                     24: \ the forth source must have the following format:
1.2       pazsan     25: \  .... name ( stack-effect ) \ [prefix-] wordset [pronounciation]
1.1       anton      26: \ \G description ...
                     27: 
1.3       crook      28: \ The output is a file of entries that look like this:
                     29: \ make-doc [--prefix]-entry name stack-effect ) wordset [pronounciation]
1.1       anton      30: \ description
                     31: \
                     32: \ (i.e., the entry is terminated by an empty line or the end-of-file)
                     33: 
                     34: \ this stuff uses the same mechanism as etags.fs, i.e., the
                     35: \ documentation is generated during compilation using a deferred
                     36: \ HEADER. It should be possible to use this togeter with etags.fs.
                     37: 
                     38: \ This is not very general. Input should come from stream files,
                     39: \ otherwise the results are unpredictable. It also does not detect
                     40: \ errors in the input (e.g., if there is something else on the
                     41: \ definition line) and reacts strangely to them.
                     42: 
                     43: \ possible improvements: we could analyse the defining word and guess
                     44: \ the stack effect. This would be handy for variables. Unfortunately,
                     45: \ we have to look back in the input buffer; we cannot use the cfa
                     46: \ because it does not exist when header is called.
                     47: 
                     48: \ This is ANS Forth with the following serious environmental
                     49: \ dependences: the variable LAST must contain a pointer to the last
                     50: \ header, NAME>STRING must convert that pointer to a string, and
                     51: \ HEADER must be a deferred word that is called to create the name.
                     52: 
                     53: 
                     54: r/w create-file throw value doc-file-id
                     55: \ contains the file-id of the documentation file
                     56: 
                     57: s" \ automatically generated by makedoc.fs" doc-file-id write-line throw
                     58: 
1.3       crook      59: : >fileCR ( c-addr u -- )
                     60:     doc-file-id write-line throw ;
                     61: : >file    ( c-addr u -- )
                     62:     doc-file-id write-file throw ;
                     63: 
1.1       anton      64: : \G ( -- )
1.3       crook      65:     source >in @ /string >fileCR
1.1       anton      66:     source >in ! drop ; immediate
                     67: 
                     68: : put-doc-entry ( -- )
1.9       anton      69:     dpp @ normal-dp =   \ not defining locals
1.7       anton      70:     latest 0<> and     \ not an anonymous (i.e. noname) header
1.1       anton      71:     if
1.3       crook      72:        s" " >fileCR
                     73:        s" make-doc " >file
1.11      anton      74:         >in @ >r
                     75:         parse-name 2dup s" (" str= if
                     76:             2drop ') parse
                     77:         else
                     78:             2dup s" {" str= if
                     79:                 2drop '} parse
                     80:             else \ no stack comment or locals
                     81:                 2drop
                     82:                 r@ >in ! \ restore "\"
                     83:                 s" unknown " \ default stack comment
                     84:             endif
                     85:         endif
1.2       pazsan     86:        [char] \ parse 2drop
1.14    ! anton      87:         >in @
        !            88:         parse-name dup
1.2       pazsan     89:        IF
1.14    ! anton      90:            2dup 1- chars + c@ [char] - =
1.2       pazsan     91:            IF
1.3       crook      92:                s" --" >file
1.14    ! anton      93:                >file drop
1.2       pazsan     94:            ELSE
1.14    ! anton      95:                2drop >in !
1.2       pazsan     96:            THEN
                     97:        ELSE
1.14    ! anton      98:            2drop >in !
1.2       pazsan     99:        THEN
1.11      anton     100:         latest name>string >file
                    101:         s"  " >file
1.3       crook     102:        >file
                    103:        s"  )" >file
1.1       anton     104:        POSTPONE \g
1.2       pazsan    105:        r> >in !
1.1       anton     106:     endif ;
                    107: 
                    108: : (doc-header) ( -- )
                    109:     defers header
                    110:     put-doc-entry ;
                    111: 
                    112: ' (doc-header) IS header

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