--- gforth/kernel/require.fs	1998/12/08 22:03:13	1.5
+++ gforth/kernel/require.fs	1999/05/17 14:55:50	1.8
@@ -21,7 +21,10 @@
 \ Now: Kernel Module, Reloadable
 
 create included-files 0 , 0 , ( pointer to and count of included files )
-here ," ./the terminal" dup c@ swap 1 + swap , A, here 2 cells -
+\ here ," ./the terminal" dup c@ swap 1 + swap , A, here 2 cells -
+\ ./ is confusing for the search path stuff! There should be never a .
+\ in sourcefilename....
+here ," #terminal#" dup c@ swap 1 + swap , A, here 2 cells -
 create image-included-files  1 , A, ( pointer to and count of included files )
 \ included-files points to ALLOCATEd space, while image-included-files
 \ points to ALLOTed objects, so it survives a save-system
@@ -31,25 +34,31 @@ create image-included-files  1 , A, ( po
     included-files 2@ loadfilename# @ min 2* cells + ;
 
 : sourcefilename ( -- c-addr u ) \ gforth
-    \G the name of the source file which is currently the input
+    \G The name of the source file which is currently the input
     \G source.  The result is valid only while the file is being
     \G loaded.  If the current input source is no (stream) file, the
     \G result is undefined.
     loadfilename 2@ ;
 
 : sourceline# ( -- u ) \ gforth		sourceline-number
-    \G the line number of the line that is currently being interpreted
+    \G The line number of the line that is currently being interpreted
     \G from a (stream) file. The first line has the number 1. If the
-    \G current input source is no (stream) file, the result is
+    \G current input source is not a (stream) file, the result is
     \G undefined.
     loadline @ ;
 
-: init-included-files ( -- )
+: init-included-files ( -- ) \ gforth
+    \G Clear the list of earlier included files.
     image-included-files 2@ 2* cells save-mem drop ( addr )
     image-included-files 2@ nip included-files 2! ;
 
 : included? ( c-addr u -- f ) \ gforth
-    \G true, iff filename c-addr u is in included-files
+    \G True only if the file @var{c-addr u} is in the list of earlier
+    \G included files. If the file has been loaded, it may have been
+    \G specified as, say, foo.fs and found somewhere on the Forth
+    \G search path. To return true from @code{included?}, you must
+    \G specify the exact path to the file, even if that is
+    \G @code{./foo.fs}
     included-files 2@ 0
     ?do ( c-addr u addr )
 	dup >r 2@ 2over compare 0=
@@ -68,7 +77,7 @@ create image-included-files  1 , A, ( po
     2! ;
 
 : included1 ( i*x file-id c-addr u -- j*x ) \ gforth
-    \G include the file file-id with the name given by c-addr u
+    \G Include the file file-id with the name given by @var{c-addr u}.
     loadfilename# @ >r
     save-mem add-included-file ( file-id )
     included-files 2@ nip 1- loadfilename# !
@@ -76,16 +85,16 @@ create image-included-files  1 , A, ( po
     r> loadfilename# !
     throw ;
     
-: included ( i*x addr u -- j*x ) \ file
+: included ( i*x c-addr u -- j*x ) \ file
     \G @code{include-file} the file whose name is given by the string
-    \G @var{addr u}.
+    \G @var{c-addr u}.
     open-fpath-file throw included1 ;
 
 : required ( i*x addr u -- j*x ) \ gforth
-    \G include the file with the name given by @var{addr u}, if it is not
-    \G @code{included} (or @code{required}) already. Currently this
-    \G works by comparing the name of the file (with path) against the
-    \G names of earlier included files.
+    \G @code{include-file} the file with the name given by @var{addr
+    \G u}, if it is not @code{included} (or @code{required})
+    \G already. Currently this works by comparing the name of the file
+    \G (with path) against the names of earlier included files.
     \ however, it may be better to fstat the file,
     \ and compare the device and inode. The advantages would be: no
     \ problems with several paths to the same file (e.g., due to
@@ -101,12 +110,12 @@ create image-included-files  1 , A, ( po
 \ INCLUDE                                               9may93jaw
 
 : include  ( ... "file" -- ... ) \ gforth
-\G includes @var{file}
-  name included ;
+    \G @code{include-file} the file @var{file}.
+    name included ;
 
 : require  ( ... "file" -- ... ) \ gforth
-\G includes @var{file} only if it is not included already
-  name required ;
+    \G @code{include-file} @var{file} only if it is not included already.
+    name required ;
 
 0 [IF]
 : \I
@@ -143,5 +152,5 @@ create image-included-files  1 , A, ( po
 	cr I 2@ type  2 cells +LOOP ;  
 
 \ contains tools/newrequire.fs
-\ \I $Id: require.fs,v 1.5 1998/12/08 22:03:13 anton Exp $
+\ \I $Id: require.fs,v 1.8 1999/05/17 14:55:50 jwilke Exp $