[bigFORTH^]
[MINOSv][Documentationv][Downloadv][ChangeLogv][Screenshotv][Mailing Listv]

[html] Forth Documentation Project

I started a collaborative documentation project, hosted by [html]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.

Download Snapshots

To get a quick look at what's available right now, I put snapshots on-line. You can get the [tar-bz2]source (595k), the [pdf]German documentation (2M) and the partly translated [pdf]English documentation (2M).

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 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 [html]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:

Historical Starting Point

I put part of the [tar-bz2]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.


Created 05jan2000. Last modified: 9mar2009 by MailBernd PaysanPGP key