bug#20737: 25.0.50; doc of `process-file'

bug#20737: 25.0.50; doc of `process-file'

[Drew Adams]

The parameters are not described correctly.

This is the complete description/explanation of INFILE and BUFFER:

 File names in INFILE and BUFFER are handled normally, but file
 names in ARGS should be relative to `default-directory', as they
 are passed to the process verbatim.  (This is a difference to
 `call-process' which does not support file handlers for INFILE
 and BUFFER.)

What does that even mean?  One might deduce that INFILE, BUFFER, and
ARGS are lists that can contain file names (and perhaps other stuff),
but that's about all.  What their structure is or what they are for are
completely unknown.

And this is all that is said about parameter DISPLAY:

 Some file handlers might not support all variants, for example
 they might behave as if DISPLAY was nil, regardless of the actual
 value passed.

That tells you less than nothing.

This is really useless doc.  Please do something to document
`process-file' properly.


In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2014-10-20 on LEG570
Bzr revision: 118168 rgm@gnu.org-20141020195941-icp42t8ttcnud09g
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --enable-checking=yes,glyphs CPPFLAGS=-DGLYPH_DEBUG=1'

bug#20737: 25.0.50; doc of `process-file'

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> The parameters are not described correctly.
>
> This is the complete description/explanation of INFILE and BUFFER:
>
>  File names in INFILE and BUFFER are handled normally, but file
>  names in ARGS should be relative to `default-directory', as they
>  are passed to the process verbatim.  (This is a difference to
>  `call-process' which does not support file handlers for INFILE
>  and BUFFER.)
>
> What does that even mean?  One might deduce that INFILE, BUFFER, and
> ARGS are lists that can contain file names (and perhaps other stuff),
> but that's about all.  What their structure is or what they are for are
> completely unknown.
>
> And this is all that is said about parameter DISPLAY:
>
>  Some file handlers might not support all variants, for example
>  they might behave as if DISPLAY was nil, regardless of the actual
>  value passed.
>
> That tells you less than nothing.
>
> This is really useless doc.  Please do something to document
> `process-file' properly.

`process-file' seems to be a shim over `call-process', but:

----
Similar to `call-process', but may invoke a file handler based on
`default-directory'.  The current working directory of the
subprocess is `default-directory'.
----

I think the rest of the doc string tries to say what's different in the
arguments between `process-file' and `call-process', but it kinda fails
at doing that.  Especially since ARGS and DISPLAY are just passed on to
`call-process' verbatim in the default case.

So somebody who knows what this function is meant to be doing (I've
never heard of it before now) should take another crack at writing a new
doc string.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#20737: 25.0.50; doc of `process-file'

[Lars Ingebrigtsen]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> So somebody who knows what this function is meant to be doing (I've
> never heard of it before now) should take another crack at writing a new
> doc string.

This was fixed in

commit 2e8825d6c55409c15749b12dacc1f49f9c8783c7
Author:     Eli Zaretskii <eliz@gnu.org>
AuthorDate: Sat Dec 29 17:34:57 2018 +0200

and

commit 0b47d731c08d0d5d4ba4a0c31f9be1152fd8c2c8
Author:     Paul Eggert <eggert@cs.ucla.edu>
AuthorDate: Sun Nov 17 15:26:55 2019 -0800

and the doc string seems pretty clear to me now.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no