file-truename, convert-standard-filename

file-truename, convert-standard-filename

[Drew Adams]

It's not clear to me when to use `file-truename' and
`convert-standard-filename'.

I understand from the doc that:

* f-t gives a name that results from following symlinks (including through
ancestor dirs). 

* c-s-f gives a file name that fits the current OS. (So if a name is intended to
be independent of a particular OS, it should not be the result of calling
c-s-f.)

But in terms of use, if I want to, say, compare two file names to see if they
represent the same file, what's typically appropriate? Grepping the Emacs
sources didn't make any guidelines jump to my eyes. For defcustoms, for
instance, sometimes f-t is used; sometimes c-s-f is used.

I didn't notice any places in the sources where both were used together. But in
my ignorance and confusion, I'm trying this:

(string= (convert-standard-filename (file-truename file1))
         (convert-standard-filename (file-truename file2)))

(There are no predefined file-name equality predicates, are there?)

I'm sure there's a deeper level of identity that really compares the files
themselves - by inode or whatever. But I'm really looking just to compare names
of some kind, without accessing the files themselves.

(I'm posting this here instead of help-gnu-emacs because I'm guessing that maybe
the doc could be improved a bit to help with this.)

Re: file-truename, convert-standard-filename

[Andreas Schwab]

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

> It's not clear to me when to use `file-truename' and
> `convert-standard-filename'.

You never apply convert-standard-filename to the name of an existing
file, since by definition this file name already fits the current OS
(otherwise it would not exist).

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: file-truename, convert-standard-filename

[Lennart Borgman]

On Fri, Feb 5, 2010 at 7:15 PM, Andreas Schwab <schwab@linux-m68k.org> wrote:
> "Drew Adams" <drew.adams@oracle.com> writes:
>
>> It's not clear to me when to use `file-truename' and
>> `convert-standard-filename'.
>
> You never apply convert-standard-filename to the name of an existing
> file, since by definition this file name already fits the current OS
> (otherwise it would not exist).


No, that must be a misunderstanding. The file name used internally in
Emacs is not the file name used by the OS. convert-standard-file-name
translates from Emacs file name syntax to OS dito.

Re: file-truename, convert-standard-filename

[Andreas Schwab]

Lennart Borgman <lennart.borgman@gmail.com> writes:

> No, that must be a misunderstanding. The file name used internally in
> Emacs is not the file name used by the OS. convert-standard-file-name
> translates from Emacs file name syntax to OS dito.

That's not true.  You use convert-standard-filename for names like
".emacs" or ".dir-locals.el" which cannot exist on DOS-like filesystems.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: file-truename, convert-standard-filename

[Lennart Borgman]

On Fri, Feb 5, 2010 at 8:45 PM, Andreas Schwab <schwab@linux-m68k.org> wrote:
> Lennart Borgman <lennart.borgman@gmail.com> writes:
>
>> No, that must be a misunderstanding. The file name used internally in
>> Emacs is not the file name used by the OS. convert-standard-file-name
>> translates from Emacs file name syntax to OS dito.
>
> That's not true.  You use convert-standard-filename for names like
> ".emacs" or ".dir-locals.el" which cannot exist on DOS-like filesystems.


Hm, we must be misunderstanding each other. I thought that was part of
what I said. ... ;-)

Re: file-truename, convert-standard-filename

[Stefan Monnier]

>> You never apply convert-standard-filename to the name of an existing
>> file, since by definition this file name already fits the current OS
>> (otherwise it would not exist).
> No, that must be a misunderstanding.

Indeed, you misunderstand.

> The file name used internally in Emacs is not the file name used by
> the OS.  convert-standard-file-name translates from Emacs file name
> syntax to OS dito.

No, convert-stndard-filename is used for standard filenames like
"~/.emacs" to make them usable (so it may turn it into "~/.e#acs" on
those OSes where `m' is not allowed).


        Stefan

Re: file-truename, convert-standard-filename

[Lennart Borgman]

