annotate doc/lispref/help.texi @ 106603:90cf0c548f89

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