Powered by ViewCVS 1.0-dev
| 1 : | anton | 1.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 : | pazsan | 1.2 | \ .... name ( stack-effect ) \ [prefix-] wordset [pronounciation] |
| 27 : | anton | 1.1 | \ \G description ... |
| 28 : | |||
| 29 : | \ The output is a Forth source file that looks like this: | ||
| 30 : | pazsan | 1.2 | \ doc[-prefix]-entry name stack-effect ) wordset [pronountiation] |
| 31 : | anton | 1.1 | \ 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 : | pazsan | 1.2 | >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 : | anton | 1.1 | last @ name>string doc-file-id write-file throw |
| 88 : | pazsan | 1.2 | doc-file-id write-file throw |
| 89 : | anton | 1.1 | s" )" doc-file-id write-file throw |
| 90 : | POSTPONE \g | ||
| 91 : | pazsan | 1.2 | r> >in ! |
| 92 : | anton | 1.1 | endif ; |
| 93 : | |||
| 94 : | : (doc-header) ( -- ) | ||
| 95 : | defers header | ||
| 96 : | put-doc-entry ; | ||
| 97 : | |||
| 98 : | ' (doc-header) IS header |
|
CVS Admin Powered by ViewCVS 1.0-dev |
ViewCVS and CVS Help |