Forth Documentation Project

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 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: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.