bug#22683: 25.1.50; auto-composition-mode

bug#22683: 25.1.50; auto-composition-mode

[Richard Stallman]

The doc string of auto-composition-mode says:

======================================================================
With a prefix argument ARG, enable Auto Composition mode if ARG
is positive, and disable it otherwise.  If called from Lisp,
enable the mode if ARG is omitted or nil.
======================================================================

The doc string suggests (but does not clearly say) that ARG present
and non-nil disables the mode.

In fact, using M-:, (auto-composition-mode t) enables the mode.
(auto-composition-mode 0) disables the mode.
(auto-composition-mode 1) enables it.

It seems this calls for a doc string fix, or a code fix.

Maybe this command is generated by a macro; the macro may
need fixing too.




In GNU Emacs 25.1.50.1 (i686-pc-linux-gnu, GTK+ Version 2.24.23)
 of 2015-12-25
Repository revision: 608b15d59d08ff7054fdc5458d1d2ae54dd043e2
System Description:	Trisquel GNU/Linux 7.0, Belenos

Configured using:
 'configure 'CFLAGS=-g -O0''

Configured features:
XPM JPEG TIFF GIF PNG RSVG SOUND GPM DBUS GCONF GSETTINGS NOTIFY
LIBXML2 FREETYPE M17N_FLT LIBOTF XFT ZLIB TOOLKIT_SCROLL_BARS GTK2 X11

Important settings:
  value of $LANG: en_US.UTF-8
  locale-coding-system: utf-8-unix

Major mode: Emacs-Lisp

Minor modes in effect:
  diff-auto-refine-mode: t
  shell-dirtrack-mode: t
  gpm-mouse-mode: t
  tooltip-mode: t
  global-eldoc-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  line-number-mode: t
  transient-mark-mode: t
  abbrev-mode: t

Recent messages:
Type C-x 1 to delete the help window.
Mark activated
nil
Making completion list...

Mark set
t

Global-Auto-Composition mode disabled in current buffer


Load-path shadows:
None found.

Features:
(shadow emacsbug eieio-opt speedbar sb-image ezimage dframe find-func
compare-w thingatpt xref project parse-time vc-cvs sgml-mode cc-mode
cc-fonts cc-guess cc-menus cc-cmds cc-styles cc-align cc-engine
cc-vars cc-defs diff-mode easy-mmode diff pp wid-edit descr-text
texinfo jka-compr battery dired-aux novice two-column kmacro
iso-transl cal-move cal-menu calendar cal-loaddefs epa-mail quail
dabbrev character-fold misearch multi-isearch shell pcomplete grep
compile comint ansi-color ring ispell rmailout rmailkwd epa derived
epg rmailsum qp mailalias url-util shr dom subr-x browse-url rmailmm
message sendmail format-spec rfc822 mml mml-sec mm-decode mm-bodies
mm-encode mailabbrev gmm-utils mailheader mail-parse rfc2231 rmail
rmail-loaddefs rfc2047 rfc2045 ietf-drums mail-utils dired
dired-loaddefs seq t-mouse view paren cus-start cus-load advice
finder-inf package epg-config url-handlers url-parse auth-source
cl-seq eieio byte-opt bytecomp byte-compile cl-extra cconv eieio-core
cl-macs gv eieio-loaddefs gnus-util time-date mm-util help-fns
help-mode easymenu cl-loaddefs pcase cl-lib mail-prsvr password-cache
url-vars mule-util tooltip eldoc electric uniquify ediff-hook vc-hooks
lisp-float-type mwheel x-win term/common-win x-dnd tool-bar dnd
fontset image regexp-opt fringe tabulated-list newcomment elisp-mode
lisp-mode prog-mode register page menu-bar rfn-eshadow timer select
scroll-bar mouse jit-lock font-lock syntax facemenu font-core frame
cl-generic cham georgian utf-8-lang misc-lang vietnamese tibetan thai
tai-viet lao korean japanese eucjp-ms cp51932 hebrew greek romanian
slovak czech european ethiopic indian cyrillic chinese charscript
case-table epa-hook jka-cmpr-hook help simple abbrev obarray
minibuffer cl-preloaded nadvice loaddefs button faces cus-face
macroexp files text-properties overlay sha1 md5 base64 format env
code-pages mule custom widget hashtable-print-readable backquote
dbusbind inotify dynamic-setting system-font-setting
font-render-setting move-toolbar gtk x-toolkit x multi-tty
make-network-process emacs)

Memory information:
((conses 8 542567 115415)
 (symbols 24 40134 5)
 (miscs 20 12330 4972)
 (strings 16 69462 28818)
 (string-bytes 1 2197955)
 (vectors 8 35255)
 (vector-slots 4 1594101 32882)
 (floats 8 333 700)
 (intervals 28 108039 6936)
 (buffers 520 408)
 (heap 1024 34295 2078))
[[[ 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. ]]]


-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.

