Uncomprehensible DOC string

Uncomprehensible DOC string

[David Kastrup]

We have

    start-file-process is a compiled Lisp function in `simple.el'.

    (start-file-process name buffer program &rest program-args)

    Start a program in a subprocess.  Return the process object for it.
    Similar to `start-process', but may invoke a file handler based on
    `default-directory'.  The current working directory of the
    subprocess is `default-directory'.

    program and program-args might be file names.  They are not
    objects of file handler invocation.

There is no mention what it means to invoke a file handler, what calling
the file handler is supposed to be good for, what the file handler is
actually going to handle (we just know that it is chosen _based_ on
default-directory, not what it is supposed to work on), and there is no
cross reference to manual or other DOC strings that would explain about
what a file handler actually is.

Nobody will get _any_ clue about why he should use start-file-process
rather than start-process, and what will be affected in what manner.

-- 
David Kastrup

Re: Uncomprehensible DOC string

[Michael Albinus]

David Kastrup <dak@gnu.org> writes:

> There is no mention what it means to invoke a file handler, what calling
> the file handler is supposed to be good for, what the file handler is
> actually going to handle (we just know that it is chosen _based_ on
> default-directory, not what it is supposed to work on), and there is no
> cross reference to manual or other DOC strings that would explain about
> what a file handler actually is.

See (info "(elisp)Magic File Names") and (info "(elisp)Asynchronous Processes")
I'll add links to these entries into the doc string tonight.

Best regards, Michael.

Re: Uncomprehensible DOC string

[David Kastrup]

Michael Albinus <michael.albinus@gmx.de> writes:

