Re: convert-standard-filename's doc

[Juanma Barranquero <lektu@mi.madritel.es>]

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