From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Lennart Borgman Newsgroups: gmane.emacs.devel Subject: Re: Suggestions for the temporary windows used from the minibuffer Date: Tue, 09 Aug 2005 18:42:44 +0200 Message-ID: <42F8DD04.30501@student.lu.se> References: <42F34A82.9070703@student.lu.se> <42F3F3D7.7060506@student.lu.se> <42F68B76.7030109@student.lu.se> NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-15; format=flowed Content-Transfer-Encoding: 7bit X-Trace: sea.gmane.org 1123605955 29626 80.91.229.2 (9 Aug 2005 16:45:55 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Tue, 9 Aug 2005 16:45:55 +0000 (UTC) Cc: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue Aug 09 18:45:52 2005 Return-path: Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1E2XCa-0006l3-39 for ged-emacs-devel@m.gmane.org; Tue, 09 Aug 2005 18:43:44 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1E2XFe-0005ei-1P for ged-emacs-devel@m.gmane.org; Tue, 09 Aug 2005 12:46:54 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1E2XFA-0005RV-C3 for emacs-devel@gnu.org; Tue, 09 Aug 2005 12:46:24 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1E2XF6-0005Pn-3N for emacs-devel@gnu.org; Tue, 09 Aug 2005 12:46:21 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1E2XF5-0005PC-Sa for emacs-devel@gnu.org; Tue, 09 Aug 2005 12:46:19 -0400 Original-Received: from [81.228.11.159] (helo=pne-smtpout2-sn1.fre.skanova.net) by monty-python.gnu.org with esmtp (Exim 4.34) id 1E2XPa-0003UT-Tj; Tue, 09 Aug 2005 12:57:11 -0400 Original-Received: from [192.168.123.121] (83.249.204.33) by pne-smtpout2-sn1.fre.skanova.net (7.2.060.1) id 42B937170075FEE0; Tue, 9 Aug 2005 18:42:44 +0200 User-Agent: Mozilla Thunderbird 1.0.6 (Windows/20050716) X-Accept-Language: en-us, en Original-To: rms@gnu.org In-Reply-To: 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:41799 Richard M. Stallman wrote: > +When calling FNAME if the optional parameters X-FUNCTION, X-CHAR > +and X-DESCRIPTION to the defined function FNAME are given they > +must all be given. In this case the the sequence > +`%X-DESCRIPTION%' in HELP-TEXT is replaced with the parameters > +X-CHAR character and the X-DESCRIPTION string. Also the keyboard > +character X-CHAR is bound to the parameter X-FUNCTION. > >I don't understand that text; I am simply lost. You need to state >it more clearly. > >The best place for this info is in the doc string of the constructed >function that will take these arguments. Moving the text there will >help you simplify the text. However, part of the reason this is >confusing is that the explanation states the algorithm for USING these >arguments. What it needs to say is WHAT THEY MEAN. Documentation >should not read like a program logic manual. > > The help text is for the macro make-help-screen. The text is just meant for the developers who wants to use this macro. The constructed function currently has a help string that just says "Help command" and I have not changed that. Putting the help text above in the constructed function would make it invisible to the developer if he/she does not read the code of make-help-screen. The users have no use for this help text. This is for use with help in isearch mode. It adds the text X-DESCRIPTION to the text that is normally shown when you type C-h. It also binds the character X-CHAR to the function X-FUNCTION in keymap used in C-h help. This is only done for isearch, otherwise the new optional arguments X-FUNCTION, X-CHAR and X-DESCRIPTION are not used. Maybe it would help to say "See isearch mode for an example"? > >+ (mapc (lambda (elt) >+ (let ((new (if (consp elt) (cdr elt) elt)) >+ (orig (if (consp elt) (car elt) elt))) >+ (mapc (lambda (key) >+ (define-key still-map key new)) >+ (where-is-internal orig)))) >+ still-lst) > >That code needs a comment to explain what it is doing. > > There is a comment right over still-map (though it is short). I can add some more comment here of course, like ";; Copy the keys from the users current key bindings that still should be available (ie keyboard scrolling with Page Up/Down)".