bug#54191: 26.3; (elisp) `Magic File Names' FILENAME parameters: absolute names?

bug#54191: 26.3; (elisp) `Magic File Names' FILENAME parameters: absolute names?

[Drew Adams]

I check this Elisp manual node for `file-remote-p'.  I try to figure out
just what kind of file name is expected by the function.  No clue.  Same
thing when I check the `C-h f' help (where the arg is called FILE).

How am I to know what kind of file name needs to be passed to this
function, e.g., whether I might need to first use `expand-file-name'?

There might be more nodes with this problem under node `Files'; dunno.
But at least please check this node and make its occurrences of FILENAME
parameters clear in this regard.
___

From the `C-h f' help I follow the files.el link to the `file-remote-p'
definition.  There I see that `find-file-name-handler' accepts the arg
FILE.  So the question then becomes what kind of file name (absolute or
not) is expected/accepted by `find-file-name-handler'.

`C-h f find-file-name-handler', likewise, says nothing about whether
the name needs to be absolute.  I look in the manual again, at a higher
level, node `Files', hoping to maybe see some intro text saying that,
by default, when the doc here talks about a file name it means an
absolute file name (or a relative file name) - something, to let me
know how to interpret all of the many references to file names in the
13 child nodes of node `Files'.  I find no such general statement.

If there is no general statement about how to understand a FILENAME
arg then the description of each function that accepts a FILENAME arg
should make clear what kind of name is expected.  (And that's anyway
preferable to expecting a reader to have come across a general default
statement of how such parameters are to be understood.
___

Grepping the Elisp sources, and looking for `expand-file-name', I came
across this in the definition of command `cd':

(and (file-remote-p (expand-file-name dir))
     (file-accessible-directory-p (expand-file-name dir))
     (expand-file-name dir))

And that leads me to believe that `file-remote-p' doesn't, itself,
expand the FILENAME argument.  This info shouldn't be so hard to find.
The descriptions of functions that accept a file-name arg should say
whether they expect an absolute file name.

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.19043
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

bug#54191: 26.3; (elisp) `Magic File Names' FILENAME parameters: absolute names?

[Drew Adams]

OK, I see that the doc string of `file-remote-p' -
but NOT its description in the Elisp manual - does
at least call out what happens if the arg FILE is
a relative file name: the function just returns nil.

That doesn't invalidate the rest of what this bug
report says.  Each function's description should say
what kind of file-name argument it expects, and if
it handles both relative and absolute file names,
how it does so - how it treats each kind.

Users shouldn't have to search the Elisp code base
to try to figure out whether they might need to
apply `expand-file-name' to a file name before
passing it to some function.

bug#54191: 26.3; (elisp) `Magic File Names' FILENAME parameters: absolute names?

[Michael Albinus]

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

Hi Drew,

> OK, I see that the doc string of `file-remote-p' -
> but NOT its description in the Elisp manual - does
> at least call out what happens if the arg FILE is
> a relative file name: the function just returns nil.
>
> That doesn't invalidate the rest of what this bug
> report says.  Each function's description should say
> what kind of file-name argument it expects, and if
> it handles both relative and absolute file names,
> how it does so - how it treats each kind.

We could discuss forever, whether this information is needed in the
Elisp manual. In my understanding, the manual is not an "extended
docstring". It is rather meant to give another view, with the help of
examples etc. IIRC, it isn't said anywhere, that a manual entry must be
comprehensive w/o the docstring.

> Users shouldn't have to search the Elisp code base
> to try to figure out whether they might need to
> apply `expand-file-name' to a file name before
> passing it to some function.

There's no need to read the implementation. The docstring of
file-remote-p is clear about this point.

Best regards, Michael.

bug#54191: 26.3; (elisp) `Magic File Names' FILENAME parameters: absolute names?

[Lars Ingebrigtsen]

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

