Re: Documentation for custom-file - is not (load custom-file) needed?

[Luc Teirlinck]

Here are my suggested changes for `custom-file'.  Most of them are
documentation changes.

The patches keep the defcustom.  However, the user wanting to
customize it through Custom gets an emphatic warning in the Custom
buffer, that is nearly impossible to overlook, when he chooses "File"
from the "Value Menu".

Reasons for keeping the defcustom are:
 
1. Some people may be used to it, and even in its present form, it
   has some conveniences.
2. Custom is also an option _browser_, and even people who
   never use Custom to set options use it as a browser.
3. After the release we might try to implement ways of making 
   customizing `custom-file' through Custom even more convenient and
   less confusing.

There are two code changes.  The first is that `custom-file' will no
longer be automatically loaded after .emacs.  This means that the
behavior will stay as it was in the last released version, 21.3.  This
prevents problems with double loading, as well as potential confusion
when a user occasionally would use versions of Emacs earlier than 21.4.

The second code change is that the _function_ `custom-file' would do
exactly what its docstring says, namely:

        Return the file name for saving customizations.

It would no longer set the variable custom-file to that file name.
That is, if the variable custom-file is nil, the function would still
return "/home/USERNAME/.emacs", or such, but the variable custom-file
would remain nil instead of being set to "/home/USERNAME/.emacs".
There is no need for the function to set the variable.  It is only
used to pass the correct file name to `find-file-noselect'.  Setting the
variable confuses Custom when one customizes the variable and then
changes one's mind and chooses "Erase Customization".  Instead of
resetting it to nil: "Your Emacs init file", it resets it to
"File: /home/USERNAME/.emacs" and claims it was customized outside
Custom.  A _second_ "Erase Customization" then really gets back to:
"Your Emacs init file".  It is all very confusing.  The patch to
cus-edit.el below fixes the problem.

===File ~/startup.el-diff===================================
*** startup.el  30 Nov 2004 16:54:10 -0600      1.335
--- startup.el  21 Dec 2004 19:39:02 -0600      
***************
*** 863,874 ****
                              (sit-for 1))
                            (setq user-init-file source))))
  
-                     (when (stringp custom-file)
-                         (unless (assoc custom-file load-history)
-                           ;; If the .emacs file has set `custom-file' but 
hasn't
-                           ;; loaded the file yet, let's load it.
-                           (load custom-file t t)))
- 
                      (unless inhibit-default-init
                          (let ((inhibit-startup-message nil))
                            ;; Users are supposed to be told their rights.
--- 863,868 ----
============================================================

===File ~/cus-edit.el-diff==================================
*** cus-edit.el 14 Dec 2004 07:57:19 -0600      1.203
--- cus-edit.el 22 Dec 2004 17:42:42 -0600      
***************
*** 3699,3733 ****
  as specified by `user-init-file'.  If the value is not nil,
  it should be an absolute file name.
  
! To make this feature work, you'll need to put something in your
! init file to specify the value of `custom-file'.  Just
! customizing the variable won't suffice, because Emacs won't know
! which file to load unless the init file sets `custom-file'.
! 
! When you change this variable, look in the previous custom file
! \(usually your init file) for the forms `(custom-set-variables ...)'
! and `(custom-set-faces ...)', and copy them (whichever ones you find)
! to the new custom file.  This will preserve your existing customizations."
!   :type '(choice (const :tag "Your Emacs init file" nil) file)
    :group 'customize)
  
  (defun custom-file ()
    "Return the file name for saving customizations."
!   (setq custom-file
!       (or custom-file
!           (let ((user-init-file user-init-file)
!                 (default-init-file
!                   (if (eq system-type 'ms-dos) "~/_emacs" "~/.emacs")))
!             (when (null user-init-file)
!               (if (or (file-exists-p default-init-file)
!                       (and (eq system-type 'windows-nt)
!                            (file-exists-p "~/_emacs")))
!                   ;; Started with -q, i.e. the file containing
!                   ;; Custom settings hasn't been read.  Saving
!                   ;; settings there would overwrite other settings.
!                   (error "Saving settings from \"emacs -q\" would overwrite 
existing customizations"))
!               (setq user-init-file default-init-file))
!             user-init-file))))
  
  (defun custom-save-delete (symbol)
    "Visit `custom-file' and delete all calls to SYMBOL from it.
--- 3699,3755 ----
  as specified by `user-init-file'.  If the value is not nil,
  it should be an absolute file name.
  
! You can set this option through Custom, if you carefully read the
! last paragraph below.  However, usually it is simpler to write
! something like the following in your init file:
! 
! \(setq custom-file \"~/.emacs-custom.el\")
! \(load custom-file)
! 
! Note that both lines are necessary: the first line tells Custom to
! save all customizations in this file, but does not load it.
! 
! When you change this variable outside Custom, look in the
! previous custom file \(usually your init file) for the
! forms `(custom-set-variables ...)'  and `(custom-set-faces ...)',
! and copy them (whichever ones you find) to the new custom file.
! This will preserve your existing customizations.
! 
! If you save this option using Custom, Custom will write all
! currently saved customizations, including the new one for this
! option itself, into the file you specify, overwriting any
! `custom-set-variables' and `custom-set-faces' forms already
! present in that file.  It will not delete any customizations from
! the old custom file.  You should do that manually if that is what you
! want.  You also have to put something like `\(load \"CUSTOM-FILE\")
! in your init file, where CUSTOM-FILE is the actual name of the
! file.  Otherwise, Emacs will not load the file when it starts up,
! and hence will not set `custom-file' to that file either."
!   :type '(choice (const :tag "Your Emacs init file" nil)
!                (file :format "%t:%v%d"
!                      :doc
!                      "Please read entire docstring below before setting \
! this through Custom.
! Click om \"More\" \(or position point there and press RETURN)
! if only the first line of the docstring is shown."))
    :group 'customize)
  
  (defun custom-file ()
    "Return the file name for saving customizations."
!   (or custom-file
!       (let ((user-init-file user-init-file)
!           (default-init-file
!             (if (eq system-type 'ms-dos) "~/_emacs" "~/.emacs")))
!       (when (null user-init-file)
!         (if (or (file-exists-p default-init-file)
!                 (and (eq system-type 'windows-nt)
!                      (file-exists-p "~/_emacs")))
!             ;; Started with -q, i.e. the file containing
!             ;; Custom settings hasn't been read.  Saving
!             ;; settings there would overwrite other settings.
!             (error "Saving settings from \"emacs -q\" would overwrite 
existing customizations"))
!         (setq user-init-file default-init-file))
!       user-init-file)))
  
  (defun custom-save-delete (symbol)
    "Visit `custom-file' and delete all calls to SYMBOL from it.
============================================================

===File ~/custom.texi-diff==================================
*** custom.texi 08 Dec 2004 17:34:48 -0600      1.71
--- custom.texi 21 Dec 2004 20:13:09 -0600      
***************
*** 487,507 ****
    The customization buffer normally saves customizations in
  @file{~/.emacs}.  If you wish, you can save customizations in another
  file instead.  To make this work, your @file{~/.emacs} should set
! @code{custom-file} to the name of that file.  If you are using Emacs
! version 21.4 or later, Emacs loads the file right after your
! @file{.emacs} if you did not load it already.  In earlier versions,
! you have to load the file in your @file{~/emacs}.  If you customize
! @code{custom-file} through the @samp{Customize} interface, you still
! need to load it in your @file{.emacs}, but there is no need to set
! it.  For example:
  
  @example
! ;; @r{if not set through the @samp{Customize} interface:}
! (setq custom-file "~/.emacs-custom")
! 
! ;; @r{in Emacs versions before 21.4 or if set through}
! ;; @r{the @samp{Customize} interface.}
! (load "~/.emacs-custom")
  @end example
  
    You can also use @code{custom-file} to specify different
--- 487,497 ----
    The customization buffer normally saves customizations in
  @file{~/.emacs}.  If you wish, you can save customizations in another
  file instead.  To make this work, your @file{~/.emacs} should set
! @code{custom-file} to the name of that file and load it.  For example:
  
  @example
! (setq custom-file "~/.emacs-custom.el")
! (load custom-file)
  @end example
  
    You can also use @code{custom-file} to specify different
============================================================