bug#38736: 26.3; ellipsis in `*Messages*', doc of `format' etc.

bug#38736: 26.3; ellipsis in `*Messages*', doc of `format' etc.

[Drew Adams]

The doc string of `format' doesn't tell you anything about control by
`print-level', `print-length', etc.  Please consider adding such info.

Consider trying to figure out, when looking at a message in
`*Messages*', why a long list value shows ellipsis ("..."), instead of
showing all the elements.  You try `C-h f message', which says nothing
about this.  The most it does is provide a bunch of details about the
formatting intermediary `format-message', imposed since Emacs 25.

Are details about %, `, and ' so important for `message' that they
merit a paragraph, but `print-level' and `print-length' are not so
important?

(What's more: the doc string for `message' goes into more detail than 
the one for `format-message', which doesn't even mention %, even
though the former tells you to refer to the latter "for  details".)

Following the `format-message' link, you still get no clue about this,
but you then follow a link for `format'.  There you still get no clue
about it, but you see that %S uses `prin1'.

Following the `prin1' link you finally find out that you can control
`message's use of ellipsis using `print-length' and `print-level'.

Users shouldn't have to go through all of that (and that even assumes
that they are able to guess that following just that thread might get 
them somewhere useful).

What's true for `message' is also true for `error', etc.  At least the
doc of `format' - and probably its often-used callers, such as `message'
- should specifically mention these "print"-controlling (really just
formatting) variables.


In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32)
 of 2019-08-29
Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd
Windowing system distributor `Microsoft Corp.', version 10.0.17763
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

bug#38736: 26.3; ellipsis in `*Messages*', doc of `format' etc.

[Eli Zaretskii]

> Date: Tue, 24 Dec 2019 13:02:55 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> 
> The doc string of `format' doesn't tell you anything about control by
> `print-level', `print-length', etc.  Please consider adding such info.
> 
> Consider trying to figure out, when looking at a message in
> `*Messages*', why a long list value shows ellipsis ("..."), instead of
> showing all the elements.  You try `C-h f message', which says nothing
> about this.  The most it does is provide a bunch of details about the
> formatting intermediary `format-message', imposed since Emacs 25.

How did you get the ellipsis in *Messages*?  I'm guessing you invoked
'eval', because this is a feature of 'eval'.  So looking for the
information in the doc string of 'message' is a somewhat strange
place.  The doc string of 'eval' does mention the variables which
control when the ellipsis is produced.

> Following the `format-message' link, you still get no clue about this,
> but you then follow a link for `format'.  There you still get no clue
> about it, but you see that %S uses `prin1'.
> 
> Following the `prin1' link you finally find out that you can control
> `message's use of ellipsis using `print-length' and `print-level'.
> 
> Users shouldn't have to go through all of that (and that even assumes
> that they are able to guess that following just that thread might get 
> them somewhere useful).
> 
> What's true for `message' is also true for `error', etc.  At least the
> doc of `format' - and probably its often-used callers, such as `message'
> - should specifically mention these "print"-controlling (really just
> formatting) variables.

I don't think it's reasonable to ask to have this low-level stuff
bubble up to such high levels, which are quite far from the features
which are affected by these variables.  %S is not a frequently used
format, so describing what prin1 does in the doc strings of 'message'
etc. just for its sake doesn't seem like a good idea to me.  OTOH, I'd
expect users who use %S to know already about the ellipsis and how to
control it.

bug#38736: 26.3; ellipsis in `*Messages*', doc of `format' etc.

[Drew Adams]

> > Consider trying to figure out, when looking at a message in
> > `*Messages*', why a long list value shows ellipsis ("..."), 
> > instead of showing all the elements.
> 
> How did you get the ellipsis in *Messages*?

By a call (message "Result: %S" result), where the
value of `result' is a long list.

> I'm guessing you invoked 'eval', because this is a
> feature of 'eval'.  So looking for the information
> in the doc string of 'message' is a somewhat strange
> place.

`message', like other functions, evaluates its args.
And `format' for %S ends up using `prin1'.

Help-wise, to get from `message' and `...' to
`print-length' is a long haul.

> > Following the `format-message' link, you still get no clue about
> > this, but you then follow a link for `format'.  There you still
> > get no clue about it, but you see that %S uses `prin1'.
> >
> > Following the `prin1' link you finally find out that you can control
> > `message's use of ellipsis using `print-length' and `print-level'.
> >
> > Users shouldn't have to go through all of that (and that even assumes
> > that they are able to guess that following just that thread might get
> > them somewhere useful).
> >
> > What's true for `message' is also true for `error', etc.  At least
> > the doc of `format' - and probably its often-used callers, such as
> > `message' - should specifically mention these "print"-controlling
> > (really just formatting) variables.
> 
> I don't think it's reasonable to ask to have this low-level stuff
> bubble up to such high levels, which are quite far from the features
> which are affected by these variables.

