Re: Predicate for true lists

["Basil L. Contovounesios" <contovob@tcd.ie>]

Eli Zaretskii <eliz@gnu.org> writes:

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

Sorry, I think I misunderstood how these indices work, and was using
them to label relevant parts of the documentation, which should probably
be done with cross-references instead.

The phrase "side effect" is actually defined under (info "(elisp) Intro
Eval"), so I will remove this index entry.  Is the definition there
satisfactory and general enough?  If not, what is it missing?

Either way, can the explanation of side effects in (info "(elisp) What
Is a Function") remain as it is, perhaps with a cross-reference to the
definition in (info "(elisp) Intro Eval")?  If not, what is it missing?

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

I will remove all four of these index entries.  The first two because
the definitions of these properties are cross-referenced in the
following paragraph, and the latter two because the sentence referencing
them is to be removed.

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

OK.

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

Will remove.

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

This is where the property is defined.  If property names are not
usually indexed, I can remove this index entry.  Otherwise, is the
following qualification OK?

  @cindex @code{pure} property

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

Mutatis mutandis.

Thanks,

-- 
Basil