bug#35222: 26.1; `read-command' documentation

bug#35222: 26.1; `read-command' documentation

[Drew Adams]

1. The doc string does not say what happens if DEFAULT is not provided
   (so `nil') and the user enters empty input.  And what happens is not
   obvious.  Please add that information to the doc string.

2. What does happen?  Well, it's documented in (elisp) `High-Level
   Completion'.  But please add information to that Info node that helps
   users understand a return value that is an empty-named interned
   symbol, which has the print and read syntax `##'.  It's pretty
   unusual for the default behavior of a read command to return such an
   odd beast.  (The default behavior is the case when arg DEFAULT is
   absent, hence `nil'.)  And please provide a cross-reference to node
   `Symbol Type', which explains this syntax.

   User code that tests the result of `read-command' typically needs to
   deal with the default DEFAULT case, hence with the possibility of the
   function returning an uninterned symbol.  Users need to be aware of
   this possibility - it's a gotcha.


In GNU Emacs 26.1 (build 1, x86_64-w64-mingw32)
 of 2018-05-30
Repository revision: 07f8f9bc5a51f5aa94eb099f3e15fbe0c20ea1ea
Windowing system distributor `Microsoft Corp.', version 10.0.17134
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

bug#35222: 26.1; `read-command' documentation

[Noam Postavsky]

On Wed, 10 Apr 2019 at 18:14, Drew Adams <drew.adams@oracle.com> wrote:
>
> 1. The doc string does not say what happens if DEFAULT is not provided
>    (so `nil') and the user enters empty input.  And what happens is not
>    obvious.  Please add that information to the doc string.

Um, can we declare the current behaviour a bug, and instead return nil
in this case? That matches the current doc string (i.e., return
DEFAULT-VALUE), and avoids the whole mess with the empty string symbol
which is weird and pretty useless as far as I can tell.

bug#35222: 26.1; `read-command' documentation

[Drew Adams]

> > 1. The doc string does not say what happens if DEFAULT is not provided
> >    (so `nil') and the user enters empty input.  And what happens is not
> >    obvious.  Please add that information to the doc string.
> 
> Um, can we declare the current behaviour a bug, and instead return nil
> in this case? That matches the current doc string (i.e., return
> DEFAULT-VALUE), and avoids the whole mess with the empty string symbol
> which is weird and pretty useless as far as I can tell.

Good question.  That was in fact my first reaction.
I wrote the bug report that way, then reconsidered.

I agree that the behavior is weird, and I'm not sure
what users, in what use cases, it could help.  IOW,
why?

But the behavior has apparently always been thus.

(Prior to Emacs 24 there was no such read/print
syntax for uninterned symbols, so it was arguably
even weirder.  If you used the result as a variable
value and did `C-h v' it would show you nothing!)

I ended up figuring that someone wanted this for
some good reason that I couldn't think of, and that
since it is documented this way (always returns a
symbol) and it is of long date we should just leave
it and make sure the doc string also helps.

But it sure is a gotcha.  Why the default DEFAULT
behavior would be something so unexpected is a
good question.  Hysterical accident?  Intentional
design?  Anyone know or have an idea what good this
is?

All I could think of is that code using it can be
sure to get a symbol.  But it sure isn't sure to
get a command...  I don't have the C sources, but
a priori (e.g. if I were writing `read-command'
from scratch in Lisp) it seems like it should
_require_ a commandp symbol, i.e., use
`completing-read' with non-nil REQUIRE arg.

Someone is sure to enlighten us.  When that happens,
and if the decision is to continue the behavior,
hopefully people will agree even more strongly with
the need to provide clear doc about this odd default
case.

bug#35222: 26.1; `read-command' documentation

[Eli Zaretskii]

> Date: Wed, 10 Apr 2019 15:13:31 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> 1. The doc string does not say what happens if DEFAULT is not provided
>    (so `nil') and the user enters empty input.  And what happens is not
>    obvious.  Please add that information to the doc string.

Thanks, fixed.

> 2. What does happen?  Well, it's documented in (elisp) `High-Level
>    Completion'.  But please add information to that Info node that helps
>    users understand a return value that is an empty-named interned
>    symbol, which has the print and read syntax `##'.  It's pretty
>    unusual for the default behavior of a read command to return such an
>    odd beast.  (The default behavior is the case when arg DEFAULT is
>    absent, hence `nil'.)  And please provide a cross-reference to node
>    `Symbol Type', which explains this syntax.

Done.

bug#35222: 26.1; `read-command' documentation

[Stefan Monnier]

>> 1. The doc string does not say what happens if DEFAULT is not provided
>>    (so `nil') and the user enters empty input.  And what happens is not
>>    obvious.  Please add that information to the doc string.
> Um, can we declare the current behaviour a bug, and instead return nil
> in this case? That matches the current doc string (i.e., return
> DEFAULT-VALUE), and avoids the whole mess with the empty string symbol
> which is weird and pretty useless as far as I can tell.

Yes, it would seem to be more in line with the usual expected behavior.
The caller can get the current behavior by passing ## as the DEFAULT
argument, so there doesn't seem to be any good reason to return ## when
DEFAULT was nil.


        Stefan

bug#35222: 26.1; `read-command' documentation

[Noam Postavsky]

Stefan Monnier <monnier@IRO.UMontreal.CA> writes:

>>> 1. The doc string does not say what happens if DEFAULT is not provided
>>>    (so `nil') and the user enters empty input.  And what happens is not
>>>    obvious.  Please add that information to the doc string.
>> Um, can we declare the current behaviour a bug, and instead return nil
>> in this case? That matches the current doc string (i.e., return
>> DEFAULT-VALUE), and avoids the whole mess with the empty string symbol
>> which is weird and pretty useless as far as I can tell.
>
> Yes, it would seem to be more in line with the usual expected behavior.
> The caller can get the current behavior by passing ## as the DEFAULT
> argument, so there doesn't seem to be any good reason to return ## when
> DEFAULT was nil.

Since this bug is already closed, this should go Bug#35231.