Reformatted.
[chise/xemacs-chise.git] / man / custom.texi
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
168 useful as a member of a hook.
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
174 member.  For other types of variables, the effect is undefined."
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
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
294 As of XEmacs 21.4.7, when @code{custom-file} is present, it is loaded
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.
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