Subject: Re: bug#65156: 29.1; Reading from pipe with --insert or insert-file-contents no longer supported

From: Paul Eggert <[email-masked]>
Date: Wed, 9 Aug 2023 23:08:49 -0700

On 2023-08-09 22:17, Eli Zaretskii wrote:
>    If REPLACE is the symbol ‘if-regular’, then eschew preserving marker
>    positions or the undo list if REPLACE is nil if FILENAME is not a
>    regular file.  Otherwise, signal an error if REPLACE is non-nil and
>    FILENAME is not a regular file.
> 
> Which part(s) of this are unclear?

In "If REPLACE is the symbol 'if-regular', then <X> if REPLACE is nil if 
<Y>. Otherwise, ..." I don't know what the first sentence means. The "if 
REPLACE is nil" seems to contradict the "If REPLACE is the symbol 
'if-regular'" and the relationship between <X> and <Y> is unclear.

Nor do I know which "if" the "Otherwise" is referring to.

Nor is it easy to see how this paragraph connects to the previous one, 
the one that begins "If optional fifth argument REPLACE is non-nil" and 
that goes on to say "When REPLACE is non-nil" as if the second phrase 
were not redundant (so which part of that paragraph talks about what 
happens when REPLACE being nil?).

It's understandable that the doc string is a mess, since the code is 
messier. (Yes, this is the peanut gallery talking....)