> David Kastrup <dak@gnu.org> writes:
>
>> There is no mention what it means to invoke a file handler, what calling
>> the file handler is supposed to be good for, what the file handler is
>> actually going to handle (we just know that it is chosen _based_ on
>> default-directory, not what it is supposed to work on), and there is no
>> cross reference to manual or other DOC strings that would explain about
>> what a file handler actually is.
>
> See (info "(elisp)Magic File Names") and (info "(elisp)Asynchronous
> Processes") I'll add links to these entries into the doc string
> tonight.

That addresses the last partial sentence of my report.  What about the
rest?  There is no sense to leave a fragmentary explanation in the DOC
string when you need to read up the function's behavior elsewhere,
anyhow.  The manual reference should be there to explain the _terms_
used in the DOC string, but the DOC string should still be _complete_
once the terms are clear.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Uncomprehensible DOC string

[Michael Albinus]

David Kastrup <dak@gnu.org> writes:

> That addresses the last partial sentence of my report.  What about the
> rest?  There is no sense to leave a fragmentary explanation in the DOC
> string when you need to read up the function's behavior elsewhere,
> anyhow.  The manual reference should be there to explain the _terms_
> used in the DOC string, but the DOC string should still be _complete_
> once the terms are clear.

I'll try to be a little bit more comprehensive in the doc
string. However, I don't believe that the doc string of
`start-file-process' is the place to explain what are file name
handlers at all.

Best regards, Michael.

Re: Uncomprehensible DOC string

[David Kastrup]

Michael Albinus <michael.albinus@gmx.de> writes:

> David Kastrup <dak@gnu.org> writes:
>
>> That addresses the last partial sentence of my report.  What about the
>> rest?  There is no sense to leave a fragmentary explanation in the DOC
>> string when you need to read up the function's behavior elsewhere,
>> anyhow.  The manual reference should be there to explain the _terms_
>> used in the DOC string, but the DOC string should still be _complete_
>> once the terms are clear.
>
> I'll try to be a little bit more comprehensive in the doc
> string. However, I don't believe that the doc string of
> `start-file-process' is the place to explain what are file name
> handlers at all.

No, but saying a file name handler will be called based on
default-directory without telling what the file name handler is actually
supposed to be processing is not much use I think.  The command?  The
command line arguments?  The executable?

-- 
David Kastrup

Re: Uncomprehensible DOC string

[Michael Albinus]

David Kastrup <dak@gnu.org> writes:

> No, but saying a file name handler will be called based on
> default-directory without telling what the file name handler is actually
> supposed to be processing is not much use I think.  The command?  The
> command line arguments?  The executable?

_The_ file name handler, which belongs to `default-directory', will be
applied. Whether there is a file name handler for one of the
parameters of `start-file-process', is not relevant. This is
different wrt to other primitive functions, like `file-exists-p'.

Currently, there ought to be only one implementation of such a file
name handler, `tramp-handle-start-file-process'. _This_ file name
handler runs the command on the corresponding remote host. Arguments
are taken literally; it would be safe to use relative file names only
as arguments of the command.

Best regards, Michael.

Re: Uncomprehensible DOC string

[David Kastrup]

Michael Albinus <michael.albinus@gmx.de> writes:

> David Kastrup <dak@gnu.org> writes:
>
>> No, but saying a file name handler will be called based on
>> default-directory without telling what the file name handler is actually
>> supposed to be processing is not much use I think.  The command?  The
>> command line arguments?  The executable?
>
> _The_ file name handler, which belongs to `default-directory', will be
> applied.

To what will it be applied?

> Currently, there ought to be only one implementation of such a file
> name handler, `tramp-handle-start-file-process'. _This_ file name
> handler runs the command on the corresponding remote host.

So what the file name handler will be employed for is executing the
program on potentially remote host.  This information is _absent_ from
the DOC string, and it shouldn't.  In contrast, what a file name handler
_is_, is best left to the info documentation.

-- 
David Kastrup

Re: Uncomprehensible DOC string

[Michael Albinus]

David Kastrup <dak@gnu.org> writes:

>> _The_ file name handler, which belongs to `default-directory', will be
>> applied.
>
> To what will it be applied?

???

To the arguments auf `start-file-process', of course. Like every other
file name handler. That's why the doc strings says "Similar to
`start-process'".

>> Currently, there ought to be only one implementation of such a file
>> name handler, `tramp-handle-start-file-process'. _This_ file name
>> handler runs the command on the corresponding remote host.
>
> So what the file name handler will be employed for is executing the
> program on potentially remote host.  This information is _absent_ from
> the DOC string, and it shouldn't.  In contrast, what a file name handler
> _is_, is best left to the info documentation.

I will add a sentence that, when `default-directory' points to a
remote host, the command will run on that remote host. But this is
just an implementation note for Tramp; there could be other file name
handler implementations for `start-file-process' as well. Admittedly,
Tramp's implementation is the only one today.

Best regards, Michael.

Re: Uncomprehensible DOC string

[David Kastrup]

Michael Albinus <michael.albinus@gmx.de> writes:

> David Kastrup <dak@gnu.org> writes:
>
>>> _The_ file name handler, which belongs to `default-directory', will be
>>> applied.
>>
>> To what will it be applied?
>
> ???
>
> To the arguments auf `start-file-process', of course.

You just stated that it will _not_ be applied to all arguments of
start-file-process.

> Like every other file name handler. That's why the doc strings says
> "Similar to `start-process'".

Why would "every other" file name handler be applied to all arguments of
start-file-process?

One file name handler is chosen based on the _default_ directory (rather
than the executable name), and it is not applied to arguments of
start-file-process, but rather is used for starting the process with the
given arguments on the system indicated by the default directory.

At least that is what I think I understand.  What the word "file" in
"start-file-process" is supposed to be about, I have no clue whatsoever.
Something like "start-nonlocal-process" or "start-handled-process" or
"start-process-anywhere" seems to be more informative.

-- 
David Kastrup

Re: Uncomprehensible DOC string

[Michael Albinus]

David Kastrup <dak@gnu.org> writes:

>>>> _The_ file name handler, which belongs to `default-directory', will be
>>>> applied.
>>>
>>> To what will it be applied?
>>
>> ???
>>
>> To the arguments auf `start-file-process', of course.
>
> You just stated that it will _not_ be applied to all arguments of
> start-file-process.

I'm getting confused. Where did you read _this_?

>> Like every other file name handler. That's why the doc strings says
>> "Similar to `start-process'".
>
> Why would "every other" file name handler be applied to all arguments of
> start-file-process?

Please David, I have the impression you are twisting my
words. `start-file-process' is like `start-process', and mostly it
uses the implementation of `start-process' from process.c. In some
cases, when `default-directory' has an own file name handler, it uses
that implementation.

That does not change the fact, that both functions work over the same
set of arguments. And a user of `start-file-process' shall be prepared
for both cases, for example by using (file-relative-name file) for all
arguments of the process to be started, which are known to be a file.

> One file name handler is chosen based on the _default_ directory (rather
> than the executable name), and it is not applied to arguments of
> start-file-process, but rather is used for starting the process with the
> given arguments on the system indicated by the default directory.

I don't see the difference, for Tramp it sounds like the same. But one
could imagine another file name handler which does not run on "another
system", but runs the command locally, with other purposes.

One could imagine a `start-file-process' file name handler for URLs,
which makes local copies of the files, and applies then the command
using these saved files. On your local host.

> At least that is what I think I understand.  What the word "file" in
> "start-file-process" is supposed to be about, I have no clue whatsoever.
> Something like "start-nonlocal-process" or "start-handled-process" or
> "start-process-anywhere" seems to be more informative.

Me too. The function name was decided by Stefan. As usual, I don't
discuss names. See <http://thread.gmane.org/gmane.emacs.devel/73149>.

Anyway, "start-nonlocal-process" or "start-process-anywhere" might be
misleading as well, because the process is started locally via
`start-process', when `default-directory' does not have a file name
handler.

Stefan: I do NOT intend to discuss it again :-)

Best regards, Michael.