I started a collaborative documentation project, hosted by Sourceforge . This documentation project takes the old documentation (in German) of the commercial versions of bigFORTH as starting point, but is intented to deliver more. The whole documentation under this project is available under GPL.
Big Red Warning Label: This is not production documentation yet, it's just start of development. LaTeX experience, knowledge of the other tools used in development and general developer skills are still necessary to work on this project.
Since this is a collaborative effort, the goal depends on those who work at it. Currently, it's just me working, and I will work on documenting bigFORTH and MINOS. Several people have expressed the wish to contribute beginner's tutorial (to various sorts of beginners), and I'll help them by providing this framework and by integrating their texts, even if they are in different formats.
To achieve this goals, I built up some infrastructure. The source of choice is LaTeX, since that's a text source, thus easy to use for automatic generation/conversion, it also gives wonderful typesetting, and it can be converted into other relevant formats, too. Conversion to HTML will however require to add a bigFORTH style to the latex2html code base, since the documents use some extensions to LaTeX.
All work is coordinated through a public accessible CVS server. This means, you should have an operating system that supports this style of development. While it may be possible to achieve all this with Windows, I strongly recommend installing Linux, because typical distributions come with all the programs you need (LaTeX, CVS, ssh, make; you also need bigFORTH for the glossary database conversion).
You can check out the source module via pserver CVS with
cvs -d:pserver:firstname.lastname@example.org:/cvsroot/bigforth login cvs -d:pserver:email@example.com:/cvsroot/bigforth co docu
If you have a Sourceforge account, and have been added to the list of contributors, you can access the CVS repository via ssh, and check in changes. Otherwise, you can extract changes by applying
cvs diff -u >your-patch.diff
in your copy of the source repository. To generate dvi output, simply type make in the docu directory, other useful targets are ps and pdf for the respective output formats, and dist to create a tarball distribution of the sources.
The whole documentation resides in the subdirectory docu of the bigFORTH directory. Language-specific files reside in subdirectories, which are named by the twoletter identifications of the languages, just as in the LANG environment variable. If you really want to create a localization for a specific variant of a language, use the convention of adding underscore and two uppercase letters of your local "dialect", e.g. en_UK for united kingdom english.
The master file of the documentation project is
bigforth.tex. It mainly consists of the
localized title, and inclusion of the chapter
files. These chapter files may come out of other
language directories during the phase of
translation, e.g. you say
before you start translation. Add the necessary
macros appropriately and specify all used languages in your options to
the babel package.
The glossary database files all end with suffix
.db. There are three
types of db files:
Stack glossaries, they end with
files are tyically language independent, and
therefore reside in the docu directory. The master
bigforth-stack.db, which loads all the
topic specific stack files. If you really need a
localization of a stack glossary, you can put one
into your language directory, the search path takes
care that this one is found first.
The format of the stack glossary is line-based. The
first entry in a line is the type of that entry.
set-voc to specify a vocabulary,
set-public to specify the public part of an object,
set-private to specify the private part; these
are state variables that are valid for all the
You specify Forth words with word, followed by tab separated entries. The first entry is the word name, then is followed by stack entries, optional parse entries (each one enclosed in < and >), finally execution type, preceeded with !, followed by up to two letters: "i" means immediate, "r" means restrict, or compile-only.
The stack entries are separated with a
-- in the
middle, but without parentheses. If you specify
another stack, use a single letter and a colon for
v: means vocabulary stack. Other
o: object stack,
r: return stack,
floating point stack.
For objects, there are other entries,
early are like word,
var have no optinal
ptr takes the pointer class as
option (not implemented yet).
Word glossaries, they end with
files are typically language dependent, thus you
need one in your language specific directory. Since
the main directory is searched later, it might be a
good idea to create a symbolic link to a generic
language glossary there.
The word glossaries have the same vocabulary and
public/private object part settings, and use glos
to preceed an entry for a word found in that
vocabulary. The next space-separated parameter is
the word name itself, and then follows the
description, written in LaTeX, terminated by an
empty line. If you need to have more than one
paragraph in your description, either insert
commands, or lines with a single spaces.
LaTeX sources with glossary links, they end with
.tex.db, and are
automatically converted to their
.tex counterparts. Make sure that
you remove the original
.tex file from the CVS repository when you
start converting it into a
.tex.db file. These files contain textual
descriptions of the big picture, and sections where the glossary
entries are referred. Glossary entries are included by putting a tag
in a single line, which is preceeded by
doc-, and contains the
word's name as rest of the line. You switch vocabularies with
<Vocabulary>; for object environments, this is
implicated. Optionally, you can append the vocabulary
But you could just as well dig around in the available files, and find out yourself.
I put part of the documentation for the commercial version of bigFORTH here (all in German, LaTeX) to create a starting point for the same amount and quality of documentation for the free version of bigFORTH. Note that this documentation is not up to date and therefore not accurate. The parts I left out are the least important ones. There's a patch to compile it on recent LaTeX2e distributions.
Big Red Warning Label: This isn't production documentation, it's for developers only. You need a LaTeX installation, Gforth, and patience.