Re: Predicate for true lists

[Basil L. Contovounesios]

How's the following updated patch?

>From 7bbcfcfc201d8a924b9f19abcc9307001b79ec86 Mon Sep 17 00:00:00 2001
From: "Basil L. Contovounesios" <address@hidden>
Date: Wed, 17 Apr 2019 16:34:47 +0100
Subject: [PATCH] Improve pure and side-effect-free docs

For discussion, see thread starting at:
https://lists.gnu.org/archive/html/emacs-devel/2019-04/msg00316.html
* doc/lispref/customize.texi (Composite Types): Do not overspecify
:match-alternatives predicates.
* doc/lispref/eval.texi (Intro Eval): Anchor definition of "side
effect" for cross-referencing...
* doc/lispref/functions.texi (What Is a Function): ...from here.
Define what a pure function is.
* doc/lispref/internals.texi (Writing Emacs Primitives): Describe
currently preferred approach to marking primitives as pure and
side-effect-free.
* doc/lispref/symbols.texi (Standard Properties): Expand description
of pure and side-effect-free properties.
---
 doc/lispref/customize.texi |  8 ++++----
 doc/lispref/eval.texi      |  1 +
 doc/lispref/functions.texi |  7 ++++++-
 doc/lispref/internals.texi |  7 +++----
 doc/lispref/symbols.texi   | 15 +++++++++++----
 5 files changed, 25 insertions(+), 13 deletions(-)

diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi
index f71dedfd8b..02eefe0f58 100644
--- a/doc/lispref/customize.texi
+++ b/doc/lispref/customize.texi
@@ -950,10 +950,10 @@ Composite Types
 
 @itemize @bullet
 @item
-A predicate---that is, a function of one argument that has no side
-effects, and returns either @code{nil} or address@hidden according to
-the argument.  Using a predicate in the list says that objects for which
-the predicate returns address@hidden are acceptable.
+A predicate---that is, a function of one argument that returns either
address@hidden or address@hidden according to the argument.  Using a
+predicate in the list says that objects for which the predicate
+returns address@hidden are acceptable.
 
 @item
 A quoted constant---that is, @code{'@var{object}}.  This sort of element
diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi
index db42dfb637..39c5a1ec50 100644
--- a/doc/lispref/eval.texi
+++ b/doc/lispref/eval.texi
@@ -87,6 +87,7 @@ Intro Eval
 (@pxref{Local Variables}).
 
 @cindex side effect
address@hidden of side effect}
   Evaluating a form may also make changes that persist; these changes
 are called @dfn{side effects}.  An example of a form that produces a
 side effect is @code{(setq foo 1)}.
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 222f863c98..97f7fb9f79 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -38,11 +38,16 @@ What Is a Function
 @cindex return value
 @cindex value of function
 @cindex argument
address@hidden pure function
   In a general sense, a function is a rule for carrying out a
 computation given input values called @dfn{arguments}.  The result of
 the computation is called the @dfn{value} or @dfn{return value} of the
 function.  The computation can also have side effects, such as lasting
-changes in the values of variables or the contents of data structures.
+changes in the values of variables or the contents of data structures
+(@pxref{Definition of side effect}).  A @dfn{pure function} is a
+function which, in addition to having no side effects, always returns
+the same value for the same combination of arguments, regardless of
+external factors such as machine type or system state.
 
   In most computer languages, every function has a name.  But in Lisp,
 a function in the strictest sense has no name: it is an object which
diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi
index fc5ce594e6..25892d4b57 100644
--- a/doc/lispref/internals.texi
+++ b/doc/lispref/internals.texi
@@ -1031,10 +1031,9 @@ Writing Emacs Primitives
 @file{lisp.h} contains the definitions for some important macros and
 functions.
 
-  If you define a function which is side-effect free, update the code
-in @file{byte-opt.el} that binds @code{side-effect-free-fns} and
address@hidden so that the compiler optimizer
-knows about it.
+  If you define a function which is side-effect free or pure, give it
+a address@hidden @code{side-effect-free} or @code{pure} property,
+respectively (@pxref{Standard Properties}).
 
 @node Writing Dynamic Modules
 @section Writing Dynamically-Loaded Modules
diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi
index a214a2d3fd..5d71fb39a2 100644
--- a/doc/lispref/symbols.texi
+++ b/doc/lispref/symbols.texi
@@ -558,9 +558,12 @@ Standard Properties
 modes.  @xref{Setting Hooks}.
 
 @item pure
address@hidden @code{pure} property
 If the value is address@hidden, the named function is considered to be
-side-effect free.  Calls with constant arguments can be evaluated at
-compile time.  This may shift run time errors to compile time.
+pure (@pxref{What Is a Function}).  Calls with constant arguments can
+be evaluated at compile time.  This may shift run time errors to
+compile time.  Not to be confused with pure storage (@pxref{Pure
+Storage}).
 
 @item risky-local-variable
 If the value is address@hidden, the named variable is considered risky
@@ -579,9 +582,13 @@ Standard Properties
 for the named variable.  @xref{File Local Variables}.
 
 @item side-effect-free
address@hidden @code{side-effect-free} property
 A address@hidden value indicates that the named function is free of
-side-effects, for determining function safety (@pxref{Function
-Safety}) as well as for byte compiler optimizations.  Do not set it.
+side effects (@pxref{What Is a Function}), so the byte compiler may
+ignore a call whose value is unused.  If the property's value is
address@hidden, the byte compiler may even delete such unused
+calls.  In addition to byte compiler optimizations, this property is
+also used for determining function safety (@pxref{Function Safety}).
 
 @item variable-documentation
 If address@hidden, this specifies the named variable's documentation
-- 
2.20.1

Thanks,

-- 
Basil