> I check this Elisp manual node for `file-remote-p'.  I try to figure out
> just what kind of file name is expected by the function.  No clue.  Same
> thing when I check the `C-h f' help (where the arg is called FILE).
>
> How am I to know what kind of file name needs to be passed to this
> function, e.g., whether I might need to first use `expand-file-name'?

In Emacs 29 (at least), this section includes examples like:

     This identifier string can include a host name and a user name, as
     well as characters designating the method used to access the remote
     system.  For example, the remote identifier string for the file
     name ‘/sudo::/some/file’ is ‘/sudo:root@localhost:’.

So I think that's clear enough, and I'm closing this bug report.

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

bug#54191: 26.3; (elisp) `Magic File Names' FILENAME parameters: absolute names?

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> Date: Sun, 27 Feb 2022 21:30:22 +0000
> 
> I check this Elisp manual node for `file-remote-p'.  I try to figure out
> just what kind of file name is expected by the function.  No clue.  Same
> thing when I check the `C-h f' help (where the arg is called FILE).
> 
> How am I to know what kind of file name needs to be passed to this
> function, e.g., whether I might need to first use `expand-file-name'?
> 
> There might be more nodes with this problem under node `Files'; dunno.
> But at least please check this node and make its occurrences of FILENAME
> parameters clear in this regard.
> ___
> 
> >From the `C-h f' help I follow the files.el link to the `file-remote-p'
> definition.  There I see that `find-file-name-handler' accepts the arg
> FILE.  So the question then becomes what kind of file name (absolute or
> not) is expected/accepted by `find-file-name-handler'.

The first paragraph of the node "Magic File Names" says:

  The principal use for this feature is in implementing access to
  remote files (*note Remote Files: (emacs)Remote Files.).

Did you follow the cross-reference?  Because there you'd find the
answer to your question, loud and clear.

bug#54191: 26.3; (elisp) `Magic File Names' FILENAME parameters: absolute names?

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> Date: Sun, 27 Feb 2022 22:42:39 +0000
> 
> Users shouldn't have to search the Elisp code base
> to try to figure out whether they might need to
> apply `expand-file-name' to a file name before
> passing it to some function.

It goes without saying that _every_ file-related function in Emacs
accepts _any_ kind of file names: absolute, relative, you name it.
What each function _does_ with each kind of file name is a different
matter.  In the specific case of file-remote-p this is described both
in the doc string and in the manual.

bug#54191: [External] : Re: bug#54191: 26.3; (elisp) `Magic File Names' FILENAME parameters: absolute names?

[Drew Adams]

> > OK, I see that the doc string of `file-remote-p' -
> > but NOT its description in the Elisp manual - does
> > at least call out what happens if the arg FILE is
> > a relative file name: the function just returns nil.
> >
> > That doesn't invalidate the rest of what this bug
> > report says.  Each function's description should say
> > what kind of file-name argument it expects, and if
> > it handles both relative and absolute file names,
> > how it does so - how it treats each kind.
> 
> We could discuss forever, whether this information is needed in the
> Elisp manual. In my understanding, the manual is not an "extended
> docstring". It is rather meant to give another view, with the help of
> examples etc. IIRC, it isn't said anywhere, that a manual entry must be
> comprehensive w/o the docstring.

I don't disagree that the manual need not say the
same things as a doc string.  Sometimes it should
say more, sometimes less, sometimes something
different (but not contradictory).

The "rest of what this bug report says" is not that
the manual is missing something the doc strings say.

Neither the manual nor the doc strings (except
`file-remote-p', at least) state that the file name
is expected to be absolute - or more precisely say
what the behavior is for absolute vs relative.  But
that info is important for using the functions, IMO.

All I was saying there was that (1) the doc string
of `file-remote-p' does in fact say what happens
differently for a relative file name - which is good,
helpful, and (2) I noticed this happy exception after
filing the general report that the doc (strings &
manual) generally does NOT mention what kind of file
name is expected, for functions that accept a file name.

That general lack is the reported bug.  That there
are happy exceptions doesn't mean there aren't places
where the doc (strings or manual or both) can be
clarified to specify this.

> > Users shouldn't have to search the Elisp code base
> > to try to figure out whether they might need to
> > apply `expand-file-name' to a file name before
> > passing it to some function.
> 
> There's no need to read the implementation. The docstring of
> file-remote-p is clear about this point.

We agree, and that's exactly what I said in the mail
you replied to.  And thank you to whoever included
that info in that particular doc string.

bug#54191: [External] : Re: bug#54191: 26.3; (elisp) `Magic File Names' FILENAME parameters: absolute names?

[Drew Adams]

