Annotation of gforth/doc/gforth.1, revision 1.5

1.1       anton       1: .de TQ
                      2: .br
                      3: .ns
                      4: .IP "\fB\\$1\fI\\$2" 9
                      5: ..
1.4       crook       6: .TH GForth 1 "April 14, 1999" \" -*- nroff -*-
1.1       anton       7: .SH NAME
1.5     ! anton       8: gforth, gforth-fast, gforthmi \- a fast and portable Forth system
1.1       anton       9: .SH SYNOPSIS
                     10: 
                     11: \fCgforth\fR [initialization options] [image-specific options]
1.5     ! anton      12: \fCgforth-fast\fR [initialization options] [image-specific options]
1.1       anton      13: 
1.3       anton      14: \fCgforthmi\fR \fIfilename\fR [initialization options] [image-specific options]
1.1       anton      15: .SH DESCRIPTION
                     16: 
                     17: \fBGForth\fR is a fast and portable implementation of the Forth
                     18: programming language. For details read the manual.
                     19: .SH ENVIRONMENT VARIABLES
                     20: 
                     21: \fCGFORTHPATH\fR contains the search path for source and image files.
                     22: 
                     23: \fCGFORTHD\fR gives the gforth executable used by
1.3       anton      24: \fCgforthmi\fR for creating the base images. It should be a
1.1       anton      25: double indirect threaded system.  Default: \fCgforth-ditc\fR.
                     26: 
                     27: \fCGFORTH\fR gives the gforth executable used by
1.3       anton      28: \fCgforthmi\fR for computing the relocatable image from the
1.1       anton      29: base images. Default: \fCgforth\fR.
                     30: 
1.4       crook      31: \fCGFORTHHIST\fR gives the location of the history file used by gforth
                     32: to allow command-line recall. Default: \fC$HOME\fR. (The history
                     33: file is named \fC.gforth-history\fR).
                     34: 
1.1       anton      35: .SH EXAMPLES
                     36: 
                     37: \fCgforth\fR
                     38: 
                     39: starts the system and goes into interactive mode.
                     40: 
                     41: \fCgforth file1 file2 \-e bye\fR
                     42: 
                     43: loads and interprets the files \fCfile1\fR and \fCfile2\fR, then
                     44: exits.
1.5     ! anton      45: 
        !            46: \fCgforth-fast\fR
        !            47: 
        !            48: is the same as \fCgforth-fast\fR, except that it does not support
        !            49: accurate backtraces for signals, and is faster by up to a factor of 2.
        !            50: Use it for debugged, performance-critical programs such as benchmarks.
1.1       anton      51: 
1.3       anton      52: \fCgforthmi asm.fi \-m 1M asm.fs\fR
1.1       anton      53: 
                     54: creates an image \fCasm.fi\fR that has a default dictionary size of
                     55: 1MB and has the file \fCasm.fs\fR loaded.
                     56: 
                     57: .SH OPTIONS
                     58: 
1.2       anton      59: .BI "\-\-help"
                     60: .TQ "\-h"
                     61: Lists the available options, including some not described here (see
                     62: also the manual).
                     63: .TP
1.1       anton      64: .BI "\-\-image\-file " "file"
                     65: .TQ "\-i " "file"
                     66: Loads the Forth image
                     67: .I file
                     68: instead of the default \fCgforth.fi\fR.
                     69: .TP
                     70: .BI "\-\-path " "path"
                     71: .TQ "\-p " "path"
                     72: Uses
                     73: .I path
                     74: for searching the image file and Forth source code
                     75: files instead of the default in the environment variable
                     76: \fCGFORTHPATH\fR
                     77: or the path specified at installation time (typically
                     78: \fC/usr/local/lib/gforth:.\fR. A path is given as a 
                     79: .BR : -separated
                     80: list.
                     81: .TP
                     82: .BI "\-\-dictionary\-size " "size"
                     83: .TQ "\-m " "size"
                     84: Allocate
                     85: .I size
                     86: space for the Forth dictionary space instead of
                     87: using the default specified in the image (typically 256K). The
                     88: .I size
                     89: specification consists of an integer and a unit (e.g., \fC4M\fR).
                     90: The unit can be one of \fCb\fR (bytes),
                     91: \fCe\fR (element size, in this case Cells),
                     92: \fCk\fR (kilobytes), and
                     93: \fCM\fR (Megabytes). If no unit is specified,
                     94: \fCe\fR is used.
                     95: .TP
                     96: .BI "\-\-data\-stack\-size " "size"
                     97: .TQ "\-d " "size"
                     98: Allocate
                     99: .I size
                    100: space for the data stack instead of using the
                    101: default specified in the image (typically 16K).
                    102: .TP
                    103: .BI "\-\-return\-stack\-size " "size"
                    104: .TQ "\-r " "size"
                    105: Allocate
                    106: .I size
                    107: space for the return stack instead of using the
                    108: default specified in the image (typically 16K).
                    109: .TP
                    110: .BI "\-\-fp\-stack\-size " "size"
                    111: .TQ "\-f " "size"
                    112: Allocate
                    113: .I size
                    114: space for the floating point stack instead of
                    115: using the default specified in the image (typically 16K). In this case
                    116: the unit specifier
                    117: \fCe\fR
                    118: refers to floating point numbers.
                    119: .TP
                    120: .BI "\-\-locals\-stack\-size " "size"
                    121: .TQ "\-l " "size"
                    122: Allocate
                    123: .I size
                    124: space for the locals stack instead of using the
                    125: default specified in the image (typically 16K).
                    126: 
                    127: .TP
                    128: .BI "\-\-evaluate " "forth"
                    129: .TQ "\-e " "forth"
                    130: Evaluates the
                    131: .I forth
                    132: code. This option takes only one argument; if you want to evaluate
                    133: more Forth words, you have to quote them or use several \fC-e\fRs.  To
                    134: exit after processing the command line (instead of entering
                    135: interactive mode) append \fC-e bye\fR to the command line. This is an
                    136: image-specific option of the default image.
                    137: .SH FILES
                    138: .nf
1.3       anton     139: .ta \w'\fC.../gforth.fi\fP     'u
                    140: \&\fC.../gforth.fi\fP  default Forth image
1.1       anton     141: \&\fC*.fi\fP   Forth loadable image
                    142: \&\fC*.fs\fP   Forth source (sequential)
                    143: \&\fC*.fb\fP   Forth source (block)
                    144: \&\fC*.fd\fP   generated with \fCmakedoc.fs\fP
                    145: \&\fC*.i\fP    C include files
                    146: \&\fC*.ds\fP   documentation source
                    147: \&\fC*TAGS\fP  etags files
                    148: .fi
                    149: .SH SEE ALSO
1.4       crook     150: The Gforth manual - available in hypertext (Info, HTML) and printable
                    151: (TeX, PS, ASCII) forms.
1.1       anton     152: 
                    153: The ANSI document X3.215-1994 (i.e., the ANS Forth standard).
                    154: 
                    155: More information on Gforth (e.g., pointers to new versions, to the
                    156: manual on the WWW and to papers about Gforth) is available through
                    157: \fChttp://www.complang.tuwien.ac.at/projects/forth.html\fR.
                    158: .SH AUTHORS
                    159: \fBGforth\fR was written by Anton Ertl, Bernd Paysan, Jens Wilke and
                    160: others.

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