Re: Defcustom write-file-functions and write-contents-functions?

[Luc Teirlinck]

Per Abrahamsen wrote:

   Luc Teirlinck <address@hidden> writes:

   > Do you really want to make those two functions customizable through
   > Custom?

   If not, it would probably be a good idea to add a comment to the
   defvar stating why they are not declared with decustom.

I propose to add some clarifications to the docstrings and to
`(elisp)Saving Buffers'.  I could install these, if desired.

===File ~/files-diff========================================
*** files.el.~1.675.~   Mon Jan  5 12:45:52 2004
--- files.el    Tue Jan  6 19:49:22 2004
***************
*** 375,381 ****
  the visited file name with \\[set-visited-file-name], but not when you
  change the major mode.
  
! See also `write-contents-functions'.")
  (put 'write-file-functions 'permanent-local t)
  (defvaralias 'write-file-hooks 'write-file-functions)
  (make-obsolete-variable 'write-file-hooks 'write-file-functions "21.4")
--- 375,386 ----
  the visited file name with \\[set-visited-file-name], but not when you
  change the major mode.
  
! This hook is not run if any of the functions in
! `write-contents-functions' returns non-nil.  Both hooks pertain
! to how to save a buffer to file, for instance, choosing a suitable
! coding system and setting mode bits.  (See Info
! node `(elisp)Saving Buffers'.)  To perform various checks or
! updates before the buffer is saved, use `before-save-hook' .")
  (put 'write-file-functions 'permanent-local t)
  (defvaralias 'write-file-hooks 'write-file-functions)
  (make-obsolete-variable 'write-file-hooks 'write-file-functions "21.4")
***************
*** 395,401 ****
  `set-visited-file-name' does not clear this variable; but changing the
  major mode does clear it.
  
! See also `write-file-functions'.")
  (make-variable-buffer-local 'write-contents-functions)
  (defvaralias 'write-contents-hooks 'write-contents-functions)
  (make-obsolete-variable 'write-contents-hooks 'write-contents-functions 
"21.4")
--- 400,410 ----
  `set-visited-file-name' does not clear this variable; but changing the
  major mode does clear it.
  
! For hooks that _do_ pertain to the particular visited file, use
! `write-file-functions'.  Both this variable and
! `write-file-functions' relate to how a buffer is saved to file.
! To perform various checks or updates before the buffer is saved,
! use `before-save-hook'.")
  (make-variable-buffer-local 'write-contents-functions)
  (defvaralias 'write-contents-hooks 'write-contents-functions)
  (make-obsolete-variable 'write-contents-hooks 'write-contents-functions 
"21.4")
============================================================

===File ~/files.texi-diff===================================
*** files.texi.~1.60.~  Mon Jan  5 12:46:02 2004
--- files.texi  Tue Jan  6 19:45:28 2004
***************
*** 404,420 ****
  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
--- 404,424 ----
  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 address@hidden, @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
  
  @defvar 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 defvar
  
  @c Emacs 19 feature
============================================================