comparison lispref/files.texi @ 53531:5bd5de5e98c2

(Saving Buffers): Clarify descriptions of `write-contents-functions' and `before-save-hook'. Make the defvar's for `before-save-hook' and `after-save-hook' into defopt's.

53530:eff208c6f20a

@c Emacs 19 feature
@defvar write-contents-functions
This works just like @code{write-file-functions}, but it is intended for
hooks that pertain to the contents of the file, as opposed to hooks that
pertain to where the file came from.  Such hooks are usually set up by
major modes, as buffer-local bindings for this variable.

This variable automatically becomes buffer-local whenever it is set;
switching to a new major mode always resets this variable.
@end defvar

@defvar before-save-hook
This normal hook runs before a buffer has been saved in its visited
file.  One use of this hook is for the Copyright package; it uses this
hook to make sure the file has the current year in the copyright
header.
@end defvar

@c Emacs 19 feature
@defvar after-save-hook
This normal hook runs after a buffer has been saved in its visited file.
One use of this hook is in Fast Lock mode; it uses this hook to save the
highlighting information in a cache file.
@end defvar

@defvar file-precious-flag
If this variable is non-@code{nil}, then @code{save-buffer} protects
against I/O errors while saving by writing the new file to a temporary
name instead of the name it is supposed to have, and then renaming it to

shown above; the details are crucial for proper behavior in the case of
multiple handlers, and for operations that have two file names that may
each have handlers.

@kindex safe-magic (@r{property})
Handlers that don't really do anything specal for actual access to the
file---such as the ones that implement completion of host names for
remote file names---should have a non-@code{nil} @code{safe-magic}
property.  For instance, Emacs normally ``protects'' directory names
it finds in @code{PATH} from becoming magic, if they look like magic
file names, by prefixing them with @samp{/:}.  But if the handler that

53531:5bd5de5e98c2

@c Emacs 19 feature
@defvar write-contents-functions
This works just like @code{write-file-functions}, but it is intended for
hooks that pertain to the contents of the file, as opposed to hooks that
pertain to where the file came from.  Such hooks are usually set up by
major modes, as buffer-local bindings for this variable.  If any of the
functions in this hook returns non-@code{nil}, @code{write-file-functions}
is not run.

This variable automatically becomes buffer-local whenever it is set;
switching to a new major mode always resets this variable, but
calling @code{set-visited-file-name} does not.
@end defvar

@defopt before-save-hook
This normal hook runs before a buffer is saved in its visited file,
regardless of whether that is done normally or by one of the hooks
described above.  One use of this hook is for the Copyright package;
it uses this hook to make sure the file has the current year in the
copyright header.
@end defopt

@c Emacs 19 feature
@defopt after-save-hook
This normal hook runs after a buffer has been saved in its visited file.
One use of this hook is in Fast Lock mode; it uses this hook to save the
highlighting information in a cache file.
@end defopt

@defvar file-precious-flag
If this variable is non-@code{nil}, then @code{save-buffer} protects
against I/O errors while saving by writing the new file to a temporary
name instead of the name it is supposed to have, and then renaming it to

shown above; the details are crucial for proper behavior in the case of
multiple handlers, and for operations that have two file names that may
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 non-@code{nil} @code{safe-magic}
property.  For instance, Emacs normally ``protects'' directory names
it finds in @code{PATH} from becoming magic, if they look like magic
file names, by prefixing them with @samp{/:}.  But if the handler that