tests: better reports when /bin/ed is not present.

[sbcl.git] / doc / manual / pathnames.texinfo

diff --git a/doc/manual/pathnames.texinfo b/doc/manual/pathnames.texinfo
index f1faf01..4eb43de 100644 (file)
--- a/doc/manual/pathnames.texinfo
+++ b/doc/manual/pathnames.texinfo
@@ -2,6 +2,8 @@
 @comment  node-name,  next,  previous,  up
 @chapter Pathnames
 
+@cindex Pathnames
+
 @menu
 * Lisp Pathnames::
 * Native Filenames::
@@ -67,10 +69,44 @@ implementation-defined and so need documentation.
 @c
 @c * Other symbols and integers have implementation-defined meaning.
 @c   (19.2.2.4.6)
-@c
+
+@subsection Home Directory Specifiers
+
+SBCL accepts the keyword @code{:home} and a list of the form
+@code{(:home "username")} as a directory component immediately
+following @code{:absolute}.
+
+@code{:home} is represented in namestrings by @code{~/} and
+@code{(:home "username"} by @code{~username/} at the start of the
+namestring. Tilde-characters elsewhere in namestrings represent
+themselves.
+
+Home directory specifiers are resolved to home directory of the
+current or specified user by @code{native-namestring}, which is used
+by the implementation to translate pathnames before passing them on to
+operating system specific routines.
+
+Using @code{(:home "user")} form on Windows signals an error.
+
+@subsection The SYS Logical Pathname Host
+
+@cindex Logical pathnames
+@cindex Pathnames, logical
+@findex @cl{logical-pathname-translations}
+@findex @setf{@cl{logical-pathname-translations}}
+
 @c * The existence and meaning of SYS: logical pathnames is
 @c   implementation-defined.  (19.3.1.1.1)
 
+The logical pathname host named by @code{"SYS"} exists in SBCL.  Its
+@code{logical-pathname-translations} may be set by the site or the user
+applicable to point to the locations of the system's sources; in
+particular, the core system's source files match the logical pathname
+@code{"SYS:SRC;**;*.*.*"}, and the contributed modules' source files
+match @code{"SYS:CONTRIB;**;*.*.*"}.
+
+@include fun-sb-ext-set-sbcl-source-location.texinfo
+
 @node Native Filenames
 @comment  node-name,  next,  previous,  up
 @section Native Filenames
@@ -91,7 +127,48 @@ namestring, if possible.  Some Lisp pathname concepts (such as the
 @code{:back} directory component) have no direct equivalents in most
 Operating Systems; the behaviour of @code{native-namestring} is
 unspecified if an inappropriate pathname designator is passed to it.
+Additionally, note that conversion from pathname to native filename
+and back to pathname should not be expected to preserve equivalence
+under @code{equal}.
 
 @include fun-sb-ext-parse-native-namestring.texinfo
 @include fun-sb-ext-native-pathname.texinfo
 @include fun-sb-ext-native-namestring.texinfo
+
+Because some file systems permit the names of directories to be
+expressed in multiple ways, it is occasionally necessary to parse a
+native file name ``as a directory name'' or to produce a native file
+name that names a directory ``as a file''.  For these cases,
+@code{parse-native-namestring} accepts the keyword argument
+@code{as-directory} to force a filename to parse as a directory, and
+@code{native-namestring} accepts the keyword argument @code{as-file}
+to force a pathname to unparse as a file.  For example,
+
+@lisp
+; On Unix, the directory "/tmp/" can be denoted by "/tmp/" or "/tmp".
+; Under the default rules for native filenames, these parse and
+; unparse differently.
+(defvar *p*)
+(setf *p* (parse-native-namestring "/tmp/")) @result{} #P"/tmp/"
+(pathname-name *p*) @result{} NIL
+(pathname-directory *p*) @result{} (:ABSOLUTE "tmp")
+(native-namestring *p*) @result{} "/tmp/"
+
+(setf *p* (parse-native-namestring "/tmp")) @result{} #P"/tmp"
+(pathname-name *p*) @result{} "tmp"
+(pathname-directory *p*) @result{} (:ABSOLUTE)
+(native-namestring *p*) @result{} "/tmp"
+
+; A non-NIL AS-DIRECTORY argument to PARSE-NATIVE-NAMESTRING forces
+; both the second string to parse the way the first does.
+(setf *p* (parse-native-namestring "/tmp"
+                                   nil *default-pathname-defaults*
+                                   :as-directory t)) @result{} #P"/tmp/"
+(pathname-name *p*) @result{} NIL
+(pathname-directory *p*) @result{} (:ABSOLUTE "tmp")
+
+; A non-NIL AS-FILE argument to NATIVE-NAMESTRING forces the pathname
+; parsed from the first string to unparse as the second string.
+(setf *p* (parse-native-namestring "/tmp/")) @result{} #P"/tmp/"
+(native-namestring *p* :as-file t) @result{} "/tmp"
+@end lisp