From: Richard M. Stallman <rms@gnu.org>
Date: Sat, 5 May 2001 22:38:58 +0000 (+0000)
Subject: Explain how handler is called, for magic file operations that take
X-Git-Tag: emacs-pretest-21.0.103~31
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=0fe6819f96934f0120d34897447746e1e9c0a3f6;p=emacs.git

Explain how handler is called, for magic file operations that take
more than one file-name argument.
---

diff --git a/lispref/files.texi b/lispref/files.texi
index 6a3704b6716..c4a20ee6211 100644
--- a/lispref/files.texi
+++ b/lispref/files.texi
@@ -2192,7 +2192,7 @@ calling @var{handler}.
 
 The first argument given to @var{handler} is the name of the primitive;
 the remaining arguments are the arguments that were passed to that
-operation.  (The first of these arguments is typically the file name
+primitive.  (The first of these arguments is most often the file name
 itself.)  For example, if you do this:
 
 @example
@@ -2207,6 +2207,27 @@ called like this:
 (funcall @var{handler} 'file-exists-p @var{filename})
 @end example
 
+When a function takes two or more arguments that must be file names,
+it checks each of those names for a handler.  For example, if you do
+this:
+
+@example
+(expand-file-name @var{filename} @var{dirname})
+@end example
+
+@noindent
+then it checks for a handler for @var{filename} and then for a handler
+for @var{dirname}.  In either case, the @var{handler} is called like
+this:
+
+@example
+(funcall @var{handler} 'expand-file-name @var{filename} @var{dirname})
+@end example
+
+@noindent
+The @var{handler} then needs to figure out whether to handle
+@var{filename} or @var{dirname}.
+
 Here are the operations that a magic file name handler gets to handle:
 
 @ifnottex