On Fri, Feb 5, 2010 at 9:14 PM, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
>
>> The file name used internally in Emacs is not the file name used by
>> the OS.  convert-standard-file-name translates from Emacs file name
>> syntax to OS dito.
>
> No, convert-stndard-filename is used for standard filenames like
> "~/.emacs" to make them usable (so it may turn it into "~/.e#acs" on
> those OSes where `m' is not allowed).


Yes, but that is not the whole story. On w32 you may have to convert
an internal Emacs file name to an OS dito.

   (convert-standard-file-name "c:/path/to/file.txt") => "c:\path\to\file.txt"

But I must have been misunderstanding someting since this is quite
obvious ... ;-)

Re: file-truename, convert-standard-filename

[Miles Bader]

Stefan Monnier <monnier@IRO.UMontreal.CA> writes:
> ... on those OSes where `m' is not allowed.

ooooh, let's support emacs on those OSes!
:/

-miles

-- 
Infancy, n. The period of our lives when, according to Wordsworth, 'Heaven
lies about us.' The world begins lying about us pretty soon afterward.

RE: file-truename, convert-standard-filename

[Drew Adams]

> You never apply convert-standard-filename to the name of an existing
> file, since by definition this file name already fits the current OS
> (otherwise it would not exist).

Which would not exist - the file or the file name?

How to know whether the name is for an existing file? Are you suggesting testing
it first using `file-exists-p', just to know whether to call c-s-f?

In the comparison I'm doing, I don't know what the file names to be compared
will be. I don't know whether they will correspond to existing files. I want to
compare the names without trying to access the files (or even call
`file-exists-p').

Sorry, I still don't quite understand.

Re: file-truename, convert-standard-filename

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Fri, 5 Feb 2010 09:31:54 -0800
> 
> It's not clear to me when to use `file-truename' and
> `convert-standard-filename'.
> 
> I understand from the doc that:
> 
> * f-t gives a name that results from following symlinks (including through
> ancestor dirs). 
> 
> * c-s-f gives a file name that fits the current OS. (So if a name is intended to
> be independent of a particular OS, it should not be the result of calling
> c-s-f.)

`convert-standard-filename' is for file names embedded as literal
strings within Emacs sources.

On Windows, `file-truename' also converts a short 8+3 alias into its
long original.  So, for example, `C:/DOCUME~1/USER/LOCALS~1/Temp' is
converted into `C:/Documents and Settings/USER/Local Settings/Temp'.
It also converts the letter-case to what is actually recorded in the
filesystem.

> But in terms of use, if I want to, say, compare two file names to see if they
> represent the same file, what's typically appropriate?

Using `file-truename' should be enough.  If you compare against a
literal string that holds a name of a file mentioned in Emacs sources,
such as ".emacs" or ".desktop", run them through
`convert-standard-filename' first.  As Andreas points out, an existing
file should not be subject to `convert-standard-filename'.

> Grepping the Emacs
> sources didn't make any guidelines jump to my eyes. For defcustoms, for
> instance, sometimes f-t is used; sometimes c-s-f is used.

Which defcustoms use `file-truename'?

RE: file-truename, convert-standard-filename

[Drew Adams]

> `convert-standard-filename' is for file names embedded as literal
> strings within Emacs sources.
> 
> On Windows, `file-truename' also converts a short 8+3 alias into its
> long original.  So, for example, `C:/DOCUME~1/USER/LOCALS~1/Temp' is
> converted into `C:/Documents and Settings/USER/Local Settings/Temp'.
> It also converts the letter-case to what is actually recorded in the
> filesystem.
> 
> > But in terms of use, if I want to, say, compare two file 
> > names to see if they represent the same file, what's
> > typically appropriate?
> 
> Using `file-truename' should be enough.  If you compare against a
> literal string that holds a name of a file mentioned in Emacs sources,
> such as ".emacs" or ".desktop", run them through
> `convert-standard-filename' first.  As Andreas points out, an existing
> file should not be subject to `convert-standard-filename'.

Thanks. Could you perhaps consider adding some of that information to the doc? I
don't see any of it there.

And judging from this thread, it appears that the purpose of
`convert-standard-filename' is not too clear to everyone. It's still not clear
to me, at least. 

What do you mean by "embedded literal string" in the source code? If the Emacs
source code has (defcustom foo ".emacs"...), do I need to apply c-s-f to foo in
order to compare its value? And does "Emacs sources" apply only to code
distributed with Emacs or to any Emacs-Lisp source code?

And you seem to say two things: a "file name embedded as a literal string" and
"a name of a file mentioned in Emacs sources". Is c-s-f needed for certain file
names (e.g. those "mentioned" in Emacs sources) or for certain strings (e.g.
literal strings in distributed source code) that name files? IOW, is it about
the name or the actual string object?

Does it matter whether it's (string= (file-truename ".emacs") (file-truename
bar)) or (string= (file-truename foo) (file-truename bar)), where foo's value is
".emacs"? Is c-s-f needed in the former case but not the latter?

Obviously, I'm not yet understanding what this is about. Does it have something
to do with strings that are defined before Emacs gets dumped?

Please feel free to ignore all my questions and just try to explain again,
directly. All I want is to understand.

I've read the replies from Andreas, Stefan, and you, and it's clear that this is
clear to all of you, but I still don't get it, based on what you've said so far.

> Which defcustoms use `file-truename'?

Hm; my bad. I coulda sworn I saw some...

Re: file-truename, convert-standard-filename

[Lennart Borgman]

On Sat, Feb 6, 2010 at 12:51 AM, Drew Adams <drew.adams@oracle.com> wrote:
>
> And judging from this thread, it appears that the purpose of
> `convert-standard-filename' is not too clear to everyone. It's still not clear
> to me, at least.


I think the description in

  (info "(elisp) Standard File Names")

is wrong. It is written in a GNU/Linux centric way and forgets about
the necessary file name syntax translation that
convert-standard-filename also does to make the file name fit the OS.

Perhaps the function from the beginning just did the expansion that
Stefan pointed to, but that is not true any more. (And if it was we
would surely need another function to do the file name syntax
translation.)

Re: file-truename, convert-standard-filename

[Eli Zaretskii]

> From: Lennart Borgman <lennart.borgman@gmail.com>
> Date: Sat, 6 Feb 2010 01:17:06 +0100
> Cc: Eli Zaretskii <eliz@gnu.org>, emacs-devel@gnu.org
> 
> I think the description in
> 
>   (info "(elisp) Standard File Names")
> 
> is wrong.

``Wrong'' means it is in error or inaccurate.  Can you please point
out these errors and inaccuracies in the documentation?

> It is written in a GNU/Linux centric way

No, it isn't.  It _recommends_ to use file names that are valid or
convenient on Posix systems, and let `convert-standard-filename' take
care of systems where there are more stringent limitations on what can
be a valid file name.  That's not ``GNU/Linux centric'', that's
GNU/Linux favorable, which is hardly a surprise in a program such as
Emacs.

> and forgets about
> the necessary file name syntax translation that
> convert-standard-filename also does to make the file name fit the OS.

Which translations it forgets?  And why is that important, anyway?  If
one wants to know _exactly_ what the function does, she should read
the sources, because there's no easy way (and no particular need, IMO)
to describe its precise transformations on each and every OS where it
has a non-trivial definition.

> Perhaps the function from the beginning just did the expansion that
> Stefan pointed to, but that is not true any more. (And if it was we
> would surely need another function to do the file name syntax
> translation.)

I'm not sure what are you talking about.  Is this about the `cygdrive'
handling?  If so, FWIW I think this is a bastardly use of this
interface; it should have been a separate function using a separate
mechanism.  This functionality was added to this function only because
otherwise the code which deals with file names elsewhere in Emacs
would become uglier, and because a fancier mechanism (like file
handlers) was not considered worth it.

In any case, why does this detail matter?

Re: file-truename, convert-standard-filename

[Lennart Borgman]

On Sat, Feb 6, 2010 at 9:45 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>> From: Lennart Borgman <lennart.borgman@gmail.com>
>> Date: Sat, 6 Feb 2010 01:17:06 +0100
>> Cc: Eli Zaretskii <eliz@gnu.org>, emacs-devel@gnu.org
>>
>> I think the description in
>>
>>   (info "(elisp) Standard File Names")
>>
>> is wrong.
>
> ``Wrong'' means it is in error or inaccurate.  Can you please point
> out these errors and inaccuracies in the documentation?


Yes, of course. I thought I already did.

This part of the manual speaks about Emacs "standard file names". It
looks to me like that is file names like "~/.emacs".

convert-standard-filename does convert such file names to something
the OS understands. That is correct.

However convert-standard-filename does more than that, ie more than
its name maybe suggests. It actually converts any Emacs file name to
something the OS understand. This could be more clearly stated in the
manual.


>> and forgets about
>> the necessary file name syntax translation that
>> convert-standard-filename also does to make the file name fit the OS.
>
> Which translations it forgets?


See above.

Re: file-truename, convert-standard-filename

[Eli Zaretskii]

> From: Lennart Borgman <lennart.borgman@gmail.com>
> Date: Sat, 6 Feb 2010 17:55:40 +0100
> Cc: drew.adams@oracle.com, emacs-devel@gnu.org
> 
> convert-standard-filename does convert such file names to something
> the OS understands. That is correct.
> 
> However convert-standard-filename does more than that, ie more than
> its name maybe suggests. It actually converts any Emacs file name to
> something the OS understand.

No, it converts the file name to a valid name on the OS.
Understanding a file name, whatever it may mean, has nothing to do
with it.

> >> and forgets about
> >> the necessary file name syntax translation that
> >> convert-standard-filename also does to make the file name fit the OS.
> >
> > Which translations it forgets?
> 
> 
> See above.

I don't see anything in your explanations that say what is the
problem.

Re: file-truename, convert-standard-filename

[Lennart Borgman]

On Sat, Feb 6, 2010 at 8:12 PM, Eli Zaretskii <eliz@gnu.org> wrote:
>> From: Lennart Borgman <lennart.borgman@gmail.com>
>> Date: Sat, 6 Feb 2010 17:55:40 +0100
>> Cc: drew.adams@oracle.com, emacs-devel@gnu.org
>>
>> convert-standard-filename does convert such file names to something
>> the OS understands. That is correct.
>>
>> However convert-standard-filename does more than that, ie more than
>> its name maybe suggests. It actually converts any Emacs file name to
>> something the OS understand.
>
> No, it converts the file name to a valid name on the OS.
> Understanding a file name, whatever it may mean, has nothing to do
> with it.

:-)

