bug#13823: 24.3.50; Elisp manual description of property `pure'

bug#13823: 24.3.50; Elisp manual description of property `pure'

[Drew Adams]

The doc for property `pure' is inadequate and misleading.  It says only
this:
 
  `pure'
     This property is used internally to mark certain named functions
     for byte compiler optimization.  Do not set it.
 
In discussion of bug #13052, no good reason was given for this.
 
The consideration of this property as somehow being "internal", and not
for use by anyone programming with Emacs Lisp other than those
developing core Emacs, is misguided.  Users deserve a real description
of what this property does, so they can determine whether and where to
use it in code they develop.
 
The same information would of course be useful to core Emacs developers
- the manual serves them too.
 
The idea of withholding such information from users is misguided.  All
users are potentially Emacs-Lisp users and even potentially core Emacs
developers.  The Elisp manual should say what such a property actually
does, specifically.
 
AFAICT, there is no difference between using this property in code
distributed as part of core Emacs and using it in other, user code.
 
Why shouldn't, for example, a user function with a definition similar
to, or even identical to, that for `kbd' have `pure' applied to it,
since it is applied to `kbd'?  Why make users guess when `pure' might be
appropriate or inappropriate?
 
Emacs Dev really needs to get over its antiquated conception of Emacs
users as something other than Emacs-Lisp developers.  The world has
moved beyond end users submitting batch requests at the Univac job
queue.
 
GNU should be in the vanguard of putting users first and encouraging
them to dig into, understand, and modify the programs that GNU provides.
Shame on GNU for not helping users by making things more transparent.

In GNU Emacs 24.3.50.1 (i386-mingw-nt5.1.2600)
 of 2013-02-25 on ODIEONE
Bzr revision: 111879 yamaoka@jpl.org-20130225224731-cv9gznq5nqf3ei7g
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.7) --no-opt --enable-checking --cflags
 -IC:/Devel/emacs/build/include --ldflags -LC:/Devel/emacs/build/lib'
 

bug#13823: 24.3.50; Elisp manual description of property `pure'

[Stefan Monnier]

> The idea of withholding such information from users is misguided.

You'd be well served to stop constantly assuming that we're intent on
withholding things (and breaking and whatever else happens to you poor
users).

If you can come up with a good description of what it does, I'm
all ears.


        Stefan

bug#13823: 24.3.50; Elisp manual description of property `pure'

[Christopher Schmidt]

Stefan Monnier <monnier@IRO.UMontreal.CA> writes:
> If you can come up with a good description of what it does, I'm
> all ears.

There is a nice description of pure in byte-opt.el

    ;; pure functions are side-effect free functions whose values depend
    ;; only on their arguments. For these functions, calls with constant
    ;; arguments can be evaluated at compile time. This may shift run
    ;; time errors to compile time.

        Christopher (<- who would like to see pure documented)

bug#13823: 24.3.50; Elisp manual description of property `pure'

[Drew Adams]

> If you can come up with a good description of what
> it does, I'm all ears.

You presumably know the content to be communicated - just what effect property
`put' has, when to use it, any gotchas or other things to be aware of etc.

I do not really know.  I'm asking for precisely that info.

If you tell me the content - what `put' does, I will be more than glad to offer
help with the wording.


From the bug #13052 thread, it seems that this might be the effect and condition
of use, but please correct if wrong:

 Non-nil means that when the symbol's function is
 called with only constant arguments the byte-compiler
 evaluates the call and replaces it in the compiled
 code by its value.[*]

 This is similar to replacing a macro call by the
 evaluation of its expansion.

 Use `put' only when the function has no side effects
 and every evaluation of that function call returns
 the same value regardless of the evaluation context.

[*] Does the byte-compiler always do this when the condition is satisfied?  Or
does non-nil `pure' mean only that it might do this?


Is the above description correct?  Should something else be said?

Perhaps the condition is too strong?  Is there a use case for a function that
might not give the same result in all contexts, but for which the only
relevant/intended context is byte-compilation?

bug#13823: 24.3.50; Elisp manual description of property `pure'

[Stefan Monnier]

>> If you can come up with a good description of what it does, I'm all ears.
> You presumably know the content to be communicated - just what effect
> property `put' has, when to use it, any gotchas or other things to be
> aware of etc.

That's a wrong presumption.  Rather than presuming, please stick to
the facts and go straight to the point.
E.g. ask "Could we have it be properly documented, please?".


        Stefan

bug#13823: 24.3.50; Elisp manual description of property `pure'

[Stefan Monnier]

>> If you can come up with a good description of what it does, I'm all ears.
> There is a nice description of pure in byte-opt.el
>     ;; pure functions are side-effect free functions whose values depend
>     ;; only on their arguments.  For these functions, calls with constant
>     ;; arguments can be evaluated at compile time.  This may shift run
>     ;; time errors to compile time.

Sounds OK.  Feel free to put it in.


        Stefan

bug#13823: 24.3.50; Elisp manual description of property `pure'

[Drew Adams]

> go straight to the point.  E.g. ask "Could we have it
> be properly documented, please?".

Oh, that's just what I did, in bug #13052:

>> How about documenting this `pure' property?

and later in that same thread:

>> In any case, this property should be documented.

Another user agreed and added that "We can be happy that [Emacs Dev does not
just tell users] `Do not use this'."

To which, ironically, the response was in fact to "document" it by just telling
users "Do not set it."

Bug #13823 is an attempt to get beyond that reaction constructively.

You asked me to come up with a description of what it does.  I proposed some
text based on my understanding, inviting correction.  Dunno whether you even
read it.

Your response was to tell me I should not assume you know more about this than
I, and that I should anyway just ask that it be properly documented.  So one
more time:

"Could we have it be properly documented, please?"

It is the only standard symbol property listed in (elisp) `Standard Properties'
about which we say virtually nothing and for which there is no cross reference
to a section that covers it.

bug#13823: 24.3.50; Elisp manual description of property `pure'

[Richard Stallman]

Since the Emacs source code is published free software,
it is impossible for us to "withhold" any information about it.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call

bug#13823: 24.3.50; Elisp manual description of property `pure'

[Christopher Schmidt]

Stefan Monnier <monnier@iro.umontreal.ca> writes:
> Sounds OK.  Feel free to put it in.

I did this, r112066.

        Christopher