convert-standard-filename's doc

convert-standard-filename's doc

[Juanma Barranquero]

Four years ago, the docstring for convert-standard-filename (in files.el)
was changed, but the ones in w32-fns.el and dos-fns.el were not.

Now, it's trivial to fix them to be identical again. But I wonder
whether

    "Convert a standard file's name to something suitable for the current OS.
  This function's standard definition is trivial; it just returns the argument.
  However, on some systems, the function is redefined with a definition
  that really does change some file names to canonicalize certain
  patterns and to guarantee valid names."

is a good description for a function which really *does* something. In
other words, I'd change the docstring for the w32-fns.el version to
read:

    "Convert a standard file's name to something suitable for Windows.

  Returns FILENAME after replacing invalid characters with ! and
  converting directory separators to the Windows style (if needed).
  It also turns Cygwin-style /cygdrive/x/ pathnames to x:/ paths."

(and add also a suitable docstring for the dos-fns.el version, of course).

                                                                Juanma

Re: convert-standard-filename's doc

[Eli Zaretskii]

> Date: Thu, 27 May 2004 16:05:36 +0200
> From: Juanma Barranquero <jmbarranquero@wke.es>
> 
> Four years ago, the docstring for convert-standard-filename (in files.el)
> was changed, but the ones in w32-fns.el and dos-fns.el were not.
> 
> Now, it's trivial to fix them to be identical again.

They don't need to be identical: once a port overloads the standard
definition with another one, the doc string is replaced as well.

So we could have a doc string that describes what that function does
on the specific platform where it runs.  The default doc string
should be left as it is now, IMHO.

> In other words, I'd change the docstring for the w32-fns.el version to
> read:
> 
>     "Convert a standard file's name to something suitable for Windows.
> 
>   Returns FILENAME after replacing invalid characters with ! and
>   converting directory separators to the Windows style (if needed).
>   It also turns Cygwin-style /cygdrive/x/ pathnames to x:/ paths."

I think that's good, but I'd also mention the conversion of slashes to
backslashes, with a reference to w32-shell-dos-semantics.

Re: convert-standard-filename's doc

[Stefan Monnier]

>> Four years ago, the docstring for convert-standard-filename (in files.el)
>> was changed, but the ones in w32-fns.el and dos-fns.el were not.
>> 
>> Now, it's trivial to fix them to be identical again.

> They don't need to be identical: once a port overloads the standard
> definition with another one, the doc string is replaced as well.

> So we could have a doc string that describes what that function does
> on the specific platform where it runs.  The default doc string
> should be left as it is now, IMHO.

I think the docstring should document what "the function
convert-standard-filename" does, not what the "the function currently
associated with the convert-standard-filename symbol" does.

So I think the "generic" text needs to be in, together with an explanation
of what this specific instance of convert-standard-filename does.

Basically I think that multiple definitions of the same function is
a bad thing.  Maybe using defadvice in dos-fns and w32-fns would be even
worse for various reasons, but I think that the docstrings should do
something similar to what we'd get if we used defadvice.


        Stefan

Re: convert-standard-filename's doc

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: 27 May 2004 18:19:09 -0400
> 
> So I think the "generic" text needs to be in, together with an explanation
> of what this specific instance of convert-standard-filename does.

I understand from this that you suggest to have in the doc string
both the generic description and the specific one for the current
platform.  If that's what you suggest, I think it's a good idea.

> Basically I think that multiple definitions of the same function is
> a bad thing.

Agreed (another case in point is the overloading of insert-directory
by ls-lisp).  But do we have a better alternative?  Perhaps something
similar to find-file-name-handler?

Re: convert-standard-filename's doc

[Stefan Monnier]

>> So I think the "generic" text needs to be in, together with an explanation
>> of what this specific instance of convert-standard-filename does.

> I understand from this that you suggest to have in the doc string
> both the generic description and the specific one for the current
> platform.  If that's what you suggest, I think it's a good idea.

>> Basically I think that multiple definitions of the same function is
>> a bad thing.

> Agreed (another case in point is the overloading of insert-directory
> by ls-lisp).  But do we have a better alternative?  Perhaps something
> similar to find-file-name-handler?

