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

Previous Next

Full log

Message #25 received at 54191 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Michael Albinus <michael.albinus <at> gmx.de>
Cc: "54191 <at> debbugs.gnu.org" <54191 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#54191: 26.3; (elisp) `Magic File Names'
 FILENAME parameters: absolute names?
Date: Mon, 28 Feb 2022 16:26:00 +0000

> > 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.