procyberian/emacs
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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

Browse source 
* 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.
This commit is contained in:
Chong Yidong 2011-01-08 17:01:13 -05:00
parent ad2d9b0e33
commit c40b51e0ff
4 changed files with 44 additions and 47 deletions
Download patch file Download diff file Expand all files Collapse all files

6
doc/emacs/ChangeLog
View file

@ -1,3 +1,9 @@
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

26
doc/emacs/files.texi
View file

@ -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

4
doc/lispref/ChangeLog
View file

@ -1,7 +1,7 @@
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>

55
doc/lispref/files.texi
View file

@ -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