Ok, I give up on this. What I am saying is just what you are saying:
"it converts the file name to a valid name on the OS". I just thought
that the manual should say this more clearly.

Though I prefer avoiding technical terms when I think it is clear what
I mean (because IMO it normally leads to faster communication and
better understanding than using pure technical terms).

Re: file-truename, convert-standard-filename

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <emacs-devel@gnu.org>
> Date: Fri, 5 Feb 2010 15:51:01 -0800
> 
> Thanks. Could you perhaps consider adding some of that information to the doc? I
> don't see any of it there.

If I have time.  Although I'm not sure where: we don't have a place in
the manual that describes how to compare file names reliably.  Perhaps
we should.

> And judging from this thread, it appears that the purpose of
> `convert-standard-filename' is not too clear to everyone. It's still not clear
> to me, at least. 

Even after reading the ELisp node where it is documented?  Could you
tell what else is missing?

> What do you mean by "embedded literal string" in the source code? If the Emacs
> source code has (defcustom foo ".emacs"...), do I need to apply c-s-f to foo in
> order to compare its value?

Only if the other string is a name of a file that already exists in
the filesystem.

> And does "Emacs sources" apply only to code distributed with Emacs
> or to any Emacs-Lisp source code?

The latter, of course.

> And you seem to say two things: a "file name embedded as a literal string" and
> "a name of a file mentioned in Emacs sources". Is c-s-f needed for certain file
> names (e.g. those "mentioned" in Emacs sources) or for certain strings (e.g.
> literal strings in distributed source code) that name files?

``Literal string'' is the main issue here.  That's why this function
was introduced in the first place: to seamlessly take care of all the
places in Emacs Lisp sources where there's a literal string serving as
a file name, and that string might be an invalid file name on some
filesystems.

> IOW, is it about the name or the actual string object?

It's about the names that are valid on some systems, but not on
others.

> Does it matter whether it's (string= (file-truename ".emacs") (file-truename
> bar)) or (string= (file-truename foo) (file-truename bar)), where foo's value is
> ".emacs"? Is c-s-f needed in the former case but not the latter?

It is needed in the first case, if `bar' is the name of a file already
existing in the filesystem, because on MS-DOS, `bar' could be "_emacs"
instead.  It _may_ be needed in the second case if one of `foo' or
`bar' is a string whose value is ".emacs", while the other is the name
of a file already existing in the filesystem.  It is _not_ needed if
both `foo' and `bar' hold names of files already existing on
filesystems of the same type.

> Obviously, I'm not yet understanding what this is about. Does it have something
> to do with strings that are defined before Emacs gets dumped?

No, Emacs dumping is not the issue here, at least not directly.  For
defcustoms, it's not an issue because a defcustom is evaluated again
when a dumped Emacs starts.  So if the filesystem where it was dumped
is different from the one where it starts, the name will be
recomputed anew.

RE: file-truename, convert-standard-filename

[Drew Adams]

> Even after reading the ELisp node where it is documented?  Could you
> tell what else is missing?

Uh, no, because, as I said, I still don't understand it. When I do, you'll
understand better what is missing or could be stated better.

> > What do you mean by "embedded literal string" in the source 
> > code? If the Emacs source code has (defcustom foo ".emacs"...),
> > do I need to apply c-s-f to foo in order to compare its value?
> 
> Only if the other string is a name of a file that already exists in
> the filesystem.

I'm comparing arbitrary, unknown file names. I don't know the names ahead of
time, and I don't know whether they name existing files.

From what you just said, I will always need to use c-s-f, since one of the files
might be ".emacs" (assuming it appears in Emacs source code as an embedded
literal) and the other might be an existing file.

That's different from your first statement that probably just f-t would be
sufficient. I used (c-s-f (f-t FILE)), but you suggested that (f-t FILE) would
be sufficient.

But I've probably got this all wrong, because I still don't understand it. I
still haven't heard (or haven't understood, if in fact you've said it) what
c-s-f is _for_: what use cases. Perhaps you can give some useful examples of
calling it and why it's needed for those calls - what can go wrong if it's not
called in those cases.

> > And does "Emacs sources" apply only to code distributed with Emacs
> > or to any Emacs-Lisp source code?
> 
> The latter, of course.

So any occurrence of a literal string in any Emacs-Lisp (or C?) code? If that
particular name is used as a file name, then one needs to wrap c-s-f around it
when it is so used? That's hard to believe.

