Quassia Gnus v0.27.
[elisp/gnus.git-] / texi / custom.texi
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
12 @node Top, Introduction, (dir), (dir)
13 @comment  node-name,  next,  previous,  up
14 @top The Customization Library
15
16 Version: 1.82
17
18 @menu
19 * Introduction::                
20 * User Commands::               
21 * The Customization Buffer::    
22 * Declarations::                
23 * Utilities::                   
24 * The Init File::               
25 * Wishlist::                    
26 @end menu
27
28 @node   Introduction, User Commands, Top, Top
29 @comment  node-name,  next,  previous,  up
30 @section Introduction
31
32 This library allows customization of @dfn{user options}.  Currently two
33 types of user options are supported, namely @dfn{variables} and
34 @dfn{faces}.  Each user option can have four different values
35 simultaneously:
36 @table @dfn
37 @item factory setting
38 The value specified by the programmer.
39 @item saved value
40 The value saved by the user as the default for this variable.  This
41 overwrites the factory setting when starting a new emacs.
42 @item current value
43 The value used by Emacs.  This will not be remembered next time you
44 run Emacs.
45 @item widget value
46 The value entered by the user in a customization buffer, but not yet
47 applied.
48 @end table
49
50 Variables also have a @dfn{type}, which specifies what kind of values
51 the variable can hold, and how the value is presented in a customization
52 buffer.  By default a variable can hold any valid expression, but the
53 programmer can specify a more limited type when declaring the variable.
54
55 The user options are organized in a number of @dfn{groups}.  Each group
56 can contain a number user options, as well as other groups.  The groups
57 allows the user to concentrate on a specific part of emacs.
58
59 @node  User Commands, The Customization Buffer, Introduction, Top
60 @comment  node-name,  next,  previous,  up
61 @section User Commands
62
63 The following commands will create a customization buffer:
64
65 @table @code
66 @item customize
67 Create a customization buffer containing a specific group, by default
68 the @code{emacs} group.
69
70 @item customize-variable
71 Create a customization buffer containing a single variable.  
72
73 @item customize-face
74 Create a customization buffer containing a single face.
75
76 @item customize-apropos
77 Create a customization buffer containing all variables, faces, and
78 groups that match a user specified regular expression.
79 @end table
80
81 @node The Customization Buffer, Declarations, User Commands, Top
82 @comment  node-name,  next,  previous,  up
83 @section The Customization Buffer.
84
85 The customization buffer allows the user to make temporary or permanent
86 changes to how specific aspects of emacs works, by setting and editing
87 user options.  
88
89 The customization buffer contains three types of text:
90
91 @table @dfn
92 @item informative text
93 where the normal editing commands are disabled.
94
95 @item editable fields
96 where you can edit with the usual emacs commands.  Editable fields are
97 usually displayed with a grey background if your terminal supports
98 colors, or an italic font otherwise.
99
100 @item buttons
101 which can be activated by either pressing the @kbd{@key{ret}} while
102 point is located on the text, or pushing @kbd{mouse-2} while the mouse
103 pointer is above the tex.  Buttons are usually displayed in a bold
104 font. 
105 @end table
106
107 You can move to the next the next editable field or button by pressing
108 @kbd{@key{tab}} or the previous with @kbd{M-@key{tab}}.  Some buttons
109 have a small helpful message about their purpose, which will be
110 displayed when you move to it with the @key{tab} key.  
111
112 The buffer is divided into three part, an introductory text, a list of
113 customization options, and a line of customization buttons.  Each part
114 will be described in the following. 
115
116 @menu
117 * The Introductory Text::       
118 * The Customization Options::   
119 * The Variable Options::        
120 * The Face Options::            
121 * The Group Options::           
122 * The State Button::            
123 * The Customization Buttons::   
124 @end menu
125
126 @node  The Introductory Text, The Customization Options, The Customization Buffer, The Customization Buffer
127 @comment  node-name,  next,  previous,  up
128 @subsection  The Introductory Text
129
130 The start of the buffer contains a short explanation of what it is, and
131 how to get help.  It will typically look like this:
132
133 @example
134 This is a customization buffer.
135 Push RET or click mouse-2 on the word _help_ for more information.
136 @end example
137
138 Rather boring.  It is mostly just informative text, but the word
139 @samp{help} is a button that will bring up this document when
140 activated.  
141
142 @node  The Customization Options, The Variable Options, The Introductory Text, The Customization Buffer
143 @comment  node-name,  next,  previous,  up
144 @subsection The Customization Options
145
146 Each customization option looks similar to the following text:
147
148 @example
149  *** custom-background-mode: default 
150  State: this item is unchanged from its factory setting.
151  [ ] [?] The brightness of the background.
152 @end example
153
154 The option contains the parts described below.
155
156 @table @samp
157 @item ***
158 The Level Button.  The customization options in the buffer are organized
159 in a hierarchy, which is indicated by the number of stars in the level
160 button.  The top level options will be shown as @samp{*}.  When they are
161 expanded, the suboptions will be shown as @samp{**}.  The example option
162 is thus a subsuboption.
163
164 Activating the level buttons will toggle between hiding and exposing the
165 content of that option.  The content can either be the value of the
166 option, as in this example, or a list of suboptions.
167
168 @item custom-background-mode
169 This is the tag of the the option.  The tag is a name of a variable, a
170 face, or customization group.  Activating the tag has an effect that
171 depends on the exact type of the option.  In this particular case,
172 activating the tag will bring up a menu that will allow you to choose
173 from the three possible values of the `custom-background-mode'
174 variable. 
175
176 @item default
177 After the tag, the options value is shown.  Depending on its type, you
178 may be able to edit the value directly.  If an option should contain a
179 file name, it is displayed in an editable field, i.e. you can edit it
180 using the standard emacs editing commands.
181
182 @item State: this item is unchanged from its factory setting.
183 The state line.  This line will explain the state of the option,
184 e.g. whether it is currently hidden, or whether it has been modified or
185 not.  Activating the button will allow you to change the state, e.g. set
186 or reset the changes you have made.  This is explained in detail in the
187 following sections.
188
189 @item [ ]
190 The magic button.  This is an abbreviated version of the state line. 
191
192 @item [?] 
193 The documentation button.  If the documentation is more than one line,
194 this button will be present.  Activating the button will toggle whether
195 the complete documentation is shown, or only the first line.
196
197 @item The brightness of the background.
198 This is a documentation string explaining the purpose of this particular
199 customization option.
200
201 @end table
202
203 @node  The Variable Options, The Face Options, The Customization Options, The Customization Buffer
204 @comment  node-name,  next,  previous,  up
205 @subsection The Variable Options
206
207 The most common customization options are emacs lisp variables.  The
208 actual editing of these variables depend on what type values the
209 variable is expected to contain.  For example, a lisp variable whose
210 value should be a string will typically be represented with an editable
211 text field in the buffer, where you can change the string directly.  If
212 the value is a list, each item in the list will be presented in the
213 buffer buffer on a separate line, with buttons to insert new items in
214 the list, or delete existing items from the list.  You may want to see 
215 @ref{User Interface,,, widget, The Widget Library}, where some examples
216 of editing are discussed.  
217
218 You can either choose to edit the value directly, or edit the lisp
219 value for that variable.  The lisp value is a lisp expression that
220 will be evaluated when you start emacs.  The result of the evaluation
221 will be used as the initial value for that variable.  Editing the
222 lisp value is for experts only, but if the current value of the
223 variable is of a wrong type (i.e. a symbol where a string is expected),
224 the `edit lisp' mode will always be selected.
225
226 You can see what mode is currently selected by looking at the state
227 button.  If it uses parenthesises (like @samp{( )}) it is in edit lisp
228 mode, with square brackets (like @samp{[ ]}) it is normal edit mode.
229 You can switch mode by activating the state button, and select either
230 @samp{Edit} or @samp{Edit lisp} from the menu.
231
232 You can change the state of the variable with the other menu items:
233
234 @table @samp
235 @item Set
236 When you have made your modifications in the buffer, you need to
237 activate this item to make the modifications take effect.  The
238 modifications will be forgotten next time you run emacs.
239
240 @item Save
241 Unless you activate this item instead!  This will mark the modification
242 as permanent, i.e. the changes will be remembered in the next emacs
243 session.
244
245 @item Reset
246 If you have made some modifications and not yet applied them, you can
247 undo the modification by activating this item.
248
249 @item Reset to Saved
250 Activating this item will reset the value of the variable to the last
251 value you marked as permanent with `Save'.
252
253 @item Reset to Factory Settings
254 Activating this item will undo all modifications you have made, and
255 reset the value to the initial value specified by the program itself. 
256 @end table
257
258 By default, the value of large or complicated variables are hidden.   You
259 can show the value by clicking on the level button.
260
261 @node  The Face Options, The Group Options, The Variable Options, The Customization Buffer
262 @comment  node-name,  next,  previous,  up
263 @subsection The Face Options
264
265 A face is an object that controls the appearance of some buffer text.
266 The face has a number of possible attributes, such as boldness,
267 foreground color, and more.  For each attribute you can specify whether
268 this attribute is controlled by the face, and if so, what the value is.
269 For example, if the attribute bold is not controlled by a face, using
270 that face on some buffer text will not affect its boldness.  If the bold
271 attribute is controlled by the face, it can be turned either on or of.
272
273 It is possible to specify that a face should have different attributes
274 on different device types.  For example, a face may make text red on a
275 color device, and bold on a monochrome device.  You do this by
276 activating `Edit All' in the state menu.
277
278 The way this is presented in the customization buffer is to have a list
279 of display specifications, and for each display specification a list of
280 face attributes.  For each face attribute, there is a checkbox
281 specifying whether this attribute has effect and what the value is.
282 Here is an example:
283
284 @example
285  *** custom-invalid-face: (sample)
286  State: this item is unchanged from its factory setting.
287  [ ] Face used when the customize item is invalid.
288  [INS] [DEL] Display: [ ] Type: [ ] X [ ] PM [ ] Win32 [ ] DOS [ ] TTY
289                       [X] Class: [X] Color [ ] Grayscale [ ] Monochrome
290                       [ ] Background: [ ] Light [ ] Dark
291              Attributes: [ ] Bold: off 
292                          [ ] Italic: off 
293                          [ ] Underline: off 
294                          [X] Foreground: yellow (sample)
295                          [X] Background: red (sample)
296                          [ ] Stipple:  
297  [INS] [DEL] Display: all
298              Attributes: [X] Bold: on 
299                          [X] Italic: on 
300                          [X] Underline: on 
301                          [ ] Foreground: default (sample)
302                          [ ] Background: default (sample)
303                          [ ] Stipple:  
304  [INS]
305 @end example
306
307 This has two display specifications.  The first will match all color
308 displays, independently on what window system the device belongs to, and
309 whether background color is dark or light.  For devices matching this
310 specification, @samp{custom-invalid-face} will force text to be
311 displayed in yellow on red, but leave all other attributes alone.
312
313 The second display will simply match everything.  Since the list is
314 prioritised, this means that it will match all non-color displays.  For
315 these, the face will not affect the foreground or background color, but
316 force the font to be both bold, italic, and underline.
317
318 You can add or delete display specifications by activating the
319 @samp{[INS]} and @samp{[DEL]} buttons, and modify them by clicking on
320 the check boxes.  The first checkbox in each line in the display
321 specification is special.  It specify whether this particular property
322 will even be relevant.  By not checking the box in the first display, we
323 match all device types, also device types other than those listed.
324
325 After modifying the face, you can activate the state button to make the
326 changes take effect.  The menu items in the state button menu is similar
327 to the state menu items for variables described in the previous section.
328
329 @node  The Group Options, The State Button, The Face Options, The Customization Buffer
330 @comment  node-name,  next,  previous,  up
331 @subsection The Group Options
332
333 Since Emacs has approximately a zillion configuration options, they have
334 been organized in groups.  Each group can contain other groups, thus
335 creating a customization hierarchy.  The nesting of the customization
336 within the visible part of this hierarchy is indicated by the number of
337 stars in the level button.
338
339 Since there is really no customization needed for the group itself, the
340 menu items in the groups state button will affect all modified group
341 members recursively.  Thus, if you activate the @samp{Set} menu item,
342 all variables and faces that have been modified and belong to that group
343 will be applied.  For those members that themselves are groups, it will
344 work as if you had activated the @samp{Set} menu item on them as well.
345
346 @node  The State Button, The Customization Buttons, The Group Options, The Customization Buffer
347 @comment  node-name,  next,  previous,  up
348 @subsection The State Line and The Magic Button
349
350 The state line has two purposes.  The first is to hold the state menu,
351 as described in the previous sections.  The second is to indicate the
352 state of each customization item.  
353
354 For the magic button, this is done by the character inside the brackets.
355 The following states have been defined, the first that applies to the
356 current item will be used:
357
358 @table @samp
359 @item -
360 The option is currently hidden.  For group options that means the
361 members are not shown, for variables and faces that the value is not
362 shown.  You cannot perform any of the state change operations on a
363 hidden customization option.
364
365 @item *
366 The value if this option has been modified in the buffer, but not yet
367 applied.  
368
369 @item +
370 The item has has been set by the user.
371
372 @item :
373 The current value of this option is different from the saved value.   
374
375 @item !
376 The saved value of this option is different from the factory setting.
377
378 @item @@
379 The factory setting of this option is not known.  This occurs when you
380 try to customize variables or faces that have not been explicitly
381 declared as customizable.
382
383 @item SPC
384 The factory setting is still in effect.
385
386 @end table
387
388 For non-hidden group options, the state shown is the most severe state
389 of its members, where more severe means that it appears earlier in the
390 list above (except hidden members, which are ignored).
391
392 @node  The Customization Buttons,  , The State Button, The Customization Buffer
393 @comment  node-name,  next,  previous,  up
394 @subsection The Customization Buttons
395
396 The last part of the customization buffer looks like this:
397
398 @example
399 [Set] [Save] [Reset] [Done]
400 @end example
401
402 Activating the @samp{[Set]}, @samp{[Save]}, or @samp{[Reset]}
403 button will affect all modified customization items that are visible in
404 the buffer.  @samp{[Done]} will bury the buffer.
405
406 @node   Declarations, Utilities, The Customization Buffer, Top
407 @comment  node-name,  next,  previous,  up
408 @section Declarations
409
410 This section describes how to declare customization groups, variables,
411 and faces.  It doesn't contain any examples, but please look at the file
412 @file{cus-edit.el} which contains many declarations you can learn from.
413
414 @menu
415 * Declaring Groups::            
416 * Declaring Variables::         
417 * Declaring Faces::             
418 * Usage for Package Authors::   
419 @end menu
420
421 All the customization declarations can be changes by keyword arguments.
422 Groups, variables, and faces all share these common keywords:
423
424 @table @code
425 @item :group
426 @var{value} should be a customization group. 
427 Add @var{symbol} to that group. 
428 @item :link
429 @var{value} should be a widget type. 
430 Add @var{value} to the extrenal links for this customization option.
431 Useful widget types include @code{custom-manual}, @code{info-link}, and
432 @code{url-link}. 
433 @item :load
434 Add @var{value} to the files that should be loaded nefore displaying
435 this customization option.  The value should be iether a string, which
436 should be a string which will be loaded with @code{load-library} unless
437 present in @code{load-history}, or a symbol which will be loaded with
438 @code{require}. 
439 @item :tag
440 @var{Value} should be a short string used for identifying the option in
441 customization menus and buffers.  By default the tag will be
442 automatically created from the options name.
443 @end table
444
445 @node  Declaring Groups, Declaring Variables, Declarations, Declarations
446 @comment  node-name,  next,  previous,  up
447 @subsection Declaring Groups
448
449 Use @code{defgroup} to declare new customization groups. 
450
451 @defun defgroup symbol members doc [keyword value]...
452 Declare @var{symbol} as a customization group containing @var{members}. 
453 @var{symbol} does not need to be quoted.
454
455 @var{doc} is the group documentation.
456
457 @var{members} should be an alist of the form ((@var{name}
458 @var{widget})...) where @var{name} is a symbol and @var{widget} is a
459 widget for editing that symbol.  Useful widgets are
460 @code{custom-variable} for editing variables, @code{custom-face} for
461 editing faces, and @code{custom-group} for editing groups.@refill
462
463 Internally, custom uses the symbol property @code{custom-group} to keep
464 track of the group members, and @code{group-documentation} for the
465 documentation string. 
466
467 The following additional @var{keyword}'s are defined:
468
469 @table @code
470 @item :prefix
471 @var{value} should be a string.  If the string is a prefix for the name
472 of a member of the group, that prefix will be ignored when creating a
473 tag for that member.
474 @end table
475 @end defun
476
477 @node  Declaring Variables, Declaring Faces, Declaring Groups, Declarations
478 @comment  node-name,  next,  previous,  up
479 @subsection Declaring Variables
480
481 Use @code{defcustom} to declare user editable variables.
482
483 @defun defcustom symbol value doc [keyword value]...
484 Declare @var{symbol} as a customizable variable that defaults to @var{value}.
485 Neither @var{symbol} nor @var{value} needs to be quoted.
486 If @var{symbol} is not already bound, initialize it to @var{value}.
487
488 @var{doc} is the variable documentation.
489
490 The following additional @var{keyword}'s are defined:
491
492 @table @code
493 @item :type     
494 @var{value} should be a widget type.
495 @item :options
496 @var{value} should be a list of possible members of the specified type.
497 For hooks, this is a list of function names.
498 @end table
499
500 @xref{Sexp Types,,,widget,The Widget Library}, for information about
501 widgets to use together with the @code{:type} keyword.
502 @end defun
503
504 Internally, custom uses the symbol property @code{custom-type} to keep
505 track of the variables type, @code{factory-value} for the program
506 specified default value, @code{saved-value} for a value saved by the
507 user, and @code{variable-documentation} for the documentation string.
508
509 Use @code{custom-add-option} to specify that a specific function is
510 useful as an meber of a hook.
511
512 @defun custom-add-option symbol option
513 To the variable @var{symbol} add @var{option}.
514
515 If @var{symbol} is a hook variable, @var{option} should be a hook
516 member.  For other types variables, the effect is undefined."
517 @end defun
518
519 @node  Declaring Faces, Usage for Package Authors, Declaring Variables, Declarations
520 @comment  node-name,  next,  previous,  up
521 @subsection Declaring Faces
522
523 Faces are declared with @code{defface}.
524
525 @defun defface face spec doc [keyword value]... 
526
527 Declare @var{face} as a customizable face that defaults to @var{spec}.
528 @var{face} does not need to be quoted.
529
530 If @var{face} has been set with `custom-set-face', set the face attributes
531 as specified by that function, otherwise set the face attributes
532 according to @var{spec}.
533
534 @var{doc} is the face documentation.
535
536 @var{spec} should be an alist of the form @samp{((@var{display} @var{atts})...)}.
537
538 @var{atts} is a list of face attributes and their values.  The possible
539 attributes are defined in the variable `custom-face-attributes'.
540 Alternatively, @var{atts} can be a face in which case the attributes of
541 that face is used.
542
543 The @var{atts} of the first entry in @var{spec} where the @var{display}
544 matches the frame should take effect in that frame.  @var{display} can
545 either be the symbol `t', which will match all frames, or an alist of
546 the form @samp{((@var{req} @var{item}...)...)}@refill
547
548 For the @var{display} to match a FRAME, the @var{req} property of the
549 frame must match one of the @var{item}.  The following @var{req} are
550 defined:@refill
551
552 @table @code
553 @item type
554 (the value of (window-system))@*
555 Should be one of @code{x} or @code{tty}.
556
557 @item class
558 (the frame's color support)@*
559 Should be one of @code{color}, @code{grayscale}, or @code{mono}.
560
561 @item background
562 (what color is used for the background text)@*
563 Should be one of @code{light} or @code{dark}.
564 @end table
565   
566 Internally, custom uses the symbol property @code{factory-face} for the
567 program specified default face properties, @code{saved-face} for
568 properties saved by the user, and @code{face-doc-string} for the
569 documentation string.@refill
570
571 @end defun
572
573 @node Usage for Package Authors,  , Declaring Faces, Declarations
574 @comment  node-name,  next,  previous,  up
575 @subsection Usage for Package Authors
576
577 The recommended usage for the author of a typical emacs lisp package is
578 to create one group identifying the package, and make all user options
579 and faces members of that group.  If the package has more than around 20
580 such options, they should be divided into a number of subgroups, with
581 each subgroup being member of the top level group.
582
583 The top level group for the package should itself be member of one or
584 more of the standard customization groups.  There exists a group for
585 each @emph{finder} keyword.  Press @kbd{C-c p} to see a list of finder
586 keywords, and add you group to each of them, using the @code{:group}
587 keyword. 
588
589 @node  Utilities, The Init File, Declarations, Top
590 @comment  node-name,  next,  previous,  up
591 @section Utilities
592
593 These utilities can come in handy when adding customization support. 
594
595 @deffn Widget custom-manual
596 Widget type for specifying the info manual entry for a customization
597 option.  It takes one argument, an info address.
598 @end deffn
599
600 @defun custom-add-to-group group member widget
601 To existing @var{group} add a new @var{member} of type @var{widget},
602 If there already is an entry for that member, overwrite it.
603 @end defun
604
605 @defun custom-add-link symbol widget
606 To the custom option @var{symbol} add the link @var{widget}.
607 @end defun
608
609 @defun custom-add-load symbol load
610 To the custom option @var{symbol} add the dependency @var{load}.
611 @var{load} should be either a library file name, or a feature name.
612 @end defun
613
614 @defun custom-menu-create symbol &optional name
615 Create menu for customization group @var{symbol}.
616 If optional @var{name} is given, use that as the name of the menu. 
617 Otherwise make up a name from @var{symbol}.
618 The menu is in a format applicable to @code{easy-menu-define}.
619 @end defun
620
621 @node  The Init File, Wishlist, Utilities, Top
622 @comment  node-name,  next,  previous,  up
623 @section The Init File
624
625 When you save the customizations, call to @code{custom-set-variables},
626 @code{custom-set-faces} are inserted into the file specified by
627 @code{custom-file}.  By default @code{custom-file} is your @file{.emacs}
628 file.  If you use another file, you must explicitly load it yourself.
629 The two functions will initialize variables and faces as you have
630 specified.
631
632 @node  Wishlist,  , The Init File, Top
633 @comment  node-name,  next,  previous,  up
634 @section Wishlist
635
636 @itemize @bullet
637 @item
638 The menu items should be grayed out when the information is
639 missing.  I.e. if a variable doesn't have a factory setting, the user
640 should not be allowed to select the @samp{Factory} menu item.
641
642 @item 
643 Better support for keyboard operations in the customize buffer.
644
645 @item
646 Integrate with @file{w3} so you can customization buffers with much
647 better formatting.  I'm thinking about adding a <custom>name</custom>
648 tag.  The latest w3 have some support for this, so come up with a
649 convincing example.
650
651 @item
652 Add an `examples' section, with explained examples of custom type
653 definitions. 
654
655 @item
656 Support selectable color themes.  I.e., change many faces by setting one
657 variable.
658
659 @item
660 Support undo using lmi's @file{gnus-undo.el}.
661
662 @item
663 Make it possible to append to `choice', `radio', and `set' options.
664
665 @item
666 Make it possible to customize code, for example to enable or disable a
667 global minor mode.
668
669 @item
670 Ask whether set or modified variables should be saved in
671 @code{kill-buffer-hook}. 
672
673 Ditto for @code{kill-emacs-query-functions}.
674
675 @item
676 Command to check if there are any customization options that
677 does not belong to an existing group. 
678
679 @item
680 Optionally disable the point-cursor and instead highlight the selected
681 item in XEmacs.  This is like the *Completions* buffer in XEmacs.
682 Suggested by Jens Lautenbacher
683 @samp{<jens@@lemming0.lem.uni-karlsruhe.de>}.@refill
684
685 @item
686 Empty customization groups should start open (harder than it looks).
687
688 @item
689 Make it possible to include a comment/remark/annotation when saving an
690 option.
691
692 @end itemize
693
694 @contents
695 @bye