Forth Documentation Project

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.

Goals

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.

• Make the whole documentation available in English.
• Create a glossary database which allows to easily extract and translate glossary information not only to automatically generate printed documentation, but also as a way to provide online help.
• Allow easy localization (i.e. translation) of the documentation.
• Allow easy maintainance of the documentation, so that it can be kept up to date without too much effort.
• Provide conversion tools to widely used formats like HTML, PostScript, PDF, ...
• Improve the available introduction material, add new tutorials.
• Find a publisher who prints that book - currently only O'Reilly prints technical books that are also available on the Internet. This isn't the primary goal, we must have content before we think about printing it.

Download Snapshots

To get a quick look at what's available right now, I put snapshots on-line. You can get the source, the German documentation as pdf and the partly translated English documentation as pdf.

Meta-Documentation

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.

CVS repository

All work is coordinated through a public accessible CVS server. This means, you should have an operating system that supports this style of developmen. 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:anonymous@cvs.bigforth.sourceforge.net:/cvsroot/bigforth login
cvs -d:pserver:anonymous@cvs.bigforth.sourceforge.net:/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.

File/Directory Formats

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 called 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

\input{../de/tutorial.tex}

before you start translation. Add the necessary \selectlanguage{} 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 -stack.db. These files are tyically language independent, and therefore reside in the docu directory. The master file is 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. You have set-voc to specify a vocabulary, set-public to specify the public part of an object, and set-private to specify the private part; these are state variables that are valid for all the following words.

  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 start, e.g. v: means vocabulary stack. Other letters: o: object stack, r: return stack, f: floating point stack.

  For objects, there are other entries, method and early are like word, static and var have no optinal parameters, and ptr takes the pointer class as option (not implemented yet).

• Word glossaries, they end with -glos.db. These 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 \par 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 \voc <Vocabulary>; for object environments, this is implicated. Optionally, you can append the vocabulary hyphen-separated.

But you could just as well dig around in the available files, and find out yourself.

Historical Starting Point

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.