From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Stefan Monnier Newsgroups: gmane.emacs.bugs Subject: bug#3888: Some variables get the wrong, platform-specific, documentation Date: Wed, 22 Jul 2009 22:43:47 -0400 Message-ID: References: <87ws63gkzh.fsf@stupidchicken.com> <8363dl6g8a.fsf@gnu.org> <83r5w84kv4.fsf@gnu.org> Reply-To: Stefan Monnier , 3888@emacsbugs.donarmstrong.com NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: ger.gmane.org 1248317874 32129 80.91.229.12 (23 Jul 2009 02:57:54 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Thu, 23 Jul 2009 02:57:54 +0000 (UTC) Cc: 3888@emacsbugs.donarmstrong.com, cyd@stupidchicken.com To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu Jul 23 04:57:47 2009 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.50) id 1MToV7-0006QV-Vs for geb-bug-gnu-emacs@m.gmane.org; Thu, 23 Jul 2009 04:57:46 +0200 Original-Received: from localhost ([127.0.0.1]:53703 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1MToV7-0000QJ-AO for geb-bug-gnu-emacs@m.gmane.org; Wed, 22 Jul 2009 22:57:45 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1MToV1-0000Mv-RT for bug-gnu-emacs@gnu.org; Wed, 22 Jul 2009 22:57:39 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1MToUu-0000EU-Od for bug-gnu-emacs@gnu.org; Wed, 22 Jul 2009 22:57:38 -0400 Original-Received: from [199.232.76.173] (port=45386 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1MToUu-0000EJ-LQ for bug-gnu-emacs@gnu.org; Wed, 22 Jul 2009 22:57:32 -0400 Original-Received: from rzlab.ucr.edu ([138.23.92.77]:44976) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1MToUu-00080U-3d for bug-gnu-emacs@gnu.org; Wed, 22 Jul 2009 22:57:32 -0400 Original-Received: from rzlab.ucr.edu (rzlab.ucr.edu [127.0.0.1]) by rzlab.ucr.edu (8.14.3/8.14.3/Debian-5) with ESMTP id n6N2vT4V029682; Wed, 22 Jul 2009 19:57:30 -0700 Original-Received: (from debbugs@localhost) by rzlab.ucr.edu (8.14.3/8.14.3/Submit) id n6N2o4KY028324; Wed, 22 Jul 2009 19:50:04 -0700 X-Loop: owner@emacsbugs.donarmstrong.com Resent-From: Stefan Monnier Resent-To: bug-submit-list@donarmstrong.com Resent-CC: Emacs Bugs Resent-Date: Thu, 23 Jul 2009 02:50:04 +0000 Resent-Message-ID: Resent-Sender: owner@emacsbugs.donarmstrong.com X-Emacs-PR-Message: followup 3888 X-Emacs-PR-Package: emacs X-Emacs-PR-Keywords: Original-Received: via spool by 3888-submit@emacsbugs.donarmstrong.com id=B3888.124831703827405 (code B ref 3888); Thu, 23 Jul 2009 02:50:04 +0000 Original-Received: (at 3888) by emacsbugs.donarmstrong.com; 23 Jul 2009 02:43:58 +0000 X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. Original-Received: from ironport2-out.teksavvy.com (ironport2-out.teksavvy.com [206.248.154.182]) by rzlab.ucr.edu (8.14.3/8.14.3/Debian-5) with ESMTP id n6N2hrhR027394 for <3888@emacsbugs.donarmstrong.com>; Wed, 22 Jul 2009 19:43:55 -0700 X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: AtcEAMdrZ0pFpZx3/2dsb2JhbACBUdB/hA0FgiKEYg X-IronPort-AV: E=Sophos;i="4.43,250,1246852800"; d="scan'208";a="42038735" Original-Received: from 69-165-156-119.dsl.teksavvy.com (HELO ceviche.home) ([69.165.156.119]) by ironport2-out.teksavvy.com with ESMTP; 22 Jul 2009 22:43:46 -0400 Original-Received: by ceviche.home (Postfix, from userid 20848) id 65C1DB40C5; Wed, 22 Jul 2009 22:43:47 -0400 (EDT) In-Reply-To: <83r5w84kv4.fsf@gnu.org> (Eli Zaretskii's message of "Wed, 22 Jul 2009 21:45:51 +0300") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/23.0.94 (gnu/linux) X-detected-operating-system: by monty-python.gnu.org: GNU/Linux 2.6 (newer, 2) Resent-Date: Wed, 22 Jul 2009 22:57:38 -0400 X-BeenThere: bug-gnu-emacs@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:29563 Archived-At: > No technical problems, but experience teaches me that these solutions > don't hold in practice, i.e. new non-internal functions that overload > others pop up with time. Yes, clearly, this solution is of the form "let's try and impose this discipline on ourselves in the future". But it's not like we usually shy away from coding conventions. > Also, the `foo-internal' trick does not solve the problem of the doc > string that needs to say something platform-specific without bothering > too much the users of other platforms. That is a docstring problem that needs to be addressed with good use of language and judgement. There's no silver bullet for this one. > Finally, there's (an admittedly very specific and quite rare) problem > of ls-lisp and its ilk that overload the default implementation with > something utterly different, and whose doc string _must_ be very > different if we want it to be useful. Yes, but again it's not difficult to find a way to do it right, e.g. by having a shared function whose docstring hyperlinks to the two possible implementation alternatives and their respective docstrings. We've done it already and can do it again. > I tried to think of an infrastructure that would solve all these > use-cases in a relatively elegant way that would not become a > maintenance burden. That would be swell, but my proposal is a lot more modest. Stefan