bug#29838: 26.0; Elisp manual: describe standard-error sexps

bug#29838: 26.0; Elisp manual: describe standard-error sexps

[Drew Adams]

[-- Attachment #1: Type: text/plain, Size: 1442 bytes --]

Please describe the sexps that are associated with standard errors.

Currently, only the error messages are described.? But users can

sometimes see an error message that refers only to the sexp for

the error.

?

Example:

?

Error in post-command-hook (foo-post-cmd-hook): (args-out-of-range 9 9)

?

I don't see anywhere in the manual where a user could find out what

`(args-out-of-range 9 9)' means - in particular, what the two

occurrences of `9' signify.

?

Node `Standard Errors' says only this:

?

? ‘args-out-of-range’

???? The message is ‘Args out of range’.? This happens when trying to

???? access an element beyond the range of a sequence, buffer, or other

???? container-like object.? *Note Sequences Arrays Vectors::, and *Note

???? Text::.

?

Looking at the manual coverage of sequence etc. functions, you find

information such as this:

?

? (elt [1 2 3 4] -1)

???? error→ Args out of range: [1 2 3 4], -1

?

But that doesn't help for understanding `(args-out-of-range 9 9)'.

?

In GNU Emacs 26.0.90 (build 3, x86_64-w64-mingw32)

of 2017-10-13

Repository revision: 906224eba147bdfc0514090064e8e8f53160f1d4

Windowing system distributor `Microsoft Corp.', version 6.1.7601

Configured using:

`configure --without-dbus --host=x86_64-w64-mingw32

--without-compress-install 'CFLAGS=-O2 -static -g3''

?

[-- Attachment #2: Type: text/html, Size: 4886 bytes --]

bug#29838: 26.0; Elisp manual: describe standard-error sexps

[Eli Zaretskii]

> Date: Sun, 24 Dec 2017 09:22:30 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> 
> Node `Standard Errors' says only this:
> 
>   ‘args-out-of-range’
>      The message is ‘Args out of range’.  This happens when trying to
>      access an element beyond the range of a sequence, buffer, or other
>      container-like object.  *Note Sequences Arrays Vectors::, and *Note
>      Text::.
> 
> Looking at the manual coverage of sequence etc. functions, you find
> information such as this:
>  
>   (elt [1 2 3 4] -1)
>      error→ Args out of range: [1 2 3 4], -1
> 
> But that doesn't help for understanding `(args-out-of-range 9 9)'.

Not sure what you want to explain and how.  The number of arguments
shown by the args-out-of-range error is not fixed (although in many
cases they are just 2), and their number and meaning are determined by
the calling application.  It's not something fixed that can be
described to match all the uses.

bug#29838: 26.0; Elisp manual: describe standard-error sexps

[Drew Adams]

> > Looking at the manual coverage of sequence etc. functions, you find
> > information such as this:
> >   (elt [1 2 3 4] -1)
> >      error→ Args out of range: [1 2 3 4], -1
> > But that doesn't help for understanding `(args-out-of-range 9 9)'.
> 
> Not sure what you want to explain and how.  The number of arguments
> shown by the args-out-of-range error is not fixed (although in many
> cases they are just 2), and their number and meaning are determined by
> the calling application.  It's not something fixed that can be
> described to match all the uses.

Please explain whatever _can_ be explained.  Clearly, if the
number and specific meanings of arguments cannot be known
generically then that info cannot be conveyed.  But so far,
nothing at all is told users about a sexp such as
`(args-out-of-range 9 9)'.

A start could to be to mention that an `args-out-of range'
error sexp has the form `(args-out-of-range ARG...)' or
whatever the truth is, and then say what ARG represents,
in general terms.

The error messages themselves (see above) are quite
different.  They show you the sequence/array/whatever
as well as the args that are out of range for it.

(And a user would naturally expect, I think, that
the info in something like `(args-out-of-range 9 9)'
would provide the range that the args are outside of,
as well as the arg values that are outside that range,
even if it didn't provide the sequence/array/etc.)

bug#29838: 26.0; Elisp manual: describe standard-error sexps

[Drew Adams]

I think this is the main point: Users can easily see
(only) a message that shows a sexp, such as
`(args-out-of-range 9 9)', about which they have no
information.

If users never saw such messages then perhaps there
would be no need to describe such things as
`(args-out-of-range 9 9)'.  If they saw only nice
error messages such as "Args out of range: [1 2 3 4], -1"
then there would be no such problem.

If Emacs can be fixed so that users never see such
undescribed and unobvious messages then great.

bug#29838: 26.0; Elisp manual: describe standard-error sexps

[Eli Zaretskii]

> Date: Sun, 24 Dec 2017 10:50:16 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 29838@debbugs.gnu.org
> 
> > > Looking at the manual coverage of sequence etc. functions, you find
> > > information such as this:
> > >   (elt [1 2 3 4] -1)
> > >      error→ Args out of range: [1 2 3 4], -1
> > > But that doesn't help for understanding `(args-out-of-range 9 9)'.
> > 
> > Not sure what you want to explain and how.  The number of arguments
> > shown by the args-out-of-range error is not fixed (although in many
> > cases they are just 2), and their number and meaning are determined by
> > the calling application.  It's not something fixed that can be
> > described to match all the uses.
> 
> Please explain whatever _can_ be explained.

Sorry, I don't know how to do that in any useful way.  Maybe someone
else will have an idea.

bug#29838: 26.0; Elisp manual: describe standard-error sexps

[Andreas Schwab]

On Dez 24 2017, Drew Adams <drew.adams@oracle.com> wrote:

> If users never saw such messages then perhaps there
> would be no need to describe such things as
> `(args-out-of-range 9 9)'.  If they saw only nice
> error messages such as "Args out of range: [1 2 3 4], -1"
> then there would be no such problem.

Is "Args out of range: 9, 9" any more informative?

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

bug#29838: 26.0; Elisp manual: describe standard-error sexps

[Drew Adams]

> >
> > Please explain whatever _can_ be explained.
> 
> Sorry, I don't know how to do that in any useful way.  Maybe someone
> else will have an idea.

As I said:

  A start could to be to mention that an `args-out-of range'
  error sexp has the form `(args-out-of-range ARG...)' or
  whatever the truth is, and then say what ARG represents,
  in general terms.

And as I said:

  If [users] saw only nice error messages such as "Args out
  of range: [1 2 3 4], -1" then there would be no such problem.

That too would take care of this bug.

Put differently, users should not see a message that refers
to something (internal?) that they cannot understand and
that you say you don't know how to explain.  But that's
what happens currently with (as one example), errors raised
on `post-command-hook'.

It is presumably possible to see such unhelpful messages
also in other contexts where raising an error is suppressed
in favor of showing a message about the error.  Perhaps a
all such inferior messages could be fixed at the same place
(dunno).

bug#29838: 26.0; Elisp manual: describe standard-error sexps

[Drew Adams]

> > If users never saw such messages then perhaps there
> > would be no need to describe such things as
> > `(args-out-of-range 9 9)'.  If they saw only nice
> > error messages such as "Args out of range: [1 2 3 4], -1"
> > then there would be no such problem.
> 
> Is "Args out of range: 9, 9" any more informative?

Of course not.  But that's not the corresponding
error message, is it?

Now that you bring that up, I don't see any good
description of the error message itself, either.
So yes, that's perhaps the first thing to fix.

Ideally the message should be self-explanatory,
and should indicate what the range is that the
specified args fall outside of.

bug#29838: 26.0; Elisp manual: describe standard-error sexps

[Andreas Schwab]

On Dez 24 2017, Drew Adams <drew.adams@oracle.com> wrote:

>> > If users never saw such messages then perhaps there
>> > would be no need to describe such things as
>> > `(args-out-of-range 9 9)'.  If they saw only nice
>> > error messages such as "Args out of range: [1 2 3 4], -1"
>> > then there would be no such problem.
>> 
>> Is "Args out of range: 9, 9" any more informative?
>
> Of course not.  But that's not the corresponding
> error message, is it?

Yes, it is.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

bug#29838: 26.0; Elisp manual: describe standard-error sexps

[Drew Adams]

> >> Is "Args out of range: 9, 9" any more informative?
> >
> > Of course not.  But that's not the corresponding
> > error message, is it?
> 
> Yes, it is.

Room for improvement in both the error messages
and the doc, then.

bug#29838: 26.0; Elisp manual: describe standard-error sexps

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

>> Please explain whatever _can_ be explained.
>
> Sorry, I don't know how to do that in any useful way.  Maybe someone
> else will have an idea.

I don't think there's much here that can be usefully said (and we don't
want to commit to any specific format, I think?), so I'm closing this
bug report.

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