Commit c40b51e0 authored by Chong Yidong's avatar Chong Yidong

Move directory-abbrev-alist doc from Lispref to Emacs manual.

* doc/emacs/files.texi (File Aliases): Move directory-abbrev-alist doc from Lisp
manual.  Explain why directory-abbrev-alist elements should be anchored
(Bug#7777).

* doc/lispref/files.texi (Directory Names): Move directory-abbrev-alist doc to
Emacs manual.
parent ad2d9b0e
2011-01-08 Chong Yidong <cyd@stupidchicken.com>
* files.texi (File Aliases): Move directory-abbrev-alist doc from Lisp
manual. Explain why directory-abbrev-alist elements should be anchored
(Bug#7777).
2011-01-07 Eli Zaretskii <eliz@gnu.org>
* msdog.texi (Windows Startup): Correct inaccurate description of
......
......@@ -1158,7 +1158,6 @@ links point to directories.
@vindex find-file-existing-other-name
@vindex find-file-suppress-same-file-warnings
Normally, if you visit a file which Emacs is already visiting under
a different name, Emacs displays a message in the echo area and uses
the existing buffer visiting that file. This can happen on systems
......@@ -1180,6 +1179,31 @@ then the file name recorded for a buffer is the file's @dfn{truename}
than the name you specify. Setting @code{find-file-visit-truename} also
implies the effect of @code{find-file-existing-other-name}.
@cindex directory name abbreviation
@vindex directory-abbrev-alist
Sometimes, a directory is ordinarily accessed through a symbolic
link, and you may want Emacs to preferentially display its ``linked''
name instead of its truename. To do this, customize the variable
@code{directory-abbrev-alist}. Each element in this list should have
the form @code{(@var{from} . @var{to})}, which says to replace
@var{from} with @var{to} when it appears in a directory name. For
this feature to work properly, @var{from} and @var{to} should point to
the same file. The @var{from} string is actually a regular expression
(@pxref{Regexps}); it should always start with @samp{\`}, to avoid
matching to an incorrect part of the original directory name. The
@var{to} string should be an ordinary absolute directory name. Do not
use @samp{~} to stand for a home directory in the @var{to} string;
Emacs performs these substitutions separately.
Here's an example, from a system on which file system
@file{/home/fsf} and so on are normally accessed through symbolic
links named @file{/fsf} and so on.
@example
(("\\`/home/fsf" . "/fsf")
("\\`/home/gd" . "/gd"))
@end example
@node Directories
@section File Directories
......
2011-01-08 Chong Yidong <cyd@stupidchicken.com>
* files.texi (Directory Names): Explain why directory-abbrev-alist
elements should be anchored (Bug#7777).
* files.texi (Directory Names): Move directory-abbrev-alist doc to
Emacs manual.
2011-01-07 Eli Zaretskii <eliz@gnu.org>
......
......@@ -1920,55 +1920,22 @@ Don't try concatenating a slash by hand, as in
because this is not portable. Always use
@code{file-name-as-directory}.
@cindex directory name abbreviation
Directory name abbreviations are useful for directories that are
normally accessed through symbolic links. Sometimes the users recognize
primarily the link's name as ``the name'' of the directory, and find it
annoying to see the directory's ``real'' name. If you define the link
name as an abbreviation for the ``real'' name, Emacs shows users the
abbreviation instead.
@defopt directory-abbrev-alist
The variable @code{directory-abbrev-alist} contains an alist of
abbreviations to use for file directories. Each element has the form
@code{(@var{from} . @var{to})}, and says to replace @var{from} with
@var{to} when it appears in a directory name.
The @var{from} string is actually a regular expression. It ought to
always start with @samp{\`}, to avoid incorrectly matching to a
relative portion of the supplied directory name.
The @var{to} string should be an ordinary absolute directory name.
Do not use @samp{~} to stand for a home directory in that string; the
function @code{abbreviate-file-name} performs these substitutions.
You can set this variable in @file{site-init.el} to describe the
abbreviations appropriate for your site.
Here's an example, from a system on which file system @file{/home/fsf}
and so on are normally accessed through symbolic links named @file{/fsf}
and so on.
@example
(("\\`/home/fsf" . "/fsf")
("\\`/home/gp" . "/gp")
("\\`/home/gd" . "/gd"))
@end example
@end defopt
To convert a directory name to its abbreviation, use this
function:
@defun abbreviate-file-name filename
@anchor{Definition of abbreviate-file-name}
This function applies abbreviations from @code{directory-abbrev-alist}
to its argument, and also substitutes @samp{~} for the user's home
directory if the argument names a file in the home directory or one of
its subdirectories. (If the home directory is a root directory, it is
not replaced with @samp{~}, because this does not make the result
shorter on many systems.) You can use it for directory names and for
file names, because it recognizes abbreviations even as part of the
name.
This function returns an abbreviated form of @var{filename}. It
applies the abbreviations specified in @code{directory-abbrev-alist}
(@pxref{File Aliases,,File Aliases, emacs, The GNU Emacs Manual}),
then substitutes @samp{~} for the user's home directory if the
argument names a file in the home directory or one of its
subdirectories. If the home directory is a root directory, it is not
replaced with @samp{~}, because this does not make the result shorter
on many systems.
You can use this function for directory names and for file names,
because it recognizes abbreviations even as part of the name.
@end defun
@node File Name Expansion
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment