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

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

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