RE: scroll-down with pixel transition

[Drew Adams <drew.adams@oracle.com>]

> >> Our convention is to end user option names in '-flag', when they
> >> are for users to set.  Let's document that, if it isn't already.

+1

Except that the criterion should not be "when they are for
users to set".  All user options are for users to set.

Perhaps you didn't mean that, but you meant only names of
Boolean options?  (Your later mention of "t-or-nil" suggests
that.)

> > It is not currently documented in code conventions.
> 
> I think it used to be there, but I demoted it to:
> 
>     @item @dots{}-flag
>     The value is significant only as to whether it is @code{nil} or not.
>     Since such variables often end up acquiring more values over time,
>     this convention is not strongly recommended.

That's not a strong reason, IMO.  Lots of things change over
time, and if we want helpful names then we update the names
as needed, accordingly.

Yes, any name is a stake in the sand, and change can erode its
relevance.  But that's not a reason not to use helpful names.
Otherwise, we'd always use names that have no special meaning
(`x', `y', 'z'), to ensure maximum space for possible changes
in meaning.

I understand completely the problem of having a Boolean
option `foo-flag' evolve to an option where certain non-nil
values have special meaning (it is no longer strictly Boolean,
or even perhaps vaguely Boolean).  That's life.  A name change
at that point lets users know about the behavior change.

And in some cases a name change is not needed - when, for
example, all of the non-nil behaviors have a major behavior in
common, and that behavior is the main raison d'etre for the
option.  IOW, if it is still essentially a Boolean, but there
are some additional behavior differences, we might want to
keep the suffix `-flag'.

It's a judgment call.  Here's an example - you might argue
whether `-flag' is appropriate here, but the point is that
non-nil means use WYSIWYG display and nil does not.

(Evolution was not involved here, in fact - it was like
this at the outset.  But it could have evolved to this
from a simple t/nil choice.)

(defcustom icicle-WYSIWYG-Completions-flag "MMMM"
  "*Non-nil means show candidates in `*Completions*' using WYSIWYG.
...the particular non-nil value determines the appearance:
* If t, the candidate displays its meaning: WYSIWYG.
* If a string, the string is propertized and then appended to the
  candidate,  to serve as a color swatch."
  :group 'Icicles-Completions-Display
  :type '(choice
          (string
           :tag "Show candidate plus a WYSIWYG swatch with text..."
           :value "MMMM")
          (const
           :tag "Show candidate itself using WYSIWYG"
           t)
          (const
           :tag "Show candidate as is, with no text properties"
           nil)))

An alternative to such a naming convention, though it too
is imperfect, is to use a test - something like this:

(defun custom-type (variable)
  (and (custom-variable-p variable)
       (get variable 'custom-type)))

In my code (Icicles), there is a command that lets you
toggle Boolean options.  By default, the only options you
can do this to are those whose `custom-type' is `boolean'.
But with a prefix argument you can also toggle options
that are effectively Boolean, such as the one above.

(`nil' is always toggled to `t' by this command, but there
are other commands that cycle specific options among the
possible values or that remember the last non-nil value
and toggle `nil' back to it.)

The point is that in Emacs "Boolean", and so `-flag', can
mean something less strict than `t' vs `nil', and it can
help users if we provide easy ways to use more or less
strict interpretation - au choix - of whether a variable
is Boolean.

> In my experience, using FOO instead of FOO-flag is a better choice.

Does this boil down to the reason given in the doc (above)
that you wrote when you made the policy change?  Or is
there some additional reason?

> Also, many boolean config variables can be introduced as minor
> modes (in which case their name should end in "-mode").

Clearly that's not a relevant argument against the
convention, since `*-mode' minor-mode variables are also
necessarily Boolean.  On the contrary: `*-flag' vs `*-mode'
makes clear that the former is not associated with a minor mode.