> > Users shouldn't have to search the Elisp code base
> > to try to figure out whether they might need to
> > apply `expand-file-name' to a file name before
> > passing it to some function.
> 
> It goes without saying that _every_ file-related function in Emacs
> accepts _any_ kind of file names: absolute, relative, you name it.

No, it doesn't go without saying.

More importantly, I didn't say "accept", I said
"expect".  Users should be able to find out what
the behavior is in each case: relative or absolute.

> What each function _does_ with each kind of file name 
> is a different matter.

Yes, and that's exactly what I wrote about.  The
behavior for each kind of file name should be
declared.  That's the point of the bug report.

> In the specific case of file-remote-p this is described
> both in the doc string and in the manual.

No, not the manual, I think (unless it was added
recently).

But the doc string, yes - it clearly calls out
the different behavior for a relative file name.
And that's exactly what I added in my second msg.

But that's NOT the case for other functions
(in this & other nodes of the manual, and in
doc strings).

That's what the bug report is about: doing just
what you said: describe what the function does
with each kind of file name.

bug#54191: [External] : Re: bug#54191: 26.3; (elisp) `Magic File Names' FILENAME parameters: absolute names?

[Drew Adams]

> The first paragraph of the node "Magic File Names" says:
> 
>   The principal use for this feature is in implementing access to
>   remote files (*note Remote Files: (emacs)Remote Files.).
> 
> Did you follow the cross-reference?  Because there you'd find the
> answer to your question, loud and clear.

I don't think it does.  No mention of absolute or
relative in that node.

But as I said in my second msg, there's no problem
for the `file-remote-p' doc string.

And it's not just about `file-remote-p'.  The
problem is more general, as reported.  And the
general problem involves doc strings and manual.
___

