From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.devel Subject: RE: (fn ...) - please fill it at the point of generation Date: Sat, 29 Dec 2007 10:15:58 -0800 Message-ID: References: <87ir2h4dle.fsf@catnip.gol.com> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1198952219 2756 80.91.229.12 (29 Dec 2007 18:16:59 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 29 Dec 2007 18:16:59 +0000 (UTC) Cc: Emacs-Devel To: "Miles Bader" Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Dec 29 19:17:12 2007 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.50) id 1J8gFE-0004Op-42 for ged-emacs-devel@m.gmane.org; Sat, 29 Dec 2007 19:17:12 +0100 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1J8gEs-0005T2-Qi for ged-emacs-devel@m.gmane.org; Sat, 29 Dec 2007 13:16:50 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1J8gEo-0005PK-1o for emacs-devel@gnu.org; Sat, 29 Dec 2007 13:16:46 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1J8gEm-0005NJ-B3 for emacs-devel@gnu.org; Sat, 29 Dec 2007 13:16:45 -0500 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1J8gEm-0005NB-5F for emacs-devel@gnu.org; Sat, 29 Dec 2007 13:16:44 -0500 Original-Received: from rgminet01.oracle.com ([148.87.113.118]) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1J8gEi-0000KL-BQ; Sat, 29 Dec 2007 13:16:40 -0500 Original-Received: from agmgw2.us.oracle.com (agmgw2.us.oracle.com [152.68.180.213]) by rgminet01.oracle.com (Switch-3.2.4/Switch-3.1.6) with ESMTP id lBTIGbh3001281; Sat, 29 Dec 2007 11:16:38 -0700 Original-Received: from acsmt350.oracle.com (acsmt350.oracle.com [141.146.40.150]) by agmgw2.us.oracle.com (Switch-3.2.0/Switch-3.2.0) with ESMTP id lBTGHERI028499; Sat, 29 Dec 2007 11:16:37 -0700 Original-Received: from dhcp-amer-csvpn-gw1-141-144-64-21.vpn.oracle.com by acsmt350.oracle.com with ESMTP id 3468984371198952145; Sat, 29 Dec 2007 10:15:45 -0800 X-Priority: 3 (Normal) X-MSMail-Priority: Normal X-Mailer: Microsoft Outlook IMO, Build 9.0.6604 (9.0.2911.0) Importance: Normal In-Reply-To: <87ir2h4dle.fsf@catnip.gol.com> X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.3198 X-Brightmail-Tracker: AAAAAQAAAAI= X-Brightmail-Tracker: AAAAAQAAAAI= X-Whitelist: TRUE X-Whitelist: TRUE X-detected-kernel: by monty-python.gnu.org: Linux 2.4-2.6 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:85628 Archived-At: > >> It's really not part of the doc string as such, it's an interface > >> description. > > > > That's a good feint. This part of the doc string isn't right, so to fix > > things we'll just say it's not part of the doc string. > > No, it was always intended as a function signature, not a text string > for display. It's put into the _raw_ docstring because that's a > convenient place to put it, but it is intended that this be filtered > appropriately for display. If the signature text is not intended as part of the doc string, then it and the doc string should each be available separately, not joined at the hip from birth. Function `documentation' (or some other function) should return only the doc string per se, and some other function (e.g. `signature') should return the signature (interface spec). In my use of it, I display a buffer which includes function names and doc strings of functions that match an input regexp. It can thus include all defined functions. That's between 8000 and 9000 doc strings at the start of an Emacs session, in my environment at least. I fit the buffer's frame automatically, which takes into account the longest line (250 chars - from a signature). You can change your input regexp on the fly, and the matching function names and doc strings are updated (and the frame is refit). It would be unreasonable to examine each matching doc string, try to determine whether it in fact contained a (fn...) signature, and, if so, fill that signature. Unreasonable in terms of performance and, I maintain, unreasonable in terms of Emacs design. Currently, AFAIK, the only function I have available to retrieve the doc string is `documentation', and that currently includes the problematic line that you are saying should not be considered to be part of the doc string. Practically speaking, it *is* part of the doc string (it is included by `documentation'), but OK, it shouldn't be. If you want to maintain the independence of the signature from the doc string, fine. But in that case, please do it right - provide a separate function that will retrieve only the doc string.