Merge from emacs--rel--22
[bpt/emacs.git] / doc / lispref / help.texi
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
4 @c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../../info/help
7 @node Documentation, Files, Modes, Top
8 @chapter Documentation
9 @cindex documentation strings
10
11 GNU Emacs Lisp has convenient on-line help facilities, most of which
12 derive their information from the documentation strings associated with
13 functions and variables. This chapter describes how to write good
14 documentation strings for your Lisp programs, as well as how to write
15 programs to access documentation.
16
17 Note that the documentation strings for Emacs are not the same thing
18 as the Emacs manual. Manuals have their own source files, written in
19 the Texinfo language; documentation strings are specified in the
20 definitions of the functions and variables they apply to. A collection
21 of documentation strings is not sufficient as a manual because a good
22 manual is not organized in that fashion; it is organized in terms of
23 topics of discussion.
24
25 For commands to display documentation strings, see @ref{Help, ,
26 Help, emacs, The GNU Emacs Manual}. For the conventions for writing
27 documentation strings, see @ref{Documentation Tips}.
28
29 @menu
30 * Documentation Basics:: Good style for doc strings.
31 Where to put them. How Emacs stores them.
32 * Accessing Documentation:: How Lisp programs can access doc strings.
33 * Keys in Documentation:: Substituting current key bindings.
34 * Describing Characters:: Making printable descriptions of
35 non-printing characters and key sequences.
36 * Help Functions:: Subroutines used by Emacs help facilities.
37 @end menu
38
39 @node Documentation Basics
40 @comment node-name, next, previous, up
41 @section Documentation Basics
42 @cindex documentation conventions
43 @cindex writing a documentation string
44 @cindex string, writing a doc string
45
46 A documentation string is written using the Lisp syntax for strings,
47 with double-quote characters surrounding the text of the string. This
48 is because it really is a Lisp string object. The string serves as
49 documentation when it is written in the proper place in the definition
50 of a function or variable. In a function definition, the documentation
51 string follows the argument list. In a variable definition, the
52 documentation string follows the initial value of the variable.
53
54 When you write a documentation string, make the first line a
55 complete sentence (or two complete sentences) since some commands,
56 such as @code{apropos}, show only the first line of a multi-line
57 documentation string. Also, you should not indent the second line of
58 a documentation string, if it has one, because that looks odd when you
59 use @kbd{C-h f} (@code{describe-function}) or @kbd{C-h v}
60 (@code{describe-variable}) to view the documentation string. There
61 are many other conventions for doc strings; see @ref{Documentation
62 Tips}.
63
64 Documentation strings can contain several special substrings, which
65 stand for key bindings to be looked up in the current keymaps when the
66 documentation is displayed. This allows documentation strings to refer
67 to the keys for related commands and be accurate even when a user
68 rearranges the key bindings. (@xref{Keys in Documentation}.)
69
70 @vindex emacs-lisp-docstring-fill-column
71 Emacs Lisp mode fills documentation strings to the width
72 specified by @code{emacs-lisp-docstring-fill-column}.
73
74 In Emacs Lisp, a documentation string is accessible through the
75 function or variable that it describes:
76
77 @itemize @bullet
78 @item
79 @kindex function-documentation
80 The documentation for a function is usually stored in the function
81 definition itself (@pxref{Lambda Expressions}). The function
82 @code{documentation} knows how to extract it. You can also put
83 function documentation in the @code{function-documentation} property
84 of the function name. That is useful with definitions such as
85 keyboard macros that can't hold a documentation string.
86
87 @item
88 @kindex variable-documentation
89 The documentation for a variable is stored in the variable's property
90 list under the property name @code{variable-documentation}. The
91 function @code{documentation-property} knows how to retrieve it.
92 @end itemize
93
94 @cindex @file{DOC-@var{version}} (documentation) file
95 To save space, the documentation for preloaded functions and variables
96 (including primitive functions and autoloaded functions) is stored in
97 the file @file{emacs/etc/DOC-@var{version}}---not inside Emacs. The
98 documentation strings for functions and variables loaded during the
99 Emacs session from byte-compiled files are stored in those files
100 (@pxref{Docs and Compilation}).
101
102 The data structure inside Emacs has an integer offset into the file, or
103 a list containing a file name and an integer, in place of the
104 documentation string. The functions @code{documentation} and
105 @code{documentation-property} use that information to fetch the
106 documentation string from the appropriate file; this is transparent to
107 the user.
108
109 @c Wordy to prevent overfull hbox. --rjc 15mar92
110 The @file{emacs/lib-src} directory contains two utilities that you can
111 use to print nice-looking hardcopy for the file
112 @file{emacs/etc/DOC-@var{version}}. These are @file{sorted-doc} and
113 @file{digest-doc}.
114
115 @node Accessing Documentation
116 @section Access to Documentation Strings
117
118 @defun documentation-property symbol property &optional verbatim
119 This function returns the documentation string that is recorded in
120 @var{symbol}'s property list under property @var{property}. It
121 retrieves the text from a file if the value calls for that. If the
122 property value isn't @code{nil}, isn't a string, and doesn't refer to
123 text in a file, then it is evaluated to obtain a string.
124
125 The last thing this function does is pass the string through
126 @code{substitute-command-keys} to substitute actual key bindings,
127 unless @var{verbatim} is non-@code{nil}.
128
129 @smallexample
130 @group
131 (documentation-property 'command-line-processed
132 'variable-documentation)
133 @result{} "Non-nil once command line has been processed"
134 @end group
135 @group
136 (symbol-plist 'command-line-processed)
137 @result{} (variable-documentation 188902)
138 @end group
139 @group
140 (documentation-property 'emacs 'group-documentation)
141 @result{} "Customization of the One True Editor."
142 @end group
143 @end smallexample
144 @end defun
145
146 @defun documentation function &optional verbatim
147 This function returns the documentation string of @var{function}.
148 @code{documentation} handles macros, named keyboard macros, and
149 special forms, as well as ordinary functions.
150
151 If @var{function} is a symbol, this function first looks for the
152 @code{function-documentation} property of that symbol; if that has a
153 non-@code{nil} value, the documentation comes from that value (if the
154 value is not a string, it is evaluated). If @var{function} is not a
155 symbol, or if it has no @code{function-documentation} property, then
156 @code{documentation} extracts the documentation string from the actual
157 function definition, reading it from a file if called for.
158
159 Finally, unless @var{verbatim} is non-@code{nil}, it calls
160 @code{substitute-command-keys} so as to return a value containing the
161 actual (current) key bindings.
162
163 The function @code{documentation} signals a @code{void-function} error
164 if @var{function} has no function definition. However, it is OK if
165 the function definition has no documentation string. In that case,
166 @code{documentation} returns @code{nil}.
167 @end defun
168
169 @defun face-documentation face
170 This function returns the documentation string of @var{face} as a
171 face.
172 @end defun
173
174 @c Wordy to prevent overfull hboxes. --rjc 15mar92
175 Here is an example of using the two functions, @code{documentation} and
176 @code{documentation-property}, to display the documentation strings for
177 several symbols in a @samp{*Help*} buffer.
178
179 @anchor{describe-symbols example}
180 @smallexample
181 @group
182 (defun describe-symbols (pattern)
183 "Describe the Emacs Lisp symbols matching PATTERN.
184 All symbols that have PATTERN in their name are described
185 in the `*Help*' buffer."
186 (interactive "sDescribe symbols matching: ")
187 (let ((describe-func
188 (function
189 (lambda (s)
190 @end group
191 @group
192 ;; @r{Print description of symbol.}
193 (if (fboundp s) ; @r{It is a function.}
194 (princ
195 (format "%s\t%s\n%s\n\n" s
196 (if (commandp s)
197 (let ((keys (where-is-internal s)))
198 (if keys
199 (concat
200 "Keys: "
201 (mapconcat 'key-description
202 keys " "))
203 "Keys: none"))
204 "Function")
205 @end group
206 @group
207 (or (documentation s)
208 "not documented"))))
209
210 (if (boundp s) ; @r{It is a variable.}
211 @end group
212 @group
213 (princ
214 (format "%s\t%s\n%s\n\n" s
215 (if (user-variable-p s)
216 "Option " "Variable")
217 @end group
218 @group
219 (or (documentation-property
220 s 'variable-documentation)
221 "not documented")))))))
222 sym-list)
223 @end group
224
225 @group
226 ;; @r{Build a list of symbols that match pattern.}
227 (mapatoms (function
228 (lambda (sym)
229 (if (string-match pattern (symbol-name sym))
230 (setq sym-list (cons sym sym-list))))))
231 @end group
232
233 @group
234 ;; @r{Display the data.}
235 (with-output-to-temp-buffer "*Help*"
236 (mapcar describe-func (sort sym-list 'string<))
237 (print-help-return-message))))
238 @end group
239 @end smallexample
240
241 The @code{describe-symbols} function works like @code{apropos},
242 but provides more information.
243
244 @smallexample
245 @group
246 (describe-symbols "goal")
247
248 ---------- Buffer: *Help* ----------
249 goal-column Option
250 *Semipermanent goal column for vertical motion, as set by @dots{}
251 @end group
252 @c Do not blithely break or fill these lines.
253 @c That makes them incorrect.
254
255 @group
256 set-goal-column Keys: C-x C-n
257 Set the current horizontal position as a goal for C-n and C-p.
258 @end group
259 @c DO NOT put a blank line here! That is factually inaccurate!
260 @group
261 Those commands will move to this position in the line moved to
262 rather than trying to keep the same horizontal position.
263 With a non-nil argument, clears out the goal column
264 so that C-n and C-p resume vertical motion.
265 The goal column is stored in the variable `goal-column'.
266 @end group
267
268 @group
269 temporary-goal-column Variable
270 Current goal column for vertical motion.
271 It is the column where point was
272 at the start of current run of vertical motion commands.
273 When the `track-eol' feature is doing its job, the value is 9999.
274 ---------- Buffer: *Help* ----------
275 @end group
276 @end smallexample
277
278 The asterisk @samp{*} as the first character of a variable's doc string,
279 as shown above for the @code{goal-column} variable, means that it is a
280 user option; see the description of @code{defvar} in @ref{Defining
281 Variables}.
282
283 @defun Snarf-documentation filename
284 @anchor{Definition of Snarf-documentation}
285 This function is used only during Emacs initialization, just before
286 the runnable Emacs is dumped. It finds the file offsets of the
287 documentation strings stored in the file @var{filename}, and records
288 them in the in-core function definitions and variable property lists in
289 place of the actual strings. @xref{Building Emacs}.
290
291 Emacs reads the file @var{filename} from the @file{emacs/etc} directory.
292 When the dumped Emacs is later executed, the same file will be looked
293 for in the directory @code{doc-directory}. Usually @var{filename} is
294 @code{"DOC-@var{version}"}.
295 @end defun
296
297 @c Emacs 19 feature
298 @defvar doc-directory
299 This variable holds the name of the directory which should contain the
300 file @code{"DOC-@var{version}"} that contains documentation strings for
301 built-in and preloaded functions and variables.
302
303 In most cases, this is the same as @code{data-directory}. They may be
304 different when you run Emacs from the directory where you built it,
305 without actually installing it. @xref{Definition of data-directory}.
306
307 In older Emacs versions, @code{exec-directory} was used for this.
308 @end defvar
309
310 @node Keys in Documentation
311 @section Substituting Key Bindings in Documentation
312 @cindex documentation, keys in
313 @cindex keys in documentation strings
314 @cindex substituting keys in documentation
315
316 When documentation strings refer to key sequences, they should use the
317 current, actual key bindings. They can do so using certain special text
318 sequences described below. Accessing documentation strings in the usual
319 way substitutes current key binding information for these special
320 sequences. This works by calling @code{substitute-command-keys}. You
321 can also call that function yourself.
322
323 Here is a list of the special sequences and what they mean:
324
325 @table @code
326 @item \[@var{command}]
327 stands for a key sequence that will invoke @var{command}, or @samp{M-x
328 @var{command}} if @var{command} has no key bindings.
329
330 @item \@{@var{mapvar}@}
331 stands for a summary of the keymap which is the value of the variable
332 @var{mapvar}. The summary is made using @code{describe-bindings}.
333
334 @item \<@var{mapvar}>
335 stands for no text itself. It is used only for a side effect: it
336 specifies @var{mapvar}'s value as the keymap for any following
337 @samp{\[@var{command}]} sequences in this documentation string.
338
339 @item \=
340 quotes the following character and is discarded; thus, @samp{\=\[} puts
341 @samp{\[} into the output, and @samp{\=\=} puts @samp{\=} into the
342 output.
343 @end table
344
345 @strong{Please note:} Each @samp{\} must be doubled when written in a
346 string in Emacs Lisp.
347
348 @defun substitute-command-keys string
349 This function scans @var{string} for the above special sequences and
350 replaces them by what they stand for, returning the result as a string.
351 This permits display of documentation that refers accurately to the
352 user's own customized key bindings.
353 @end defun
354
355 Here are examples of the special sequences:
356
357 @smallexample
358 @group
359 (substitute-command-keys
360 "To abort recursive edit, type: \\[abort-recursive-edit]")
361 @result{} "To abort recursive edit, type: C-]"
362 @end group
363
364 @group
365 (substitute-command-keys
366 "The keys that are defined for the minibuffer here are:
367 \\@{minibuffer-local-must-match-map@}")
368 @result{} "The keys that are defined for the minibuffer here are:
369 @end group
370
371 ? minibuffer-completion-help
372 SPC minibuffer-complete-word
373 TAB minibuffer-complete
374 C-j minibuffer-complete-and-exit
375 RET minibuffer-complete-and-exit
376 C-g abort-recursive-edit
377 "
378
379 @group
380 (substitute-command-keys
381 "To abort a recursive edit from the minibuffer, type\
382 \\<minibuffer-local-must-match-map>\\[abort-recursive-edit].")
383 @result{} "To abort a recursive edit from the minibuffer, type C-g."
384 @end group
385 @end smallexample
386
387 There are other special conventions for the text in documentation
388 strings---for instance, you can refer to functions, variables, and
389 sections of this manual. @xref{Documentation Tips}, for details.
390
391 @node Describing Characters
392 @section Describing Characters for Help Messages
393 @cindex describe characters and events
394
395 These functions convert events, key sequences, or characters to
396 textual descriptions. These descriptions are useful for including
397 arbitrary text characters or key sequences in messages, because they
398 convert non-printing and whitespace characters to sequences of printing
399 characters. The description of a non-whitespace printing character is
400 the character itself.
401
402 @defun key-description sequence &optional prefix
403 @cindex Emacs event standard notation
404 This function returns a string containing the Emacs standard notation
405 for the input events in @var{sequence}. If @var{prefix} is
406 non-@code{nil}, it is a sequence of input events leading up to
407 @var{sequence} and is included in the return value. Both arguments
408 may be strings, vectors or lists. @xref{Input Events}, for more
409 information about valid events.
410
411 @smallexample
412 @group
413 (key-description [?\M-3 delete])
414 @result{} "M-3 <delete>"
415 @end group
416 @group
417 (key-description [delete] "\M-3")
418 @result{} "M-3 <delete>"
419 @end group
420 @end smallexample
421
422 See also the examples for @code{single-key-description}, below.
423 @end defun
424
425 @defun single-key-description event &optional no-angles
426 @cindex event printing
427 @cindex character printing
428 @cindex control character printing
429 @cindex meta character printing
430 This function returns a string describing @var{event} in the standard
431 Emacs notation for keyboard input. A normal printing character
432 appears as itself, but a control character turns into a string
433 starting with @samp{C-}, a meta character turns into a string starting
434 with @samp{M-}, and space, tab, etc.@: appear as @samp{SPC},
435 @samp{TAB}, etc. A function key symbol appears inside angle brackets
436 @samp{<@dots{}>}. An event that is a list appears as the name of the
437 symbol in the @sc{car} of the list, inside angle brackets.
438
439 If the optional argument @var{no-angles} is non-@code{nil}, the angle
440 brackets around function keys and event symbols are omitted; this is
441 for compatibility with old versions of Emacs which didn't use the
442 brackets.
443
444 @smallexample
445 @group
446 (single-key-description ?\C-x)
447 @result{} "C-x"
448 @end group
449 @group
450 (key-description "\C-x \M-y \n \t \r \f123")
451 @result{} "C-x SPC M-y SPC C-j SPC TAB SPC RET SPC C-l 1 2 3"
452 @end group
453 @group
454 (single-key-description 'delete)
455 @result{} "<delete>"
456 @end group
457 @group
458 (single-key-description 'C-mouse-1)
459 @result{} "<C-mouse-1>"
460 @end group
461 @group
462 (single-key-description 'C-mouse-1 t)
463 @result{} "C-mouse-1"
464 @end group
465 @end smallexample
466 @end defun
467
468 @defun text-char-description character
469 This function returns a string describing @var{character} in the
470 standard Emacs notation for characters that appear in text---like
471 @code{single-key-description}, except that control characters are
472 represented with a leading caret (which is how control characters in
473 Emacs buffers are usually displayed). Another difference is that
474 @code{text-char-description} recognizes the 2**7 bit as the Meta
475 character, whereas @code{single-key-description} uses the 2**27 bit
476 for Meta.
477
478 @smallexample
479 @group
480 (text-char-description ?\C-c)
481 @result{} "^C"
482 @end group
483 @group
484 (text-char-description ?\M-m)
485 @result{} "\xed"
486 @end group
487 @group
488 (text-char-description ?\C-\M-m)
489 @result{} "\x8d"
490 @end group
491 @group
492 (text-char-description (+ 128 ?m))
493 @result{} "M-m"
494 @end group
495 @group
496 (text-char-description (+ 128 ?\C-m))
497 @result{} "M-^M"
498 @end group
499 @end smallexample
500 @end defun
501
502 @defun read-kbd-macro string &optional need-vector
503 This function is used mainly for operating on keyboard macros, but it
504 can also be used as a rough inverse for @code{key-description}. You
505 call it with a string containing key descriptions, separated by spaces;
506 it returns a string or vector containing the corresponding events.
507 (This may or may not be a single valid key sequence, depending on what
508 events you use; @pxref{Key Sequences}.) If @var{need-vector} is
509 non-@code{nil}, the return value is always a vector.
510 @end defun
511
512 @node Help Functions
513 @section Help Functions
514
515 Emacs provides a variety of on-line help functions, all accessible to
516 the user as subcommands of the prefix @kbd{C-h}. For more information
517 about them, see @ref{Help, , Help, emacs, The GNU Emacs Manual}. Here
518 we describe some program-level interfaces to the same information.
519
520 @deffn Command apropos pattern &optional do-all
521 This function finds all ``meaningful'' symbols whose names contain a
522 match for the apropos pattern @var{pattern}. An apropos pattern is
523 either a word to match, a space-separated list of words of which at
524 least two must match, or a regular expression (if any special regular
525 expression characters occur). A symbol is ``meaningful'' if it has a
526 definition as a function, variable, or face, or has properties.
527
528 The function returns a list of elements that look like this:
529
530 @example
531 (@var{symbol} @var{score} @var{fn-doc} @var{var-doc}
532 @var{plist-doc} @var{widget-doc} @var{face-doc} @var{group-doc})
533 @end example
534
535 Here, @var{score} is an integer measure of how important the symbol
536 seems to be as a match, and the remaining elements are documentation
537 strings for @var{symbol}'s various roles (or @code{nil}).
538
539 It also displays the symbols in a buffer named @samp{*Apropos*}, each
540 with a one-line description taken from the beginning of its
541 documentation string.
542
543 @c Emacs 19 feature
544 If @var{do-all} is non-@code{nil}, or if the user option
545 @code{apropos-do-all} is non-@code{nil}, then @code{apropos} also
546 shows key bindings for the functions that are found; it also shows
547 @emph{all} interned symbols, not just meaningful ones (and it lists
548 them in the return value as well).
549 @end deffn
550
551 @defvar help-map
552 The value of this variable is a local keymap for characters following the
553 Help key, @kbd{C-h}.
554 @end defvar
555
556 @deffn {Prefix Command} help-command
557 This symbol is not a function; its function definition cell holds the
558 keymap known as @code{help-map}. It is defined in @file{help.el} as
559 follows:
560
561 @smallexample
562 @group
563 (define-key global-map (char-to-string help-char) 'help-command)
564 (fset 'help-command help-map)
565 @end group
566 @end smallexample
567 @end deffn
568
569 @defun print-help-return-message &optional function
570 This function builds a string that explains how to restore the previous
571 state of the windows after a help command. After building the message,
572 it applies @var{function} to it if @var{function} is non-@code{nil}.
573 Otherwise it calls @code{message} to display it in the echo area.
574
575 This function expects to be called inside a
576 @code{with-output-to-temp-buffer} special form, and expects
577 @code{standard-output} to have the value bound by that special form.
578 For an example of its use, see the long example in @ref{Accessing
579 Documentation}.
580 @end defun
581
582 @defvar help-char
583 The value of this variable is the help character---the character that
584 Emacs recognizes as meaning Help. By default, its value is 8, which
585 stands for @kbd{C-h}. When Emacs reads this character, if
586 @code{help-form} is a non-@code{nil} Lisp expression, it evaluates that
587 expression, and displays the result in a window if it is a string.
588
589 Usually the value of @code{help-form} is @code{nil}. Then the
590 help character has no special meaning at the level of command input, and
591 it becomes part of a key sequence in the normal way. The standard key
592 binding of @kbd{C-h} is a prefix key for several general-purpose help
593 features.
594
595 The help character is special after prefix keys, too. If it has no
596 binding as a subcommand of the prefix key, it runs
597 @code{describe-prefix-bindings}, which displays a list of all the
598 subcommands of the prefix key.
599 @end defvar
600
601 @defvar help-event-list
602 The value of this variable is a list of event types that serve as
603 alternative ``help characters.'' These events are handled just like the
604 event specified by @code{help-char}.
605 @end defvar
606
607 @defvar help-form
608 If this variable is non-@code{nil}, its value is a form to evaluate
609 whenever the character @code{help-char} is read. If evaluating the form
610 produces a string, that string is displayed.
611
612 A command that calls @code{read-event} or @code{read-char} probably
613 should bind @code{help-form} to a non-@code{nil} expression while it
614 does input. (The time when you should not do this is when @kbd{C-h} has
615 some other meaning.) Evaluating this expression should result in a
616 string that explains what the input is for and how to enter it properly.
617
618 Entry to the minibuffer binds this variable to the value of
619 @code{minibuffer-help-form} (@pxref{Definition of minibuffer-help-form}).
620 @end defvar
621
622 @defvar prefix-help-command
623 This variable holds a function to print help for a prefix key. The
624 function is called when the user types a prefix key followed by the help
625 character, and the help character has no binding after that prefix. The
626 variable's default value is @code{describe-prefix-bindings}.
627 @end defvar
628
629 @defun describe-prefix-bindings
630 This function calls @code{describe-bindings} to display a list of all
631 the subcommands of the prefix key of the most recent key sequence. The
632 prefix described consists of all but the last event of that key
633 sequence. (The last event is, presumably, the help character.)
634 @end defun
635
636 The following two functions are meant for modes that want to provide
637 help without relinquishing control, such as the ``electric'' modes.
638 Their names begin with @samp{Helper} to distinguish them from the
639 ordinary help functions.
640
641 @deffn Command Helper-describe-bindings
642 This command pops up a window displaying a help buffer containing a
643 listing of all of the key bindings from both the local and global keymaps.
644 It works by calling @code{describe-bindings}.
645 @end deffn
646
647 @deffn Command Helper-help
648 This command provides help for the current mode. It prompts the user
649 in the minibuffer with the message @samp{Help (Type ? for further
650 options)}, and then provides assistance in finding out what the key
651 bindings are, and what the mode is intended for. It returns @code{nil}.
652
653 This can be customized by changing the map @code{Helper-help-map}.
654 @end deffn
655
656 @c Emacs 19 feature
657 @defvar data-directory
658 @anchor{Definition of data-directory}
659 This variable holds the name of the directory in which Emacs finds
660 certain documentation and text files that come with Emacs. In older
661 Emacs versions, @code{exec-directory} was used for this.
662 @end defvar
663
664 @c Emacs 19 feature
665 @defmac make-help-screen fname help-line help-text help-map
666 This macro defines a help command named @var{fname} that acts like a
667 prefix key that shows a list of the subcommands it offers.
668
669 When invoked, @var{fname} displays @var{help-text} in a window, then
670 reads and executes a key sequence according to @var{help-map}. The
671 string @var{help-text} should describe the bindings available in
672 @var{help-map}.
673
674 The command @var{fname} is defined to handle a few events itself, by
675 scrolling the display of @var{help-text}. When @var{fname} reads one of
676 those special events, it does the scrolling and then reads another
677 event. When it reads an event that is not one of those few, and which
678 has a binding in @var{help-map}, it executes that key's binding and
679 then returns.
680
681 The argument @var{help-line} should be a single-line summary of the
682 alternatives in @var{help-map}. In the current version of Emacs, this
683 argument is used only if you set the option @code{three-step-help} to
684 @code{t}.
685
686 This macro is used in the command @code{help-for-help} which is the
687 binding of @kbd{C-h C-h}.
688 @end defmac
689
690 @defopt three-step-help
691 If this variable is non-@code{nil}, commands defined with
692 @code{make-help-screen} display their @var{help-line} strings in the
693 echo area at first, and display the longer @var{help-text} strings only
694 if the user types the help character again.
695 @end defopt
696
697 @ignore
698 arch-tag: ba36b4c2-e60f-49e2-bc25-61158fdcd815
699 @end ignore