changeset 37582:fdf780ddf0ae

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

--- a/lispref/files.texi	Sat May 05 22:37:56 2001 +0000
+++ b/lispref/files.texi	Sat May 05 22:38:58 2001 +0000
@@ -2192,7 +2192,7 @@
 
 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 @@
 (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