bug#40671: [DOC] modify literal objects

[Michael Heerdegen]

Paul Eggert <eggert@cs.ucla.edu> writes:

> Yes, in hindsight I suppose you're right. If you like I can revert the
> changes now.

I can't estimate, for me it is enough if you are willing to revert if
there is no consent and we discuss all of this now.

> > Before your changes the manual used the
> > term "literal" objects, now you added a different wording "constant"
> > vs. "mutable" that describes more or less the same thing.
>
> Thanks, I hadn't recalled that use of "literal object" (in the
> Equality Predicates) section. Although the two notions are related
> they're not identical. For example, the reason one shouldn't modify
> byte-code objects is not the sharing issue mentioned in Equality
> Predicates: it's because doing so can make Emacs crash.

> That being said, it would be helpful discuss the two notions in a
> unified way rather than separately, as is the case now.

I would like to leave the suggestion of a good wording to someone like
Stefan, feeling not competent enough myself.

I have just the feeling sure if you simplify too much.  Lisp has
reading, compiling, evaluation.  When the reader reads something like
'(x y z), the (x y z) already produces the literal thing because the
reader transforms it into an object, contrarily to creation of objects
at run-time.  The compiler can handle it differently.  That's the main
difference.  The quote comes into play when the thing gets evaluated.
When you evaluate the expression, the literal is returned.  It could
also end up as part of a program, which was the pitfall case in the
initial report.

> > Then some things you added are just wrong, at least in the generality
> > you word them.  As Drew said, `quote' doesn't always return constant
> > objects, the special form just returns the OBJECT, whatever it is, when
> > it is evaluated.
>
> It depends on what one means by "constant" objects. If we uniformly
> changed that word to "literal" would that remove the objection? For
> example, although byte-code objects aren't normally what one would
> think of as being "literal", we could simply define them to be
> "literal".

No, that's not (only) what I mean.  Maybe you should remember how quote
is used in `defmacro's for example?  Generally it's just a mean to
prevent evaluation.  In your examples this returned the literal notated
after the quote, but it can be anything.

Or - about what do you speak?  The part of the program being quoted, or
the thing "behind" the quote when the program is executed?  When you
describe the return value of quote, the special form, in the docstring,
you are speaking about the latter, and then this is wrong, the return
value is the arbitrary OBJECT.

E.g.

(let ((l (list 1 2 3)))
  `',l)

==> '(1 2 3)

If you evaluate this (the return value is a valid expression), `quote'
returns a list, but it's not a list literal.  But if you try to modify
what the reader constructed after reading ",l", also a list (\, l),
you'll probably get a problem.

As a special case, quote can be used to create lists because Lisp
programs are lists and use list notation anyway.  But that's only one
way of using it.

> > |  Vectors written with square brackets are constants and should not be
> > |  modified via @code{aset} or other destructive operations.
> > (let ((l (list 1 2 3)))
> >    (let ((my-vector `[,@l]))
> >      my-vector))
> > What does this sentence tell me about the vector I constructed?
>
> Nothing, just as the documentation for splicing also says nothing
> about that vector.

One could read your sentence as suggesting that `my-vector' would be
constant because square brackets are used to construct it.  This was an
example to demonstrate where your wording is too vague in my opinion.


Michael.