Return to makedoc.fs CVS log

Up to [gforth] / gforth / doc

Added OOF documentation
Added scope prefix to glossary generator to document different occurances
of the same word

    1: \ create a documentation file
    2: 
    3: \ Copyright (C) 1995 Free Software Foundation, Inc.
    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
    9: \ as published by the Free Software Foundation; either version 2
   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
   18: \ along with this program; if not, write to the Free Software
   19: \ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
   20: 
   21: 
   22: \ the stack effect of loading this file is: ( addr u -- )
   23: \ it takes the name of the doc-file to be generated.
   24: 
   25: \ the forth source must have the following format:
   26: \  .... name ( stack-effect ) \ [prefix-] wordset [pronounciation]
   27: \ \G description ...
   28: 
   29: \ The output is a Forth source file that looks like this:
   30: \ doc[-prefix]-entry name stack-effect ) wordset [pronountiation]
   31: \ description
   32: \
   33: \ (i.e., the entry is terminated by an empty line or the end-of-file)
   34: 
   35: \ this stuff uses the same mechanism as etags.fs, i.e., the
   36: \ documentation is generated during compilation using a deferred
   37: \ HEADER. It should be possible to use this togeter with etags.fs.
   38: 
   39: \ This is not very general. Input should come from stream files,
   40: \ otherwise the results are unpredictable. It also does not detect
   41: \ errors in the input (e.g., if there is something else on the
   42: \ definition line) and reacts strangely to them.
   43: 
   44: \ possible improvements: we could analyse the defining word and guess
   45: \ the stack effect. This would be handy for variables. Unfortunately,
   46: \ we have to look back in the input buffer; we cannot use the cfa
   47: \ because it does not exist when header is called.
   48: 
   49: \ This is ANS Forth with the following serious environmental
   50: \ dependences: the variable LAST must contain a pointer to the last
   51: \ header, NAME>STRING must convert that pointer to a string, and
   52: \ HEADER must be a deferred word that is called to create the name.
   53: 
   54: 
   55: r/w create-file throw value doc-file-id
   56: \ contains the file-id of the documentation file
   57: 
   58: s" \ automatically generated by makedoc.fs" doc-file-id write-line throw
   59: 
   60: : \G ( -- )
   61:     source >in @ /string doc-file-id write-line throw
   62:     source >in ! drop ; immediate
   63: 
   64: : put-doc-entry ( -- )
   65:     locals-list @ 0=	\ not in a colon def, i.e., not a local name
   66:     last @ 0<> and	\ not an anonymous (i.e. noname) header
   67:     if
   68: 	s" " doc-file-id write-line throw
   69: 	s" make-doc " doc-file-id write-file throw
   70: 	>in @ >r
   71: 	[char] ( parse 2drop
   72: 	[char] ) parse
   73: 	[char] \ parse 2drop
   74: 	>in @
   75: 	bl word  dup c@
   76: 	IF
   77: 	    dup count 1- chars + c@ [char] - =
   78: 	    IF
   79: 		s" --" doc-file-id write-file throw
   80: 		count doc-file-id write-file throw drop
   81: 	    ELSE
   82: 		drop >in !
   83: 	    THEN
   84: 	ELSE
   85: 	    drop >in !
   86: 	THEN
   87: 	last @ name>string doc-file-id write-file throw
   88: 	doc-file-id write-file throw
   89: 	s"  )" doc-file-id write-file throw
   90: 	POSTPONE \g
   91: 	r> >in !
   92:     endif ;
   93: 
   94: : (doc-header) ( -- )
   95:     defers header
   96:     put-doc-entry ;
   97: 
   98: ' (doc-header) IS header