RE: Predicate for true lists

[Drew Adams]

> > Isn't this in direct contradiction with (info "(elisp) Standard
> > Properties") which states that side-effect-free should not be set?:
> >
> > ‘side-effect-free’
> >      A non-‘nil’ value indicates that the named function is free of
> >      side-effects, for determining function safety (*note Function
> >      Safety::) as well as for byte compiler optimizations.  Do not set
> >      it.
> 
> No, because the audience of (info "(elisp) Standard Properties") is the
> average Elisp author, whereas the audience of (info "(elisp) Writing
> Emacs Primitives") is the average contributor to Emacs core.
> 
> Currently, the side-effect-free property seems to be intended as an
> internal one, since it makes some pretty strong guarantees, and is
> described only in the commentary and code of byte-opt.el.  This is my
> interpretation of the "Do not set it" wording.
> 
> Unless someone beats me to it, I intend to try to clarify this in the
> next version of my patch.

Caveat: I haven't been following this thread.

1. I don't see why anyone would say that some node
of the Elisp manual is intended for "the average
contributor to Emacs core" and _not_ for "the average
Elisp author".

The Elisp manual is (should be) for all Emacs users,
even users who may never write an Elisp sexp knowingly.

If you want to publish "internal" guidelines that apply
only for code that we distribute as part of GNU Emacs
then please do so elsewhere (e.g. in some dev readme or
in code comments).  I don't think that should be part
of the Elisp manual.

2. On the other hand, it would be helpful if the doc
for `side-effect-free' said something about _why_ it
tells us not to set this.

Imperatives like "Do not do X", with no other info
(background) do not help users understand.  They can
sometimes be worse than no admonition.  Our doc should
help users understand, not just tell us not to do this
or that.  Could someone please add a sentence giving
some idea about why it is not good to set this?

If info about this "standard symbol" property is not
something that you want to disclose to users then
perhaps this property should not be mentioned in the
manual.  IMO that would probably be a bad, not a good
thing, but if it's documented, and if we say something
like "Don't set it" then we owe it to users (ourselves)
to say why.

Just one opinion (well, two opinions by one opinioner).