[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Suggestions for the temporary windows used from the minibuffer

From: Lennart Borgman
Subject: Re: Suggestions for the temporary windows used from the minibuffer
Date: Tue, 09 Aug 2005 18:42:44 +0200
User-agent: Mozilla Thunderbird 1.0.6 (Windows/20050716)

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)".

reply via email to

[Prev in Thread] Current Thread [Next in Thread]