> > And you seem to say two things: a "file name embedded as a 
> > literal string" and "a name of a file mentioned in Emacs sources".
> > Is c-s-f needed for certain file names (e.g. those "mentioned" in
> > Emacs sources) or for certain strings (e.g. literal strings in
> > distributed source code) that name files?
> 
> ``Literal string'' is the main issue here.  That's why this function
> was introduced in the first place: to seamlessly take care of all the
> places in Emacs Lisp sources where there's a literal string serving as
> a file name, and that string might be an invalid file name on some
> filesystems.

I'm beginning to understand, I think.

It sounds like c-s-f is something to use at the point where the literal string
is introduced into the code - and only then. If code is written so that any
literal string that might be used as a file name is first wrapped with c-s-f
before being bound our assigned to a variable, and there are no other literal
occurrences of it, then one should be OK. Is that it?

What about a literal string that is not in code, but is provided by a user
interactively or constructed dynamically (e.g. (concat ".em" "acs"))? If a
prompt asks a user where to save his blahs, and he answers ".emacs.blah", does
code that handles that filename then need to wrap it with c-s-f? And does it
matter whether the file in question already exists (as was stated before)?

I'm guessing that the answers here are no and no, that it applies only to
strings in code and it has nothing to do with whether the files named already
exist. But please let me know.

> > IOW, is it about the name or the actual string object?
> 
> It's about the names that are valid on some systems, but not on
> others.

So it is _not_ the string that's important. So it is also not the fact that a
literal string is in code (as opposed to being entered or created dynamically).
(concat ".e" "macs") is just as problematic as ".emacs", and needs to be wrapped
with c-s-f. Is that it?

Very sorry, but as you can see, this is still not clear at all to me. You say
its the presence of a literal string that's problematic, then you say it's the
name itself that is problematic, since a file with that name might not be
possible on some system.

Every statement you make makes me think I understand a bit, until I reach the
next statement, which seems to say something different. I'm sure that once I
understand then all of the statements will make sense together, but so far they
do not, for me.

> > Does it matter whether it's (string= (file-truename 
> > ".emacs") (file-truename bar)) or (string= (file-truename foo)
> > (file-truename bar)), where foo's value is
> > ".emacs"? Is c-s-f needed in the former case but not the latter?
> 
> It is needed in the first case, if `bar' is the name of a file already
> existing in the filesystem, because on MS-DOS, `bar' could be "_emacs"
> instead.

But .emacs and _emacs could be two different files on MS-DOC, no? I'm not
familiar with MS-DOS - is a file named ".emacs" impossible (unlike Windows)?

> It _may_ be needed in the second case if one of `foo' or
> `bar' is a string whose value is ".emacs", while the other is the name
> of a file already existing in the filesystem.  It is _not_ needed if
> both `foo' and `bar' hold names of files already existing on
> filesystems of the same type.
> 
> > Obviously, I'm not yet understanding what this is about. 
> > Does it have something
> > to do with strings that are defined before Emacs gets dumped?
> 
> No, Emacs dumping is not the issue here, at least not directly.  For
> defcustoms, it's not an issue because a defcustom is evaluated again
> when a dumped Emacs starts.  So if the filesystem where it was dumped
> is different from the one where it starts, the name will be
> recomputed anew.

Hm. But there _are_ lots of defcustoms that use c-s-f. (I was mistaken about
defcustoms with f-t, but not c-s-f.)

I think that with just a little more help, especially some examples, I might get
it. But I'm not there yet. Some examples without it that are problematic, and
just what the problems are (bad consequences). And the same examples fixed to
use c-s-f. Thx.

Re: file-truename, convert-standard-filename

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <emacs-devel@gnu.org>
> Date: Sat, 6 Feb 2010 07:33:17 -0800
> 
> But .emacs and _emacs could be two different files on MS-DOC, no?

No.  MS-DOS does not allow file names with leading dots.  There cannot
be a file name like .emacs there.

Look, I think this discussion is getting out of hand.  Let me try to
step back a notch and try anew.

There's a problem with file names, such as ".emacs", defined in Emacs
Lisp code as literal strings: some filesystems don't allow such
names.  `convert-standard-filename' was introduced to take a Posix
file name and produce from it a file name that can be used instead on
the particular filesystem.  So instead of

  (defvar foo-file
          (if (eq system-type 'foo)
              "this"
             (if (eq system-type 'bar)
                 "that"
                ....

we can now have just this:

  (defvar foo-file (convert-standard-filename "this"))

So far so good?

Same considerations apply when a file name is constructed from
fragments, like in

   (append ".emacs." (user-full-name) ".log")

In order to get a file name that any supported platform could use, you
need to run the result of this through `convert-standard-filename'.

Okay?

If this part is understood, then just use `convert-standard-filename'
in any situation where a string to be used as a file name might not be
valid on the underlying filesystem, like e.g. a literal `?' on a
Windows disk.  An arbitrary string generally needs such a treatment,
before it can safely be used as a file name.  That's why Emacs
defcustoms use it.

Any questions so far?

RE: file-truename, convert-standard-filename

[Drew Adams]

> Let me try to step back a notch and try anew.

Thank you.

> There's a problem with file names, such as ".emacs", defined in Emacs
> Lisp code as literal strings: some filesystems don't allow such
> names.  `convert-standard-filename' was introduced to take a Posix
> file name and produce from it a file name that can be used instead on
> the particular filesystem.  So instead of
>   (defvar foo-file
>           (if (eq system-type 'foo)
>               "this"
>              (if (eq system-type 'bar)
>                  "that"
>                 ....
> we can now have just this:
>   (defvar foo-file (convert-standard-filename "this"))
> 
> So far so good?

Yes.

> Same considerations apply when a file name is constructed from
> fragments, like in (append ".emacs." (user-full-name) ".log")

OK. (But I think you meant `concat', not `append'.)

So it in fact has nothing specially to do with literal strings in source code.
That was apparently a red herring. (But you keep repeating it - e.g. see above;
so I wonder.)

This is the general rule, apparently:

