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:14:57 -0800 Message-ID: References: <87d4spqvha.fsf@ambire.localdomain> 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 1198952142 2587 80.91.229.12 (29 Dec 2007 18:15:42 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 29 Dec 2007 18:15:42 +0000 (UTC) To: "Thien-Thi Nguyen" , Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Dec 29 19:15:55 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 1J8gDy-00042C-ON for ged-emacs-devel@m.gmane.org; Sat, 29 Dec 2007 19:15:55 +0100 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1J8gDd-00047W-68 for ged-emacs-devel@m.gmane.org; Sat, 29 Dec 2007 13:15:33 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1J8gD5-0003e5-Ic for emacs-devel@gnu.org; Sat, 29 Dec 2007 13:14:59 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1J8gD3-0003c7-Mt for emacs-devel@gnu.org; Sat, 29 Dec 2007 13:14:58 -0500 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1J8gD3-0003bt-DI for emacs-devel@gnu.org; Sat, 29 Dec 2007 13:14:57 -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 1J8gD3-0008HE-3Z for emacs-devel@gnu.org; Sat, 29 Dec 2007 13:14:57 -0500 Original-Received: from rgmgw2.us.oracle.com (rgmgw2.us.oracle.com [138.1.186.111]) by rgminet01.oracle.com (Switch-3.2.4/Switch-3.1.6) with ESMTP id lBTIEsdv000404; Sat, 29 Dec 2007 11:14:54 -0700 Original-Received: from rcsmt251.oracle.com (rcsmt251.oracle.com [148.87.90.196]) by rgmgw2.us.oracle.com (Switch-3.2.4/Switch-3.2.4) with ESMTP id lBTI0idN017134; Sat, 29 Dec 2007 11:14:53 -0700 Original-Received: from dhcp-amer-csvpn-gw1-141-144-64-21.vpn.oracle.com by acsmt351.oracle.com with ESMTP id 3468984291198952084; Sat, 29 Dec 2007 10:14:44 -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: <87d4spqvha.fsf@ambire.localdomain> 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:85627 Archived-At: > What's the advantage of having one line in a doc string > that doesn't fit the doc-string pattern (convention)? > How is that more general and less of a special case? > > "one line" to munge is more general than "one form". put > another way: more tools know how to parse the former than > the latter. > > the "docstring pattern (convention)" is applicable for > viewing the docstring. although the part under discussion > is technically included in the "string", it should be > semantically distinguished from the rest of the string > because it is not intended for direct viewing. Fair enough. If that is the intention, then, yes, it should be not only semantically but also practically distinguished from the rest of the string (which is presentation-ready). IOW, we should have separate retrieval functions for the doc string per se and the interface spec (signature). > that part is markup, requiring further processing at the > presentation stage. to conflate the presentation and the > generation is a step towards bad design. a good middle > path would be to pool common presentation methods, as long > as those methods are not imposed on the phases uninvolved > w/ presentation. The only way currently to recuperate the doc string gives you all of it, including the part you consider not to be part of the doc string but "markup". If that last line (interface spec) is not part of the doc string, and you want to keep it unfilled because filling is presentation, then `documentation' (or some other function) should return only the doc string per se, not the whole kit and caboodle. Especially since `documentation' is written in C, so it can't be hacked without rebuilding Emacs. IOW, either the "interface spec" is part of the doc string or it is not. If it is, then it too should be presentation-ready, like the rest of the string. If it is not, then we should have a separate function that gives us only the doc string (without interface spec).