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