Diff for /gforth/Attic/gforth.texi between versions 1.5 and 1.7

version 1.5, 1994/08/19 17:47:21 version 1.7, 1994/09/05 17:36:19
Line 157  deviations of the book. Line 157  deviations of the book.
   
 There is, of course, the standard, the definite reference if you want to  There is, of course, the standard, the definite reference if you want to
 write ANS Forth programs. It will be available in printed form from  write ANS Forth programs. It will be available in printed form from
 !! somtime in spring or summer 1994. If you are lucky, you can still get  Global Engineering Documents !! somtime in spring or summer 1994. If you
 dpANS6 (the draft that was approved as standard) by aftp from  are lucky, you can still get dpANS6 (the draft that was approved as
 ftp.uu.net:/vendor/minerva/x3j14.  standard) by aftp from ftp.uu.net:/vendor/minerva/x3j14.
   
 @cite{Forth: The new model} by Jack Woehr (!! Publisher) is an introductory  @cite{Forth: The new model} by Jack Woehr (!! Publisher) is an
 book based on a draft version of the standard. It does not cover the  introductory book based on a draft version of the standard. It does not
 whole standard. It also contains interesting background information  cover the whole standard. It also contains interesting background
 (Jack Woehr was in the ANS Forth Technical Committe).  information (Jack Woehr was in the ANS Forth Technical Committe). It is
   not appropriate for complete newbies, but programmers experienced in
   other languages should find it ok.
   
 @node Invocation, Words, Other Books, Top  @node Invocation, Words, Other Books, Top
 @chapter Invocation  @chapter Invocation
   
 You will usually just say @code{gforth}. More generally, the default GNU  You will usually just say @code{gforth}. In many other cases the default
 Forth image can be invoked like this  GNU Forth image will be invoked like this:
   
 @example  @example
 gforth [--batch] [files] [-e forth-code]  gforth [files] [-e forth-code]
 @end example  @end example
   
 The @code{--batch} option makes @code{gforth} exit after processing the  executing the contents of the files and the Forth code in the order they
 command line. Also, the startup message is suppressed. @file{files} are  are given.
 Forth source files that are executed in the order in which they  
 appear. The @code{-e @samp{forth-code}} or @code{--evaluate  In general, the command line looks like this:
 @samp{forth-code}} option evaluates the forth code; it can be freely  
 mixed with the files. This option takes only one argument; if you want  @example
 to evaluate more Forth words, you have to quote them or use several  gforth [initialization options] [image-specific options]
 @code{-e}s. !! option for suppressing default loading.  @end example
   
 You can use the command line option @code{-i @samp{file}} or  The initialization options must come before the rest of the command
 @code{--image-file @samp{file}} to specify a different image file. Note  line. They are:
 that this option must be the first in the command line. The rest of the  
 command line is processed by the image file.  @table @code
   @item --image-file @samp{file}
 If the @code{--image-file} option is not used, GNU Forth searches for a  Loads the Forth image @samp{file} instead of the default
 file named @file{gforth.fi} in the path specified by the environment  @file{gforth.fi}.
 variable @code{GFORTHPATH}; if this does not exist, in  
 @file{/usr/local/lib/gforth} and in @file{/usr/lib/gforth}.  @item --path @samp{path}
   Uses @samp{path} for searching the image file and Forth source code
   files instead of the default in the environment variable
   @code{GFORTHPATH} or the path specified at installation time (typically
   @file{/usr/local/lib/gforth:.}). A path is given as a @code{:}-separated
   list.
   
   @item --dictionary-size @samp{size}
   @item -m @samp{size}
   Allocate @samp{size} space for the Forth dictionary space instead of
   using the default specified in the image (typically 256K). The
   @samp{size} specification consists of an integer and a unit (e.g.,
   @code{4M}). The unit can be one of @code{b} (bytes), @code{e} (element
   size, in this case Cells), @code{k} (kilobytes), and @code{M}
   (Megabytes). If no unit is specified, @code{e} is used.
   
   @item --data-stack-size @samp{size}
   @item -d @samp{size}
   Allocate @samp{size} space for the data stack instead of using the
   default specified in the image (typically 16K).
   
   @item --return-stack-size @samp{size}
   @item -r @samp{size}
   Allocate @samp{size} space for the return stack instead of using the
   default specified in the image (typically 16K).
   
   @item --fp-stack-size @samp{size}
   @item -f @samp{size}
   Allocate @samp{size} space for the floating point stack instead of
   using the default specified in the image (typically 16K). In this case
   the unit specifier @code{e} refers to floating point numbers.
   
   @item --locals-stack-size @samp{size}
   @item -l @samp{size}
   Allocate @samp{size} space for the locals stack instead of using the
   default specified in the image (typically 16K).
   
   @end table
   
   As explained above, the image-specific command-line arguments for the
   default image @file{gforth.fi} consist of a sequence of filenames and
   @code{-e @samp{forth-code}} options that are interpreted in the seqence
   in which they are given. The @code{-e @samp{forth-code}} or
   @code{--evaluate @samp{forth-code}} option evaluates the forth
   code. This option takes only one argument; if you want to evaluate more
   Forth words, you have to quote them or use several @code{-e}s. To exit
   after processing the command line (instead of entering interactive mode)
   append @code{-e bye} to the command line.
   
   Not yet implemented:
   On startup the system first executes the system initialization file
   (unless the option @code{--no-init-file} is given; note that the system
   resulting from using this option may not be ANS Forth conformant). Then
   the user initialization file @file{.gforth.fs} is executed, unless the
   option @code{--no-rc} is given; this file is first searched in @file{.},
   then in @file{~}, then in the path given by the normal path (see below).
   
 @node Words,  , Invocation, Top  @node Words,  , Invocation, Top
 @chapter Forth Words  @chapter Forth Words
Line 357  variables. Note that while every sane Fo Line 414  variables. Note that while every sane Fo
 point stack, this is not strictly required; an ANS Forth system could  point stack, this is not strictly required; an ANS Forth system could
 theoretically keep floating point numbers on the data stack. As an  theoretically keep floating point numbers on the data stack. As an
 additional difficulty, you don't know how many cells a floating point  additional difficulty, you don't know how many cells a floating point
 numkber takes. It is reportedly possible to write words in a way that  number takes. It is reportedly possible to write words in a way that
 they work also for a unified stack model, but we do not recommend trying  they work also for a unified stack model, but we do not recommend trying
 it. Also, a Forth system is allowed to keep the local variables on the  it. Also, a Forth system is allowed to keep the local variables on the
 return stack. This is reasonable, as local variables usually eliminate  return stack. This is reasonable, as local variables usually eliminate
 the need to use the return stack explicitely. So, if you want to produce  the need to use the return stack explicitly. So, if you want to produce
 a standard complying program and if you are using local variables in a  a standard complying program and if you are using local variables in a
 word, forget about return stack manipulations in that word (see the  word, forget about return stack manipulations in that word (see the
 standard document for the exact rules).  standard document for the exact rules).
Line 402  r@ Line 459  r@
 rdrop  rdrop
 2>r  2>r
 2r>  2r>
   2r@
   2rdrop
   
 @subsection Locals stack  @subsection Locals stack
   

Removed from v.1.5  
changed lines
  Added in v.1.7


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