Re: convert-standard-filename documentation is insufficient

[Stefan Monnier <monnier@iro.umontreal.ca>]

>     (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?