It's not lower-level than are the details currently
included about %, `, and '.  

If it's enough for the `message' doc to just refer
to `format-message' for `print-length' (eventually,
after following links), then it should be enough
for that doc to just refer to `format-message' for
the info about %, `, and ', no?

And as mentioned, % is not even mentioned in the
doc for `format-message'.  Why is it more important
to mention % in the "higher-level" function `message'
than in `format-message'?

> %S is not a frequently used format,

Why do you think so?

It's perhaps the most common formatting string when
using `message' for debugging etc., which I think
is a common use case.

%S is the most general formatting string, accepting
any Lisp object.

> I'd expect users who use %S to know already
> about the ellipsis and how to control it.

IOW, you expect users of `message' - which is pretty
much everyone who uses Elisp - to know that.  Well,
I use `message' and `%S' a lot, yet I had to track
it down, exactly as reported:

 `message' > `format-message' > `format' > %S >
 `prin1' > `print-length'

Using %S with `message' likely doesn't give you
`...' often.  When it does, you can want to ask
Emacs how to control that.  Currently you have
to dig deeply to find out.

bug#38736: 26.3; ellipsis in `*Messages*', doc of `format' etc.

[Eli Zaretskii]

> Date: Wed, 25 Dec 2019 08:44:53 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 38736@debbugs.gnu.org
> 
> > > Consider trying to figure out, when looking at a message in
> > > `*Messages*', why a long list value shows ellipsis ("..."), 
> > > instead of showing all the elements.
> > 
> > How did you get the ellipsis in *Messages*?
> 
> By a call (message "Result: %S" result), where the
> value of `result' is a long list.

That's not a "call", that's evaluation.  And using %S is a
prerequisite, AFAIK; you won't get the ellipsis with other formats.

Like I said: eval's doc string documents this feature, you just looked
for the documentation in the wrong place (and still found it, albeit
through a long path).  So I see nothing to be done here, and I'm
closing this bug report.

bug#38736: 26.3; ellipsis in `*Messages*', doc of `format' etc.

[Drew Adams]

> > > How did you get the ellipsis in *Messages*?
> >
> > By a call (message "Result: %S" result), where
> > the value of `result' is a long list.
> 
> That's not a "call", that's evaluation.

Huh?  It's in code, in a function body.  But of
course, code (source/byte-compiled) is evaluated
(interpreted, executed, whatever term you prefer).

Executing that code means evaluating that sexp,
yes.  And?  It's not clear what hairs you are
trying to split, here.

> And using %S is a prerequisite, AFAIK; you won't
> get the ellipsis with other formats.

Correct, which is why I said (message "%S"), and
not just calling `message'.

> Like I said: eval's doc string documents this
> feature,

I see nothing in the doc string of `eval' that
tells you `%S' in the `message' format string is
controlled by `print-length'.  Or even anything
close to it.

 eval is a built-in function in 'C source code'.
 (eval FORM &optional LEXICAL)
 Evaluate FORM and return its value.

 If LEXICAL is t, evaluate using lexical scoping.
 LEXICAL can also be an actual lexical environment,
 in the form of an alist mapping symbols to their value.

Pointing to `eval' here seems like a very red
herring.

> you just looked for the documentation in the
> wrong place

`C-h f eval' is the right place?  How so?  How
does it help?

> (and still found it, albeit through a long path).

Exactly what I reported.  A long road to get to
info about a commonly used construct.

(Or do you still maintain that %S is rarely used
with `message'?)

And note that if you try to find it in the Elisp
manual, starting with `message' (node `Displaying
Messages') and linking to node `Formatting Strings',
then what you find for %S is this:

 '%S'
 Replace the specification with the printed representation of the
 object, made with quoting (that is, using 'prin1'-*note Output
 Functions::).  Thus, strings are enclosed in '"' characters, and
 '\' characters appear where necessary before special characters.

Then you need to follow the `Output Functions'
link to read about `prin1'.  Again, several links
to follow.

Even in `Formatting Strings' it would make sense
to not give the impression that `prin1' is only
about "quoting".

  "quoting (that is, using `prin1'"

`prin1's use of variables `print-length' etc.
have nothing to do with "quoting".

> So I see nothing to be done here, and I'm
> closing this bug report.

Too bad, once again.

bug#38736: 26.3; ellipsis in `*Messages*', doc of `format' etc.

[Michael Heerdegen]

Eli Zaretskii <eliz@gnu.org> writes:

> Like I said: eval's doc string documents this feature

I don't understand that comment either, did you mean `prin1'?

> you just looked for the documentation in the wrong place (and still
> found it, albeit through a long path).  So I see nothing to be done
> here, and I'm closing this bug report.

I can agree that what we have is acceptable.

But in this sentence in the docstring of `message':

"The first argument is a format control string [...]"

"format" could get quoted so that it gets transformed into a link to the
`format' help page - right?

Michael.

bug#38736: 26.3; ellipsis in `*Messages*', doc of `format' etc.

