bug#52741: 27.2; Doc string of `visual-line-mode'

bug#52741: 27.2; Doc string of `visual-line-mode'

[Drew Adams]

This part of the doc isn't helpful:

 If called interactively, enable Visual-Line mode if ARG is positive,
 and disable it if ARG is zero or negative.

What on earth is ARG, for interactive use?  The description of
interactive use should talk about things like a prefix arg, not about
unexplained things like ARG.  How will a user know how to pass argument
ARG interactively?

(Once again, minor-mode doc problems.  This seems to be a never-ending
cleanup.)

In GNU Emacs 27.2 (build 1, x86_64-w64-mingw32)
 of 2021-03-26 built on CIRROCUMULUS
Repository revision: deef5efafb70f4b171265b896505b92b6eef24e6
Repository branch: HEAD
Windowing system distributor 'Microsoft Corp.', version 10.0.19042
System Description: Microsoft Windows 10 Pro (v10.0.2009.19042.1348)

bug#52741: 27.2; Doc string of `visual-line-mode'

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> This part of the doc isn't helpful:
>
>  If called interactively, enable Visual-Line mode if ARG is positive,
>  and disable it if ARG is zero or negative.
>
> What on earth is ARG, for interactive use?  The description of
> interactive use should talk about things like a prefix arg, not about
> unexplained things like ARG.  How will a user know how to pass argument
> ARG interactively?
>
> (Once again, minor-mode doc problems.  This seems to be a never-ending
> cleanup.)

I think you've reported this a couple of times before?  And it's fixed
in Emacs 28:

---
This is a minor mode.  If called interactively, toggle the
‘Visual-Line mode’ mode.  If the prefix argument is positive, enable
the mode, and if it is zero or negative, disable the mode.

If called from Lisp, toggle the mode if ARG is ‘toggle’.  Enable the
mode if ARG is nil, omitted, or is a positive number.  Disable the
mode if ARG is a negative number.
---

So I'm closing this bug report.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#52741: [External] : Re: bug#52741: 27.2; Doc string of `visual-line-mode'

[Drew Adams]

> I think you've reported this a couple of times before?  And it's fixed
> in Emacs 28:

Ah, yes, you're right; sorry.

I and others (13926, 25428, 25434, 25435).  
There were multiple problems with that doc string.

bug#52741: 27.2; Doc string of `visual-line-mode'

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > What on earth is ARG, for interactive use?  The description of
  > interactive use should talk about things like a prefix arg, not about
  > unexplained things like ARG.  How will a user know how to pass argument
  > ARG interactively?

It's standard -- every user should know how to give a command a numeric arg.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

bug#52741: [External] : Re: bug#52741: 27.2; Doc string of `visual-line-mode'

[Drew Adams]

> > What on earth is ARG, for interactive use?  The description of
> > interactive use should talk about things like a prefix arg, not about
> > unexplained things like ARG.  How will a user know how to pass argument
> > ARG interactively?
> 
> It's standard -- every user should know how to give a command a numeric arg.

Sure.  But the doc string normally says, "With a
prefix arg...", or "A numeric prefix arg means...".
or some such.

It doesn't talk about an undescribed ARG in the
context of interactive use.  If it talks about ARG
in that context, it tells you it's the prefix arg.

This is the relevant part of the doc string in
question, for Emacs 27.2, which is what I reported on:

 If called interactively, enable Visual-Line mode if
 ARG is positive, and disable it if ARG is zero or
 negative.

What's missing there is "prefix" or (preferably)
"numeric prefix", before "ARG" (or "arg").