Re: Suggestions for the temporary windows used from the minibuffer

[Lennart Borgman]

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