"Non-nil means" versus "On means" in docstrings

"Non-nil means" versus "On means" in docstrings

[Bill Wohler]

When running checkdoc, I get a "Flag variable doc strings should usually
start: Non-nil means" error on the following:

  (defcustom mh-compose-space-does-completion-flag nil
    "*On means \\<mh-letter-mode-map>\\[mh-letter-complete-or-space] does completion in message header."
    :type 'boolean
    :group 'mh-letter)

This might have been fine before the advent of customize, but now that
we have customize, we have opened our applications (such as MH-E) to
non-programmers who would have no idea what "Non-nil" means. When they
click on the customize button, they see "On" and "Off".

I would therefore propose, for the sake of usability, to modify
checkdoc-this-string-valid-engine so that it accepts "On means" as well
as "Non-nil means".

Index: checkdoc.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/emacs-lisp/checkdoc.el,v
retrieving revision 1.51
diff -u -u -r1.51 checkdoc.el
--- checkdoc.el	24 Sep 2005 13:43:59 -0000	1.51
+++ checkdoc.el	27 Oct 2005 22:22:37 -0000
@@ -1635,7 +1635,8 @@
 
 	     ;; If the variable has -flag in the name, make sure
 	     (if (and (string-match "-flag$" (car fp))
-		      (not (looking-at "\"\\*?Non-nil\\s-+means\\s-+")))
+		      (not (looking-at
+                            "\"\\*?\\(Non-nil\\|On\\)\\s-+means\\s-+")))
 		 (checkdoc-create-error
 		  "Flag variable doc strings should usually start: Non-nil means"
 		  s (marker-position e) t))

-- 
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.

Re: "Non-nil means" versus "On means" in docstrings

[Eli Zaretskii]

> Date: Thu, 27 Oct 2005 15:29:59 -0700
> From: Bill Wohler <wohler@newt.com>
> 
>  	     ;; If the variable has -flag in the name, make sure
>  	     (if (and (string-match "-flag$" (car fp))
> -		      (not (looking-at "\"\\*?Non-nil\\s-+means\\s-+")))
> +		      (not (looking-at
> +                            "\"\\*?\\(Non-nil\\|On\\)\\s-+means\\s-+")))
>  		 (checkdoc-create-error
>  		  "Flag variable doc strings should usually start: Non-nil means"
>  		  s (marker-position e) t))

I don't have a strong opinion about this, but IMHO if we allow "On" as
well as "Non-nil", the message displayed if none of them is used
should mention both possibilities.  You suggest to modify the code,
but not the message.

Re: "Non-nil means" versus "On means" in docstrings

[Bill Wohler]

Eli Zaretskii <eliz@gnu.org> wrote:

> > Date: Thu, 27 Oct 2005 15:29:59 -0700
> > From: Bill Wohler <wohler@newt.com>
> > 
> >  	     ;; If the variable has -flag in the name, make sure
> >  	     (if (and (string-match "-flag$" (car fp))
> > -		      (not (looking-at "\"\\*?Non-nil\\s-+means\\s-+")))
> > +		      (not (looking-at
> > +                            "\"\\*?\\(Non-nil\\|On\\)\\s-+means\\s-+")))
> >  		 (checkdoc-create-error
> >  		  "Flag variable doc strings should usually start: Non-nil means"
> >  		  s (marker-position e) t))
> 
> I don't have a strong opinion about this, but IMHO if we allow "On" as
> well as "Non-nil", the message displayed if none of them is used
> should mention both possibilities.  You suggest to modify the code,
> but not the message.

I would be happy to modify the message too.

-- 
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.

Re: "Non-nil means" versus "On means" in docstrings

[Bill Wohler]

Bill Wohler <wohler@newt.com> writes:

