File:  [gforth] / gforth / doc / gforth.1
Revision 1.4: download - view: text, annotated - select for diffs
Fri Apr 16 22:19:51 1999 UTC (22 years, 6 months ago) by crook
Branches: MAIN
CVS tags: HEAD
.cvsignore -- added a couple of other files I was tired of seeing flagged
by CVS

README -- added references to a couple more .fs files that are part of
the gforth distribution

blocks.fs -- fixed a bug in UPDATED? and added glossary entries for all
words.

colorize.fs -- fixed a bug that was introduced by a dictionary
structure change between 0.3.0 and 0.4.0 (I think.. it used to work
on 0.3.0 and I compared the color WORDS with the normal WORDS and found
some dirrerences

doc/gforth.1 -- minor tweaks to man page. I now think that I'd like to
be able to auto-generate the man page from what is now Chapter 3 of the
manual. That's in line with GNU's general attitude towards man pages..

doc/gforth.ds -- added stuff about blocks, revamped Chapter 3 and other
miscellaneous changes.

kernel/comp.fs -- glossary tweaks

kernel/require.fs -- glossary tweaks

.de TQ
.br
.ns
.IP "\fB\\$1\fI\\$2" 9
..
.TH GForth 1 "April 14, 1999" \" -*- nroff -*-
.SH NAME
gforth, gforthmi \- a fast and portable Forth system
.SH SYNOPSIS

\fCgforth\fR [initialization options] [image-specific options]

\fCgforthmi\fR \fIfilename\fR [initialization options] [image-specific options]
.SH DESCRIPTION

\fBGForth\fR is a fast and portable implementation of the Forth
programming language. For details read the manual.
.SH ENVIRONMENT VARIABLES

\fCGFORTHPATH\fR contains the search path for source and image files.

\fCGFORTHD\fR gives the gforth executable used by
\fCgforthmi\fR for creating the base images. It should be a
double indirect threaded system.  Default: \fCgforth-ditc\fR.

\fCGFORTH\fR gives the gforth executable used by
\fCgforthmi\fR for computing the relocatable image from the
base images. Default: \fCgforth\fR.

\fCGFORTHHIST\fR gives the location of the history file used by gforth
to allow command-line recall. Default: \fC$HOME\fR. (The history
file is named \fC.gforth-history\fR).

.SH EXAMPLES

\fCgforth\fR

starts the system and goes into interactive mode.

\fCgforth file1 file2 \-e bye\fR

loads and interprets the files \fCfile1\fR and \fCfile2\fR, then
exits.

\fCgforthmi asm.fi \-m 1M asm.fs\fR

creates an image \fCasm.fi\fR that has a default dictionary size of
1MB and has the file \fCasm.fs\fR loaded.

.SH OPTIONS

.BI "\-\-help"
.TQ "\-h"
Lists the available options, including some not described here (see
also the manual).
.TP
.BI "\-\-image\-file " "file"
.TQ "\-i " "file"
Loads the Forth image
.I file
instead of the default \fCgforth.fi\fR.
.TP
.BI "\-\-path " "path"
.TQ "\-p " "path"
Uses
.I path
for searching the image file and Forth source code
files instead of the default in the environment variable
\fCGFORTHPATH\fR
or the path specified at installation time (typically
\fC/usr/local/lib/gforth:.\fR. A path is given as a 
.BR : -separated
list.
.TP
.BI "\-\-dictionary\-size " "size"
.TQ "\-m " "size"
Allocate
.I size
space for the Forth dictionary space instead of
using the default specified in the image (typically 256K). The
.I size
specification consists of an integer and a unit (e.g., \fC4M\fR).
The unit can be one of \fCb\fR (bytes),
\fCe\fR (element size, in this case Cells),
\fCk\fR (kilobytes), and
\fCM\fR (Megabytes). If no unit is specified,
\fCe\fR is used.
.TP
.BI "\-\-data\-stack\-size " "size"
.TQ "\-d " "size"
Allocate
.I size
space for the data stack instead of using the
default specified in the image (typically 16K).
.TP
.BI "\-\-return\-stack\-size " "size"
.TQ "\-r " "size"
Allocate
.I size
space for the return stack instead of using the
default specified in the image (typically 16K).
.TP
.BI "\-\-fp\-stack\-size " "size"
.TQ "\-f " "size"
Allocate
.I size
space for the floating point stack instead of
using the default specified in the image (typically 16K). In this case
the unit specifier
\fCe\fR
refers to floating point numbers.
.TP
.BI "\-\-locals\-stack\-size " "size"
.TQ "\-l " "size"
Allocate
.I size
space for the locals stack instead of using the
default specified in the image (typically 16K).

.TP
.BI "\-\-evaluate " "forth"
.TQ "\-e " "forth"
Evaluates the
.I forth
code. This option takes only one argument; if you want to evaluate
more Forth words, you have to quote them or use several \fC-e\fRs.  To
exit after processing the command line (instead of entering
interactive mode) append \fC-e bye\fR to the command line. This is an
image-specific option of the default image.
.SH FILES
.nf
.ta \w'\fC.../gforth.fi\fP 	'u
\&\fC.../gforth.fi\fP	default Forth image
\&\fC*.fi\fP	Forth loadable image
\&\fC*.fs\fP	Forth source (sequential)
\&\fC*.fb\fP	Forth source (block)
\&\fC*.fd\fP	generated with \fCmakedoc.fs\fP
\&\fC*.i\fP	C include files
\&\fC*.ds\fP	documentation source
\&\fC*TAGS\fP	etags files
.fi
.SH SEE ALSO
The Gforth manual - available in hypertext (Info, HTML) and printable
(TeX, PS, ASCII) forms.

The ANSI document X3.215-1994 (i.e., the ANS Forth standard).

More information on Gforth (e.g., pointers to new versions, to the
manual on the WWW and to papers about Gforth) is available through
\fChttp://www.complang.tuwien.ac.at/projects/forth.html\fR.
.SH AUTHORS
\fBGforth\fR was written by Anton Ertl, Bernd Paysan, Jens Wilke and
others.

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>