Documentation

Good documentation for a system with several variants is a problem that seldom is solved nicely. For example, because ciforth comes in 16 and 32 bits versions, you could have all over the documentation such confusing sentences as "two times the bit size of the system, see introduction". Or "this section only applies whenever files have an owner, like on Linux or Windows versions after Windows 95.".

The solutions that I have chosen, is to not write the documentation but generate it from a single source file (together with the tests).

So the source file cannot be assembled directly. It means that at the place where the code of for example the word DROP resides, we also find the explanation about the stack effect, and several tests. The documentation system collects these pieces of documentation, groups them and places them in the glossary in alphabetic order.

The code for TYPE differs for MSDOS and Linux, but the source file is common for all Forth's. The MSDOS TYPE is surrounded by

_HOSTED_MSDOS_({ HEADER({TYPE} ..... ... ... ... })

and the Linux TYPE code by

_LINUX_({ HEADER({TYPE} ..... ... ... ... })

In generating the assembler file for Linux the part for MSDOS is ignored. This is comparable with the use of [IF] [THEN] [ELSE] in Forth source, of #if #then #else in c-source. The juicy thing is that this is used at the same time to select documentation that is relevant to DOS c.q. Linux.

In other words, after the configuration step we have dedicated, albeit raw documentation, a file with tests and a file accepted by the assembler.

It will be clear that we need a lot of auxiliary programs. Unix is well equipped to do this kind of automatic text processing. The Unix used by me is LGX : Linux, GNU, X-windows. The system is also flexible in the sense that it can generate any output format, like PostScript and HTML. I hear you say, "I want Word". Helas that is not possible, not because Unix or I are not clever enough, but because the Word format is secret and/or you must pay just to use it. Windows help files similarly have a secret format. A same situation exists with PDF files, but less severe.