[Emacs-diffs] Changes to emacs/lispref/files.texi

[Richard M . Stallman]

Index: emacs/lispref/files.texi
diff -c emacs/lispref/files.texi:1.78 emacs/lispref/files.texi:1.79
*** emacs/lispref/files.texi:1.78       Sun Apr 24 13:24:05 2005
--- emacs/lispref/files.texi    Sat Apr 30 20:30:03 2005
***************
*** 2441,2447 ****
  the file name matches @var{regexp}, the primitives handle that file by
  calling @var{handler}.
  
! The first argument given to @var{handler} is the name of the
  primitive, as a symbol; the remaining arguments are the arguments that
  were passed to that primitive.  (The first of these arguments is most
  often the file name itself.)  For example, if you do this:
--- 2441,2447 ----
  the file name matches @var{regexp}, the primitives handle that file by
  calling @var{handler}.
  
!   The first argument given to @var{handler} is the name of the
  primitive, as a symbol; the remaining arguments are the arguments that
  were passed to that primitive.  (The first of these arguments is most
  often the file name itself.)  For example, if you do this:
***************
*** 2458,2464 ****
  (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:
  
--- 2458,2464 ----
  (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:
  
***************
*** 2479,2485 ****
  The @var{handler} then needs to figure out whether to handle
  @var{filename} or @var{dirname}.
  
! If the specified file name matches more than one handler, the one
  whose match starts last in the file name gets precedence.  This rule
  is chosen so that handlers for jobs such as uncompression are handled
  first, before handlers for jobs such as remote file access.
--- 2479,2485 ----
  The @var{handler} then needs to figure out whether to handle
  @var{filename} or @var{dirname}.
  
!   If the specified file name matches more than one handler, the one
  whose match starts last in the file name gets precedence.  This rule
  is chosen so that handlers for jobs such as uncompression are handled
  first, before handlers for jobs such as remote file access.
***************
*** 2575,2586 ****
  @end flushleft
  @end iftex
  
! Handlers for @code{insert-file-contents} typically need to clear the
  buffer's modified flag, with @code{(set-buffer-modified-p nil)}, if the
  @var{visit} argument is address@hidden  This also has the effect of
  unlocking the buffer if it is locked.
  
! The handler function must handle all of the above operations, and
  possibly others to be added in the future.  It need not implement all
  these operations itself---when it has nothing special to do for a
  certain operation, it can reinvoke the primitive, to handle the
--- 2575,2586 ----
  @end flushleft
  @end iftex
  
!   Handlers for @code{insert-file-contents} typically need to clear the
  buffer's modified flag, with @code{(set-buffer-modified-p nil)}, if the
  @var{visit} argument is address@hidden  This also has the effect of
  unlocking the buffer if it is locked.
  
!   The handler function must handle all of the above operations, and
  possibly others to be added in the future.  It need not implement all
  these operations itself---when it has nothing special to do for a
  certain operation, it can reinvoke the primitive, to handle the
***************
*** 2603,2609 ****
               (apply operation args)))))
  @end smallexample
  
! When a handler function decides to call the ordinary Emacs primitive for
  the operation at hand, it needs to prevent the primitive from calling
  the same handler once again, thus leading to an infinite recursion.  The
  example above shows how to do this, with the variables
--- 2603,2609 ----
               (apply operation args)))))
  @end smallexample
  
!   When a handler function decides to call the ordinary Emacs primitive for
  the operation at hand, it needs to prevent the primitive from calling
  the same handler once again, thus leading to an infinite recursion.  The
  example above shows how to do this, with the variables
***************
*** 2614,2620 ****
  each have handlers.
  
  @kindex safe-magic (@r{property})
! Handlers that don't really do anything special for actual access to the
  file---such as the ones that implement completion of host names for
  remote file names---should have a address@hidden @code{safe-magic}
  property.  For instance, Emacs normally ``protects'' directory names
--- 2614,2620 ----
  each have handlers.
  
  @kindex safe-magic (@r{property})
!   Handlers that don't really do anything special for actual access to the
  file---such as the ones that implement completion of host names for
  remote file names---should have a address@hidden @code{safe-magic}
  property.  For instance, Emacs normally ``protects'' directory names
***************
*** 2623,2628 ****
--- 2623,2637 ----
  would be used for them has a address@hidden @code{safe-magic}
  property, the @samp{/:} is not added.
  
+ @kindex operations (@r{property})
+   A file name handler can have an @code{operations} property to
+ declare which operations it handles in a nontrivial way.  If this
+ property has a address@hidden value, it should be a list of
+ operations; then only those operations will call the handler.  This
+ avoids inefficiency, but its main purpose is for autoloaded handler
+ functions, so that they won't be loaded except when they have real
+ work to do.
+ 
  @defvar inhibit-file-name-handlers
  This variable holds a list of handlers whose use is presently inhibited
  for a certain operation.