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

From: Drew Adams <[email-masked]>
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'.

`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''