> Eli Zaretskii <eliz@gnu.org> wrote:
>
>> > Date: Thu, 27 Oct 2005 15:29:59 -0700
>> > From: Bill Wohler <wohler@newt.com>
>> > 
>> >  	     ;; If the variable has -flag in the name, make sure
>> >  	     (if (and (string-match "-flag$" (car fp))
>> > -		      (not (looking-at "\"\\*?Non-nil\\s-+means\\s-+")))
>> > +		      (not (looking-at
>> > +                            "\"\\*?\\(Non-nil\\|On\\)\\s-+means\\s-+")))
>> >  		 (checkdoc-create-error
>> >  		  "Flag variable doc strings should usually start: Non-nil means"
>> >  		  s (marker-position e) t))
>> 
>> I don't have a strong opinion about this, but IMHO if we allow "On" as
>> well as "Non-nil", the message displayed if none of them is used
>> should mention both possibilities.  You suggest to modify the code,
>> but not the message.
>
> I would be happy to modify the message too.

As well as (elisp) Documentation Tips.

-- 
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.

Re: "Non-nil means" versus "On means" in docstrings

[Richard M. Stallman]

    I would therefore propose, for the sake of usability, to modify
    checkdoc-this-string-valid-engine so that it accepts "On means" as well
    as "Non-nil means".

This is a real issue, but it opens a can of worms.  Your solution
makes it easier to understand in Custom and harder to understand at
the Lisp level.  I don't think that is a good solution; that is not
the way to go.

How to make things clear at both levels, as best as possible with
reasonable amounts of effort, calls for a lot of thought.  It should
not be rushed.  This is something people can think about now, but
think in terms of doing it after the release.

For the mean time, I don't want to change our conventions
or make a few exceptions to them.

Re: "Non-nil means" versus "On means" in docstrings

[Lennart Borgman]

Richard M. Stallman wrote:

>    I would therefore propose, for the sake of usability, to modify
>    checkdoc-this-string-valid-engine so that it accepts "On means" as well
>    as "Non-nil means".
>
>
>  
>
...

>How to make things clear at both levels, as best as possible with
>reasonable amounts of effort, calls for a lot of thought.  It should
>not be rushed.  This is something people can think about now, but
>think in terms of doing it after the release.
>  
>
One way of doing it might be to keep "non-nil" in the doc strings but 
make it a link to an explanation. Like it would have been done on a web 
page.

Re: "Non-nil means" versus "On means" in docstrings

[Richard M. Stallman]

    One way of doing it might be to keep "non-nil" in the doc strings but 
    make it a link to an explanation. Like it would have been done on a web 
    page.

That would definitely be an improvement, and maybe it would only
require changes in Custom, not in thousands of defcustoms.
So it is a candidate.

Let's see what other ideas people suggest.

Re: "Non-nil means" versus "On means" in docstrings

[Kim F. Storm]

"Richard M. Stallman" <rms@gnu.org> writes:

>     One way of doing it might be to keep "non-nil" in the doc strings but 
>     make it a link to an explanation. Like it would have been done on a web 
>     page.
>
> That would definitely be an improvement, and maybe it would only
> require changes in Custom, not in thousands of defcustoms.
> So it is a candidate.
>
> Let's see what other ideas people suggest.

A tooltip rather than a link perhaps?

Or custom could reformat the doc string to say "On" rather than non-nil.

But what about all those boolean variables which are not named -flag ?

This need a good design and perhaps quite some changes, so let it wait
until after the release.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: "Non-nil means" versus "On means" in docstrings

[Lennart Borgman]

Kim F. Storm wrote:

>>    One way of doing it might be to keep "non-nil" in the doc strings but 
>>    make it a link to an explanation. Like it would have been done on a web 
>>    page.
>>
>>    
>>
>A tooltip rather than a link perhaps?
>  
>

Too invisible in my opinion.

Re: "Non-nil means" versus "On means" in docstrings

[Bill Wohler]

"Richard M. Stallman" <rms@gnu.org> writes:

>     I would therefore propose, for the sake of usability, to modify
>     checkdoc-this-string-valid-engine so that it accepts "On means" as well
>     as "Non-nil means".
>
> This is a real issue, but it opens a can of worms.  Your solution
> makes it easier to understand in Custom and harder to understand at
> the Lisp level.  I don't think that is a good solution; that is not
> the way to go.
>
> How to make things clear at both levels, as best as possible with
> reasonable amounts of effort, calls for a lot of thought.  It should
> not be rushed.  This is something people can think about now, but
> think in terms of doing it after the release.

That sounds prudent. I'll stick with "non-nil means" in MH-E for now.

-- 
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.