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
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>