> In order to get a file name that any supported platform could use, you
> need to run the result of this through `convert-standard-filename'.
> Okay?

I think so.

That means that in order to use ANY file name (any file-name string, no matter
where it was coded or how it is produced), you need to apply c-s-f to it, if you
don't know whether the name is supported by all platforms that might be used by
your code.

Am I wrong about that?

That would mean that the original code I showed would be necessary, and that
using f-t alone, without c-s-f, would not be sufficient. This is the original
code:

(string= (c-s-f (f-t FILE1)) (c-s-f (f-t FILE2)))

So am I misunderstanding now, or was your advice wrong that just f-t suffices
here? I'm not trying to point fingers - I appreciate your patient efforts to
explain; I'm just trying to understand.

> If this part is understood, then just use `convert-standard-filename'
> in any situation where a string to be used as a file name might not be
> valid on the underlying filesystem, 

Which for an unknown string (e.g. the string value of a variable) means ALL
situations, no? If I don't know which file system a user has, and I don't know
which file names are involved, then my code needs to call c-s-f for each file
name. No?

> like e.g. a literal `?' on a
> Windows disk.  An arbitrary string generally needs such a treatment,
> before it can safely be used as a file name.  That's why Emacs
> defcustoms use it.
> 
> Any questions so far?

I think I understand now - see above.
c-s-f is needed for an arbitrary string.

Confirmation or correction is welcome.

BTW, I notice that prior to Emacs 23 the Emacs source code did not use c-s-f
very much (e.g. defcustoms, such as in recentf.el); Emacs 23 uses it much more.
I suppose this means that we had more problems with this before Emacs 23.

But it does not seem like even the Emacs 23 source code calls c-s-f for all of
the situations that I think you're describing.

You seem to be saying that it's _nearly always needed_, unless (a) you know
which file system is being used, (b) you know the file name being used, and (c)
you know that that particular file name is a valid one for that particular file
system.

I haven't analyzed the Emacs code, but I don't get the impression that (a), (b),
and (c) are true for each file-name occurrence where it doesn't call c-s-f.
Maybe adding c-s-f everywhere is an ongoing thing, and the code just hasn't yet
caught up with the rule?

Thx - Drew

Re: file-truename, convert-standard-filename

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <emacs-devel@gnu.org>
> Date: Sat, 6 Feb 2010 12:46:02 -0800
> 
> That means that in order to use ANY file name (any file-name string, no matter
> where it was coded or how it is produced), you need to apply c-s-f to it, if you
> don't know whether the name is supported by all platforms that might be used by
> your code.

Again, the case when the string is known to be a name of an existing
file is the important exception.  For example, if it comes from
buffer-file-name, or from default-directory, or from other similar
interfaces.

> > If this part is understood, then just use `convert-standard-filename'
> > in any situation where a string to be used as a file name might not be
> > valid on the underlying filesystem, 
> 
> Which for an unknown string (e.g. the string value of a variable) means ALL
> situations, no?

It could be, unless, again, you know that a file by that name already
exists.

> BTW, I notice that prior to Emacs 23 the Emacs source code did not use c-s-f
> very much (e.g. defcustoms, such as in recentf.el); Emacs 23 uses it much more.
> I suppose this means that we had more problems with this before Emacs 23.

No, it just means we made some cleanup.  The situations where this
really matters are very rare, and if you ignore the MS-DOS case, are
almost non-existent.  People rarely use characters in file names that
get you in trouble on MS-Windows.  And if the file name comes from the
user, you can almost be certain she will never use such characters,
and even if she does, she deserves the error message.

About the only real use-case is when the file name comes from the Lisp
code itself.  Which is why I mentioned literal strings so many times.

> But it does not seem like even the Emacs 23 source code calls c-s-f for all of
> the situations that I think you're describing.

It does where we are certain it matters.  See files.el for a few
examples.

> Maybe adding c-s-f everywhere is an ongoing thing, and the code just hasn't yet
> caught up with the rule?

Something like that.  But again, many places will never need it.

RE: file-truename, convert-standard-filename

[Drew Adams]

> > That means that in order to use ANY file name (any 
> > file-name string, no matter where it was coded or how
> > it is produced), you need to apply c-s-f to it, if you
> > don't know whether the name is supported by all platforms 
> > that might be used by your code.
> 
> Again, the case when the string is known to be a name of an existing
> file is the important exception.  For example, if it comes from
> buffer-file-name, or from default-directory, or from other similar
> interfaces.

OK. Then add "and you do not know whether the file named exists" to what I
wrote. Again, that is the general case.

