This is the third RfD on this topic. The second one was in July
2007. You find the updated text further down.

The main point of contention was about the prefix syntax. I solved it
by removing the prefix stuff.

Changes:

3rd RfD:

The main way to specify source-directory-relative filenames is now F",
not prefixes. Removed prefixes from proposal, but discuss them in the
Remarks section.

2nd RfD:

Added INCLUDE-NAME-ABS.
Added Sections "Which prefix?", "What if there is no currently
including file?", "Isn't specifying "/" as directory separator too
OS-specific?"
Replaced many mentions of "./" with "prefix".
Minor rewrites to make some prose clearer.

Problem:

Summary: How do I refer to another file that is distributed with the
Forth file at hand, in the presence of directories?

Example: Let us assume that the current working directory is /wd/, and
that we have a program installed in directory /prog1/, but on the next
installation it might be installed in /prog2/. The file to be
INCLUDEd by the user is /prog1/prog.fs, and it is supposed to INCLUDE
library.fs and read a data file data.txt residing in the same
directory. How should prog.fs refer to library.fs and data.txt?
Remember that on the next installation they might be in a different
directory than in this installation (but in the same directory as
prog.fs).

As an additional complication, consider the case where prog.fs loads a
library /prog1/lib1/lib.fs, that has been developed independently of
prog.fs, and without knowledge that it would later wind up in
/prog1/lib1; /prog1/lib1/lib.fs refers to another file foo.fs which
resides at /prog1/lib1/foo.fs in this installation. How should Forth
code in the library refer to other files of the library?


Solution outline:

First we need to specify a directory separator. The "/" is supported
in all important OSs (including Windows, except in cmd.exe), so we
specify it for Forth.

Next, we need a way to specify a file name relative to the directory
that contains the Forth source file that contains the file name (as a
string): F" file" produces a filename in a source-file-independent
way. E.g., in the example above, the prog.fs file would contain code
like

F" library.fs"
F" data.txt"
F" lib1/lib.fs"

and lib.fs would contain code like

F" foo.fs"

In addition, a word INCLUDE-NAME-ABS for converting a string from an
include-relative filename to an absolute filename is a natural factor
of F" and can be useful in some cases.


Typical usage:

F" lib1/lib.fs" required
F" data.txt" r/o open-file
S\" ./funny\"filename" include-name-abs r/o open-file


Proposal, reference implementation and tests:

Will be done after the solution has solidified after some discussion.


Existing practice and experience:

Gforth implements this functionality by interpreting the ./ prefix of
filenames in INCLUDED and friends (i.e., in the consumer, not in the
producer, as suggested here). We have had very good experiences with
that (consumer and producer are usually in the same file).

Some other Forth systems have similar facilities, e.g., Win32Forth,
typically as part of the regular file search path (so no special
prefix is necessary).

Modern C compilers like gcc do

#include "bla.h"

relative to the directory of the currently-included file. The
proposed equivalent would be "INCLUDE ./bla.h".

When executing a program or script, the Unix shell searches relative
names like bla.sh in the path (which often does not include "."), but
if you write ./bla.sh, this refers to and only to the bla.sh in the
current working directory (unfortunately not the directory containing
the current file, but the shell offers ways to work around this
shortcoming).


Remarks:

What about specifying the source directory as a file name prefix?

There was considerable resistance to using the "./" prefix in the
first RfD, and to other short prefixes. We probably could find
consensus on a prefix, but it will be so long that it does not provide
any savings in typing over using F", so the only people who would use
such a prefix are probably those people who would also use F" if there
is no prefix, so having a prefix just causes additional work for the
proponent and the implementors with little gain to the community.

For those interested in prefixes, my conclusion of the prefix
discussion before I decided to go without prefixes is available in an
<a href="directories-with-prefixes.html">older version of this RfD</a>.



What about specifying file names relative to a library root etc.?

Several people have suggested having a word (or a prefix) for
specifying a library directory. While this is a worthwhile goal, I
feel that finding a consensus on that topic is hard enough that it
should be attacked in a separate RfD.


What if the user puts an absolute file name inside F" or with
INCLUDE-NAME-ABS?

We could specify that F" then just returns the absulute file name, or
that this is an ambiguous condition. Unless there is a good reason to
make it ambiguous, I lean towards the first option. One potential
reason for making it ambiguous is that the Forth system does not
necessarily recognize absolute file names (e.g., Windows has all kinds
of syntax for absolute file names).


What if the user uses F" or INCLUDE-NAME-ABS outside a Forth source file?

That is an ambiguous condition. I.e., a standard program would have
to specify the directory in another way in this situation. However, a
standrd program will typically come in a Forth source file (or it will
come as blocks and not access files at all).


Why not use a CD word for this purpose?

While a word for changing the current working directory may have its
uses in Forth, it is usually not a good idea to change the working
directory for loading code. Apart from the usual nesting/unnesting
complications, the user usually sets the working directory to some
directory on purpose, because that's where he is working; the program
or library directory is usually not where he is working. If the user
passes a data file name to the included file, he expects it to be
interpreted in the context of his working directory, not the program's
directory.


Isn't specifying "/" as directory separator too OS-specific?

It works in practice, and other approaches don't. E.g., Peter Knaggs
writes <4505c44b$0$2665$ed2619ec@...>:

|Java has a special DirectorySeparator constant you are supposed to use,
|but nobody ever does.

If there is ever a Forth 200x system for an OS that has a different
directory syntax (e.g., VMS), the Forth system can translate the
filename with the slashes into the native directory syntax (I guess
that the POSIX layer for such OSs does the same).

- anton