bug#40671: [DOC] modify literal objects

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

(This ended up long and a bit off-topic; sorry.
Hope it still helps.)

> > And it's especially not good to use "value" in the two
> > different senses, as (1) something you see ("appears")
> > in a source program and (2) a runtime value that results
> > from reading, byte-compiling, or interpreting that source
> > code.
> >
> > Maybe "object" or "Lisp object" instead of "value", for
> > #2?
> 
> The term "value" is used all over the place in the manual for #2, so
> people are familiar with it, we need a better term for (1) instead I
> think.  (info "(elisp) Equality Predicates") already uses the term
> "literal object" btw:
> 
>      The Emacs Lisp byte compiler may collapse identical literal
>      objects, such as literal strings, into references to the same
>      object, with the effect that the byte-compiled code will compare
>      such objects as ‘eq’, while the interpreted version of the same
>      code will not.

BTW, that node does NOT already contain that text.
That paragraph is new for Emacs 27, which is not yet
released.  IOW, that text is _proposed_ for Emacs 27.

But OK.  That describes the problem as being about
"literal objects".

That's essentially the message we're discussing, I
think, but it should be broadened beyond just the
byte-compiler, I think.

Where, if anywhere, does the manual define or describe
"literal objects"?  I don't think we want to be doing
that, unless it's done carefully.

For the message we're talking about, I'd say start by
talking about source code: forms, sexps.

Yes, the sexps that are problematic are, I suppose,
what that text calls "literal objects".  But I don't
see that term defined anywhere.  And it seems odd to
me to talk about source-code thingies as "objects".

Maybe the result of reading, or the result of some
initial stage of byte-compiling or interpreting, is a
"literal object", but is a source-code sexp a "literal
object"?

A "literal string" makes sense to me, as a string
in source code ("...").  But "literal object" doesn't
sound like a source-code thing.  Perhaps that's what
literal numbers, strings, etc. in source code are
called now - "objects"?  Sounds odd to me.

Checking `i literal' in the Emacs 27 manual, I see
no "literal object", but I do see "literal evaluation"
and "literal in rx", where "literal" is used as a noun
(in both cases presumably).

However, the former index entry takes you to node
`Self-Evaluating Forms', which never once uses the
word "literal" (as adjective or noun) - it talks only
about "forms", i.e., source code.  That text looks OK.
The index item seems wrong - you never get any text
that tells you anything about "literal evaluation".
This node, and index entry "literal evaluation" are
in Emacs 26 (and probably earlier).

[Index entry "literal in rx" takes you to node `Rx
Constructs', where you find `(literal EXPR)', which
is about matching a "literal string".  To me, "literal
string" is clear enough, and I think of it as both a
source-code thing (text) and as a Lisp object (after
reading the text, for example).  This node is new for
Emacs 27.]

Searching the Emacs 27 Elisp manual for "literal"
I see that there is another occurrence of "literal
object", also in a node that is new for release 27,
`pcase Macro'.

There too the term "literal object"is totally
unexplained: "Matches if EXPL equals the literal
object.  This is a special case of ‘'VAL’, above,
possible because  literal objects of these types
are self-quoting."

(The "possible because..." is not correct English,
and I don't know what it's trying to say.  Maybe
"possibly because..." was meant.  Or maybe what
was meant was to end a sentence after "above" and
start a new sentence with "This is possible
because...".)

And again, in another new-to-Emacs-27 node,
`Backquote Patterns', I see "literal object":
"Matches if the corresponding element of EXPVAL
is ‘equal’ to the specified literal object."  And
again, the term is totally unexplained.

(That node also has "literal symbol", which, like
"literal string" doesn't shock me.  It is "literal
object" that I find odd.)

Both Emacs 27 and 26, node `Mode-Specific Indent',
mention "a literal value (usually zero)".  That's
OK, I guess, but I think it's untrue.  I think
what's meant is just "a number (usually zero)".
There's nothing literal about it.

Node `Rx Constructs' of Emacs 27 introduces
"Literals" (noun) as forms (source-code sexps),
and shows that they can be strings or chars.
I don't have a problem with that.

Node `Rx Functions' says "if `literal' or `regexp'
forms are used", and I guess that's referring to
the forms `(literal...)' and `(regexp...)'
introduced in node `Rx Constructs'.  And it refers
to "string literals".  All of that's OK.

Node `Extending Rx' mentions "a list literal".
Again, like string literal, char literal, etc.,
this isn't introduced anywhere that I can see,
but that's OK - use of "literal" as a noun in
such cases clearly means the same as "literal
string" etc.

Node `Module Initialization' is another new one
for Emacs 27, and another place where "literal"
is used as a noun: "number literal".  Again, no
problem for me with that (like "string literal").

All other occurrences of "literal" in the manual
are about literal chars, finding a file literally, 
displaying or matching text literally, or
replacing literal text.  No problem there, and
nothing new there.

In sum, "literal object" is nowhere defined,
described, or explained.  And "object" sounds
wrong, to me, when referring to source-code text.