--- gforth/kernel/tools.fs	1997/05/21 20:40:18	1.1
+++ gforth/kernel/tools.fs	2011/08/10 12:16:09	1.28
@@ -1,12 +1,12 @@
 \ TOOLS.FS     Toolkit extentions                      2may93jaw
 
-\ Copyright (C) 1995 Free Software Foundation, Inc.
+\ Copyright (C) 1995,1998,1999,2001,2003,2006,2007 Free Software Foundation, Inc.
 
 \ This file is part of Gforth.
 
 \ Gforth is free software; you can redistribute it and/or
 \ modify it under the terms of the GNU General Public License
-\ as published by the Free Software Foundation; either version 2
+\ as published by the Free Software Foundation, either version 3
 \ of the License, or (at your option) any later version.
 
 \ This program is distributed in the hope that it will be useful,
@@ -15,24 +15,36 @@
 \ GNU General Public License for more details.
 
 \ You should have received a copy of the GNU General Public License
-\ along with this program; if not, write to the Free Software
-\ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+\ along with this program. If not, see http://www.gnu.org/licenses/.
 
 \ May be cross-compiled
 
+require ./io.fs		\ type ...
+require ./nio.fs	\ . <# ...
+require ./int.fs	\ wordlist-id ..
+
 hex
 
 \ .S            CORE / CORE EXT                         9may93jaw
 
-variable maxdepth-.s
+
+defer .s.
+' . is .s.
+
+variable maxdepth-.s ( -- addr ) \ gforth maxdepth-dot-s
+\G A variable containing 9 by default.  @code{.s} and @code{f.s}
+\G display at most that many stack items.
 9 maxdepth-.s !
 
-: .s ( -- )
+: .s ( -- ) \ tools dot-s
+\G Display the number of items on the data stack, followed by a list
+\G of the items (but not more than specified by @code{maxdepth-.s};
+\G TOS is the right-most item.
     ." <" depth 0 .r ." > "
     depth 0 max maxdepth-.s @ min
     dup 0
     ?do
-	dup i - pick .
+	dup i - pick .s.
     loop
     drop ;
 
@@ -43,7 +55,7 @@ Variable /dump
 
 : .4 ( addr -- addr' )
     3 FOR  -1 /dump +!  /dump @ 0<
-        IF  ."    "  ELSE  dup c@ 0 <# # # #> type space  THEN
+        IF  ."    "  ELSE  dup c@ 0 <<# # # #> type #>> space  THEN
     char+ NEXT ;
 : .chars ( addr -- )
     /dump @ bounds
@@ -54,7 +66,11 @@ Variable /dump
 : .line ( addr -- )
   dup .4 space .4 ." - " .4 space .4 drop  10 /dump +!  space .chars ;
 
-: dump  ( addr u -- )
+: dump  ( addr u -- ) \ tools dump
+    \G Display @var{u} lines of memory starting at address @var{addr}. Each line
+    \G displays the contents of 16 bytes. When Gforth is running under
+    \G an operating system you may get @file{Invalid memory address} errors
+    \G if you attempt to access arbitrary locations.
     cr base @ >r hex        \ save base on return stack
     0 ?DO  I' I - 10 min /dump !
 	dup 8 u.r ." : " dup .line cr  10 +
@@ -63,7 +79,36 @@ Variable /dump
 
 \ ?                                                     17may93jaw
 
-: ? @ . ;
-
-\ INCLUDE see.fs
+: ? ( a-addr -- ) \ tools question
+    \G Display the contents of address @var{a-addr} in the current number base.
+    @ . ;
+
+\ words visible in roots                               14may93py
+
+include  ./../termsize.fs
+
+: wordlist-words ( wid -- ) \ gforth
+    \G Display the contents of the wordlist wid.
+    [ has? ec 0= [IF] ] wordlist-id [ [THEN] ]
+    0 swap cr
+    BEGIN
+	@ dup
+    WHILE
+	2dup name>string nip 2 + dup >r +
+	cols >=
+	IF
+	    cr nip 0 swap
+	THEN
+	dup name>string type space r> rot + swap
+    REPEAT
+    2drop ;
+
+: words
+    \G ** this will not get annotated. See other defn in search.fs .. **
+    \G It does not work to use "wordset-" prefix since this file is glossed
+    \G by cross.fs which doesn't have the same functionalty as makedoc.fs
+    [ has? ec 0= [IF] ] context @ [ [ELSE] ] forth-wordlist [ [THEN] ]
+    wordlist-words ;
 
+' words alias vlist ( -- ) \ gforth
+\g Old (pre-Forth-83) name for @code{WORDS}.