Re: Further problem with recent changes to custom-magic-alist.

[Luc Teirlinck]

Lennart Borgman wrote:

   Put a link to an Info page with information about where the saving is done
   in the customize buffer.

I agree.  Moreover, other people have asked for a link explaining
`custom-file'.

I enclose a patch which implements this and also makes the states of
options more recognizable, by using messages starting with a
capitalized keyword.  After installing the patch in my own private
Emacs, I found that it indeed made it a lot easier for me to quickly
recognize states.  It goes part of the way in the direction of a
change suggested by Drew.  I could install in CVS, if desired.

Motivation for new link to Emacs manual node on `custom-file':

I believe that more people use `custom-file' than Richard believes.
There are two unrelated reasons to use it.  The first is because
trying to use the same file (.emacs) for different Emacs versions might
not work because of incompatibilities.  (That is why I _need_ to have
several Custom files.)  The second is because people do not like two
huge blurbs to be written in their .emacs.

Putting the fact that saving writes into `custom-file' in the State
message does not work very well, because there is no place there to do
it appropriately and because it is told after the fact.  If people did
not like Custom to write into their .emacs, it is already done.

The patch below puts the info on top of the Custom buffer, where
people can see it _before_ they save.  It puts in a link to the node
in the Emacs manual explaining `custom-file', as people have
requested.  It is much shorter than my previous similar proposal.  It
adds only one line, containing the new link.

Motivation for message style change:

   I would prefer something like

      You've set and saved this %c.

I believe that we should shorten the messages as much as possible and
put one capitalized keyword in front, allowing people who already know
the rest of the text by heart to quickly recognize the State.

The State message would become:

SAVED, but not set.

If deemed _really_ necessary, there would be place for things like:

SAVED, but not set.  Code written into `custom-file'.

Or, less accurately, if custom-file is set:

SAVED, but not set.  Code written in your init file.

However, the patch below already puts much more helpful info on top of
the Custom buffer.  I see no reason to repeat it for every single saved
option.

The capitalized keywords I used are essentially the same as the
internal Custom symbols, except that I replaced "MODIFIED" with
"EDITED", which seemed clearer.  I replaced "ROGUE" with "STRAY",
because otherwise there might be confusion with `M-x customize-rogue',
which is actually meant to produce a buffer containing all CHANGED
(outside customize) options.  The "ROGUE"-"STRAY" issue is not very
relevant, because such options normally never occur in Custom buffers.
They can only "stray" into them by very badly written code.

No info present in the current messages was lost (except for the
writing into .emacs, which went to the top of the buffer.)  Space was
saved by using a more compacted style, not by deleting info.  For the
"CHANGED" state, very essential info was added.

===File ~/cus-edit-latest-diff==============================
*** cus-edit.el 22 Feb 2005 16:55:41 -0600      1.213
--- cus-edit.el 24 Feb 2005 13:59:31 -0600      
***************
*** 1377,1392 ****
        (widget-insert (format ".
  %s show active fields; type RET or click mouse-1
  on an active field to invoke its action.  Editing an option value
! changes the text in the buffer; invoke the State button and
! choose the Set operation to set the option value.
! Invoke " (if custom-raised-buttons
!            "`Raised' buttons"
!            "Square brackets")))
        (widget-create 'info-link
                       :tag "Help"
                       :help-echo "Read the online help."
                       "(emacs)Easy Customization")
!       (widget-insert " for more information.\n\n")
        (message "Creating customization buttons...")
        (widget-insert "Operate on everything in this buffer:\n "))
      (widget-insert " "))
--- 1377,1399 ----
        (widget-insert (format ".
  %s show active fields; type RET or click mouse-1
  on an active field to invoke its action.  Editing an option value
! changes only the text in the buffer.  Invoke the State button to set or
! save the option value.  Saving an option normally edits your init file.
! Invoke "
!                              (if custom-raised-buttons
!                                  "`Raised' buttons"
!                                "Square brackets")))
!       (widget-create 'info-link
!                      :tag "Custom file"
!                      "(emacs)Saving Customizations")
!       (widget-insert
!        " for information on how to save in a different file.
! Invoke ")
        (widget-create 'info-link
                       :tag "Help"
                       :help-echo "Read the online help."
                       "(emacs)Easy Customization")
!       (widget-insert " for general information.\n\n")
        (message "Creating customization buttons...")
        (widget-insert "Operate on everything in this buffer:\n "))
      (widget-insert " "))
***************
*** 1665,1695 ****
  
  (defconst custom-magic-alist
    '((nil "#" underline "\
! uninitialized, you should not see this.")
      (unknown "?" italic "\
! unknown, you should not see this.")
      (hidden "-" default "\
! hidden, invoke \"Show\" in the previous line to show." "\
  group now hidden, invoke \"Show\", above, to show contents.")
      (invalid "x" custom-invalid-face "\
! the value displayed for this %c is invalid and cannot be set.")
      (modified "*" custom-modified-face "\
! you have edited the value as text, but you have not set the %c." "\
  you have edited something in this group, but not set anything yet.")
      (set "+" custom-set-face "\
! you have set this %c, but not saved it for future sessions." "\
  you have set something in this group, but not saved anything yet.")
      (changed ":" custom-changed-face "\
! this %c has been changed outside the customize buffer." "\
  something in this group has been changed outside customize.")
      (saved "!" custom-saved-face "\
! You have set this %c and saved it through Customize in your init file." "\
  something in this group has been set and saved.")
      (rogue "@" custom-rogue-face "\
! this %c has not been changed with customize." "\
  something in this group is not prepared for customization.")
      (standard " " nil "\
! this %c is unchanged from its standard setting." "\
  visible group members are all at standard settings."))
    "Alist of customize option states.
  Each entry is of the form (STATE MAGIC FACE ITEM-DESC [ GROUP-DESC ]), where
--- 1672,1702 ----
  
  (defconst custom-magic-alist
    '((nil "#" underline "\
! UNINITIALIZED, you should not see this.")
      (unknown "?" italic "\
! UNKNOWN, you should not see this.")
      (hidden "-" default "\
! HIDDEN, invoke \"Show\" in the previous line to show." "\
  group now hidden, invoke \"Show\", above, to show contents.")
      (invalid "x" custom-invalid-face "\
! INVALID, the displayed value cannot be set.")
      (modified "*" custom-modified-face "\
! EDITED, but not set." "\
  you have edited something in this group, but not set anything yet.")
      (set "+" custom-set-face "\
! SET, but not saved." "\
  you have set something in this group, but not saved anything yet.")
      (changed ":" custom-changed-face "\
! CHANGED outside Customize; operating on it here may be unreliable." "\
  something in this group has been changed outside customize.")
      (saved "!" custom-saved-face "\
! SAVED and set." "\
  something in this group has been set and saved.")
      (rogue "@" custom-rogue-face "\
! STRAY, you should not see this." "\
  something in this group is not prepared for customization.")
      (standard " " nil "\
! STANDARD." "\
  visible group members are all at standard settings."))
    "Alist of customize option states.
  Each entry is of the form (STATE MAGIC FACE ITEM-DESC [ GROUP-DESC ]), where
***************
*** 1709,1715 ****
  `set'
     This item has been set but not saved.
  `changed'
!    The current value of this item has been changed temporarily.
  `saved'
     This item is marked for saving.
  `rogue'
--- 1716,1722 ----
  `set'
     This item has been set but not saved.
  `changed'
!    The current value of this item has been changed outside Customize.
  `saved'
     This item is marked for saving.
  `rogue'
============================================================