[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] master 05f9ffd: Improve expand-file-name doc
From: |
Paul Eggert |
Subject: |
[Emacs-diffs] master 05f9ffd: Improve expand-file-name doc |
Date: |
Sat, 26 Aug 2017 00:14:12 -0400 (EDT) |
branch: master
commit 05f9ffd53c65699e8de6cca4817b1f2dc2f63a79
Author: Paul Eggert <address@hidden>
Commit: Paul Eggert <address@hidden>
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 ~.
---
doc/lispref/files.texi | 16 +++++++++++++---
doc/lispref/minibuf.texi | 2 +-
doc/misc/org.texi | 31 ++++++++++++-------------------
3 files changed, 26 insertions(+), 23 deletions(-)
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 6036923..bb355f1 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
address@hidden, 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
@address@hidden/../}.
@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 @address@hidden 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
address@hidden(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 8140255..89dee84 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 e1de308..2d53794 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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] master 05f9ffd: Improve expand-file-name doc,
Paul Eggert <=