Improve expand-file-name doc

* doc/lispref/files.texi (Relative File Names, Directory Names)
(File Name Expansion):
* doc/lispref/minibuf.texi (Reading File Names):
Document expand-file-name behavior with ~ more clearly
and accurately.
* doc/misc/org.texi (Batch execution): Simplify example
script so that it does not need expand-file-name and thus
will not mishandle file names with leading ~.

3 files changed, 26 insertions, 23 deletions

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 60369236ff5..bb355f1ee35 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -2137,7 +2137,8 @@ file name, @code{nil} otherwise.
 @end example
 @end defun
 
-  Given a possibly relative file name, you can convert it to an
+  Given a possibly relative file name, you can expand any
+leading @samp{~} and convert the result to an
 absolute name using @code{expand-file-name} (@pxref{File Name
 Expansion}).  This function converts absolute file names to relative
 names:
@@ -2264,6 +2265,10 @@ might be nil (for example, from an element of @code{load-path}), use:
 (expand-file-name @var{relfile} @var{dirname})
 @end example
 
+However, @code{expand-file-name} expands leading @samp{~} in
+@var{relfile}, which may not be what you want.  @xref{File Name
+Expansion}.
+
   To convert a directory name to its abbreviation, use this
 function:
 
@@ -2302,7 +2307,8 @@ and eliminating redundancies like @file{./} and @file{@var{name}/../}.
 @defun expand-file-name filename &optional directory
 This function converts @var{filename} to an absolute file name.  If
 @var{directory} is supplied, it is the default directory to start with
-if @var{filename} is relative.  (The value of @var{directory} should
+if @var{filename} is relative and does not start with @samp{~}.
+(The value of @var{directory} should
 itself be an absolute directory name or directory file name; it may
 start with @samp{~}.)  Otherwise, the current buffer's value of
 @code{default-directory} is used.  For example:
@@ -2322,11 +2328,15 @@ start with @samp{~}.)  Otherwise, the current buffer's value of
 @end group
 @end example
 
-If the part of the combined file name before the first slash is
+If the part of @var{filename} before the first slash is
 @samp{~}, it expands to the value of the @env{HOME} environment
 variable (usually your home directory).  If the part before the first
 slash is @samp{~@var{user}} and if @var{user} is a valid login name,
 it expands to @var{user}'s home directory.
+If you do not want this expansion for a relative @var{filename} that
+might begin with a literal @samp{~}, you can use @code{(concat
+(file-name-as-directory directory) filename)} instead of
+@code{(expand-file-name filename directory)}.
 
 Filenames containing @samp{.} or @samp{..} are simplified to their
 canonical form:
diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index 81402552678..89dee847841 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -1439,7 +1439,7 @@ platform-dependent.  Here, we simply document the behavior when using
 the minibuffer.
 
 @code{read-file-name} does not automatically expand the returned file
-name.  You must call @code{expand-file-name} yourself if an absolute
+name.  You can call @code{expand-file-name} yourself if an absolute
 file name is required.
 
 The optional argument @var{require-match} has the same meaning as in
diff --git a/doc/misc/org.texi b/doc/misc/org.texi
index e1de3087311..2d537946be0 100644
--- a/doc/misc/org.texi
+++ b/doc/misc/org.texi
@@ -1040,8 +1040,8 @@ shown below.
       debug-on-quit nil)
 
 ;; add latest org-mode to load path
-(add-to-list 'load-path (expand-file-name "/path/to/org-mode/lisp"))
-(add-to-list 'load-path (expand-file-name "/path/to/org-mode/contrib/lisp" t))
+(add-to-list 'load-path "/path/to/org-mode/lisp")
+(add-to-list 'load-path "/path/to/org-mode/contrib/lisp" t)
 @end lisp
 
 If an error occurs, a backtrace can be very useful (see below on how to
@@ -16900,25 +16900,18 @@ The sample script shows batch processing of multiple files using
 
 @example
 #!/bin/sh
-# -*- mode: shell-script -*-
-#
 # tangle files with org-mode
 #
-DIR=`pwd`
-FILES=""
-
-# wrap each argument in the code required to call tangle on it
-for i in $@@; do
-    FILES="$FILES \"$i\""
-done
-
-emacs -Q --batch \
-     --eval "(progn
-     (require 'org)(require 'ob)(require 'ob-tangle)
-     (mapc (lambda (file)
-            (find-file (expand-file-name file \"$DIR\"))
-            (org-babel-tangle)
-            (kill-buffer)) '($FILES)))" 2>&1 |grep -i tangled
+emacs -Q --batch --eval "
+    (progn
+      (require 'ob-tangle)
+      (mapc (lambda (file)
+              (save-current-buffer
+                (find-file file)
+                (org-babel-tangle)
+                (kill-buffer)))
+            command-line-args-left))
+  " "$@@"
 @end example
 
 @node Miscellaneous