convert-standard-filename documentation is insufficient

convert-standard-filename documentation is insufficient

[Jari Aalto]

Given following description:

    (convert-standard-filename FILENAME)

    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.

This leaves completely open where function would be used.
Please provide concrete examples in the documentation string.

Jari

Re: convert-standard-filename documentation is insufficient

[Eli Zaretskii]

> From: Jari Aalto <jari.aalto@cante.net>
> Date: Sat, 06 Nov 2004 20:07:07 +0200
> 
>     (convert-standard-filename FILENAME)
> 
>     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.
> 
> This leaves completely open where function would be used.
> Please provide concrete examples in the documentation string.

This function was introduced for Lisp programmers, not for users.  The
rationale for its existence and its recommended usage are explained in
the ELisp manual (which will be part of the standard Emacs distro as
of the next release).

Given the above, I personally don't see any convincing reasons to add
the usage information to the doc string.

Re: convert-standard-filename documentation is insufficient

[Luc Teirlinck]

Eli Zaretskii wrote:
    
    Given the above, I personally don't see any convincing reasons to add
    the usage information to the doc string.

Actually, the docstring appears to have already been expanded in
current CVS:

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

  This function's standard definition is trivial; it just returns
  the argument.  However, 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')."

I would propose a small change in the 72 character first line.
Replace `something' by `one'.  This brings it down to 66 characters,
which is within the maximum allowed 67 and looks better in the
`apropos' output:

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

If there are no objections, I will install this change in CVS.

Sincerely,

Luc.

Re: convert-standard-filename documentation is insufficient

[Eli Zaretskii]

> Date: Sun, 7 Nov 2004 16:00:02 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> CC: bug-gnu-emacs@gnu.org, bug-gnu-emacs@gnu.org
> 
> Eli Zaretskii wrote:
>     
>     Given the above, I personally don't see any convincing reasons to add
>     the usage information to the doc string.
> 
> Actually, the docstring appears to have already been expanded in
> current CVS:
> 
>     "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.
> 
>   This function's standard definition is trivial; it just returns
>   the argument.  However, 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')."

This still doesn't say what the OP wanted: what is the intended use of
this function.  It just says what the function does, but not in what
circumstances it should be used.

> Convert a standard file's name to one suitable for the current OS.
> 
> If there are no objections, I will install this change in CVS.

FWIW, I find the current wording more clear.

Re: convert-standard-filename documentation is insufficient

[Stefan Monnier]

>     (convert-standard-filename FILENAME)

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

> This leaves completely open where function would be used.
> Please provide concrete examples in the documentation string.

This function is to be used for packages which use hardcoded file names.
E.g. it is used for ~/.emacs, ~/.gnus and things like that, where the author
has to choose a name and wants to make sure that it still works on systems
where this name might not be valid.

I'm not sure how to best express it.  Do you have a concrete suggestion for
a new docstring?  (please don't just say "yes, your above four lines would
be fine")


        Stefan


PS: Now that I think about it, why on earth does it try to handle
    cygwin filenames?  Or more specifically, under what circumstance would
    this function receive a cygwin file name?

Re: convert-standard-filename documentation is insufficient

[Luc Teirlinck]

Alternately, we could just put in a link to the Elisp manual.  All the
user has to do is click mouse-2 or press RETURN on the link.

Also the first line needs to be shortened since it is 72 characters, 5
longer than the maximum allowed 67.  I first suggested doing this by
replacing `something' by `one'.  An alternative is to delete "current"
in front of OS.  It is redundant.  Which _other_ operating system
could be meant?

That would give:

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

  This function's standard definition is trivial; it just returns
  the argument.  However, 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'

  See `(elisp)Standard File Names' for more details."

Sincerely,

Luc.

Re: convert-standard-filename documentation is insufficient

[Luc Teirlinck]

Sorry, I forgot to put `Info node' in front of the link:

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

This function's standard definition is trivial; it just returns
the argument.  However, 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'

See Info node `(elisp)Standard File Names' for more details."

Sincerely,

Luc.

Re: convert-standard-filename documentation is insufficient

[Jeff Dwork]

How about this for the first line?

  "Convert string FILENAME to a legal filename for the OS.

remainder as below.

Jeff

Luc Teirlinck writes:
 > To: teirllm@dms.auburn.edu
 > cc: bug-gnu-emacs@gnu.org, monnier@iro.umontreal.ca
 > Subject: Re: convert-standard-filename documentation is insufficient
 > Date: Mon, 8 Nov 2004 16:02:11 -0600 (CST)
 > 
 > Sorry, I forgot to put `Info node' in front of the link:
 > 
 >   "Convert a standard file's name to something suitable for the OS.
 > This means to guarantee valid names and perhaps to canonicalize
 > certain patterns.
 > 
 > This function's standard definition is trivial; it just returns
 > the argument.  However, 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'
 > 
 > See Info node `(elisp)Standard File Names' for more details."
 > 
 > Sincerely,
 > 
 > Luc.
 > 
 > 
 > _______________________________________________
 > Bug-gnu-emacs mailing list
 > Bug-gnu-emacs@gnu.org
 > http://lists.gnu.org/mailman/listinfo/bug-gnu-emacs

-- 
Jeff Dwork                     | jeff.dwork@amd.com  408-307-2496 (cell)
Advanced Micro Devices, M/S 362| 408-749-5216 (desk) 408-774-7811 (fax)
PO Box 3453                    |----------------------------------------
Sunnyvale, Ca 94088-3453       | 

Re: convert-standard-filename documentation is insufficient

[Werner LEMBERG]

>   "Convert string FILENAME to a legal filename for the OS.

`valid', not `legal', please.


    Werner

Re: convert-standard-filename documentation is insufficient

[Luc Teirlinck]

Jeff Dwork wrote:

   How about this for the first line?

     "Convert string FILENAME to a legal filename for the OS.

   remainder as below.

If I understand correctly, the purpose of `convert-standard-filename'
is not to take a file name that is _valid_ (or "legal") under GNU/Unix
type systems and convert it to a name that is valid under another OS.
I believe that is done by other functions such as
`file-name-as-directory' and `expand-file-name'.  I believe that the
purpose of `convert-standard-filename' is to convert a _standard_ file
name under GNU/Unix type systems into a name that is standard under
another OS, or maybe just "suitable" if there is no real standard form
on that OS.  Hence:

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

Sincerely,

Luc.

Re: convert-standard-filename documentation is insufficient

[Luc Teirlinck]

I probably used the wrong terminology in my previous reply and
explained things somewhat inaccurately.  It probably works better on
an example.  The "standard file name" of the file to store abbrevs in
is ".abbrev_defs" on GNU/Unix type systems.  This file name follows
some standard conventions on GNU/Linux.  It is not just "valid" on
GNU/Linux.  On MS-DOS this gets converted to _abbrev.def, which is not
just valid on MS-DOS, but follows conventions standard on MS-DOS.

In:

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

"standard file name" means something like ".abbrev_defs", as opposed
to a file name chosen by the user.  "something suitable for the OS".
means not just merely valid, but also following standard conventions
for the OS.

Sincerely,

Luc.