--- gforth/kernel/vars.fs	1998/12/19 13:43:18	1.8
+++ gforth/kernel/vars.fs	1999/02/22 21:39:44	1.12
@@ -25,14 +25,19 @@ hex \ everything now hex!
 \ dpANS6 (sect 3.1.3.1) says 
 \ "a true flag ... [is] a single-cell value with all bits set"
 \ better definition: 0 0= constant true ( no dependence on 2's compl)
- -1 Constant true               \ see starts looking for
-                                \ primitives after this word!
-  0 Constant false
+ -1 Constant true ( -- f ) \ core-ext
+\G CONSTANT: f is a cell with all bits set.
+\ see starts looking for primitives after this word!
+
+  0 Constant false ( -- f ) \ core-ext
+\G CONSTANT: f is a cell with all bits clear.
 
 1 cells Constant cell ( -- u ) \ gforth
 1 floats Constant float ( -- u ) \ gforth
 
-20 Constant bl \ used by docon:, must be constant
+20 Constant bl ( -- c-char ) \ core
+\G c-char is the character value for a space.
+\ used by docon:, must be constant
 
 FF Constant /line
 
@@ -41,8 +46,14 @@ FF Constant /line
 400 Constant chars/block
 
 $20 8 2* cells + 2 + cell+ constant word-pno-size ( -- u )
+create holdbuf word-pno-size chars allot
+holdbuf word-pno-size chars + aconstant holdbuf-end
+avariable holdptr holdbuf-end holdptr a!
+avariable holdend holdbuf-end holdend a!
+
 84 constant pad-minsize ( -- u )
 
+
 \ that's enough so long
 
 \ User variables                                       13feb93py
@@ -60,12 +71,28 @@ Variable udp \ user area size? -anton
 AUser next-task        main-task next-task !
 AUser prev-task        main-task prev-task !
 AUser save-task        0 save-task !
-AUser sp0 	\ used by douser:, must be user
-		' sp0 Alias s0
-AUser rp0	' rp0 Alias r0
-AUser fp0       \ no f0, because this leads to unexpected results
-AUser lp0	' lp0 Alias l0
+AUser sp0 ( -- a-addr ) \ gforth
+\G USER VARIABLE: Initial value of the data stack pointer.
+\ sp0 is used by douser:, must be user
+    ' sp0 Alias s0 ( -- a-addr ) \ gforth
+\G OBSOLETE alias of @code{sp0}
+
+AUser rp0 ( -- a-addr ) \ gforth
+\G USER VARIABLE: Initial value of the return stack pointer.
+    ' rp0 Alias r0 ( -- a-addr ) \ gforth
+\G OBSOLETE alias of @code{rp0}
+
+AUser fp0 ( -- a-addr ) \ gforth
+\G USER VARIABLE: Initial value of the floating-point stack pointer.
+\ no f0, because this leads to unexpected results when using hex
+
+AUser lp0 ( -- a-addr ) \ gforth
+\G USER VARIABLE: Initial value of the locals stack pointer.
+    ' lp0 Alias l0 ( -- a-addr ) \ gforth
+\G OBSOLETE alias of @code{lp0}
+
 AUser handler	\ pointer to last throw frame
+AUser backtrace-empty \ true if the next THROW should store a backtrace
 \ AUser output
 \ AUser input
 
@@ -76,11 +103,25 @@ AUser "error            0 "error !
 [IFUNDEF] #tib		\ in ec-Version we may define this ourself
  User tibstack		\ saves >tib in execute
  User >tib		\ pointer to terminal input buffer
- User #tib		\ chars in terminal input buffer
- User >in               0 >in ! \ char number currently processed in tib
+ User #tib ( -- a-addr ) \ core-ext
+ \G USER VARIABLE: a-addr is the address of a cell containing
+ \G the number of characters in the terminal input buffer.
+ \G OBSOLESCENT: @code{source} superceeds the function of this word.
+
+ User >in ( -- a-addr ) \ core
+ \G USER VARIABLE: a-addr is the address of a cell containing the
+ \G char offset from the start of the terminal input buffer to the
+ \G start of the parse area
+                        0 >in ! \ char number currently processed in tib
 [THEN]
 has? file [IF]
- User blk               0 blk !
+ User blk ( -- a-addr ) \ block
+ \G USER VARIABLE: a-addr is the address of a cell containing zero
+ \G (in which case the input source is not a block and can be identified
+ \G by @code{source-id}) or the number of the block currently being
+ \G interpreted. A Standard program should not alter @code{blk} directly.
+			0 blk !
+
  User loadfile          0 loadfile !
 
  User loadfilename#	0 loadfilename# !
@@ -94,10 +135,26 @@ has? file [IF]
                         \ the current interpreted line (in TIB)
 [THEN]
 
- User base              A base !
+ User base ( -- a-addr ) \ core
+ \G USER VARIABLE: a-addr is the address of a cell that stores the
+ \G number base used by default for number conversion during input and output.
+                        A base !
  User dpl               -1 dpl !
 
- User state             0 state !
+ User state ( -- a-addr ) \ core,tools-ext
+ \G Recommended reading: @cite{@code{State}-smartness--Why it is evil
+ \G and how to exorcise it},
+ \G @url{http://www.complang.tuwien.ac.at/papers/ertl98.ps.gz}; short
+ \G version: Don't use @code{state}! @xref{Interpretation and
+ \G Compilation Semantics} for an alternative. USER VARIABLE: a-addr
+ \G is the address of a cell containing the compilation state flag. 0
+ \G => interpreting, -1 => compiling.  A program shall not directly
+ \G alter the value of @code{state}. The following Standard words
+ \G alter the value in @code{state}: @code{:} (colon) @code{;}
+ \G (semicolon) @code{abort} @code{quit} @code{:noname} @code{[}
+ \G (left-bracket) @code{]} (right-bracket) @code{;code}
+			0 state !
+
 AUser normal-dp		\ the usual dictionary pointer
 AUser dpp		normal-dp dpp !
 			\ the pointer to the current dictionary pointer