From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Richard Stallman Newsgroups: gmane.emacs.devel Subject: Re: Patch: make eldoc indicate current argument Date: Wed, 27 Jun 2007 19:42:53 -0400 Message-ID: References: Reply-To: rms@gnu.org NNTP-Posting-Host: lo.gmane.org Content-Type: text/plain; charset=ISO-8859-15 X-Trace: sea.gmane.org 1182987805 27952 80.91.229.12 (27 Jun 2007 23:43:25 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Wed, 27 Jun 2007 23:43:25 +0000 (UTC) Cc: emacs-devel@gnu.org To: tromey@redhat.com Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Jun 28 01:43:23 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 1I3hAM-0002bT-HU for ged-emacs-devel@m.gmane.org; Thu, 28 Jun 2007 01:43:18 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1I3hAL-0002Fg-W5 for ged-emacs-devel@m.gmane.org; Wed, 27 Jun 2007 19:43:18 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1I3h9y-0001zR-U9 for emacs-devel@gnu.org; Wed, 27 Jun 2007 19:42:55 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1I3h9y-0001z3-KR for emacs-devel@gnu.org; Wed, 27 Jun 2007 19:42:54 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1I3h9y-0001yz-94 for emacs-devel@gnu.org; Wed, 27 Jun 2007 19:42:54 -0400 Original-Received: from fencepost.gnu.org ([140.186.70.10]) by monty-python.gnu.org with esmtp (Exim 4.60) (envelope-from ) id 1I3h9x-0005nr-VC for emacs-devel@gnu.org; Wed, 27 Jun 2007 19:42:54 -0400 Original-Received: from rms by fencepost.gnu.org with local (Exim 4.60) (envelope-from ) id 1I3h9x-0005k0-OS; Wed, 27 Jun 2007 19:42:53 -0400 In-reply-to: (message from Tom Tromey on Wed, 27 Jun 2007 11:04:08 -0600) X-detected-kernel: Linux 2.6, seldom 2.4 (older, 4) 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:73952 Archived-At: * Emacs formats documentation inconsistently. Some functions use &optional and &rest in their description. I think you are talking about calling patterns in doc strings, not about documentation in general. Is that right? &optional and &rest appear in calling patterns of functions. We use ellipses and square brackets in calling patterns of macros and special forms. Some use "..." appended to an argument name, e.g. "CLAUSES...". And, some use "..." as a standalone argument name (see 'when'). Do you mean this? (when COND BODY ...) If so, I think that is a misunderstanding. The ellipsis here is not an argument name, it is just an ellipsis. The space after `BODY' has no significance. Perhaps we should delete that space, for consistency. Would someone like to do that? Would you like to make a list of the places where such spurious spaces appear? * If the documentation comments had a bit more structure, this could also show the description of the current argument, say as a tooltip. I don't think there is a reliable way to extract this information at present. Alas, this would be a tremendous rewrite, and could make the doc strings less readable for their current use if we're not careful. Maybe some sort of cookie to indicate where the discussion of an argument begins, within the doc string, would let you do this, but it won't be easy. The difficulty can be seen in the doc string of `when': If COND yields non-nil, do BODY, else return nil. When COND yields non-nil, eval BODY forms sequentially and return value of last one, or nil if there are none. It is not natural to separate this into a discussion of COND and a discussion of BODY. But if you don't insist that each segment discuss only one argument, we could subdivide each doc string into segments, and they you could find all the segments in which the argument name is mentioned, and display them. Suppose that we use `][' as the segment separator. Here as an example is the doc string of call-process, showing what this would look like. (call-process PROGRAM &optional INFILE BUFFER DISPLAY &rest ARGS) Call PROGRAM synchronously in separate process. The remaining arguments are optional. ][The program's input comes from file INFILE (nil means `/dev/null'). ][Insert output in BUFFER before point; t means current buffer; nil for BUFFER means discard it; 0 means discard and don't wait. BUFFER can also have the form (REAL-BUFFER STDERR-FILE); in that case, REAL-BUFFER says what to do with standard output, as above, while STDERR-FILE says what to do with standard error in the child. STDERR-FILE may be nil (discard standard error output), t (mix it with ordinary output), or a file name string. ][Fourth arg DISPLAY non-nil means redisplay buffer as output is inserted. ][Remaining arguments are strings passed as command arguments to PROGRAM. ][If executable PROGRAM can't be found as an executable, `call-process' signals a Lisp error. `call-process' reports errors in execution of the program only through its return and output. ][If BUFFER is 0, `call-process' returns immediately with value nil. Otherwise it waits for PROGRAM to terminate and returns a numeric exit status or a signal description string. ][If you quit, the process is killed with SIGINT, or SIGKILL if you quit again. If you like, you could try experimenting with this idea and see what you can make it do.