GNU bug report logs - #52334
26.3; Doc string of `process-file'

Previous Next

To reply to this bug, email your comments to 52334 AT debbugs.gnu.org.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: "bug-gnu-emacs <at> gnu.org" <bug-gnu-emacs <at> gnu.org>
Subject: 26.3; Doc string of `process-file'
Date: Mon, 6 Dec 2021 18:57:52 +0000

1. The doc string includes this:

 File names in INFILE and BUFFER are handled normally, but file
 names in ARGS should be relative to `default-directory'...

This doesn't at all specify what args INFILE and BUFFER are.  What does
"handled normally" mean?  Presumably it means that such file names are
something from relative file names.  That something isn't called out.

But more importantly, what are INFILE and BUFFER, besides the hint that
they can (but need not?) contain some (absolute?) file names?

The mention of `call-process' might lead a reader to hope for a
description of INFILE and BUFFER there, and then hope that the same
applies to `process-file'.  There's an INFILE arg described there, but
no BUFFER arg.

Please consider making the doc string of `process-file' complete.
It should be standalone, or it should explicitly refer to some other doc
for descriptions of some of its args.

Maybe something like this (?):

* For INFILE, repeat what `call-process' says:

 The program's input comes from file INFILE (nil means `null-device').

* For BUFFER, adjust what `call-process' says for a buffer DESTINATION:

 Output is inserted in BUFFER (current buffer if BUFFER is `t').

2. Args DISPLAY and ARGS are also unspecified in the doc string.
___

I suggest that someone familiar with `process-file' and `call-process'
fix the former's doc string.  If it makes sense for it to refer to the
doc string of `call-process', fine, but please do that explicitly and
clearly.

Someone with little knowledge should be able to grok what this
function's args are about - what they can be and how they're handled.


In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32)
 of 2019-08-29
Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd
Windowing system distributor `Microsoft Corp.', version 10.0.19042
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.