linum-mode docstring is unclear

linum-mode docstring is unclear

[John Shahid]

Hey all,

I think the linum-mode docstring is unclear about when the mode is
turned on when called from Lisp. According to the docstring:

  "....  If called from Lisp, enable the mode if ARG is omitted or nil."

This isn't true. In fact, passing any value other than 0 will turn on
the mode. Furthermore, the docstring doesn't mention that passing
'toggle will toggle the state of the mode. WDYT, is that something that
can be/need clarification ?

I was thinking about borrowing the following from define-minor-mode:

  "When called from Lisp, the mode command toggles the mode if the
  argument is ‘toggle’, disables the mode if the argument is a
  non-positive integer, and enables the mode otherwise (including
  if the argument is omitted or nil or a positive integer)."

- js

Re: linum-mode docstring is unclear

[Emanuel Berg]

John Shahid wrote:

> I think the linum-mode docstring is unclear
> about when the mode is turned on when called
> from Lisp. According to the docstring:
>
>   ".... If called from Lisp, enable the mode
> if ARG is omitted or nil."
>
> This isn't true. In fact, passing any value
> other than 0 will turn on the mode.
> Furthermore, the docstring doesn't mention
> that passing 'toggle will toggle the state of
> the mode. WDYT, is that something that can
> be/need clarification ?

Well, obviously :)

I wonder if this is a general problem/phrasing
that appears more than once?

-- 
underground experts united
http://user.it.uu.se/~embe8573

Re: linum-mode docstring is unclear

[John Shahid]

I guess any mode that uses define-minor-mode is susceptible to this kind
of problem. That said, I'm not aware about other modes with similar
phrasing issues. I also sent a patch to fix linum-mode docstring to
bug-gnu-emacs@gnu.org.

cheers,

-js

Emanuel Berg <moasen@zoho.com> writes:

> John Shahid wrote:
>
>> I think the linum-mode docstring is unclear
>> about when the mode is turned on when called
>> from Lisp. According to the docstring:
>>
>>   ".... If called from Lisp, enable the mode
>> if ARG is omitted or nil."
>>
>> This isn't true. In fact, passing any value
>> other than 0 will turn on the mode.
>> Furthermore, the docstring doesn't mention
>> that passing 'toggle will toggle the state of
>> the mode. WDYT, is that something that can
>> be/need clarification ?
>
> Well, obviously :)
>
> I wonder if this is a general problem/phrasing
> that appears more than once?

Re: linum-mode docstring is unclear

[Emanuel Berg]

John Shahid wrote:

> I guess any mode that uses define-minor-mode
> is susceptible to this kind of problem.
> That said, I'm not aware about other modes
> with similar phrasing issues. I also sent
> a patch to fix linum-mode docstring to
> bug-gnu-emacs@gnu.org

Good work!

-- 
underground experts united
http://user.it.uu.se/~embe8573