> > > If this part is understood, then just use 
> > > `convert-standard-filename' in any situation where a
> > > string to be used as a file name might not be
> > > valid on the underlying filesystem, 
> > 
> > Which for an unknown string (e.g. the string value of a 
> > variable) means ALL situations, no?
> 
> It could be, unless, again, you know that a file by that name already
> exists.

Got it.

> > BTW, I notice that prior to Emacs 23 the Emacs source code 
> > did not use c-s-f very much (e.g. defcustoms, such as in
> > recentf.el); Emacs 23 uses it much more.
> > I suppose this means that we had more problems with this 
> > before Emacs 23.
> 
> No, it just means we made some cleanup.  The situations where this
> really matters are very rare, and if you ignore the MS-DOS case, are
> almost non-existent.  People rarely use characters in file names that
> get you in trouble on MS-Windows.  And if the file name comes from the
> user, you can almost be certain she will never use such characters,
> and even if she does, she deserves the error message.
> 
> About the only real use-case is when the file name comes from the Lisp
> code itself.  Which is why I mentioned literal strings so many times.

Hm. That changes things considerably.

My summary:

THEORETICALLY, one _always_ needs c-s-f, unless either (1) you know that the
file that is named exists or (2) you know _all_ of the following: (2a) the file
system being used, (2b) the file name being used, and (2c) that the given file
name is a valid one for the given file system.

IN PRACTICE, however, the only real use-case is for MS-DOS support, and in
particular, only when the file name is a literal string in Lisp code.

Have I got it now?

If so, then for my purposes, since I do not care about MS-DOS support for my
code, I will _never_ need to use c-s-f. Hope I'm understanding correctly now.
For me, it seems, the ALWAYS of theoretically changes quickly to the NEVER of
practically. That's a big change.

If I've got it right, then (practically) the use of c-s-f is pretty much only an
internal one for Emacs development. I don't expect there is a lot of 3rd-party
code intended for MS-DOS. (But I might be mistaken about that.)

Anyway, assuming I finally understand this, thank you very much. (If I don't,
I'd be grateful if you would try once more.)

And I think you now know what kinds of things you might want to say and not say
in the doc, to clear things up. 

If you want my suggestion about that (the doc), and assuming my understanding is
correct, then I'd say that what I just wrote above (theoretical vs practical) is
all anyone needs to find in the doc. In particular: in practice, c-s-f is only
for MS-DOS support. So unless you develop code for the Emacs distribution, YAGNI
(use cases are "almost non-existent").

Thanks, Eli. If I'm still missing the point, please let me know.

Re: file-truename, convert-standard-filename

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <emacs-devel@gnu.org>
> Date: Sat, 6 Feb 2010 15:12:05 -0800
> 
> My summary:
> 
> THEORETICALLY, one _always_ needs c-s-f, unless either (1) you know that the
> file that is named exists or (2) you know _all_ of the following: (2a) the file
> system being used, (2b) the file name being used, and (2c) that the given file
> name is a valid one for the given file system.
> 
> IN PRACTICE, however, the only real use-case is for MS-DOS support, and in
> particular, only when the file name is a literal string in Lisp code.
> 
> Have I got it now?

Yes, pretty much.

> If you want my suggestion about that (the doc), and assuming my understanding is
> correct, then I'd say that what I just wrote above (theoretical vs practical) is
> all anyone needs to find in the doc. In particular: in practice, c-s-f is only
> for MS-DOS support. So unless you develop code for the Emacs distribution, YAGNI
> (use cases are "almost non-existent").

The problem is to say that without ever mentioning the OS name
explicitly ;-)

Re: file-truename, convert-standard-filename

[Stefan Monnier]

> THEORETICALLY, one _always_ needs c-s-f, unless either (1) you know
> that the file that is named exists or (2) you know _all_ of the
> following: (2a) the file system being used, (2b) the file name being
> used, and (2c) that the given file name is a valid one for the given
> file system.

No, I think it should be more restrictive: you should use c-s-f if and
only if the file name might not be valid on the current system, and
where it would be a bug if that file name turned out to be invalid on
the current system.

In most cases, the first condition is already false: you generally get
file names which you know are valid on the current system.  Of the
remining cases, most fail the second condition: for most files that may
not be valid, it's perfectly OK to signal an error if it turns out to be
invalid, because it was a user-error to use that file name.

So yes, the cases where c-s-f are needed are rare and mostly "internal".


        Stefan

RE: file-truename, convert-standard-filename

[Drew Adams]

> > THEORETICALLY, one _always_ needs c-s-f, unless either (1) you know
> > that the file that is named exists or (2) you know _all_ of the
> > following: (2a) the file system being used, (2b) the file name being
> > used, and (2c) that the given file name is a valid one for the given
> > file system.
> 
> No, I think it should be more restrictive: you should use c-s-f if and
> only if the file name might not be valid on the current system, and
> where it would be a bug if that file name turned out to be invalid on
> the current system.

From that and the rest of what you wrote, you seem to be speaking of a usage
guideline that is more restrictive based on PRACTICAL considerations.

The text you quoted was, in contrast, trying just to describe the cases that
THEORETICALLY could be problematic. It says nothing about practical guidelines:
what to do about such cases (avoid them by using c-s-f or not).

I was trying to paraphrase what Eli said when he was describing which cases
could be problematic. Those are (I think) the criteria he cited. They are
presumably the rationale behind the current use of c-s-f (e.g. in defcustoms).

But he also said that in practice such cases are marginal (rare). And you've now
added that even for some of those rare cases we don't care enough to protect
against an error.

It is a PRACTICAL matter whether the problematic cases are in fact rare (they
are, apparently). And it is a PRACTICAL matter whether some of the problematic
cases should be ignored (so that an error is raised) if they arise.

If the code doesn't know what the current system might be when it is run, then
c-s-f is needed IF you want to be sure there is no problem. The "IF" part is a
PRACTICAL choice.

(Of course, if the set of problematic OSes is known, then the code can test to
see whether the current OS is one of them - but I didn't notice such a test in
the current Emacs code.)

> In most cases, the first condition is already false: you generally get
> file names which you know are valid on the current system.

"Generally" as in most often? Sure. "Generally" as in you can depend on that to
be the case? No.

Again, that's the point I was trying to make in distinguishing theoretical from
practical considerations. If you don't know, then THEORETICALLY you need to call
c-s-f, that is, IF you want to play safe. IN PRACTICE, however, you might not
care.

I'm just paraphrasing what I understood from Eli. I don't claim either that I
understood him correctly or that what he said is right. ;-)

> Of the remining cases, most fail the second condition: for most 
> files that may not be valid, it's perfectly OK to signal an
> error if it turns out to be invalid, because it was a
> user-error to use that file name.

That's a legitimate point - and it's a design choice, i.e., a PRACTICAL matter.

By "THEORETICALLY", I was trying to describe the situations in which you
wouldn't know enough to determine whether the file name might be invalid - and
so c-s-f would be called for IF you wanted to play it safe.

If instead it makes sense to let an error be raised because of an invalid name,
that's a different story. That choice doesn't affect the criteria that define a
problematic case. Making such a choice is a PRACTICAL matter.

Eli was trying to help me understand both (a) the potential problem and (b) when
and whether it arises in practice. I had trouble understanding, because there is
a difference between the two. He seemed at first to be saying contradictory
things (you need c-s-f to protect against... vs you probably don't need c-s-f).

> So yes, the cases where c-s-f are needed are rare and mostly 
> "internal".

Got it. I won't need c-s-f at all.

I was confused because I ran across it in the doc, and from its description it
seemed to be something I would need in order to compare file names. I suggest
that we remove it from the manual and clarify the doc string, so that users who
run across it don't use it unnecessarily.

> > IN PRACTICE, however, the only real use-case is for
> > MS-DOS support, and in particular, only when the file
> > name is a literal string in Lisp code.

RE: file-truename, convert-standard-filename

[Davis Herring]

[I was reading this old thread and thought I might provide my own useful
summary.]

> OK. Then add "and you do not know whether the file named exists" to what I
> wrote. Again, that is the general case.

I think too much attention is being paid to the question of whether files
exist, which adds noise because so often we don't know (in advance)
whether a particular file exists.

The simple explanation is this: out of the set of all possible strings,
some of them are valid filenames on a given platform/filesystem.  On GNU,
the only character that cannot occur in a filename is NUL, which is so
rarely considered that we say that the two sets (strings and valid
filenames) are the same.  On Windows, several common characters are
invalid: ? and * for instance.  (This is justified by the different rules
about wildcards in the common Windows shells.)  So there, the sets differ
substantially.  On DOS, things get even worse, because there are peculiar
restrictions on the use of . in filenames.  (It's not prohibited, but you
can only use one per path component, and it can't be the first character,
etc.)

When the user asks to visit a file, or we get a filename from `ls' or
whatever other system source, the distinction between these two sets is
unimportant, because system tools will only generate filenames in the
valid set, and reporting to the user that their filename is invalid is
sufficient (as they can then choose another).

