From c40b51e0ff77adfbe27150de0e154bd0015a4ec5 Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Sat, 8 Jan 2011 17:01:13 -0500 Subject: [PATCH] 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. --- doc/emacs/ChangeLog | 6 ++++++ doc/emacs/files.texi | 26 +++++++++++++++++++++++- doc/lispref/ChangeLog | 4 ++-- doc/lispref/files.texi | 55 ++++++++++---------------------------------------- 4 files changed, 44 insertions(+), 47 deletions(-) diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog index 829f61efb38..4825f08979f 100644 --- a/doc/emacs/ChangeLog +++ b/doc/emacs/ChangeLog @@ -1,3 +1,9 @@ +2011-01-08 Chong Yidong + + * 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 * msdog.texi (Windows Startup): Correct inaccurate description of diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi index 4df81caa8f2..530c2bb94f7 100644 --- a/doc/emacs/files.texi +++ b/doc/emacs/files.texi @@ -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 diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 1c4e6b9074f..e1180124c05 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,7 +1,7 @@ 2011-01-08 Chong Yidong - * 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 diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index c2a14b5025e..1f66da98347 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -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 -- 2.11.4.GIT