GNU bug report logs - #52741
27.2; Doc string of `visual-line-mode'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 52741 in the body.
You can then email your comments to 52741 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: "bug-gnu-emacs <at> gnu.org" <bug-gnu-emacs <at> gnu.org>
Subject: 27.2; Doc string of `visual-line-mode'
Date: Wed, 22 Dec 2021 22:42:50 +0000

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)

Message #8 received at 52741 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 52741 <at> debbugs.gnu.org
Subject: Re: bug#52741: 27.2; Doc string of `visual-line-mode'
Date: Wed, 22 Dec 2021 23:45:54 +0100

Drew Adams <drew.adams <at> 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

Message #13 received at 52741 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: "52741 <at> debbugs.gnu.org" <52741 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#52741: 27.2; Doc string of `visual-line-mode'
Date: Wed, 22 Dec 2021 23:18:46 +0000

> 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.

Message #16 received at 52741 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 52741 <at> debbugs.gnu.org
Subject: Re: bug#52741: 27.2; Doc string of `visual-line-mode'
Date: Thu, 23 Dec 2021 23:13:18 -0500

[[[ 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)

Message #19 received at 52741 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: "rms <at> gnu.org" <rms <at> gnu.org>
Cc: "52741 <at> debbugs.gnu.org" <52741 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#52741: 27.2; Doc string of `visual-line-mode'
Date: Fri, 24 Dec 2021 05:32:52 +0000

> > 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").

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.