However, when Emacs (or any of its libraries or extensions) picks a
filename, there is no intelligence that can react to an error when the
filename is invalid.  So we must plan ahead and have a mapping from the
set of strings to the (system-dependent) set of valid names.  That mapping
is `convert-standard-filename', and it is therefore necessary precisely
whenever it is Emacs itself that is choosing (or constructing, like the
`concat' examples) a filename.

The set of valid filenames is closed under the common operations on them
(like `file-name-directory', `file-relative-name', `expand-file-name',
`file-truename').  So once all agents picking filenames have chosen valid
ones, no invalid names will ever be generated from them, so
`convert-standard-filename' is never needed again.  This is why so many of
its uses are on literal strings; literals are the commonest way for Emacs
to "pick" filenames, and after that point it's unneeded.

It is of course true that an existing file must have a valid name, and an
invalid filename cannot name an existing file (since it can't even name a
nonexistent file, as one might create with `write-region').  But note that
nowhere in this exposition (outside of the introductory paragraph and this
one) is any mention made of whether files exist or not.

Davis

-- 
This product is sold by volume, not by mass.  If it appears too dense or
too sparse, it is because mass-energy conversion has occurred during
shipping.

RE: file-truename, convert-standard-filename

[Drew Adams]

> > OK. Then add "and you do not know whether the file named 
> > exists" to what I wrote. Again, that is the general case.
> 
> I think too much attention is being paid to the question of 
> whether files exist, which adds noise because so often we
> don't know (in advance) whether a particular file exists.
> 
> The simple explanation is this
> ...
> 
> When the user asks to visit a file, or we get a filename from `ls' or
> whatever other system source, the distinction between these 
> two sets is unimportant, because system tools will only
> generate filenames in the valid set, and reporting to the user
> that their filename is invalid is sufficient (as they can then
> choose another).

This is where I either still do not understand (probably) or do not completely
agree. Platform-knowledgeable tools generating file names is one thing; a user
entering a file name is another.

If a user provides a file name, what's to ensure that the name is valid for the
given platform? Much (most?) file-name input by users is lax, not requiring a
match against an existing file. A user could include `?' for Windows, for
instance.

This might be where a connection with a test for an existing file would come in?
(Dunno.)

If my code gets a file name from the user, and I can't depend on it being valid
for the given platform, why would I *not* need to call `convert...'? Just
wondering. Seems to me this would be similar to the
literal-file-name-string-in-code situation.

Anyway, thanks for the extended explanation. It was what I eventually had
understood from the thread, but it helps in any case. If it had come earlier in
the thread, it might have made the thread shorter. ;-)

RE: file-truename, convert-standard-filename

[Davis Herring]

> If my code gets a file name from the user, and I can't depend on it
> being valid for the given platform, why would I *not* need to call
> `convert...'? Just wondering. Seems to me this would be similar to the
> literal-file-name-string-in-code situation.

What harm comes from not calling it?  There are plenty of ways that
filenames can be useless without `convert-standard-filename' even being
able to help.  The filename might reside in a directory to which the user
has no access, or it might involve a directory that doesn't exist, or be a
file you want to open for writing on a read-only filesystem, or...  In
other words, your code already has to be capable of dealing with the
user's filename causing an error when you try to use it.  That the error
might be "invalid character" rather than "permission denied" is
irrelevant; the user has the intelligence (that literal strings lack) to
address the problem, so just report it.

The error message that Emacs receives from the system in case of an
invalid file name might be unhelpful (not tell the user what was wrong
with their filename).  Nonetheless, transparently changing (on Windows) a
user's value of "really?" to "really_" (or whatever) is Not The Right
Thing.  If it turns out that such uninformative errors are a problem, we
instead need

(defun filename-valid-p (f) (not (equal f (convert-standard-filename f))))
; or similar

that you can test when the error occurs so as to substitute a more helpful
error message.

> Anyway, thanks for the extended explanation. It was what I eventually
> had understood from the thread, but it helps in any case. If it had
> come earlier in the thread, it might have made the thread shorter. ;-)

If the thread had been shorter, I might not have gotten so far behind and
the reply might have come earlier.  ;)

Davis

-- 
This product is sold by volume, not by mass.  If it appears too dense or
too sparse, it is because mass-energy conversion has occurred during
shipping.

RE: file-truename, convert-standard-filename

[Drew Adams]

> > If my code gets a file name from the user, and I can't depend on it
> > being valid for the given platform... Seems to me this would be 
> > similar to the literal-file-name-string-in-code situation.
>
> ...
> The error message that Emacs receives from the system in case of an
> invalid file name might be unhelpful (not tell the user what was wrong
> with their filename).  Nonetheless, transparently changing 
> (on Windows) a user's value of "really?" to "really_" (or whatever)
> is Not The Right Thing.

;-)

I was thinking more of a defcustom value entered by a user (not a default
defcustom value). Seems like that could be problematic in the same way a literal
string might be.

But the bottom line in practical terms wrt `c-s-f' still seems to be: YAGNI.

As Stefan said, `c-s-f' is needed "where it would be a bug if that file name
turned out to be invalid on the current system", as opposed to situations where
an error will be raised if the name is invalid.

Re: file-truename, convert-standard-filename

[MON KEY]

Re: file-truename, convert-standard-filename,

,----
| I've read the replies from Andreas, Stefan, and you, and it's clear
| that this is clear to all of you, but I still don't get it, based on
| what you've said so far.
`----

FWIW I don't get the impression that it is entirely clear that it is
clear to these parties either.

The distinction which should be clarified in the docs is that between a
file as an object and the name of that object as a string.

I recently had the unpleasure of learning that the file-truename of an
empty string is `default-directory'.

 (file-truename "")