bug#22683: 25.1.50; auto-composition-mode

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Mon, 15 Feb 2016 12:46:07 -0500
> 
> 
> The doc string of auto-composition-mode says:
> 
> ======================================================================
> With a prefix argument ARG, enable Auto Composition mode if ARG
> is positive, and disable it otherwise.  If called from Lisp,
> enable the mode if ARG is omitted or nil.
> ======================================================================
> 
> The doc string suggests (but does not clearly say) that ARG present
> and non-nil disables the mode.
> 
> In fact, using M-:, (auto-composition-mode t) enables the mode.
> (auto-composition-mode 0) disables the mode.
> (auto-composition-mode 1) enables it.
> 
> It seems this calls for a doc string fix, or a code fix.

We say these things for every mode, so this issue is not specific to
this particular mode.

I believe the fix is to add "also" to the last sentence (as in "also
enable the mode if ..."), but is this really so serious to require
changes in hundreds of doc strings?

bug#22683: 25.1.50; auto-composition-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. ]]]

The words

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

seem to mean, "If the arg is omitted or nil, enable the mode;
otherwise disable it."  I was surprised by the actual behavior.

Does that text come from a macro?


-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.

bug#22683: 25.1.50; auto-composition-mode

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> CC: 22683@debbugs.gnu.org
> Date: Tue, 16 Feb 2016 17:47:07 -0500
> 
> The words
> 
>   >   If called from Lisp,
>   > > enable the mode if ARG is omitted or nil.
> 
> seem to mean, "If the arg is omitted or nil, enable the mode;
> otherwise disable it."  I was surprised by the actual behavior.

Yes, the text is ambiguous.

> Does that text come from a macro?

No, it comes from the call to define-minor-mode.  Problem is, this is
a standard wording we have in more than 200 modes in Emacs.  If we
want to change that, we need to change all of them.

bug#22683: 25.1.50; auto-composition-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. ]]]

  > No, it comes from the call to define-minor-mode.  Problem is, this is
  > a standard wording we have in more than 200 modes in Emacs.  If we
  > want to change that, we need to change all of them.

It is not a herculean labor to change 200 similar strings.

What are all the argument values that enable these modes?

-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.

bug#22683: 25.1.50; auto-composition-mode

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> CC: 22683@debbugs.gnu.org
> Date: Fri, 19 Feb 2016 07:34:28 -0500
> 
> What are all the argument values that enable these modes?

Non-positive disables, 'toggle' toggles, anything else enables.

bug#22683: 25.1.50; auto-composition-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. ]]]

  > Non-positive disables, 'toggle' toggles, anything else enables.

How about using this doc string text?  Is this accurate and clear?

When calling from Lisp, 0 or a negative number disables the mode,
'toggle' toggles it, any other argument enables it.

-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.

bug#22683: 25.1.50; auto-composition-mode

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> CC: 22683@debbugs.gnu.org
> Date: Sat, 20 Feb 2016 09:28:53 -0500
> 
>   > Non-positive disables, 'toggle' toggles, anything else enables.
> 
> How about using this doc string text?  Is this accurate and clear?
> 
> When calling from Lisp, 0 or a negative number disables the mode,
> 'toggle' toggles it, any other argument enables it.

It's accurate and clear to me, yes.

bug#22683: 25.1.50; auto-composition-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. ]]]

  > > When calling from Lisp, 0 or a negative number disables the mode,
  > > 'toggle' toggles it, any other argument enables it.

  > It's accurate and clear to me, yes.

Does anyone have a criicism?
-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.

bug#22683: 25.1.50; auto-composition-mode

[Stefan Kangas]

Richard Stallman <rms@gnu.org> writes:

> The doc string of auto-composition-mode says:
>
> ======================================================================
> With a prefix argument ARG, enable Auto Composition mode if ARG
> is positive, and disable it otherwise.  If called from Lisp,
> enable the mode if ARG is omitted or nil.
> ======================================================================
>
> The doc string suggests (but does not clearly say) that ARG present
> and non-nil disables the mode.
>
> In fact, using M-:, (auto-composition-mode t) enables the mode.
> (auto-composition-mode 0) disables the mode.
> (auto-composition-mode 1) enables it.
>
> It seems this calls for a doc string fix, or a code fix.

This text was recently changed in response to Bug#49843:

    https://debbugs.gnu.org/cgi/bugreport.cgi?bug=49843

The text now says now says:

,----
| This is a minor mode.  If called interactively, toggle the
| ‘Auto-Composition 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.
`----

Is that sufficiently clear?

It doesn't say what happens if ARG is zero, so perhaps the last sentence
above should be amended to say "negative number or zero".

bug#22683: 25.1.50; auto-composition-mode

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> It doesn't say what happens if ARG is zero, so perhaps the last sentence
> above should be amended to say "negative number or zero".

I think we wanted to discourage people from using zero here, which is
why that's not documented.  (Since it historically leads to confusion, I
think.)

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

bug#22683: [External] : bug#22683: 25.1.50; auto-composition-mode

[Drew Adams]

> I think we wanted to discourage people from using zero here,

Why would we want to do that?

> which is why that's not documented.  (Since it
> historically leads to confusion, I think.)

What kind of confusion?
___

FWIW, I agree with what Richard and Eli said.
Simple and clear, I think.
___

Whatever's decided, it's quite important to get
this right - clear text.  Zillions of minor modes
get defined, and their generated doc strings have
long been problematic.

bug#22683: 25.1.50; auto-composition-mode

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Stefan Kangas <stefan@marxist.se> writes:
>
>> It doesn't say what happens if ARG is zero, so perhaps the last sentence
>> above should be amended to say "negative number or zero".
>
> I think we wanted to discourage people from using zero here, which is
> why that's not documented.  (Since it historically leads to confusion, I
> think.)

Fine by me.

So should we close this bug report, or is there more to do here?

bug#22683: 25.1.50; auto-composition-mode

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> So should we close this bug report, or is there more to do here?

Skimming the bug report, it seems like everything's been covered, so
please go ahead and close it.

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

bug#22683: 25.1.50; auto-composition-mode

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Stefan Kangas <stefan@marxist.se> writes:
>
>> So should we close this bug report, or is there more to do here?
>
> Skimming the bug report, it seems like everything's been covered, so
> please go ahead and close it.

Done.

bug#22683: 25.1.50; auto-composition-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. ]]]

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

  > Is that sufficiently clear?

Yes, but

  > It doesn't say what happens if ARG is zero, so perhaps the last sentence
  > above should be amended to say "negative number or zero".

I think it should not leave zero an undocumented mystery.  If we want
to discourage it (though I don't follow why), let's say "Don't use
zero as argument."  Otherwise, let's say what zero means as argument.

-- 
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#22683: 25.1.50; auto-composition-mode

[Stefan Kangas]

Richard Stallman <rms@gnu.org> writes:

>   > Is that sufficiently clear?
>
> Yes, but
>
>   > It doesn't say what happens if ARG is zero, so perhaps the last sentence
>   > above should be amended to say "negative number or zero".
>
> I think it should not leave zero an undocumented mystery.  If we want
> to discourage it (though I don't follow why), let's say "Don't use
> zero as argument."  Otherwise, let's say what zero means as argument.

That makes sense to me.

I have no opinion on whether or not we should allow it, so I'll leave it
to someone else to decide what to do here.

bug#22683: 25.1.50; auto-composition-mode

[Rudolf Adamkovič via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Stefan Kangas <stefan@marxist.se> writes:

> It doesn't say what happens if ARG is zero, so perhaps the last 
> sentence above should be amended to say "negative number or 
> zero". 

By the law of trichotomy, every real number is either positive, 
negative, or zero. Thus, if a real number is not positive, it must 
be either negative or zero. It follows that it suffices to say:

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

Clear and precise.

R+

-- 
Programming reliably --- must be an activity of an undeniably 
mathematical nature [...] You see, mathematics is about thinking, 
and doing mathematics is always trying to think as well as 
possible. -- Edsger W. Dijkstra (1981)  Rudolf Adamkovič 
<salutis@me.com> Studenohorská 25 84103 Bratislava Slovakia 
[he/him]

bug#22683: 25.1.50; auto-composition-mode

[Eli Zaretskii]

> Cc: Lars Ingebrigtsen <larsi@gnus.org>, 22683@debbugs.gnu.org
> Date: Sun, 26 Sep 2021 22:27:55 +0200
> From:  Rudolf Adamkovič via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> By the law of trichotomy, every real number is either positive, 
> negative, or zero. Thus, if a real number is not positive, it must 
> be either negative or zero. It follows that it suffices to say:
> 
> "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 otherwise."
> 
> Clear and precise.

Thanks.  We don't always expect our users to be proficient in
theoretical logics.  So sometimes we prefer to make things clear even
for those who aren't.

bug#22683: 25.1.50; auto-composition-mode

[Rudolf Adamkovič via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Eli Zaretskii <eliz@gnu.org> writes:

> We don't always expect our users to be proficient in theoretical 
> logics.

Interesting. From my experience, young children in elementary 
school can follow the logic behind "if positive, … otherwise …" A 
plain, well-placed "otherwise" simplifies the involved "if 
positive … if negative or zero …" statement, no? Either way, I 
agree with RMS that we should account for the entire set of 
integers with perfect clarity, one way or the other.

BTW, other modes in Emacs have the same problem. From 
"global-visual-line-mode" help:

> Enable the mode if ARG is nil, omitted, or is a positive number. 
> Disable the mode if ARG is a negative number.

R+

-- 
Programming reliably --- must be an activity of an undeniably 
mathematical nature [...] You see, mathematics is about thinking, 
and doing mathematics is always trying to think as well as 
possible. -- Edsger W. Dijkstra (1981)  Rudolf Adamkovič 
<salutis@me.com> Studenohorská 25 84103 Bratislava Slovakia 
[he/him]

bug#22683: 25.1.50; auto-composition-mode

[Stefan Kangas]

Rudolf Adamkovič <salutis@me.com> writes:

> BTW, other modes in Emacs have the same problem. From
> "global-visual-line-mode" help:

That's because that text is auto-generated by `define-minor-mode'.  On
current master, that text is:

    Toggle Visual-Line mode in all buffers.
    With prefix ARG, enable Global Visual-Line mode if ARG is positive;
    otherwise, disable it.

    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.