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

[Lars Ingebrigtsen <larsi@gnus.org>]

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