--- gforth/kernel/require.fs	1997/05/21 20:40:17	1.1
+++ gforth/kernel/require.fs	2000/07/01 07:59:10	1.10
@@ -1,6 +1,6 @@
 \ require.fs
 
-\ Copyright (C) 1995-1997 Free Software Foundation, Inc.
+\ Copyright (C) 1995,1996,1997,1998 Free Software Foundation, Inc.
 
 \ This file is part of Gforth.
 
@@ -20,38 +20,45 @@
 
 \ Now: Kernel Module, Reloadable
 
-\ $Id: require.fs,v 1.1 1997/05/21 20:40:17 anton Exp $
-
 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
 
-: loadfilename ( -- a-addr )
-    \G a-addr 2@ produces the current file name ( c-addr u )
+: loadfilename ( -- a-addr ) \ gforth
+    \G @i{a-addr} @code{2@@} produces the current file name ( @i{c-addr u} )
     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, @file{foo.fs} and found somewhere on the
+    \G Forth search path. To return @code{true} from @code{included?},
+    \G you must specify the exact path to the file, even if that is
+    \G @file{./foo.fs}
     included-files 2@ 0
     ?do ( c-addr u addr )
 	dup >r 2@ 2over compare 0=
@@ -70,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# !
@@ -78,19 +85,22 @@ create image-included-files  1 , A, ( po
     r> loadfilename# !
     throw ;
     
-: included ( i*x addr u -- j*x ) \ file
-    open-fpath-file included1 ;
+: included ( i*x c-addr u -- j*x ) \ file
+    \G @code{include-file} the file whose name is given by the string
+    \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 addr u, if it is not
-    \G included already. Currently this works by comparing the name of
-    \G the file (with path) against the names of earlier included
-    \G files; however, it would probably be better to fstat the file,
-    \G and compare the device and inode. The advantages would be: no
-    \G problems with several paths to the same file (e.g., due to
-    \G links) and we would catch files included with include-file and
-    \G write a require-file.
-    open-fpath-file 2dup included?
+    \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
+    \ links) and we would catch files included with include-file and
+    \ write a require-file.
+    open-fpath-file throw 2dup included?
     if
 	2drop close-file throw
     else
@@ -99,11 +109,13 @@ create image-included-files  1 , A, ( po
 
 \ INCLUDE                                               9may93jaw
 
-: include  ( "file" -- ) \ gforth
-  name included ;
-
-: require  ( "file" -- ) \ gforth
-  name required ;
+: include  ( ... "file" -- ... ) \ gforth
+    \G @code{include-file} the file @var{file}.
+    name included ;
+
+: require  ( ... "file" -- ... ) \ gforth
+    \G @code{include-file} @var{file} only if it is not included already.
+    name required ;
 
 0 [IF]
 : \I
@@ -112,7 +124,8 @@ create image-included-files  1 , A, ( po
   string,
   needsrcs^ @ ! ;
 
-: .modules
+: .included ( -- ) \ gforth
+    \G list the names of the files that have been @code{included}
   cr
   needs^ @
   BEGIN		dup 
@@ -135,10 +148,11 @@ create image-included-files  1 , A, ( po
 : loadfilename#>str ( n -- adr len )
     included-files 2@ drop swap 2* cells + 2@ ;
 
-: .modules
+: .included ( -- ) \ gforth
+    \G list the names of the files that have been @code{included}
     included-files 2@ 2* cells bounds ?DO
 	cr I 2@ type  2 cells +LOOP ;  
 
 \ contains tools/newrequire.fs
-\ \I $Id: require.fs,v 1.1 1997/05/21 20:40:17 anton Exp $
+\ \I $Id: require.fs,v 1.10 2000/07/01 07:59:10 anton Exp $