--- gforth/search.fs	1999/05/22 20:03:53	1.10
+++ gforth/search.fs	2000/08/16 09:26:52	1.15
@@ -24,18 +24,22 @@ Variable vp
   0 A, 0 A,  0 A, 0 A,   0 A, 0 A,   0 A, 0 A, 
 
 : get-current  ( -- wid ) \ search
-  \G @var{wid} is the identifier of the current compilation word list.
+  \G @i{wid} is the identifier of the current compilation word list.
   current @ ;
 
 : set-current  ( wid -- )  \ search
-  \G Set the compilation word list to the word list identified by @var{wid}.
+  \G Set the compilation word list to the word list identified by @i{wid}.
   current ! ;
 
-\ : context ( -- addr )  vp dup @ cells + ;
-: vp! dup vp ! cells vp + to context ;
+:noname ( -- addr )
+    vp dup @ cells + ;
+is context
+
+: vp! ( u -- )
+    vp ! ;
 : definitions  ( -- ) \ search
-  \G Make the compilation word list the same as the word list
-  \G that is currently at the top of the search order stack.
+  \G Set the compilation word list to be the same as the word list
+  \G that is currently at the top of the search order.
   context @ current ! ;
 
 \ wordlist Vocabulary also previous                    14may93py
@@ -51,7 +55,7 @@ Variable slowvoc   0 slowvoc !
   dup initvoc ;
 
 : wordlist  ( -- wid ) \ search
-  \G Create a new, empty word list represented by @var{wid}.
+  \G Create a new, empty word list represented by @i{wid}.
   slowvoc @
   IF    \ this is now f83search because hashing may be loaded already
 	\ jaw
@@ -61,8 +65,9 @@ Variable slowvoc   0 slowvoc !
 
 : Vocabulary ( "name" -- ) \ gforth
   \G Create a definition "name" and associate a new word list with it.
-  \G The run-time effect of "name" is to push the new word list's wid
-  \G onto the top of the search order stack.
+  \G The run-time effect of "name" is to replace the @i{wid} at the
+  \G top of the search order with the @i{wid} associated with the new
+  \G word list.
   Create wordlist drop  DOES> context ! ;
 
 : check-maxvp ( n -- )
@@ -72,14 +77,14 @@ Variable slowvoc   0 slowvoc !
     \g Push @var{wid} on the search order.
     vp @ 1+ dup check-maxvp vp! context ! ;
 
-: also  ( -- ) \ search ext
-  \G Perform a @code{DUP} on the search order stack. Usually used prior
-  \G to @code{Forth}, @code{definitions} etc.
+: also  ( -- ) \ search-ext
+  \G Like @code{DUP} for the search order. Usually used before a
+  \G vocabulary (e.g., @code{also Forth}); the combined effect is to push
+  \G the wordlist represented by the vocabulary on the search order.
   context @ push-order ;
 
-: previous ( -- ) \ search ext
-  \G Perform a @code{DROP} on the search order stack, thereby removing the wid at the
-  \G top of the (search order) stack from the search order.
+: previous ( -- ) \ search-ext
+  \G Drop the wordlist at the top of the search order.
   vp @ 1- dup 0= -50 and throw vp! ;
 
 \ vocabulary find                                      14may93py
@@ -126,15 +131,15 @@ slowvoc off
 
 \ Only root                                            14may93py
 
-Vocabulary Forth ( -- ) \ thisone- search-ext
-  \G Push the @var{wid} associated with @code{forth-wordlist} onto the
-  \G search order stack.
+Vocabulary Forth ( -- ) \ gforthman- search-ext
+  \G Replace the @i{wid} at the top of the search order with the
+  \G @i{wid} associated with the word list @code{forth-wordlist}.
+
 
 Vocabulary Root ( -- ) \ gforth
-  \G Add the vocabulary @code{Root} to the search order stack.
-  \G This vocabulary makes up the minimum search order and
-  \G contains these words: @code{order} @code{set-order}
-  \G @code{forth-wordlist} @code{Forth} @code{words}
+  \G Add the root wordlist to the search order stack.  This vocabulary
+  \G makes up the minimum search order and contains only a
+  \G search-order words.
 
 : Only ( -- ) \ search-ext
   \G Set the search order to the implementation-defined minimum search
@@ -155,13 +160,14 @@ lookup ! \ our dictionary search order b
 \ get-order set-order                                  14may93py
 
 : get-order  ( -- widn .. wid1 n ) \ search
-  \G Copy the search order stack to the data stack. The current search
-  \G order has @var{n} entries, of which @var{wid1} represents the word
-  \G list that is searched first (the word list at the top of the stack) and
-  \G @var{widn} represents the word order that is searched last.
-  vp @ 0 ?DO  vp cell+ I cells + @  LOOP  vp @ ;
+  \G Copy the search order to the data stack. The current search order
+  \G has @i{n} entries, of which @i{wid1} represents the wordlist
+  \G that is searched first (the word list at the top of the search
+  \G order) and @i{widn} represents the wordlist that is searched
+  \G last.
+  vp @ 0 ?DO vp cell+ I cells + @ LOOP vp @ ;
 
-: set-order  ( widn .. wid1 n -- ) \ thisone- search
+: set-order  ( widn .. wid1 n -- ) \ gforthman- search
     \G If @var{n}=0, empty the search order.  If @var{n}=-1, set the
     \G search order to the implementation-defined minimum search order
     \G (for Gforth, this is the word list @code{Root}). Otherwise,
@@ -182,9 +188,9 @@ lookup ! \ our dictionary search order b
   context @ 1 set-order ;
 
 : .voc
-    body> >head name>string type space ;
+    body> >head-noprim name>string type space ;
 
-: order ( -- )  \  thisone- search-ext
+: order ( -- )  \  gforthman- search-ext
   \G Print the search order and the compilation word list.  The
   \G word lists are printed in the order in which they are searched
   \G (which is reversed with respect to the conventional way of
@@ -215,9 +221,9 @@ Root definitions
 \G of the search order.
 ' Forth Alias Forth
 ' forth-wordlist alias forth-wordlist ( -- wid ) \ search
-  \G CONSTANT: @var{wid} identifies the word list that includes all of the standard words
+  \G @code{Constant} -- @i{wid} identifies the word list that includes all of the standard words
   \G provided by Gforth. When Gforth is invoked, this word list is the compilation word
-  \G list and is at the top of the word list stack.
+  \G list and is at the top of the search order.
 ' set-order alias set-order
 ' order alias order