I was expecting nil ...

It has since been made more clear to me that the result `must' be a
directory, it allows such as this:

 (dired (file-relative-name (file-truename "")))

This said, I continue to have occasion for surprise when Emacs does
treat files as objects e.g.:

(require 'file)

In this case the string got hidden behind &optional ... tricky tricky.

Re: file-truename, convert-standard-filename

[Eli Zaretskii]

> Date: Fri, 5 Feb 2010 22:52:33 -0500
> From: MON KEY <monkey@sandpframing.com>
> Cc: emacs-devel@gnu.org
> 
> The distinction which should be clarified in the docs is that between a
> file as an object and the name of that object as a string.

??? It should be clear that `file-truename' operates on the file's
name alone; see the ``name'' part of the function's name and also the
function's doc string.  Why would one be confused about that?

Or are you talking about some other function(s)?

Re: file-truename, convert-standard-filename

[MON KEY]

On Sat, Feb 6, 2010 at 3:28 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> It should be clear that `file-truename' operates on the file's name
> alone; see the ``name'' part of the function's name and also the
> function's doc string.

It certainly is clear that it operates on a filename. What is that?

It certianly is not always clear when the filename is string and when it
is some other object type.

> Why would one be confused about that?

These are assumptions which cause problems.
Why would one not be?

> Or are you talking about some other function(s)?

I'm talking about the general shift which seems to occur when it is
convenient for a handler to treat a file as an object or a string
depending on the context. While the context may be clear to the geese I
doubt it is as transparent to the gander.

/s_P\

Re: file-truename, convert-standard-filename

[MON KEY]

On Sat, Feb 6, 2010 at 11:05 PM, Eli Zaretskii <eliz@gnu.org> wrote:
> See above: a file name is always a string.

Yeah.
I'm surely beating this horse but....

(substring (documentation 'require) 0 56)

=> "If feature FEATURE is not loaded, load it from FILENAME."

(require 'foo)

Which is the string of the filename referenced in the above form?

/s_P\

Re: file-truename, convert-standard-filename

[Andreas Schwab]

MON KEY <monkey@sandpframing.com> writes:

> On Sat, Feb 6, 2010 at 11:05 PM, Eli Zaretskii <eliz@gnu.org> wrote:
>> See above: a file name is always a string.
>
> Yeah.
> I'm surely beating this horse but....
>
> (substring (documentation 'require) 0 56)
>
> => "If feature FEATURE is not loaded, load it from FILENAME."
>
> (require 'foo)
>
> Which is the string of the filename referenced in the above form?

The one that is described in the doc string.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: file-truename, convert-standard-filename

[Eli Zaretskii]

> Date: Sun, 7 Feb 2010 18:26:41 -0500
> From: MON KEY <monkey@sandpframing.com>
> Cc: emacs-devel@gnu.org
> 
> On Sat, Feb 6, 2010 at 11:05 PM, Eli Zaretskii <eliz@gnu.org> wrote:
> > See above: a file name is always a string.
> 
> Yeah.
> I'm surely beating this horse but....
> 
> (substring (documentation 'require) 0 56)
> 
> => "If feature FEATURE is not loaded, load it from FILENAME."
> 
> (require 'foo)
> 
> Which is the string of the filename referenced in the above form?

As Andreas points out, rather than looking at a small portion of the
doc string, why don't you read it in its entirety?  The answer to your
question is there.

Re: file-truename, convert-standard-filename

[MON KEY]

On Sun, Feb 7, 2010 at 11:10 PM, Eli Zaretskii <eliz@gnu.org> wrote:
>> (require 'foo)
>>
>> Which is the string of the filename referenced in the above form?
>
> As Andreas points out, rather than looking at a small portion of the
> doc string, why don't you read it in its entirety?  The answer to your
> question is there.
>

FWIW the string quoted is what appears in apropos... which is why i
referenced it as such.

None the less, the FEATURE 'foo is not a filename and does not
designate the optional arg FILENAME.
In the docstring of `require' FILENAME is an optional argument.

In the example above the feature 'foo is a quoted symbol. There is no
second arg FILENAME.

Is the second arg implicit by virtue the ``printname of FEATURE''?

(print 'foo (current-buffer))

Where is the string?

The reality is that  behind the scenes Emacs is interpolating the
symbol FEATURE to a filename string which corresponds; _not_
necessarily to FILENAME the arg. On the face of it this does not make
them one and the same. Rather the opposite actually. My point is only
that Emacs does not always make a clear distinction between files as
objects and files as strings.

Or am I misinterpreting what occurs?

/s_P\

Re: file-truename, convert-standard-filename

[Andreas Schwab]

MON KEY <monkey@sandpframing.com> writes:

> behind the scenes

It's documented.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: file-truename, convert-standard-filename

[Eli Zaretskii]

> Date: Tue, 9 Feb 2010 16:32:55 -0500
> From: MON KEY <monkey@sandpframing.com>
> 
> On Sun, Feb 7, 2010 at 11:10 PM, Eli Zaretskii <eliz@gnu.org> wrote:
> >> (require 'foo)
> >>
> >> Which is the string of the filename referenced in the above form?
> >
> > As Andreas points out, rather than looking at a small portion of the
> > doc string, why don't you read it in its entirety?  The answer to your
> > question is there.
> >
> 
> FWIW the string quoted is what appears in apropos... which is why i
> referenced it as such.
> 
> None the less, the FEATURE 'foo is not a filename and does not
> designate the optional arg FILENAME.
> In the docstring of `require' FILENAME is an optional argument.
> 
> In the example above the feature 'foo is a quoted symbol. There is no
> second arg FILENAME.
> 
> Is the second arg implicit by virtue the ``printname of FEATURE''?
> 
> (print 'foo (current-buffer))
> 
> Where is the string?

I have no idea what you are talking about, even though I understand
all the words.  The doc string of `require' says:

    (require FEATURE &optional FILENAME NOERROR)

    If feature FEATURE is not loaded, load it from FILENAME.
    If FEATURE is not a member of the list `features', then the feature
    is not loaded; so load the file FILENAME.
    If FILENAME is omitted, the printname of FEATURE is used as the file name,

I don't know what you see there, but what I see is that FILENAME _is_
documented, and the last sentence says what happens if it's omitted.

> Or am I misinterpreting what occurs?

Yes, you are.