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

[Eli Zaretskii]

> Date: Wed, 9 Aug 2023 23:08:49 -0700
> Cc: mail@lucaswerkmeister.de, larsi@gnus.org, 65156@debbugs.gnu.org
> From: Paul Eggert <eggert@cs.ucla.edu>
> 
> 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.

I think it should be changed to say this instead:

  If REPLACE is the symbol ‘if-regular’, then eschew preserving marker
  positions or the undo list when FILENAME is not a regular file.
  Otherwise, signal an error if REPLACE is non-nil and FILENAME is not
  a regular file.

AFAICT, this is what the code does.

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

It alludes to the case that REPLACE is not 'if-regular'.

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

This describes what happens when REPLACE is neither nil nor
'if-regular', AFAICT.  IOW, the "smart" replacement happens only with
regular files; with non-regular files we either erase the buffer and
insert the stuff from the file (if REPLACE is 'if-regular') or signal
an error.

If you agree that this is what the doc string should say, I will
reword it (but feel free to beat me to that ;-).