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

[Drew Adams <drew.adams@oracle.com>]

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