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.