Return to glossaries.doc CVS log

Up to [gforth] / gforth / doc

jwilke's changes:
Moved many files to other directories
renamed many files
other changes unknown to me.

    1: WRITING GLOSSARY FILES FOR FORTH WORDSETS IS DULL AND ERROR-PRONE.
    2: 
    3: Maintaining them if the wordsets change, is never done accurately.
    4: 
    5: Therefore, let's automate it.
    6: 
    7: The file glosgen.str implements a very basic form of the glossary generator
    8: I like to be used as a standard tool with ANSFIG. BTW, it is written in
    9: standard (mostly standard?) ANS Forth, so it should be usable on many
   10: systems. You must first fix a small bug in WRITE-FILE (it returns bytes
   11: written and io result while it must return only io result 15/7/93) if you 
   12: want to use it on ANSFIG. This same bug affects WRITE-LINE too. Further
   13: CREATE-FILE creates (with me on Linux) a file with no permissions at all.
   14: Is this intended behaviour, or a bug?
   15: 
   16: A special word (I call it \G, but now it is still open to discussion) is
   17: used to mark glossary comments. This word should be added to the
   18: kernel as all source files of ansfig should have such comments.
   19: 
   20: The file glosgen.str is currently the only file with glossary comments in
   21: it. The file glosgen.glo is the glossary file of it. It was created by the
   22: following commands:
   23:  newglos
   24:  makeglos glosgen.str
   25:  writeglos glosgen.glo
   26: 
   27: Making a file suitable for glossary generation should be possible with
   28: little effort. The usual stack comments should be added right after each
   29: definition. After that is an optional slash comment with the wordset and if
   30: necessary pronunciation info. The name of the new word must be the second
   31: word on the line, which is natural for colon definitions and most other
   32: words, but not for constants (should be fixed though). Directly above or
   33: below the header line of the definition come one or more \G comments.
   34: These are explanatory comments, which should be in the source file anyway.
   35: ORdinary ( or \ comments are not included in the glossary. A block of only
   36: \G comments is placed at the start of the glossary. Take for example the
   37: following word.
   38: 
   39: \G Return the absolute value of n1.
   40: \G The largest negative number is returned unchanged.
   41: : ABS ( n1 --- n2) \ CORE  
   42:   DUP 0<
   43:   IF NEGATE \ Negate leaves the largest negative number unchanged.
   44:   THEN
   45: ;
   46: 
   47: This will appear in the glossary file as follows.
   48: 
   49: ABS   n1 --- n2                  CORE
   50: Return the absolute value of n1.
   51: The largest negative number is returnded unchanged.
   52: 
   53: All entries in the glossary files are in asciibetical order. It is possible
   54: to run more source files through the generator to form one glossary file.
   55: 
   56: Things left to do:
   57: - Process the wordsets fields and pronunciation fields.
   58: - Select only words that occur in a particular word set.
   59: - Make a more sophisticated guess of the word name. Currently it is
   60:   the second word on the line, which is wrong with constants.
   61: - Process the primitives file too. Or make the primitives file
   62:   compatible with glosgen.
   63: - Generate other formats than straight ascii, (LaTeX, texinfo).
   64: 
   65: Possible changes
   66: - Add several types of glossary comments, general and more technical 
   67:   comments. (\G and \T) Words of general interest get \G comments and
   68:   words that are used only internally have \T comments. Then it is possible
   69:   to generate a basic glossary for general users and a more technical 
   70:   glossary for programmers. Of course the source itself is the most
   71:   technical description.
   72: - If Forth gets a VIEW file system a la F83 or F-PC, it would be possible
   73:   to scan the words of an already compiled word list and find the defining
   74:   line in the source file this way. (then the name is always right).
   75: 
   76: Lennart Benschop