(Also, the Magic... node uses FILENAME for the
file-name parameter for some functions and FILE
for others.  Not important, but consistency, at
least locally to a node, wouldn't hurt.) 

bug#54191: [External] : Re: bug#54191: 26.3; (elisp) `Magic File Names' FILENAME parameters: absolute names?

[Drew Adams]

> > How am I to know what kind of file name needs to be passed to this
> > function, e.g., whether I might need to first use `expand-file-name'?
> 
> In Emacs 29 (at least), this section includes examples like:
> 
>      This identifier string can include a host name and a user name, as
>      well as characters designating the method used to access the
>      remote system.  For example, the remote identifier string for the
>      file name ‘/sudo::/some/file’ is ‘/sudo:root@localhost:’.

That says nothing about what happens if you pass a
relative file name.

How is it clear from what you cite what the
behavior is for a relative or absolute name?

Even if you think it does say that (I don't), that
text applies only to `file-remote-p'.  The bug
report applies generally, to functions that accept
file-name arguments.

> So I think that's clear enough, and I'm closing this bug report.

Alas.

bug#54191: [External] : Re: bug#54191: 26.3; (elisp) `Magic File Names' FILENAME parameters: absolute names?

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> CC: "54191@debbugs.gnu.org" <54191@debbugs.gnu.org>
> Date: Mon, 28 Feb 2022 16:26:30 +0000
> 
> > The first paragraph of the node "Magic File Names" says:
> > 
> >   The principal use for this feature is in implementing access to
> >   remote files (*note Remote Files: (emacs)Remote Files.).
> > 
> > Did you follow the cross-reference?  Because there you'd find the
> > answer to your question, loud and clear.
> 
> I don't think it does.  No mention of absolute or
> relative in that node.

It _shows_ them.

> And it's not just about `file-remote-p'.  The
> problem is more general, as reported.  And the
> general problem involves doc strings and manual.

There's no more general problem here.

bug#54191: [External] : Re: bug#54191: 26.3; (elisp) `Magic File Names' FILENAME parameters: absolute names?

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> CC: "54191@debbugs.gnu.org" <54191@debbugs.gnu.org>
> Date: Mon, 28 Feb 2022 16:26:24 +0000
> 
> > > Users shouldn't have to search the Elisp code base
> > > to try to figure out whether they might need to
> > > apply `expand-file-name' to a file name before
> > > passing it to some function.
> > 
> > It goes without saying that _every_ file-related function in Emacs
> > accepts _any_ kind of file names: absolute, relative, you name it.
> 
> No, it doesn't go without saying.
> 
> More importantly, I didn't say "accept", I said
> "expect".

These functions don't "expect" anything.  They handle any kind of file
names.

> Users should be able to find out what
> the behavior is in each case: relative or absolute.

The behavior is the same: each function does its documented job and
returns the advertised value.

> > What each function _does_ with each kind of file name 
> > is a different matter.
> 
> Yes, and that's exactly what I wrote about.  The
> behavior for each kind of file name should be
> declared.  That's the point of the bug report.

Then there's no bug, because this particular function's behavior is
documented.

> > In the specific case of file-remote-p this is described
> > both in the doc string and in the manual.
> 
> No, not the manual, I think (unless it was added
> recently).

Yes, in the manual as well.

> That's what the bug report is about: doing just
> what you said: describe what the function does
> with each kind of file name.

We already did.

bug#54191: [External] : Re: bug#54191: 26.3; (elisp) `Magic File Names' FILENAME parameters: absolute names?

[Drew Adams]

> > > Did you follow the cross-reference?  Because there you'd find the
> > > answer to your question, loud and clear.
> >
> > I don't think it does.  No mention of absolute or
> > relative in that node.
> 
> It _shows_ them.

I don't see any showing of a relative file name.
Can you point to one there?

> > And it's not just about `file-remote-p'.  The
> > problem is more general, as reported.  And the
> > general problem involves doc strings and manual.
> 
> There's no more general problem here.

FILENAME in `Remote Files'
FILENAME and FILE in `Magic File Names'
FILENAME in `Visiting Functions'
FILENAME in `Subroutines of Visiting'
FILENAME in `Saving Buffers'
FILENAME in `Reading from Files'
FILENAME in `Writing to Files'
FILENAME and FILE in `File Locks'
...
and so on - lots of places.

Similarly, doc strings of functions that
accept file-name args.  It's _not_ obvious
what the behavior is.

And yes, some functions do automatically
apply `expand-file-name' to a FILE(NAME) arg.

The question of whether a function does that,
and more generally how a function handles a
relative vs absolute file-name arg, is not
nothing.

bug#54191: [External] : Re: bug#54191: 26.3; (elisp) `Magic File Names' FILENAME parameters: absolute names?

[Drew Adams]

> They handle any kind of file names.

The question is how they handle them - how they
handle relative vs absolute names.

> > Users should be able to find out what
> > the behavior is in each case: relative or absolute.
> 
> The behavior is the same: each function does its documented job and
> returns the advertised value.

It no doubt does what's documented.  But if
what's documented is incomplete, then so will
be your understanding of what the function does.

> > > What each function _does_ with each kind of file name
> > > is a different matter.
> >
> > Yes, and that's exactly what I wrote about.  The
> > behavior for each kind of file name should be
> > declared.  That's the point of the bug report.
> 
> Then there's no bug, because this particular function's behavior is
> documented.

In the doc string.  Not in the manual.

And (for the Nth time), this bug report isn't
about "this particular function".  I couldn't
be clearer about that. 
> 
> > > In the specific case of file-remote-p this is described
> > > both in the doc string and in the manual.
> >
> > No, not the manual, I think (unless it was added
> > recently).
> 
> Yes, in the manual as well.

Where?  As one reader, I don't see that.

And again, this bug report is _not_ about
`file-remote-p'.

> > That's what the bug report is about: doing just
> > what you said: describe what the function does
> > with each kind of file name.
> 
> We already did.

I disagree.  I wouldn't have filed the bug
report if that were the case. 

bug#54191: [External] : Re: bug#54191: 26.3; (elisp) `Magic File Names' FILENAME parameters: absolute names?

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> CC: "54191@debbugs.gnu.org" <54191@debbugs.gnu.org>
> Date: Mon, 28 Feb 2022 17:22:09 +0000
> 
> > > > Did you follow the cross-reference?  Because there you'd find the
> > > > answer to your question, loud and clear.
> > >
> > > I don't think it does.  No mention of absolute or
> > > relative in that node.
> > 
> > It _shows_ them.
> 
> I don't see any showing of a relative file name.

Exactly.

> > > And it's not just about `file-remote-p'.  The
> > > problem is more general, as reported.  And the
> > > general problem involves doc strings and manual.
> > 
> > There's no more general problem here.
> 
> FILENAME in `Remote Files'
> FILENAME and FILE in `Magic File Names'
> FILENAME in `Visiting Functions'
> FILENAME in `Subroutines of Visiting'
> FILENAME in `Saving Buffers'
> FILENAME in `Reading from Files'
> FILENAME in `Writing to Files'
> FILENAME and FILE in `File Locks'
> ...
> and so on - lots of places.

These are just references to file names.  How is that a problem?

> Similarly, doc strings of functions that
> accept file-name args.  It's _not_ obvious
> what the behavior is.

When you type a file name as an argument to a shell command, like
this:

  my-program my-file

what do you expect my-program to do when my-file is not an absolute
file name?  How do you expect it to interpret such a file name?

> And yes, some functions do automatically
> apply `expand-file-name' to a FILE(NAME) arg.

Some?

Anyway, that's the implementation.  We aren't talking about the
implementation.

> The question of whether a function does that,
> and more generally how a function handles a
> relative vs absolute file-name arg, is not
> nothing.

From "File Names" in the Emacs user manual:

                                 Emacs always assumes that any relative
  file name is relative to the default directory, e.g., entering a file
  name without a directory specifies a file in the default directory.

This is so central to Emacs handling of file names that I'm astonished
that someone who uses Emacs and programs for Emacs for so many years
doesn't know that.

bug#54191: [External] : Re: bug#54191: 26.3; (elisp) `Magic File Names' FILENAME parameters: absolute names?

[Drew Adams]

> > > > No mention of absolute or relative in that node.
> > >
> > > It _shows_ them.
> >
> > I don't see any showing of a relative file name.
> 
> Exactly.

 ez> It shows them [absolute & relative file names].
 da>> I don't see it showing relative names.
 ez>>> Exactly.

Wow.

Showing only absolute names doesn't say what
happens when a relative name is passed.

> > > There's no more general problem here.
> >
> > FILENAME in `Remote Files'
> > FILENAME and FILE in `Magic File Names'
> > FILENAME in `Visiting Functions'
> > FILENAME in `Subroutines of Visiting'
> > FILENAME in `Saving Buffers'
> > FILENAME in `Reading from Files'
> > FILENAME in `Writing to Files'
> > FILENAME and FILE in `File Locks'
> > ...
> > and so on - lots of places.
> 
> These are just references to file names.  How is that a problem?

As the bug report requests: The doc should say
how the function handles relative and absolute
file-name args.  ("How" meaning what it does,
not "how" meaning the function's implementation.)

It's a problem that we don't tell users this.

> Anyway, that's the implementation.  We aren't 
> talking about the implementation.

??

We're talking about the behavior of a function;
specifically, how it handles a file-name arg
that is a relative or an absolute name.

We're not (I'm not) talking about how the
function is implemented.  We're (I am) talking
about its _behavior_ - what it does.

> > The question of whether a function does that,
> > and more generally how a function handles a
> > relative vs absolute file-name arg, is not
> > nothing.
> 
> From "File Names" in the Emacs user manual:
> 
>   Emacs always assumes that any relative file name
>   is relative to the default directory, e.g., entering a file
>   name without a directory specifies a file in the default directory.
> 
> This is so central to Emacs handling of file names that I'm astonished
> that someone who uses Emacs and programs for Emacs for so many years
> doesn't know that.

You know that I do know that. But you just love
to poke, don't you, Eli?

That text is irrelevant to this bug report.  No
one said that we don't tell users what relative
and absolute file names are, or that a relative
name is by default resolved using the value of
`default-directory'.

And you omitted the context of that sentence:

 "Whenever Emacs reads a file name using the
  minibuffer"

That context is irrelevant to this bug.  But
I think you realize that.  This bug is about
documenting the behavior of functions that
accept file-name arguments - calling out what
they do for a relative vs absolute name.

It's clear that you don't want to fix this bug.
Fine; though that's too bad.

But you apparently want to go on and on about
this, even though the bug was closed.  I've
felt obliged to respond to your extraneous,
irrelevant arguments.  I hope you're done with
them now - please consider giving it a rest.
We both deserve that, I think.

bug#54191: [External] : Re: bug#54191: 26.3; (elisp) `Magic File Names' FILENAME parameters: absolute names?

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> CC: "54191@debbugs.gnu.org" <54191@debbugs.gnu.org>
> Date: Mon, 28 Feb 2022 18:32:15 +0000
> 
> > > > > No mention of absolute or relative in that node.
> > > >
> > > > It _shows_ them.
> > >
> > > I don't see any showing of a relative file name.
> > 
> > Exactly.
> 
>  ez> It shows them [absolute & relative file names].
>  da>> I don't see it showing relative names.
>  ez>>> Exactly.
> 
> Wow.
> 
> Showing only absolute names doesn't say what
> happens when a relative name is passed.

It tells you what are remote file names.

> > > FILENAME in `Remote Files'
> > > FILENAME and FILE in `Magic File Names'
> > > FILENAME in `Visiting Functions'
> > > FILENAME in `Subroutines of Visiting'
> > > FILENAME in `Saving Buffers'
> > > FILENAME in `Reading from Files'
> > > FILENAME in `Writing to Files'
> > > FILENAME and FILE in `File Locks'
> > > ...
> > > and so on - lots of places.
> > 
> > These are just references to file names.  How is that a problem?
> 
> As the bug report requests: The doc should say
> how the function handles relative and absolute
> file-name args.

I explained how.  Let me repeat:

                                 Emacs always assumes that any relative
  file name is relative to the default directory, e.g., entering a file
  name without a directory specifies a file in the default directory.

> > Anyway, that's the implementation.  We aren't 
> > talking about the implementation.
> 
> ??
> 
> We're talking about the behavior of a function;

Saying that it calls expand-file-name is not describing the behavior,
it describes the implementation which leads to the behavior.

> specifically, how it handles a file-name arg
> that is a relative or an absolute name.

It handles them like every reasonable person will expect: relative
file names are interpreted relative to the default directory.  You
want this to be told and retold, time and again, with every function
we document?  We say that once, and that should be enough, especially
since the Emacs handling of relative file names is the only reasonable
and natural handling of such file names.

> > From "File Names" in the Emacs user manual:
> > 
> >   Emacs always assumes that any relative file name
> >   is relative to the default directory, e.g., entering a file
> >   name without a directory specifies a file in the default directory.
> > 
> > This is so central to Emacs handling of file names that I'm astonished
> > that someone who uses Emacs and programs for Emacs for so many years
> > doesn't know that.
> 
> You know that I do know that.

You do?  Then why do you keep asking about it as if you don't, as if
you are confused, and as if this is undocumented?

> That text is irrelevant to this bug report.  No
> one said that we don't tell users what relative
> and absolute file names are, or that a relative
> name is by default resolved using the value of
> `default-directory'.

There's nothing else to say about "behavior with absolute and relative
file names", certainly not in general.

> And you omitted the context of that sentence:
> 
>  "Whenever Emacs reads a file name using the
>   minibuffer"

No, it's you who omitted the context.  The full quotation is this:

                     Regardless, Emacs always assumes that any relative
  file name is relative to the default directory, e.g., entering a file
  name without a directory specifies a file in the default directory.

"Regardless", i.e. not just with respect to entering file names in the
minibuffer, but in general.

> It's clear that you don't want to fix this bug.
> Fine; though that's too bad.

There is no bug.  You just keep arguing for the sake of an argument,
although it should be clear to everyone that you have no case.

bug#54191: [External] : Re: bug#54191: 26.3; (elisp) `Magic File Names' FILENAME parameters: absolute names?

[Michael Albinus]

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

Hi Drew,


> Neither the manual nor the doc strings (except
> `file-remote-p', at least) state that the file name
> is expected to be absolute - or more precisely say
> what the behavior is for absolute vs relative.  But
> that info is important for using the functions, IMO.
>
> All I was saying there was that (1) the doc string
> of `file-remote-p' does in fact say what happens
> differently for a relative file name - which is good,
> helpful, and (2) I noticed this happy exception after
> filing the general report that the doc (strings &
> manual) generally does NOT mention what kind of file
> name is expected, for functions that accept a file name.
>
> That general lack is the reported bug.  That there
> are happy exceptions doesn't mean there aren't places
> where the doc (strings or manual or both) can be
> clarified to specify this.

Except the file-remote-p case, there is no need to say something special
about relative or absolute file names in case of file operations working
remotely. They simply work the same way in the local or remote case.

(If not it would be a bug.)

Best regards, Michael.