Re: Predicate for true lists

[Eli Zaretskii <eliz@gnu.org>]

> From: "Basil L. Contovounesios" <contovob@tcd.ie>
> Cc: Alex Branham <branham@utexas.edu>,  Eli Zaretskii <eliz@gnu.org>,  monnier@iro.umontreal.ca,  emacs-devel@gnu.org
> Date: Wed, 17 Apr 2019 18:56:40 +0100
> 
> --- 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
> +@cindex side effect
> +@cindex 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.
> +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.

The index entry "side effect" here means that this term is explained.
But the text doesn't live up to that promise, it just gives an
example.  Can we add a more general explanation?

> +@cindex @code{side-effect-free}
> +@cindex @code{pure}
> +@vindex side-effect-free-fns
> +@vindex side-effect-and-error-free-fns

Some of these index entries are redundant, because they start with the
same string and point to the same place in the manual.

Also, you already have an index entry "pure" elsewhere.  If you think
there should be another one that points here, please qualify one or
both, so that the entries will be different.  having identical index
entries gets in the way when you type "i foo TAB" and are
presented with completion candidates "foo" and "foo<1>", with no way
of telling which one do you want.

> +  If you define a function which is side-effect free and/or pure, give
> +it a non-@code{nil} @code{side-effect-free} and/or @code{pure}
> +property, respectively (@pxref{Standard Properties}).  Alternatively,
> +you can update the code in @file{byte-opt.el} that binds
> +@code{side-effect-free-fns} and @code{side-effect-and-error-free-fns},
> +but this approach is less modular and no longer encouraged.

I don't think we need to tell in the manual when to modify the
sources, so I think the last sentence should be removed.

> --- a/doc/lispref/macros.texi
> +++ b/doc/lispref/macros.texi
> @@ -523,6 +523,7 @@ Eval During Expansion
>  
>  @node Repeated Expansion
>  @subsection How Many Times is the Macro Expanded?
> +@cindex side effect

Once again, a duplicate index entry without qualifications.

> --- a/doc/lispref/symbols.texi
> +++ b/doc/lispref/symbols.texi
> @@ -558,9 +558,12 @@ Standard Properties
>  modes.  @xref{Setting Hooks}.
>  
>  @item pure
> +@cindex @code{pure}

Likewise.

> @@ -579,9 +582,13 @@ Standard Properties
>  for the named variable.  @xref{File Local Variables}.
>  
>  @item side-effect-free
> +@cindex @code{side-effect-free}

And again.

Thanks.