[Eli Zaretskii]

> Date: Wed, 25 Dec 2019 12:54:54 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 38736-done@debbugs.gnu.org
> 
> > Like I said: eval's doc string documents this
> > feature,
> 
> I see nothing in the doc string of `eval' that
> tells you `%S' in the `message' format string is
> controlled by `print-length'.  Or even anything
> close to it.

Sorry, I meant eval-expression, what is run by M-:.

bug#38736: 26.3; ellipsis in `*Messages*', doc of `format' etc.

[Eli Zaretskii]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Cc: eliz@gnu.org,  drew.adams@oracle.com
> Date: Thu, 26 Dec 2019 04:24:07 +0100
> 
> But in this sentence in the docstring of `message':
> 
> "The first argument is a format control string [...]"
> 
> "format" could get quoted so that it gets transformed into a link to the
> `format' help page - right?

No, because that "format" is not a reference to 'format' the
function.  There's a link to 'format-message' a little bit below that,
so I think we are fine on that front.

bug#38736: 26.3; ellipsis in `*Messages*', doc of `format' etc.

[Drew Adams]

> > > Like I said: eval's doc string documents this
> > > feature,
> >
> > I see nothing in the doc string of `eval' that
> > tells you `%S' in the `message' format string is
> > controlled by `print-length'.  Or even anything
> > close to it.
> 
> Sorry, I meant eval-expression, what is run by M-:.

FWIW, I made it clear that I did not use
`eval-expression' (`M-:):

 >>> How did you get the ellipsis in *Messages*?
 >>
 >> By a call (message "Result: %S" result),
 >> where the value of `result' is a long list.

And when you then said that (message "Result:
%S" result) is "not a call, that's evaluation",
I replied that it was used "in code, in a
function body."

The general point is that a user who wants
to know about the behavior of `message', in
particular for a format string with %S (but
not limited to that), now needs to dig deep
into a chain of doc strings or manual links.

`message', like `format', is very commonly
used.  And (I think) %S may be the most
commonly used %-sequence with `message'.

We now clutter the doc of `message' with info
about ` and ', and to link to the doc for
`format-message'.  That further complicates
trying to understand `message' behavior.

The `message' doc even has this gratuitous
text now:

  To display STRING without special treatment,
  use (message "%s" STRING).

There's no STRING in the function signature.
There's nothing special about a STRING arg,
and %s doesn't just print a STRING as a
string - it prints anything as a string.

Parameter ARGS isn't even described by name.
It's OK that we say that "the rest are data
to be formatted...".  But, especially because
of that sentence about STRING data, it's not
made sufficiently clear that the "data", are
Lisp objects of any kind.

If you really want to have a statement about
using %s to produce string output then just
say that.  Don't show a call to `message'
where the second arg is STRING - that's
misleading.

Here's my suggestion, at this point.  But
perhaps we can do better - I don't have all
the answers.

1. Say that the ARGS are Lisp objects of any
   kind.
2. Say that ARGS are handled by `format-message',
   (alas) and the result is shown as a message.
3. Users can follow the `format-message' link
   to get all the formatting info they need.
4. Don't mention `, ', or %.  That doesn't help
   without more info; it's just noise.
5. If you _do_ show an example using % then use
   %S, and point out that it uses `prin1'.
   (Maybe even say that `prin1' is controlled
   by variables such as `print-level'.)

#3 is a step back from my initial suggestion
for trying to shorten the journey to info about
the `prin1' variables.  #5 might mitigate #3.

I don't have a perfect solution, at this point.

It's _really_ too bad that we had to introduce
`format-message'.  Going from `message' doc to
`format-message' doc works against usability
and understanding.

As opposed to `format', the `format-message'
doc talks only about the new "quoting" hoops.
It forces you to move to the `format' doc to
get the %-sequences info you really need, to
make use of `message' in the most common ways.

The "quoting" stuff should be the last, not
the first, thing you read when trying to
understand `message' and the like.  (And
`format-message' is specifically for
messaging.)

It would be better - if we're forced to send
people to `format-message' first - if its doc
string contained all of the info that's in
the `format' doc, and it added the "quoting"
stuff only at the end.

Better, IOW, for users coming from `message'
and the like to get the main format-control
info (%-sequences) first.

As it stands now, the cart ("quoting") is
put before the horse (%-sequences), when
trying to understand `message' and the like.

I know that we don't want to just duplicate
all the `format' doc.  That's not great.

But `message' is a high-level access point
for using format control strings, and to get
to the important info about those, you now
have to get past the unhelpful, noisy doc of
`format-message'.  If a user stops at that
doc, and doesn't plow forward to the `format'
doc, then the most important messages about
`message' will not get through.

[This would have been avoided as a problem
if `message' had not been co-opted to use
`format-message', i.e., if we had instead
just added a separate function, e.g.,
`message-with-quote-munging', which used
`format-message'.  Alas, that ship has
sailed.]