--- gforth/Attic/gforth.texi	1994/06/17 12:35:02	1.3
+++ gforth/Attic/gforth.texi	1994/08/31 16:37:46	1.6
@@ -106,7 +106,46 @@ for introductory material.
 @comment node-name,     next,           previous, up
 @chapter Goals of GNU Forth
 @cindex Goals
-!! Insert Goals here
+The goal of the GNU Forth Project is to develop a standard model for
+ANSI Forth. This can be split into several subgoals:
+
+@itemize @bullet
+@item
+GNU Forth should conform to the ANSI Forth standard.
+@item
+It should be a model, i.e. it should define all the
+implementation-dependent things.
+@item
+It should become standard, i.e. widely accepted and used. This goal
+is the most difficult one.
+@end itemize
+
+To achieve these goals GNU Forth should be
+@itemize @bullet
+@item
+Similar to previous models (fig-Forth, F83)
+@item
+Powerful. It should provide for all the things that are considered
+necessary today and even some that are not yet considered necessary.
+@item
+Efficient. It should not get the reputation of being exceptionally
+slow.
+@item
+Free.
+@item
+Available on many machines/easy to port.
+@end itemize
+
+Have we achieved these goals? GNU Forth conforms to the ANS Forth
+standard; it may be considered a model, but we have not yet documented
+which parts of the model are stable and which parts we are likely to
+change; it certainly has not yet become a de facto standard. It has some
+similarities and some differences to previous models; It has some
+powerful features, but not yet everything that we envisioned; on RISCs
+it is as fast as interpreters programmed in assembly, on
+register-starved machines it is not so fast, but still faster than any
+other C-based interpretive implementation; it is free and available on
+many machines.
 
 @node Other Books, Invocation, Goals, Top
 @chapter Other books on ANS Forth
@@ -118,14 +157,16 @@ deviations of the book.
 
 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
-!! somtime in spring or summer 1994. If you are lucky, you can still get
-dpANS6 (the draft that was approved as standard) by aftp from
-ftp.uu.net:/vendor/minerva/x3j14.
-
-@cite{Forth: The new model} by Jack Woehr (!! Publisher) is an introductory
-book based on a draft version of the standard. It does not cover the
-whole standard. It also contains interesting background information
-(Jack Woehr was in the ANS Forth Technical Committe).
+Global Engineering Documents !! somtime in spring or summer 1994. If you
+are lucky, you can still get dpANS6 (the draft that was approved as
+standard) by aftp from ftp.uu.net:/vendor/minerva/x3j14.
+
+@cite{Forth: The new model} by Jack Woehr (!! Publisher) is an
+introductory book based on a draft version of the standard. It does not
+cover the whole standard. It also contains interesting background
+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
 @chapter Invocation
@@ -223,7 +264,7 @@ The name of a stack item corresponds in
 @item name starts with
 Type
 @item f
-Bool, i.e. false (0) or true (-1).
+Bool, i.e. @code{false} or @code{true}.
 @item c
 Char
 @item w
@@ -318,11 +359,11 @@ variables. Note that while every sane Fo
 point stack, this is not strictly required; an ANS Forth system could
 theoretically keep floating point numbers on the data stack. As an
 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
 it. Also, a Forth system is allowed to keep the local variables on the
 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
 word, forget about return stack manipulations in that word (see the
 standard document for the exact rules).
@@ -363,6 +404,8 @@ r@
 rdrop
 2>r
 2r>
+2r@
+2rdrop
 
 @subsection Locals stack
 
@@ -397,10 +440,16 @@ df!
 @subsection Memory block access
 
 move
-fill
-blanks
 erase
 
+While the previous words work on address units, the rest works on
+characters.
+
+cmove
+cmove>
+fill
+blank
+
 @node Control Structures
 @section Control Structures
 
@@ -437,7 +486,16 @@ system that only supplies @code{THEN} is
 : endif   POSTPONE then ; immediate
 @end example
 
-We also provide the words @code{?dup-if} and @code{?dup-not-if}, so you
+[According to @cite{Webster's New Encyclopedic Dictionary}, @dfn{then
+(adv.)}  has the following meanings:
+@quotation
+... 2b: following next after in order ... 3d: as a necessary consequence
+(if you were there, then you saw them).
+@end quotation
+Forth's @code{THEN} has the meaning 2b, @code{THEN} in Pascal
+and many other programming languages has the meaning 3d.]
+
+We also provide the words @code{?dup-if} and @code{?dup-0=-if}, so you
 can avoid using @code{?dup}.
 
 @example
@@ -550,11 +608,27 @@ The loop is terminated when the border b
 @var{limit} is crossed. However, @code{S+LOOP} is not part of the ANS
 Forth standard.
 
-The @code{?DO} can be replaced by @code{DO}. @code{DO} enters the loop
-even when the start and the limit value are equal. We do not recommend
-using @code{DO}. It will just give you maintenance troubles.
+@code{?DO} can be replaced by @code{DO}. @code{DO} enters the loop even
+when the start and the limit value are equal. We do not recommend using
+@code{DO}. It will just give you maintenance troubles.
+
+@code{UNLOOP} is used to prepare for an abnormal loop exit, e.g., via
+@code{EXIT}. @code{UNLOOP} removes the loop control parameters from the
+return stack so @code{EXIT} can get to its return address.
+
+Another counted loop is
+@example
+@var{n}
+FOR
+  @var{body}
+NEXT
+@end example
+This is the preferred loop of native code compiler writers who are too
+lazy to optimize @code{?DO} loops properly. In GNU Forth, this loop
+iterates @var{n+1} times; @code{i} produces values starting with @var{n}
+and ending with 0. Other Forth systems may differently, even if they
+support @code{FOR} loops.
 
-FOR NEXT UNLOOP
 
 @contents
 @bye