How about something like

   (defun foo ()
     "doc"
     (if-when-compile (memq system-name '(bar baz))
         toto
       titi))

For insert-directory, the answer would be a bit different (it can't be
decided at compile-time), but the idea would be the same:

   (defun insert-directory (blabla)
     "doc"
     (if insert-directory-use-ls
         (insert-directory-using-ls blabla)
       (insert-directory-using-lisp blabla)))

I.e. nothing clever.


        Stefan

Re: convert-standard-filename's doc

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: 28 May 2004 12:19:31 -0400
> 
> How about something like
> 
>    (defun foo ()
>      "doc"
>      (if-when-compile (memq system-name '(bar baz))
>          toto
>        titi))
> 
> For insert-directory, the answer would be a bit different (it can't be
> decided at compile-time), but the idea would be the same:

I think we cannot decide anything at compile time, as all the *.el
files are compiled on a GNU or Unix machine when a release is being
prepared.

>    (defun insert-directory (blabla)
>      "doc"
>      (if insert-directory-use-ls
>          (insert-directory-using-ls blabla)
>        (insert-directory-using-lisp blabla)))
> 
> I.e. nothing clever.

Yes, something like that will do, although it being non-clever means
that someone needs to manuall find all those places and modify them as
above.  Not a catastrophe, of course.

Re: convert-standard-filename's doc

[Juanma Barranquero]

On 27 May 2004 18:19:09 -0400
Stefan Monnier <monnier@iro.umontreal.ca> wrote:

> So I think the "generic" text needs to be in, together with an explanation
> of what this specific instance of convert-standard-filename does.

Yes, I agree. What I objected to is the way it is now, because reading
the docstring for a non-default version of the func it is non-obvious
whether the function is "trivial" (does nothing) or not.

> Basically I think that multiple definitions of the same function is
> a bad thing.

Yes!!

On the "help argument highlighting" issue I finally added a function
that the user must redefine to customize the arg highlighting. I did so
per RMS' request, but I *hate* this way to customize. I would much
prefer to have a hook. Every time I have to redefine a function to
change some tiny think I'm afraid I'll accidentally miss fixes and
enhancements to the original function.

> Maybe using defadvice in dos-fns and w32-fns would be even
> worse for various reasons, but I think that the docstrings should do
> something similar to what we'd get if we used defadvice.

Hmm... I'm not sure repeating all the original func's docstring is
necessary. Better IMO something like:

  "Convert a standard file's name to something suitable for the current OS.

The default definition just returns the argument.
On Windows systems, however, this function

 - replaces invalid characters in FILENAME with !
 - turns Cygwin-style /cygdrive/x/ pathnames into x:/ paths
 - converts slashes to backslashes

Conversion of slashes only happens if the current shell expects
it, as indicated by `w32-shell-dos-semantics'."

                                                                Juanma

Re: convert-standard-filename's doc

[Kai Grossjohann]

Juanma Barranquero <jmbarranquero@wke.es> writes:

> Hmm... I'm not sure repeating all the original func's docstring is
> necessary. Better IMO something like:
>
>   "Convert a standard file's name to something suitable for the current OS.
>
> The default definition just returns the argument.
> On Windows systems, however, this function
>
>  - replaces invalid characters in FILENAME with !
>  - turns Cygwin-style /cygdrive/x/ pathnames into x:/ paths
>  - converts slashes to backslashes
>
> Conversion of slashes only happens if the current shell expects
> it, as indicated by `w32-shell-dos-semantics'."

How about just documenting all of the behavior on all systems?  The
same logic I used previously (wanting to write portable Lisp code)
tells me that it would be good to learn about the behavior of this
function on systems that I don't use.

Compare file-name-directory: it documents the VMS behavior even on my
GNU/Linux system.

Kai

Re: convert-standard-filename's doc

[Juanma Barranquero]

On Fri, 28 May 2004 15:51:19 +0200, Kai Grossjohann <kai@emptydomain.de> wrote:

> How about just documenting all of the behavior on all systems?  The
> same logic I used previously (wanting to write portable Lisp code)
> tells me that it would be good to learn about the behavior of this
> function on systems that I don't use.

I'm not convinced.

I think you were right in saying that the docstring must not be totally
system-dependant, so people who consults it can see it varies from
system to system and the version you're seeing is not the only one.

But if someone has to call `convert-standard-filename' in such a way
that it really depends of whether the function changes / to \\ or
ThisLongFileName.Dat to THISLONG.FIL, he can take the trouble to look
for the different implementations. In many cases, it'll probably suffice
to know that the function is going to make the filename valid for the
local system.

Doing what you suggest means a longish docstring with much non-useful
info (non-useful for each system's users, I mean), and fixing all
versions of the docstring each time one of the functions is changed or a
new system added.

> Compare file-name-directory: it documents the VMS behavior even on my
> GNU/Linux system.

Yeah, but that's two lines of system-specific explanation. We're talking
here of a potentially much longer docstring.

                                                           /L/e/k/t/u

Re: convert-standard-filename's doc

[Kai Grossjohann]

Juanma Barranquero <lektu@mi.madritel.es> writes:

> But if someone has to call `convert-standard-filename' in such a way
> that it really depends of whether the function changes / to \\ or
> ThisLongFileName.Dat to THISLONG.FIL, he can take the trouble to look
> for the different implementations. In many cases, it'll probably suffice
> to know that the function is going to make the filename valid for the
> local system.

Hm.  Now I've taken a look at the different definitions.  What do you
think about the following docstring?

    Convert a standard file's name to something suitable for the current OS.
    This means to guarantee valid names and perhaps to canonicalize certain
    patterns.

    On Windows and DOS, remove invalid characters.  On DOS, make sure to
    obey the 8.3 format.  On Windows, turn Cygwin names into native
    names, and also turn slashes into backslashes if the shell requires it.

I think this is not too verbose, and it also helps everyone to know
what to expect.

Kai

Re: convert-standard-filename's doc

[Eli Zaretskii]

> From: Kai Grossjohann <kai@emptydomain.de>
> Date: Sat, 29 May 2004 13:13:55 +0200
> 
>     Convert a standard file's name to something suitable for the current OS.
>     This means to guarantee valid names and perhaps to canonicalize certain
>     patterns.
> 
>     On Windows and DOS, remove invalid characters.  On DOS, make sure to
>     obey the 8.3 format.  On Windows, turn Cygwin names into native
>     names, and also turn slashes into backslashes if the shell requires it.

This doc string is fine with me, except ``remove invalid characters''
is not quite true; ``replace'' is closer.  Also, I would add an
explicit reference to w32-shell-dos-semantics.  So:

    Convert a standard file's name to something suitable for the current OS.
    This means to guarantee valid names and perhaps to canonicalize certain
    patterns.

    On Windows and DOS, replace invalid characters.  On DOS, make sure to
    obey the 8.3 limitations.  On Windows, turn Cygwin names into native
    names, and also turn slashes into backslashes if the shell requires it
    (see `w32-shell-dos-semantics').

Re: convert-standard-filename's doc

[Kai Grossjohann]

"Eli Zaretskii" <eliz@gnu.org> writes:

> This doc string is fine with me, except ``remove invalid characters''
> is not quite true; ``replace'' is closer.  Also, I would add an
> explicit reference to w32-shell-dos-semantics.

I like it.

Kai

Re: convert-standard-filename's doc

[Juanma Barranquero]

On Sat, 29 May 2004 13:13:55 +0200, Kai Grossjohann <kai@emptydomain.de> wrote:

> Hm.  Now I've taken a look at the different definitions.  What do you
> think about the following docstring?
> 
>     Convert a standard file's name to something suitable for the current OS.
>     This means to guarantee valid names and perhaps to canonicalize certain
>     patterns.
> 
>     On Windows and DOS, remove invalid characters.  On DOS, make sure to
>     obey the 8.3 format.  On Windows, turn Cygwin names into native
>     names, and also turn slashes into backslashes if the shell requires it.

I honestly don't like a function with three different implementations
having the same docstring explaining its funcionality in every posible
environment.  Yes, I agree the first bit (the first two sentences)
should be in all them.  But after that I would add just valid info.  On
most cases, when I'm going to use a funcion on a Windows Emacs, I'm
interested on what it does, not what it would do, were I to use it on
GNU/Linux (or any other present or future environment)...

BTW, shouldn't it mention that on DOS it strips trailing (back)?slashes
and converts a leading . into _? It doesn't do these things on Windows.

                                                           /L/e/k/t/u

Re: {Spam?} Re: convert-standard-filename's doc

[Stefan Monnier]

> most cases, when I'm going to use a funcion on a Windows Emacs, I'm
> interested on what it does, not what it would do, were I to use it on
> GNU/Linux (or any other present or future environment)...

Agreed.  The only thing important is "what does it conceptually do", and
then maybe some examples.  The conceptual behavior is system-agnostic, so
its description is the generic part of the docstring.  The system-specific
part doesn't have to be complete since it should just give enough examples
for people to be able to infer the rest.


        Stefan

Re: convert-standard-filename's doc

[Eli Zaretskii]

> Date: Sat, 29 May 2004 19:55:52 +0200
> From: Juanma Barranquero <lektu@mi.madritel.es>
> 
> BTW, shouldn't it mention that on DOS it strips trailing (back)?slashes
> and converts a leading . into _?

No.

The trailing slash is not removed in the final result, as the code
does this:

      (if (memq (aref filename (1- flen)) '(?/ ?\\))
	  (concat (convert-standard-filename
		   (substring filename 0 (1- flen)))
		  "/")

As you see, the trailing slash is put back into what the recursive
invocation returns.

As for replacing the leading dot, that's one of the aspects of making
the file name compatible with the 8+3 limitations: a leading dot is
not allowed.

Re: convert-standard-filename's doc

[Juanma Barranquero]

On 31 May 2004 09:05:18 +0200
Eli Zaretskii <eliz@gnu.org> wrote:

> No.
> 
> The trailing slash is not removed in the final result

Ah, OK. I just took a cursory look at the code.

Anyway, I've installed the docstring you proposed, with a slight change
in the default function (the one in files.el). I don't like having all
the systems explained in the doctring, but we've already spend too much
time in such a bikeshed.

                                                                Juanma

Re: convert-standard-filename's doc

[Eli Zaretskii]

> Date: Fri, 28 May 2004 20:26:12 +0200
> From: Juanma Barranquero <lektu@mi.madritel.es>
> 
> Doing what you suggest means a longish docstring with much non-useful
> info (non-useful for each system's users, I mean), and fixing all
> versions of the docstring each time one of the functions is changed or a
> new system added.

We could have a short version in the doc string and a longer one in
the manual.

In any case, I think Kai is right saying that the doc string should
give more emphasis to the fact that the function makes the file name
a valid one for the underlying platform.

Re: convert-standard-filename's doc

[Stefan Monnier]

> prefer to have a hook. Every time I have to redefine a function to
> change some tiny think I'm afraid I'll accidentally miss fixes and
> enhancements to the original function.

Redefine with defadvice.  It's the only half-robust way to do it.


        Stefan

Re: convert-standard-filename's doc

[Juanma Barranquero]

On 28 May 2004 12:21:24 -0400, Stefan Monnier <monnier@iro.umontreal.ca> wrote:

> Redefine with defadvice.  It's the only half-robust way to do it.

Yeah, I already have about a dozen defadvice's in my .emacs.

But sometimes you just want to change a small thing inside a function 
(for example, to take out the downcasing on help-default-arg-highlight).
No amount of defadvising is going to help here; at most you can do an
around advice and just don't use ad-do-it, and then there's no gain wrt
just redefining the function in the first place.

                                                           /L/e/k/t/u

Re: convert-standard-filename's doc

[Richard Stallman]

    > prefer to have a hook. Every time I have to redefine a function to
    > change some tiny think I'm afraid I'll accidentally miss fixes and
    > enhancements to the original function.

    Redefine with defadvice.  It's the only half-robust way to do it.

Ordinarily we have a rule that packages in Emacs should never use
defadvice.  However, in this particular case, I suppose using defadvice
is no worse than completely redefining the function.

Re: convert-standard-filename's doc

[Juanma Barranquero]

On Sat, 29 May 2004 13:02:27 -0400, Richard Stallman <rms@gnu.org> wrote:

> Ordinarily we have a rule that packages in Emacs should never use
> defadvice.  However, in this particular case, I suppose using defadvice
> is no worse than completely redefining the function.

AFAICS, `convert-standard-filename' is always present. That would make
advice.el load unconditionally on Windows and DOS ports (which doesn't
happen right now).

                                                           /L/e/k/t/u

Re: convert-standard-filename's doc

[Kai Grossjohann]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> Basically I think that multiple definitions of the same function is
> a bad thing.

Perhaps we could define three functions
convert-standard-filename-{unix,w32,dos}, and then we could define an
alias convert-standard-filename which invokes the right function
depending on the system?

Kai

Re: convert-standard-filename's doc

[Richard Stallman]

    Perhaps we could define three functions
    convert-standard-filename-{unix,w32,dos}, and then we could define an
    alias convert-standard-filename which invokes the right function
    depending on the system?

I think this comparatively unimportant detail is sucking up lots of
time from people who are capable of doing much more important and
useful things.  Let's make a small change only, and do it quickly,
and move on to those other things.

Re: convert-standard-filename's doc

[Juanma Barranquero]

On Thu, 27 May 2004 20:21:41 +0200
"Eli Zaretskii" <eliz@gnu.org> wrote:

> They don't need to be identical: once a port overloads the standard
> definition with another one, the doc string is replaced as well.

That was my thinking too, but I think Kai's got a point.

> So we could have a doc string that describes what that function does
> on the specific platform where it runs.  The default doc string
> should be left as it is now, IMHO.

I think for the local versions it'll be better to do what Stefan
suggests: a generic part and a specific one. The default one seems
already right.

> >   Returns FILENAME after replacing invalid characters with ! and
> >   converting directory separators to the Windows style (if needed).
> >   It also turns Cygwin-style /cygdrive/x/ pathnames to x:/ paths."
> 
> I think that's good, but I'd also mention the conversion of slashes to
> backslashes,

That's what "converting directory separatos to the Windows style" was
meant to suggest ;)

> with a reference to w32-shell-dos-semantics.

Good idea.

                                                                Juanma

Re: convert-standard-filename's doc

[Eli Zaretskii]

> Date: Fri, 28 May 2004 09:28:59 +0200
> From: Juanma Barranquero <jmbarranquero@wke.es>
> > 
> > I think that's good, but I'd also mention the conversion of slashes to
> > backslashes,
> 
> That's what "converting directory separatos to the Windows style" was
> meant to suggest ;)

Sure, but I'd mention forward and backward slashes explicitly, as not
everyone would guess what ``Windows style'' means.

Re: convert-standard-filename's doc

[Kai Grossjohann]

Juanma Barranquero <jmbarranquero@wke.es> writes:

> Four years ago, the docstring for convert-standard-filename (in files.el)
> was changed, but the ones in w32-fns.el and dos-fns.el were not.
>
> Now, it's trivial to fix them to be identical again. But I wonder
> whether [...]
> is a good description for a function which really *does* something. In
> other words, I'd change the docstring for the w32-fns.el version to
> read: [...]

If I was working on Windows and wanted to develop some Lisp that work
on Unix, and if I would read your Windows description, then I'd think
that I don't want to call this function unconditionally, since Unix
users will not want /cygdrive/foo thingies replaced.

That's the wrong message, I think.

Can you make it clear(er?) that this function is meant to be called
unconditionally and will DTRT on each system?

Kai

Re: convert-standard-filename's doc

[Juanma Barranquero]

On Fri, 28 May 2004 07:22:25 +0200
Kai Grossjohann <kai@emptydomain.de> wrote:

> If I was working on Windows and wanted to develop some Lisp that work
> on Unix, and if I would read your Windows description, then I'd think
> that I don't want to call this function unconditionally

Yes, you're right.

> since Unix
> users will not want /cygdrive/foo thingies replaced.

As an aside, I don't think many Unix/Linux systems use /cygdrive as a
valid directory/mount point/driver/etc., so it shouldn't be a problem...

> Can you make it clear(er?) that this function is meant to be called
> unconditionally and will DTRT on each system?

Do you like better the new wording I've posted?

                                                                Juanma