Re: Predicate for true lists

[Basil L. Contovounesios]

Drew Adams <address@hidden> writes:

>> > 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".

Because one is a main chapter node listing standard symbol properties
that one is likely to encounter, whereas the other is an appendix
documenting Emacs internals.

The wording of my last message may not be 100% accurate or to your
liking, but it was only intended as a summary to illustrate a point.

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

It is and will continue to be following my next patch, if not more so.

> 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.

There is a balance to be reached between what is and isn't documented in
the manual.  The Elisp manual currently documents various internals
which are very useful for someone interested in hacking on Emacs like
myself.  It would be a shame and disservice to remove this existing
documentation or avoid updating and expanding it.

The 'pure' and 'side-effect-free' properties have been prominently
advertised for quite a while, and are central to the operations of the
compiler optimiser.  The former, in particular, is frequently used by
third-party Elisp packages.  I think they neither qualify as too
internal to document properly, nor should have their existing
documentation removed.  It's just that their documentation can be
reworded, expanded, and restructured in a more useful way, so that it is
clearer when and how to use them; that is what Eli's review was about,
and what led to Alex's question.

> 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.

That is exactly what I meant when I said:

>> Unless someone beats me to it, I intend to try to clarify this in the
>> next version of my patch.

Thanks,

-- 
Basil