RE: [External] : Dialling down symbol escaping slightly?

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

> In a bug report,

Please, refer to the bug report, where this was
presented and discussed.  It's bug #23130:

https://debbugs.gnu.org/cgi/bugreport.cgi?bug=23130

Go ahead, read the report; it's not long.
(You can ignore the rest of the bug thread
without missing anything.)

> Drew pointed out that a function like
> (defun foo. ()) got a *Help* buffer like:
> 
>   foo\. is a Lisp closure.
> 
>   (foo\.)

Also from the bug report:

 (defun bar\  () (message "BARRRR"))

 `C-h f'
 Describe function (default bar ): RET

   bar\ is a Lisp function.

   (bar\ )

 Note that the first line here is not even correct - it should at least
 have another SPC char after the `\ '.  The way it is written now, it
 suggests that the name is `bar\', i.e., that the symbol is bar\\.

The point of the report is that *Help* and prompts
should talk about a function or variable using the
same way the Emacs manual and help usually do: by
quoting its _name_: `foo.' (or curly quotes).

From the bug report:

 it would be better to show something like this:

   `foo.' is a Lisp function.

   (foo\.)

   `bar ' is a Lisp function.

   (bar\ )

 And it would be better to use `...' also in the prompt:

   Describe function (default `foo.'):
   Describe function (default `bar '):

(The same situation exists for other languages, BTW.)

We should talk about a function, variable, face,
... whatever has a name, by referring to its _name_.

Its name is unambiguous, and we don't need to use
Lisp reader syntax to talk about it in our help/doc.

There's a difference between _using_ a named thing,
as in Lisp read+eval, and _mentioning_ it, as in
help.  When mentioning a name we quote it.  That's
as old as the hills.  (For fun, read some Quine...)

In code, to use function `bar ' we use (bar\ ).
(When talking about that use we use `(bar\ )'.)

That's all this bug is about.  It shouldn't be a
big deal to fix.  There's _nothing_ complicated
going on here, at all.

> This is because we're using prin1 (as we should) here, and because the
> printer always adds a backslash before the dot.  You also get the same
> thing with a question mark, which is perhaps a more serious usability
> problem, because quite a few people like to use that convention for
> predicates:
...

and so on.

That all misses the point.  This is not about
_using_ functions or variables or... that have
such names.  It's about talking about them in
our doc/help/prompts.

(And yes, in interaction such as prompts, some
contexts might be exceptions - Lisp read syntax
might be appropriate.  Lisp is like that - using
it and talking about it almost at the same time.
We need not make a black-&-white thing of this.)

> foo\? is a Lisp closure.
> 
> This isn't only for *Help*, of course, but in any context where we
> display a symbol, like in backtraces and the like, where "foo\?" is
> confusing and therefore less than optimal.

Yes and no.

Yes, if it's a context where we're talking about
the thing and it's important that we humans
reading that might otherwise get confused.  If
we want to be sure to be clear in that case then
we can quote the name: `...'.

But no, we do _not_ need to do that "in any [i.e.
every] context where we display a symbol".  No.
Absolutely not.

If it's not so important in some context to be
super clear, and a human reader understands
that the text written there is something that
could be Lisp-read, then we need not necessarily
quote it.  Lisp-read syntax can sometimes be
handier, and even clearer.  In such contexts we
know to put on our little Lisp-reader hats and
read like Lisp...

But when it comes to doc/help talking about
things, we should in general quote their names.

And we already do that in our doc.  It's not an
accident that Emacs has always taken pains to
quote names in the doc.  We do it even for names
that are not problematic.  All the more reason
to do it for problematic ones (problematic for
us human readers) - e.g., names that start or
end with chars such as SPC.

All this bug is about is *Help* descriptions
and some prompts.  And only a tiny part of such
descriptions - in in general we already quote
names in *Help*.

The bug just points out a rare case where we've
neglected to do that.  It's a detail, a corner
case.  But it's worth fixing.

There's zero reason to make a big thing out of
this, and to start going on about Lisp sexp
printing, or reading, or closures...

This is only about improving user help a tiny
bit, by quoting function, var, and face names
in a few places where we've not done that yet.

> Now, as far as I can tell, the only symbol containing a dot that needs
> to be escaped is the `.' symbol.  That is, it needs to be printed as
> \. to differentiate between that and the dot operator in `(1 . 2)'.  As
> for the question mark, it apparently only needs to be quoted when it's
> the first character in a symbol (to differentiate between the symbol
> and the character syntax).
> 
> Does anybody see any problems with tweaking the printer to drop
> escaping "." and "?" (except in the two cases described above)?

That's all blah-blah, IMO.  No, this is not
about needing to tweak the printer for _any_
specific characters.  I'm afraid you may have
completely missed the point.

Let's just fix bug #23130 and then move along...