Hmm, I thought I had already sent my reply to this, but I don't see it
anywhere; I must have dreamt it.

Eli Zaretskii <eliz@gnu.org> writes:

>> >From f42cb45f449dbb6c3d806398a128bc5914fdebab Mon Sep 17 00:00:00 2001
>> From: "Basil L. Contovounesios" <contovob@tcd.ie>
>> Date: Fri, 6 Jul 2018 00:41:11 +0300
>> Subject: [PATCH 1/3] Add convenience function proper-list-length
>> 
>> * lisp/subr.el (proper-list-length): New function.
>> Suggested by Paul Eggert <eggert@cs.ucla.edu> in
>> https://lists.gnu.org/archive/html/emacs-devel/2018-06/msg00138.html.
>> * doc/lispref/lists.texi (List Elements):
>> * etc/NEWS: Mention it.
>
> The "it" part here is ambiguous, because it's too far from the last
> place where the function's name was mentioned.  Please state the name
> of the function for better readability.
>
>> * lisp/emacs-lisp/byte-opt.el (byte-optimize-if):
>> * lisp/emacs-lisp/cl-macs.el (cl--make-usage-args):
>> * lisp/org/ob-core.el (org-babel-insert-result): Use it.
>
> Likewise.
>
>> * lisp/emacs-lisp/ert.el (ert--proper-list-p): Remove.
>> (ert--explain-equal-rec): Use proper-list-length instead.
>> * lisp/format.el (format-proper-list-p): Remove.
>
> Maybe consider mentioning that these are removed "because
> SUCH-AND-SUCH replaces them in file FOO."
>
>> +@defun proper-list-length object
>> +This function returns the length of @var{object} if it is a proper
>> +list, @code{nil} otherwise.  In addition to satisfying @code{listp}, a
>> +proper list is neither circular nor dotted.
>
> Proper list is defined elsewhere in the manual, so please add here a
> cross-reference to that spot (I'd suggest doing that with @pxref in
> parentheses at the end of the first sentence).

Done x4.

>> +** New function 'proper-list-length'.
>> +Given a proper list as argument, this function returns its length;
>> +otherwise, it returns nil.  This function can thus be used as a
>> +predicate for proper lists.
>
> Do we really want this usage of the function as a predicate?  I find
> this slightly unnatural, and also not future-proof enough, because you
> rely on the checks 'length' does internally.  If the internals of
> 'length' change one day, this predicate usage will collapse like a
> house of cards.  Would it make more sense to have a separate
> predicate?

My reading of the ensuing subthread is that it is okay to define
proper-list-p such that it relies on Flength's now-documented error
behaviour to return a proper list's length.

The only alternative I can think of (which avoids traversing a list
twice) is to write proper-list-p in C by duplicating the relevant parts
of Flength's current behaviour.  Any preferences?

By the way, is proper-list-p preferred over list-proper-p?

>> +(defun proper-list-length (object)
>> +  "Return OBJECT's length if it is a proper list, nil otherwise.
>> +A proper list is neither circular nor dotted (i.e., its last cdr
>> +is nil)."
>
> But if we do want to use this as a predicate, then the doc string
> should say so.

This isn't necessary if the function is called proper-list-p and is
documented under '(elisp) List-related Predicates', right?

>> * doc/lispref/lists.texi (Cons Cells, Building Lists):
>> * doc/lispref/sequences.texi (Vector Functions): Do it.
>
> Please put the full description in the log entry.  "Do it" refers to
> what the header says, I presume, but I at least am used to ignoring
> the headers and reading the entries, because they are generally more
> informative (due to space constraints on the header).

Done.

>> +@cindex proper list
>>  @cindex true list
>>    Also by convention, the @sc{cdr} of the last cons cell in a list is
>>  @code{nil}.  We call such a @code{nil}-terminated structure a
>> -@dfn{true list}.  In Emacs Lisp, the symbol @code{nil} is both a
>> +@dfn{proper list}.  In Emacs Lisp, the symbol @code{nil} is both a
>
> We still have "true list" in the index (and rightly so), so I think
> the new text should say, perhaps in parens or in a footnote, that such
> lists are also known as "true lists".  Imagine a reader who follows
> the "true list" index entry and gets placed on this text -- they will
> be confused to not see "true list" mentioned anywhere.  Besides, that
> term is in wide usage elsewhere.

Done as a footnote in the style of the first one under
'(elisp) Intro Eval'.

I reattach the three patches, updated also for Paul's feedback in
https://lists.gnu.org/archive/html/emacs-devel/2018-07/msg00149.html.

Thanks!

-- 
Basil