From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Juanma Barranquero Newsgroups: gmane.emacs.devel Subject: Re: convert-standard-filename's doc Date: Fri, 28 May 2004 20:26:12 +0200 Sender: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Message-ID: <20040528200923.5B69.LEKTU@mi.madritel.es> References: <20040528092904.7532.JMBARRANQUERO@wke.es> <86k6ywk6co.fsf@rumba.de.uu.net> NNTP-Posting-Host: deer.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="US-ASCII" Content-Transfer-Encoding: 7bit X-Trace: sea.gmane.org 1085799462 17399 80.91.224.253 (29 May 2004 02:57:42 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sat, 29 May 2004 02:57:42 +0000 (UTC) Original-X-From: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Sat May 29 04:57:35 2004 Return-path: Original-Received: from quimby.gnus.org ([80.91.224.244]) by deer.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 1BTu2R-0002NS-00 for ; Sat, 29 May 2004 04:57:35 +0200 Original-Received: from lists.gnu.org ([199.232.76.165]) by quimby.gnus.org with esmtp (Exim 3.35 #1 (Debian)) id 1BTu2Q-0000Zc-00 for ; Sat, 29 May 2004 04:57:35 +0200 Original-Received: from [127.0.0.1] (helo=mailman.gnu.org) by lists.gnu.org with esmtp (Exim 4.33) id 1BTu2U-0007mj-ML for emacs-devel@quimby.gnus.org; Fri, 28 May 2004 22:57:38 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.33) id 1BTtsK-0003I0-Um for emacs-devel@gnu.org; Fri, 28 May 2004 22:47:09 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.33) id 1BTtsF-0003FG-Io for emacs-devel@gnu.org; Fri, 28 May 2004 22:47:05 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.33) id 1BTtsE-0003Eo-TR for emacs-devel@gnu.org; Fri, 28 May 2004 22:47:03 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.34) id 1BTn7o-000116-6E for emacs-devel@gnu.org; Fri, 28 May 2004 15:34:40 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.34) id 1BTmGx-0000Bv-GX for emacs-devel@gnu.org; Fri, 28 May 2004 14:40:35 -0400 Original-Received: from [62.81.186.16] (helo=smtp06.retemail.es) by monty-python.gnu.org with esmtp (Exim 4.34) id 1BTm3a-0006Lj-H4 for emacs-devel@gnu.org; Fri, 28 May 2004 14:26:14 -0400 Original-Received: from [127.0.0.1] ([213.37.34.123]) by smtp06.retemail.es (InterMail vM.5.01.05.32 201-253-122-126-132-20030307) with ESMTP id <20040528182611.WOLB1219.smtp06.retemail.es@[127.0.0.1]> for ; Fri, 28 May 2004 20:26:11 +0200 Original-To: emacs-devel@gnu.org In-Reply-To: <86k6ywk6co.fsf@rumba.de.uu.net> X-Mailer: Becky! ver. 2.09.01 [en] X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.4 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Xref: main.gmane.org gmane.emacs.devel:24118 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:24118 On Fri, 28 May 2004 15:51:19 +0200, Kai Grossjohann 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