|
98
|
1 \input texinfo.tex
|
|
|
2
|
|
|
3 @c %**start of header
|
|
|
4 @setfilename custom
|
|
|
5 @settitle The Customization Library
|
|
|
6 @iftex
|
|
|
7 @afourpaper
|
|
|
8 @headings double
|
|
|
9 @end iftex
|
|
|
10 @c %**end of header
|
|
|
11
|
|
155
|
12 @node Top, Declaring Groups, (dir), (dir)
|
|
98
|
13 @comment node-name, next, previous, up
|
|
|
14 @top The Customization Library
|
|
|
15
|
|
155
|
16 This manual describes how to declare customization groups, variables,
|
|
120
|
17 and faces. It doesn't contain any examples, but please look at the file
|
|
|
18 @file{cus-edit.el} which contains many declarations you can learn from.
|
|
|
19
|
|
98
|
20 @menu
|
|
|
21 * Declaring Groups::
|
|
|
22 * Declaring Variables::
|
|
|
23 * Declaring Faces::
|
|
102
|
24 * Usage for Package Authors::
|
|
155
|
25 * Utilities::
|
|
|
26 * The Init File::
|
|
|
27 * Wishlist::
|
|
98
|
28 @end menu
|
|
|
29
|
|
|
30 All the customization declarations can be changes by keyword arguments.
|
|
|
31 Groups, variables, and faces all share these common keywords:
|
|
|
32
|
|
|
33 @table @code
|
|
|
34 @item :group
|
|
|
35 @var{value} should be a customization group.
|
|
|
36 Add @var{symbol} to that group.
|
|
|
37 @item :link
|
|
|
38 @var{value} should be a widget type.
|
|
|
39 Add @var{value} to the extrenal links for this customization option.
|
|
|
40 Useful widget types include @code{custom-manual}, @code{info-link}, and
|
|
|
41 @code{url-link}.
|
|
|
42 @item :load
|
|
|
43 Add @var{value} to the files that should be loaded nefore displaying
|
|
|
44 this customization option. The value should be iether a string, which
|
|
|
45 should be a string which will be loaded with @code{load-library} unless
|
|
|
46 present in @code{load-history}, or a symbol which will be loaded with
|
|
|
47 @code{require}.
|
|
|
48 @item :tag
|
|
|
49 @var{Value} should be a short string used for identifying the option in
|
|
|
50 customization menus and buffers. By default the tag will be
|
|
|
51 automatically created from the options name.
|
|
|
52 @end table
|
|
|
53
|
|
155
|
54 @node Declaring Groups, Declaring Variables, Top, Top
|
|
98
|
55 @comment node-name, next, previous, up
|
|
155
|
56 @section Declaring Groups
|
|
98
|
57
|
|
|
58 Use @code{defgroup} to declare new customization groups.
|
|
|
59
|
|
|
60 @defun defgroup symbol members doc [keyword value]...
|
|
|
61 Declare @var{symbol} as a customization group containing @var{members}.
|
|
|
62 @var{symbol} does not need to be quoted.
|
|
|
63
|
|
|
64 @var{doc} is the group documentation.
|
|
|
65
|
|
|
66 @var{members} should be an alist of the form ((@var{name}
|
|
|
67 @var{widget})...) where @var{name} is a symbol and @var{widget} is a
|
|
|
68 widget for editing that symbol. Useful widgets are
|
|
|
69 @code{custom-variable} for editing variables, @code{custom-face} for
|
|
|
70 editing faces, and @code{custom-group} for editing groups.@refill
|
|
|
71
|
|
|
72 Internally, custom uses the symbol property @code{custom-group} to keep
|
|
|
73 track of the group members, and @code{group-documentation} for the
|
|
|
74 documentation string.
|
|
|
75
|
|
|
76 The following additional @var{keyword}'s are defined:
|
|
|
77
|
|
|
78 @table @code
|
|
|
79 @item :prefix
|
|
|
80 @var{value} should be a string. If the string is a prefix for the name
|
|
|
81 of a member of the group, that prefix will be ignored when creating a
|
|
|
82 tag for that member.
|
|
|
83 @end table
|
|
|
84 @end defun
|
|
|
85
|
|
155
|
86 @node Declaring Variables, Declaring Faces, Declaring Groups, Top
|
|
98
|
87 @comment node-name, next, previous, up
|
|
155
|
88 @section Declaring Variables
|
|
98
|
89
|
|
|
90 Use @code{defcustom} to declare user editable variables.
|
|
|
91
|
|
|
92 @defun defcustom symbol value doc [keyword value]...
|
|
|
93 Declare @var{symbol} as a customizable variable that defaults to @var{value}.
|
|
|
94 Neither @var{symbol} nor @var{value} needs to be quoted.
|
|
|
95 If @var{symbol} is not already bound, initialize it to @var{value}.
|
|
|
96
|
|
|
97 @var{doc} is the variable documentation.
|
|
|
98
|
|
|
99 The following additional @var{keyword}'s are defined:
|
|
|
100
|
|
|
101 @table @code
|
|
155
|
102 @item :type
|
|
98
|
103 @var{value} should be a widget type.
|
|
149
|
104
|
|
98
|
105 @item :options
|
|
|
106 @var{value} should be a list of possible members of the specified type.
|
|
|
107 For hooks, this is a list of function names.
|
|
149
|
108
|
|
|
109 @item :initialize
|
|
|
110 @var{value} should be a function used to initialize the variable. It
|
|
|
111 takes two arguments, the symbol and value given in the @code{defcustom} call.
|
|
|
112 Some predefined functions are:
|
|
|
113
|
|
|
114 @table @code
|
|
|
115 @item custom-initialize-set
|
|
|
116 Use the @code{:set} method to initialize the variable. Do not
|
|
|
117 initialize it if already bound. This is the default @code{:initialize}
|
|
|
118 method.
|
|
|
119
|
|
|
120 @item custom-initialize-default
|
|
|
121 Always use @code{set-default} to initialize the variable, even if a
|
|
|
122 @code{:set} method has been specified.
|
|
|
123
|
|
|
124 @item custom-initialize-reset
|
|
|
125 If the variable is already bound, reset it by calling the @code{:set}
|
|
|
126 method with the value returned by the @code{:get} method.
|
|
|
127
|
|
|
128 @item custom-initialize-changed
|
|
|
129 Like @code{custom-initialize-reset}, but use @code{set-default} to
|
|
|
130 initialize the variable if it is not bound and has not been set
|
|
|
131 already.
|
|
|
132 @end table
|
|
|
133
|
|
|
134 @item :set
|
|
|
135 @var{value} should be a function to set the value of the symbol. It
|
|
|
136 takes two arguments, the symbol to set and the value to give it. The
|
|
|
137 default is @code{set-default}.
|
|
|
138
|
|
|
139 @item :get
|
|
|
140 @var{value} should be a function to extract the value of symbol. The
|
|
|
141 function takes one argument, a symbol, and should return the current
|
|
|
142 value for that symbol. The default is @code{default-value}.
|
|
|
143
|
|
|
144 @item :require
|
|
|
145 @var{value} should be a feature symbol. Each feature will be required
|
|
|
146 after initialization, of the the user have saved this option.
|
|
|
147
|
|
98
|
148 @end table
|
|
|
149
|
|
|
150 @xref{Sexp Types,,,widget,The Widget Library}, for information about
|
|
|
151 widgets to use together with the @code{:type} keyword.
|
|
|
152 @end defun
|
|
|
153
|
|
|
154 Internally, custom uses the symbol property @code{custom-type} to keep
|
|
153
|
155 track of the variables type, @code{standard-value} for the program
|
|
98
|
156 specified default value, @code{saved-value} for a value saved by the
|
|
|
157 user, and @code{variable-documentation} for the documentation string.
|
|
|
158
|
|
|
159 Use @code{custom-add-option} to specify that a specific function is
|
|
|
160 useful as an meber of a hook.
|
|
|
161
|
|
|
162 @defun custom-add-option symbol option
|
|
|
163 To the variable @var{symbol} add @var{option}.
|
|
|
164
|
|
|
165 If @var{symbol} is a hook variable, @var{option} should be a hook
|
|
|
166 member. For other types variables, the effect is undefined."
|
|
|
167 @end defun
|
|
|
168
|
|
155
|
169 @node Declaring Faces, Usage for Package Authors, Declaring Variables, Top
|
|
98
|
170 @comment node-name, next, previous, up
|
|
155
|
171 @section Declaring Faces
|
|
98
|
172
|
|
|
173 Faces are declared with @code{defface}.
|
|
|
174
|
|
|
175 @defun defface face spec doc [keyword value]...
|
|
|
176
|
|
|
177 Declare @var{face} as a customizable face that defaults to @var{spec}.
|
|
|
178 @var{face} does not need to be quoted.
|
|
|
179
|
|
|
180 If @var{face} has been set with `custom-set-face', set the face attributes
|
|
|
181 as specified by that function, otherwise set the face attributes
|
|
|
182 according to @var{spec}.
|
|
|
183
|
|
|
184 @var{doc} is the face documentation.
|
|
|
185
|
|
|
186 @var{spec} should be an alist of the form @samp{((@var{display} @var{atts})...)}.
|
|
|
187
|
|
|
188 @var{atts} is a list of face attributes and their values. The possible
|
|
|
189 attributes are defined in the variable `custom-face-attributes'.
|
|
|
190
|
|
|
191 The @var{atts} of the first entry in @var{spec} where the @var{display}
|
|
|
192 matches the frame should take effect in that frame. @var{display} can
|
|
|
193 either be the symbol `t', which will match all frames, or an alist of
|
|
|
194 the form @samp{((@var{req} @var{item}...)...)}@refill
|
|
|
195
|
|
|
196 For the @var{display} to match a FRAME, the @var{req} property of the
|
|
|
197 frame must match one of the @var{item}. The following @var{req} are
|
|
|
198 defined:@refill
|
|
|
199
|
|
|
200 @table @code
|
|
|
201 @item type
|
|
108
|
202 (the value of (window-system))@*
|
|
98
|
203 Should be one of @code{x} or @code{tty}.
|
|
|
204
|
|
|
205 @item class
|
|
108
|
206 (the frame's color support)@*
|
|
98
|
207 Should be one of @code{color}, @code{grayscale}, or @code{mono}.
|
|
|
208
|
|
|
209 @item background
|
|
108
|
210 (what color is used for the background text)@*
|
|
98
|
211 Should be one of @code{light} or @code{dark}.
|
|
|
212 @end table
|
|
|
213
|
|
149
|
214 Internally, custom uses the symbol property @code{face-defface-spec} for
|
|
|
215 the program specified default face properties, @code{saved-face} for
|
|
|
216 properties saved by the user, and @code{face-documentation} for the
|
|
98
|
217 documentation string.@refill
|
|
|
218
|
|
|
219 @end defun
|
|
|
220
|
|
155
|
221 @node Usage for Package Authors, Utilities, Declaring Faces, Top
|
|
102
|
222 @comment node-name, next, previous, up
|
|
155
|
223 @section Usage for Package Authors
|
|
102
|
224
|
|
|
225 The recommended usage for the author of a typical emacs lisp package is
|
|
|
226 to create one group identifying the package, and make all user options
|
|
|
227 and faces members of that group. If the package has more than around 20
|
|
|
228 such options, they should be divided into a number of subgroups, with
|
|
|
229 each subgroup being member of the top level group.
|
|
|
230
|
|
|
231 The top level group for the package should itself be member of one or
|
|
|
232 more of the standard customization groups. There exists a group for
|
|
|
233 each @emph{finder} keyword. Press @kbd{C-c p} to see a list of finder
|
|
|
234 keywords, and add you group to each of them, using the @code{:group}
|
|
|
235 keyword.
|
|
|
236
|
|
155
|
237 @node Utilities, The Init File, Usage for Package Authors, Top
|
|
98
|
238 @comment node-name, next, previous, up
|
|
|
239 @section Utilities
|
|
|
240
|
|
|
241 These utilities can come in handy when adding customization support.
|
|
|
242
|
|
|
243 @deffn Widget custom-manual
|
|
|
244 Widget type for specifying the info manual entry for a customization
|
|
|
245 option. It takes one argument, an info address.
|
|
|
246 @end deffn
|
|
|
247
|
|
|
248 @defun custom-add-to-group group member widget
|
|
|
249 To existing @var{group} add a new @var{member} of type @var{widget},
|
|
|
250 If there already is an entry for that member, overwrite it.
|
|
|
251 @end defun
|
|
|
252
|
|
|
253 @defun custom-add-link symbol widget
|
|
|
254 To the custom option @var{symbol} add the link @var{widget}.
|
|
|
255 @end defun
|
|
|
256
|
|
|
257 @defun custom-add-load symbol load
|
|
|
258 To the custom option @var{symbol} add the dependency @var{load}.
|
|
|
259 @var{load} should be either a library file name, or a feature name.
|
|
|
260 @end defun
|
|
|
261
|
|
124
|
262 @defun customize-menu-create symbol &optional name
|
|
98
|
263 Create menu for customization group @var{symbol}.
|
|
|
264 If optional @var{name} is given, use that as the name of the menu.
|
|
124
|
265 Otherwise the menu will be named `Customize'.
|
|
98
|
266 The menu is in a format applicable to @code{easy-menu-define}.
|
|
|
267 @end defun
|
|
|
268
|
|
155
|
269 @node The Init File, Wishlist, Utilities, Top
|
|
98
|
270 @comment node-name, next, previous, up
|
|
|
271 @section The Init File
|
|
|
272
|
|
|
273 When you save the customizations, call to @code{custom-set-variables},
|
|
|
274 @code{custom-set-faces} are inserted into the file specified by
|
|
|
275 @code{custom-file}. By default @code{custom-file} is your @file{.emacs}
|
|
116
|
276 file. If you use another file, you must explicitly load it yourself.
|
|
|
277 The two functions will initialize variables and faces as you have
|
|
|
278 specified.
|
|
98
|
279
|
|
155
|
280 @node Wishlist, , The Init File, Top
|
|
98
|
281 @comment node-name, next, previous, up
|
|
|
282 @section Wishlist
|
|
|
283
|
|
|
284 @itemize @bullet
|
|
|
285 @item
|
|
120
|
286 Better support for keyboard operations in the customize buffer.
|
|
98
|
287
|
|
|
288 @item
|
|
155
|
289 Integrate with @file{w3} so you can get customization buffers with much
|
|
98
|
290 better formatting. I'm thinking about adding a <custom>name</custom>
|
|
108
|
291 tag. The latest w3 have some support for this, so come up with a
|
|
|
292 convincing example.
|
|
98
|
293
|
|
|
294 @item
|
|
|
295 Add an `examples' section, with explained examples of custom type
|
|
|
296 definitions.
|
|
|
297
|
|
|
298 @item
|
|
110
|
299 Support selectable color themes. I.e., change many faces by setting one
|
|
|
300 variable.
|
|
|
301
|
|
|
302 @item
|
|
98
|
303 Support undo using lmi's @file{gnus-undo.el}.
|
|
|
304
|
|
|
305 @item
|
|
|
306 Make it possible to append to `choice', `radio', and `set' options.
|
|
|
307
|
|
|
308 @item
|
|
|
309 Ask whether set or modified variables should be saved in
|
|
|
310 @code{kill-buffer-hook}.
|
|
|
311
|
|
|
312 Ditto for @code{kill-emacs-query-functions}.
|
|
|
313
|
|
|
314 @item
|
|
|
315 Command to check if there are any customization options that
|
|
|
316 does not belong to an existing group.
|
|
|
317
|
|
|
318 @item
|
|
|
319 Optionally disable the point-cursor and instead highlight the selected
|
|
|
320 item in XEmacs. This is like the *Completions* buffer in XEmacs.
|
|
|
321 Suggested by Jens Lautenbacher
|
|
|
322 @samp{<jens@@lemming0.lem.uni-karlsruhe.de>}.@refill
|
|
|
323
|
|
120
|
324 @item
|
|
155
|
325 Explain why it is necessary that all choices have differnet default
|
|
|
326 values.
|
|
120
|
327
|
|
124
|
328 @item
|
|
|
329 Make it possible to include a comment/remark/annotation when saving an
|
|
|
330 option.
|
|
|
331
|
|
149
|
332 @item
|
|
|
333 Add some direct support for meta variables, i.e. make it possible to
|
|
|
334 specify that this variable should be reset when that variable is
|
|
|
335 changed.
|
|
|
336
|
|
|
337 @item
|
|
|
338 Add tutorial.
|
|
|
339
|
|
|
340 @item
|
|
|
341 Describe the @code{:type} syntax in this manual.
|
|
|
342
|
|
|
343 @item
|
|
|
344 Find a place is this manual for the following text:
|
|
|
345
|
|
|
346 @strong{Radio vs. Buttons}
|
|
|
347
|
|
|
348 Use a radio if you can't find a good way to describe the item in the
|
|
|
349 choice menu text. I.e. it is better to use a radio if you expect the
|
|
|
350 user would otherwise manually select each item from the choice menu in
|
|
|
351 turn to see what it expands too.
|
|
|
352
|
|
|
353 Avoid radios if some of the items expands to complex structures.
|
|
|
354
|
|
|
355 I mostly use radios when most of the items are of type
|
|
|
356 @code{function-item} or @code{variable-item}.
|
|
|
357
|
|
|
358 @item
|
|
|
359 Update customize buffers when @code{custom-set-variable} or
|
|
|
360 @code{custom-save-customized} is called.
|
|
|
361
|
|
|
362 @item
|
|
|
363 Better handling of saved but uninitialized items.
|
|
|
364
|
|
153
|
365 @item
|
|
|
366 Detect when faces have been changed outside customize.
|
|
|
367
|
|
|
368 @item
|
|
155
|
369 Enable mouse help in Emacs by default.
|
|
153
|
370
|
|
|
371 @item
|
|
|
372 Add an easy way to display the standard settings when an item is modified.
|
|
|
373
|
|
155
|
374 @item
|
|
|
375 Option or command to create new buffer instead of expanding a group
|
|
|
376 inline.
|
|
|
377
|
|
|
378 @item
|
|
|
379 See if it is feasible to scan files for customization information
|
|
|
380 instead of loading them,
|
|
|
381
|
|
|
382 @item
|
|
|
383 Add hint message when user push a non-pushable tag.
|
|
|
384
|
|
|
385 Suggest that the user unhide if hidden, and edit the value directly
|
|
|
386 otherwise.
|
|
|
387
|
|
98
|
388 @end itemize
|
|
|
389
|
|
|
390 @contents
|
|
|
391 @bye
|
