bug#31125: 26; (emacs) `Highlight Interactively'

bug#31125: 26; (emacs) `Highlight Interactively'

[Drew Adams]

In the Emacs manual, `i symbol TAB' shows `Highlight Interactively' as a
place where symbols are mentioned.  They are, via
`highlight-symbol-at-point'.  This perhaps the only place in the Emacs
manual where symbols are mentioned.

1. It seems (?), by tracking backward through `highlight-symbol-at-point'
and then (thing-at-point 'symbol), that `highlight-symbol-at-point' is
about highlighting Lisp symbols, not text that has characters with
symbol-constituent syntax.  If so, it would be helpful for the doc of
`highlight-symbol*' to specifically say "Lisp symbol".

2. Assuming that it is in fact about Lisp symbols, please consider
adding a link in (emacs) `Highlight Interactively' to (elisp) `Symbols',
so readers of the Emacs manual can more easily discover something about
Lisp symbols.



In GNU Emacs 26.1 (build 1, x86_64-w64-mingw32)
 of 2018-04-10
Repository revision: c267421647510319d2a70554e42f0d1c394dba0a
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''

bug#31125: 26; (emacs) `Highlight Interactively'

[Eli Zaretskii]

> Date: Wed, 11 Apr 2018 07:45:54 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> In the Emacs manual, `i symbol TAB' shows `Highlight Interactively' as a
> place where symbols are mentioned.  They are, via
> `highlight-symbol-at-point'.  This perhaps the only place in the Emacs
> manual where symbols are mentioned.

No, there's also "symbol search", shown after I type TAB in the above
recipe.

> 1. It seems (?), by tracking backward through `highlight-symbol-at-point'
> and then (thing-at-point 'symbol), that `highlight-symbol-at-point' is
> about highlighting Lisp symbols, not text that has characters with
> symbol-constituent syntax.  If so, it would be helpful for the doc of
> `highlight-symbol*' to specifically say "Lisp symbol".

No, it isn't only about Lisp.  I just tried this command in a buffer
whose major mode is C, and it works there as I'd expect.

Why did you decide that it was only about Lisp symbols?

bug#31125: 26; (emacs) `Highlight Interactively'

[Drew Adams]

> > 1. It seems (?), by tracking backward through `highlight-symbol-at-
> point'
> > and then (thing-at-point 'symbol), that `highlight-symbol-at-point' is
> > about highlighting Lisp symbols, not text that has characters with
> > symbol-constituent syntax.  If so, it would be helpful for the doc of
> > `highlight-symbol*' to specifically say "Lisp symbol".
> 
> No, it isn't only about Lisp.  I just tried this command in a buffer
> whose major mode is C, and it works there as I'd expect.
> Why did you decide that it was only about Lisp symbols?

My bad. You can close this bug.

(It does somehow seem to bad that someone can read the
entire Emacs manual without knowing anything about
Lisp symbols, including that there is such a critter.)

bug#31125: 26; (emacs) `Highlight Interactively'

[Eli Zaretskii]

> Date: Wed, 11 Apr 2018 12:41:09 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 31125@debbugs.gnu.org
> 
> > No, it isn't only about Lisp.  I just tried this command in a buffer
> > whose major mode is C, and it works there as I'd expect.
> > Why did you decide that it was only about Lisp symbols?
> 
> My bad. You can close this bug.

Done.

> (It does somehow seem to bad that someone can read the
> entire Emacs manual without knowing anything about
> Lisp symbols, including that there is such a critter.)

Actually, "Symbol Search", which is where you get if you select
"symbol search" from the completion list popped up by "i search TAB",
does try to tell what is a symbol in language-independent terms.

bug#31125: 26; (emacs) `Highlight Interactively'

[Drew Adams]

> > (It does somehow seem to bad that someone can read the
> > entire Emacs manual without knowing anything about
> > Lisp symbols, including that there is such a critter.)
> 
> Actually, "Symbol Search", which is where you get if you select
> "symbol search" from the completion list popped up by "i search TAB",
> does try to tell what is a symbol in language-independent terms.

Yes, I'm aware of that.  And that additional, syntactic
meaning of "symbol" in Emacs jargon has little-to-nothing
to do with Lisp symbols.

A reader won't learn anything about Lisp symbols by
reading that node.  On the contrary: s?he will instead
mislearn something untrue that suggests it is about Lisp
symbols but is not.

A Lisp symbol is not just "a source code token", nor are
Lisp-mode "source code tokens" necessarily Lisp symbols.
Using `forward-symbol' or "symbol search" in Lisp does
not move across or find Lisp symbols.
 
It's too bad that Emacs chose to appropriate the term
"symbol" for that other, essentially unrelated meaning.
But it did.  It's a shame because Lisp is something
really important to Emacs, and so to Emacs users.  And
symbols are something important to Lisp.

This is what Lisp symbols are about (though they have
additional characteristics):

https://en.wikipedia.org/wiki/Symbol_(programming)

bug#31125: 26; (emacs) `Highlight Interactively'

[Eli Zaretskii]

> Date: Wed, 11 Apr 2018 21:37:50 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 31125-done@debbugs.gnu.org
> 
> Yes, I'm aware of that.  And that additional, syntactic
> meaning of "symbol" in Emacs jargon has little-to-nothing
> to do with Lisp symbols.
> 
> A reader won't learn anything about Lisp symbols by
> reading that node.  On the contrary: s?he will instead
> mislearn something untrue that suggests it is about Lisp
> symbols but is not.
> 
> A Lisp symbol is not just "a source code token", nor are
> Lisp-mode "source code tokens" necessarily Lisp symbols.
> Using `forward-symbol' or "symbol search" in Lisp does
> not move across or find Lisp symbols.
>  
> It's too bad that Emacs chose to appropriate the term
> "symbol" for that other, essentially unrelated meaning.
> But it did.  It's a shame because Lisp is something
> really important to Emacs, and so to Emacs users.  And
> symbols are something important to Lisp.
> 
> This is what Lisp symbols are about (though they have
> additional characteristics):
> 
> https://en.wikipedia.org/wiki/Symbol_(programming)

We were talking about the user manual, where the reader is not
necessarily a Lisp programmer.  For the latter, see "Symbols" in the
ELisp manual.

bug#31125: 26; (emacs) `Highlight Interactively'

[Drew Adams]

> We were talking about the user manual, where the reader is not
> necessarily a Lisp programmer.  For the latter, see "Symbols"
> in the ELisp manual.

You replied to my parenthetical remark after I said that
this bug can be closed, which was precisely about the
fact that the Emacs manual does not say anything about
Lisp symbols:

  (It does somehow seem to[o] bad that someone can read
  the entire Emacs manual without knowing anything about
  Lisp symbols, including that there is such a critter.)

This particular discussion is not related to the bug
report, and it is exactly about the fact that the Emacs
manual does (too) little to guide users toward Lisp.

And some knowledge of Lisp is the single most important
aid and guide a user can have, to improve her experience
and use of Emacs.

This discussion is irrelevant to my (misguided) bug
report.  But it is not irrelevant to the user manual.

A reader of the Emacs manual should not _need_ to
know Lisp to be able to read the manual.  But that
doesn't mean the manual should keep completely
clear of Lisp.  It could help, I think, for it to
occasionally point out some connections that can be
helpful for users.