From 0fe6819f96934f0120d34897447746e1e9c0a3f6 Mon Sep 17 00:00:00 2001
From: "Richard M. Stallman" <rms@gnu.org>
Date: Sat, 5 May 2001 22:38:58 +0000
Subject: [PATCH] Explain how handler is called, for magic file operations that
 take more than one file-name argument.

---
 lispref/files.texi | 23 ++++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

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