Source

XEmacs / man / custom.texi

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
\input texinfo.tex

@c %**start of header
@setfilename custom
@settitle The Customization Library
@iftex
@afourpaper
@headings double
@end iftex
@c %**end of header

@node Top, Introduction, (dir), (dir)
@comment  node-name,  next,  previous,  up
@top The Customization Library

Version: 1.20

@menu
* Introduction::                
* User Commands::               
* The Customization Buffer::    
* Declarations::                
* Utilities::                   
* The Init File::               
* Wishlist::                    
@end menu

@node   Introduction, User Commands, Top, Top
@comment  node-name,  next,  previous,  up
@section Introduction

This library allows customization of @dfn{user options}.  Currently two
types of user options are supported, namely @dfn{variables} and
@dfn{faces}.  Each user option can have four different values
simultaneously:
@table @dfn
@item factory setting
The value specified by the programmer.
@item saved value
The value saved by the user as the default for this variable.  This
overwrites the factory setting when starting a new emacs.
@item current value
The value used by Emacs.  This will not be remembered next time you
run Emacs.
@item widget value
The value entered by the user in a customization buffer, but not yet
applied.
@end table

Variables also have a @dfn{type}, which specifies what kind of values
the variable can hold, and how the value is presented in a customization
buffer.  By default a variable can hold any valid expression, but the
programmer can specify a more limited type when declaring the variable.

The user options are organized in a number of @dfn{groups}.  Each group
can contain a number user options, as well as other groups.  The groups
allows the user to concentrate on a specific part of emacs.

@node  User Commands, The Customization Buffer, Introduction, Top
@comment  node-name,  next,  previous,  up
@section User Commands

The following commands will create a customization buffer:

@table @code
@item customize
Create a customization buffer containing a specific group, by default
the @code{emacs} group.

@item customize-variable
Create a customization buffer containing a single variable.  

@item customize-face
Create a customization buffer containing a single face.

@item customize-apropos
Create a customization buffer containing all variables, faces, and
groups that match a user specified regular expression.
@end table

@node The Customization Buffer, Declarations, User Commands, Top
@comment  node-name,  next,  previous,  up
@section The Customization Buffer.

The customization buffer allows the user to make temporary or permanent
changes to how specific aspects of emacs works, by setting and editing
user options.  

The customization buffer contains three types of text:

@table @dfn
@item informative text
where the normal editing commands are disabled.

@item editable fields
where you can edit with the usual emacs commands.  Editable fields are
usually displayed with a grey background if your terminal supports
colors, or an italic font otherwise.

@item buttons
which can be activated by either pressing the @kbd{@key{ret}} while
point is located on the text, or pushing @kbd{mouse-2} while the mouse
pointer is above the tex.  Buttons are usually displayed in a bold
font. 
@end table

You can move to the next the next editable field or button by pressing
@kbd{@key{tab}} or the previous with @kbd{M-@key{tab}}.  Some buttons
have a small helpful message about their purpose, which will be
displayed when you move to it with the @key{tab} key.  

The buffer is divided into three part, an introductory text, a list of
customization options, and a line of customization buttons.  Each part
will be described in the following. 

@menu
* The Introductory Text::       
* The Customization Options::   
* The Variable Options::        
* The Face Options::            
* The Group Options::           
* The State Button::            
* The Customization Buttons::   
@end menu

@node  The Introductory Text, The Customization Options, The Customization Buffer, The Customization Buffer
@comment  node-name,  next,  previous,  up
@subsection  The Introductory Text

The start of the buffer contains a short explanation of what it is, and
how to get help.  It will typically look like this:

@example
This is a customization buffer.
Push RET or click mouse-2 on the word _help_ for more information.
@end example

Rather boring.  It is mostly just informative text, but the word
@samp{help} is a button that will bring up this document when
activated.  

@node  The Customization Options, The Variable Options, The Introductory Text, The Customization Buffer
@comment  node-name,  next,  previous,  up
@subsection The Customization Options

Each customization option looks similar to the following text:

@example
 *** custom-background-mode: default 
 State: this item is unchanged from its factory setting.
 [ ] [?] The brightness of the background.
@end example

The option contains the parts described below.

@table @samp
@item ***
The Level Button.  The customization options in the buffer are organized
in a hierarchy, which is indicated by the number of stars in the level
button.  The top level options will be shown as @samp{*}.  When they are
expanded, the suboptions will be shown as @samp{**}.  The example option
is thus a subsuboption.

Activating the level buttons will toggle between hiding and exposing the
content of that option.  The content can either be the value of the
option, as in this example, or a list of suboptions.

@item custom-background-mode
This is the tag of the the option.  The tag is a name of a variable, a
face, or customization group.  Activating the tag has an effect that
depends on the exact type of the option.  In this particular case,
activating the tag will bring up a menu that will allow you to choose
from the three possible values of the `custom-background-mode'
variable. 

@item default
After the tag, the options value is shown.  Depending on its type, you
may be able to edit the value directly.  If an option should contain a
file name, it is displayed in an editable field, i.e. you can edit it
using the standard emacs editing commands.

@item State: this item is unchanged from its factory setting.
The state line.  This line will explain the state of the option,
e.g. whether it is currently hidden, or whether it has been modified or
not.  Activating the button will allow you to change the state, e.g. set
or reset the changes you have made.  This is explained in detail in the
following sections.

@item [ ]
The magic button.  This is an abbreviated version of the state line. 

@item [?] 
The documentation button.  If the documentation is more than one line,
this button will be present.  Activating the button will toggle whether
the complete documentation is shown, or only the first line.

@item The brightness of the background.
This is a documentation string explaining the purpose of this particular
customization option.

@end table

@node  The Variable Options, The Face Options, The Customization Options, The Customization Buffer
@comment  node-name,  next,  previous,  up
@subsection The Variable Options

The most common customization options are emacs lisp variables.  The
actual editing of these variables depend on what type values the
variable is expected to contain.  For example, a lisp variable whose
value should be a string will typically be represented with an editable
text field in the buffer, where you can change the string directly.  If
the value is a list, each item in the list will be presented in the
buffer buffer on a separate line, with buttons to insert new items in
the list, or delete existing items from the list.  You may want to see 
@ref{User Interface,,, widget, The Widget Library}, where some examples
of editing are discussed.  

You can either choose to edit the value directly, or edit the lisp
value for that variable.  The lisp value is a lisp expression that
will be evaluated when you start emacs.  The result of the evaluation
will be used as the initial value for that variable.  Editing the
lisp value is for experts only, but if the current value of the
variable is of a wrong type (i.e. a symbol where a string is expected),
the `edit lisp' mode will always be selected.

You can see what mode is currently selected by looking at the state
button.  If it uses parenthesises (like @samp{( )}) it is in edit lisp
mode, with square brackets (like @samp{[ ]}) it is normal edit mode.
You can switch mode by activating the state button, and select either
@samp{Edit} or @samp{Edit lisp} from the menu.

You can change the state of the variable with the other menu items:

@table @samp
@item Set
When you have made your modifications in the buffer, you need to
activate this item to make the modifications take effect.  The
modifications will be forgotten next time you run emacs.

@item Save
Unless you activate this item instead!  This will mark the modification
as permanent, i.e. the changes will be remembered in the next emacs
session.

@item Reset
If you have made some modifications and not yet applied them, you can
undo the modification by activating this item.

@item Reset to Saved
Activating this item will reset the value of the variable to the last
value you marked as permanent with `Save'.

@item Reset to Factory Settings
Activating this item will undo all modifications you have made, and
reset the value to the initial value specified by the program itself. 
@end table

By default, the value of large or complicated variables are hidden.   You
can show the value by clicking on the level button.

@node  The Face Options, The Group Options, The Variable Options, The Customization Buffer
@comment  node-name,  next,  previous,  up
@subsection The Face Options

A face is an object that controls the appearance of some buffer text.
The face has a number of possible attributes, such as boldness,
foreground color, and more.  For each attribute you can specify whether
this attribute is controlled by the face, and if so, what the value is.
For example, if the attribute bold is not controlled by a face, using
that face on some buffer text will not affect its boldness.  If the bold
attribute is controlled by the face, it can be turned either on or of.

It is possible to specify that a face should have different attributes
on different device types.  For example, a face may make text red on a
color device, and bold on a monochrome device.

The way this is presented in the customization buffer is to have a list
of display specifications, and for each display specification a list of
face attributes.  For each face attribute, there is a checkbox
specifying whether this attribute has effect and what the value is.
Here is an example:

@example
 *** custom-invalid-face: (sample)
 [ ] Face used when the customize item is invalid.
 [INS] [DEL] Display: [ ] Type: [ ] X [ ] TTY
                      [X] Class: [X] Color [ ] Grayscale [ ] Monochrome
                      [ ] Background: [ ] Light [ ] Dark
             Attributes: [ ] Bold: off 
                         [ ] Italic: off 
                         [ ] Underline: off 
                         [X] Foreground: yellow (sample)
                         [X] Background: red (sample)
                         [ ] Stipple:  
 [INS] [DEL] Display: all
             Attributes: [X] Bold: on 
                         [X] Italic: on 
                         [X] Underline: on 
                         [ ] Foreground: default (sample)
                         [ ] Background: default (sample)
                         [ ] Stipple:  
 [INS]
@end example

This has two display specifications.  The first will match all color
displays, independently on whether the device is X11 or a tty, and
whether background color is dark or light.  For devices matching this
specification, @samp{custom-invalid-face} will force text to be
displayed in yellow on red, but leave all other attributes alone.

The second display will simply match everything.  Since the list is
prioritised, this means that it will match all non-color displays.  For
these, the face will not affect the foreground or background color, but
force the font to be both bold, italic, and underline.

You can add or delete display specifications by activating the
@samp{[INS]} and @samp{[DEL]} buttons, and modify them by clicking on
the check boxes.  The first checkbox in each line in the display
specification is special.  It specify whether this particular property
will even be relevant.  By not checking the box in the first display, we
match all device types, also device types other than X11 and tty, for
example ms-windows, nextstep, and mac os.

After modifying the face, you can activate the state button to make the
changes take effect.  The menu items in the state button menu is similar
to the state menu items for variables described in the previous section.

@node  The Group Options, The State Button, The Face Options, The Customization Buffer
@comment  node-name,  next,  previous,  up
@subsection The Group Options

Since Emacs has approximately a zillion configuration options, they have
been organized in groups.  Each group can contain other groups, thus
creating a customization hierarchy.  The nesting of the customization
within the visible part of this hierarchy is indicated by the number of
stars in the level button.

Since there is really no customization needed for the group itself, the
menu items in the groups state button will affect all modified group
members recursively.  Thus, if you activate the @samp{Set} menu item,
all variables and faces that have been modified and belong to that group
will be applied.  For those members that themselves are groups, it will
work as if you had activated the @samp{Set} menu item on them as well.

@node  The State Button, The Customization Buttons, The Group Options, The Customization Buffer
@comment  node-name,  next,  previous,  up
@subsection The State Line and The Magic Button

The state line has two purposes.  The first is to hold the state menu,
as described in the previous sections.  The second is to indicate the
state of each customization item.  

For the magic button, this is done by the character inside the brackets.
The following states have been defined, the first that applies to the
current item will be used:

@table @samp
@item -
The option is currently hidden.  For group options that means the
members are not shown, for variables and faces that the value is not
shown.  You cannot perform any of the state change operations on a
hidden customization option.

@item *
The value if this option has been modified in the buffer, but not yet
applied.  

@item +
The item has has been set by the user.

@item :
The current value of this option is different from the saved value.   

@item !
The saved value of this option is different from the factory setting.

@item @@
The factory setting of this option is not known.  This occurs when you
try to customize variables or faces that have not been explicitly
declared as customizable.

@item SPC
The factory setting is still in effect.

@end table

For non-hidden group options, the state shown is the most severe state
of its members, where more severe means that it appears earlier in the
list above (except hidden members, which are ignored).

@node  The Customization Buttons,  , The State Button, The Customization Buffer
@comment  node-name,  next,  previous,  up
@subsection The Customization Buttons

The last part of the customization buffer looks like this:

@example
[Set] [Save] [Reset]
@end example

Activating the @samp{[Set]}, @samp{[Save]}, or @samp{[Reset]}
button will affect all modified customization items that are visible in
the buffer.

@node   Declarations, Utilities, The Customization Buffer, Top
@comment  node-name,  next,  previous,  up
@section Declarations

@menu
* Declaring Groups::            
* Declaring Variables::         
* Declaring Faces::             
@end menu

All the customization declarations can be changes by keyword arguments.
Groups, variables, and faces all share these common keywords:

@table @code
@item :group
@var{value} should be a customization group. 
Add @var{symbol} to that group. 
@item :link
@var{value} should be a widget type. 
Add @var{value} to the extrenal links for this customization option.
Useful widget types include @code{custom-manual}, @code{info-link}, and
@code{url-link}. 
@item :load
Add @var{value} to the files that should be loaded nefore displaying
this customization option.  The value should be iether a string, which
should be a string which will be loaded with @code{load-library} unless
present in @code{load-history}, or a symbol which will be loaded with
@code{require}. 
@item :tag
@var{Value} should be a short string used for identifying the option in
customization menus and buffers.  By default the tag will be
automatically created from the options name.
@end table

@node  Declaring Groups, Declaring Variables, Declarations, Declarations
@comment  node-name,  next,  previous,  up
@subsection Declaring Groups

Use @code{defgroup} to declare new customization groups. 

@defun defgroup symbol members doc [keyword value]...
Declare @var{symbol} as a customization group containing @var{members}. 
@var{symbol} does not need to be quoted.

@var{doc} is the group documentation.

@var{members} should be an alist of the form ((@var{name}
@var{widget})...) where @var{name} is a symbol and @var{widget} is a
widget for editing that symbol.  Useful widgets are
@code{custom-variable} for editing variables, @code{custom-face} for
editing faces, and @code{custom-group} for editing groups.@refill

Internally, custom uses the symbol property @code{custom-group} to keep
track of the group members, and @code{group-documentation} for the
documentation string. 

The following additional @var{keyword}'s are defined:

@table @code
@item :prefix
@var{value} should be a string.  If the string is a prefix for the name
of a member of the group, that prefix will be ignored when creating a
tag for that member.
@end table
@end defun

@node  Declaring Variables, Declaring Faces, Declaring Groups, Declarations
@comment  node-name,  next,  previous,  up
@subsection Declaring Variables

Use @code{defcustom} to declare user editable variables.

@defun defcustom symbol value doc [keyword value]...
Declare @var{symbol} as a customizable variable that defaults to @var{value}.
Neither @var{symbol} nor @var{value} needs to be quoted.
If @var{symbol} is not already bound, initialize it to @var{value}.

@var{doc} is the variable documentation.

The following additional @var{keyword}'s are defined:

@table @code
@item :type	
@var{value} should be a widget type.
@item :options
@var{value} should be a list of possible members of the specified type.
For hooks, this is a list of function names.
@end table

@xref{Sexp Types,,,widget,The Widget Library}, for information about
widgets to use together with the @code{:type} keyword.
@end defun

Internally, custom uses the symbol property @code{custom-type} to keep
track of the variables type, @code{factory-value} for the program
specified default value, @code{saved-value} for a value saved by the
user, and @code{variable-documentation} for the documentation string.

Use @code{custom-add-option} to specify that a specific function is
useful as an meber of a hook.

@defun custom-add-option symbol option
To the variable @var{symbol} add @var{option}.

If @var{symbol} is a hook variable, @var{option} should be a hook
member.  For other types variables, the effect is undefined."
@end defun

@node  Declaring Faces,  , Declaring Variables, Declarations
@comment  node-name,  next,  previous,  up
@subsection Declaring Faces

Faces are declared with @code{defface}.

@defun defface face spec doc [keyword value]... 

Declare @var{face} as a customizable face that defaults to @var{spec}.
@var{face} does not need to be quoted.

If @var{face} has been set with `custom-set-face', set the face attributes
as specified by that function, otherwise set the face attributes
according to @var{spec}.

@var{doc} is the face documentation.

@var{spec} should be an alist of the form @samp{((@var{display} @var{atts})...)}.

@var{atts} is a list of face attributes and their values.  The possible
attributes are defined in the variable `custom-face-attributes'.
Alternatively, @var{atts} can be a face in which case the attributes of
that face is used.

The @var{atts} of the first entry in @var{spec} where the @var{display}
matches the frame should take effect in that frame.  @var{display} can
either be the symbol `t', which will match all frames, or an alist of
the form @samp{((@var{req} @var{item}...)...)}@refill

For the @var{display} to match a FRAME, the @var{req} property of the
frame must match one of the @var{item}.  The following @var{req} are
defined:@refill

@table @code
@item type
(the value of (window-system))@br
Should be one of @code{x} or @code{tty}.

@item class
(the frame's color support)@br
Should be one of @code{color}, @code{grayscale}, or @code{mono}.

@item background
(what color is used for the background text)@br
Should be one of @code{light} or @code{dark}.
@end table
  
Internally, custom uses the symbol property @code{factory-face} for the
program specified default face properties, @code{saved-face} for
properties saved by the user, and @code{face-documentation} for the
documentation string.@refill

@end defun

@node  Utilities, The Init File, Declarations, Top
@comment  node-name,  next,  previous,  up
@section Utilities

These utilities can come in handy when adding customization support. 

@deffn Widget custom-manual
Widget type for specifying the info manual entry for a customization
option.  It takes one argument, an info address.
@end deffn

@defun custom-add-to-group group member widget
To existing @var{group} add a new @var{member} of type @var{widget},
If there already is an entry for that member, overwrite it.
@end defun

@defun custom-add-link symbol widget
To the custom option @var{symbol} add the link @var{widget}.
@end defun

@defun custom-add-load symbol load
To the custom option @var{symbol} add the dependency @var{load}.
@var{load} should be either a library file name, or a feature name.
@end defun

@defun custom-menu-create symbol &optional name
Create menu for customization group @var{symbol}.
If optional @var{name} is given, use that as the name of the menu. 
Otherwise make up a name from @var{symbol}.
The menu is in a format applicable to @code{easy-menu-define}.
@end defun

@node  The Init File, Wishlist, Utilities, Top
@comment  node-name,  next,  previous,  up
@section The Init File

When you save the customizations, call to @code{custom-set-variables},
@code{custom-set-faces} are inserted into the file specified by
@code{custom-file}.  By default @code{custom-file} is your @file{.emacs}
file.  The two functions will initialize variables and faces as you have
specified. 

@node  Wishlist,  , The Init File, Top
@comment  node-name,  next,  previous,  up
@section Wishlist

@itemize @bullet
@item
The menu items should be grayed out when the information is
missing.  I.e. if a variable doesn't have a factory setting, the user
should not be allowed to select the @samp{Factory} menu item.

@item 
We need @strong{much} better support for keyboard operations in the
customize buffer.

@item
Support real specifiers under XEmacs.

@item
Integrate with @file{w3} so you can customization buffers with much
better formatting.  I'm thinking about adding a <custom>name</custom>
tag. 

@item
Add an `examples' section, with explained examples of custom type
definitions. 

@item
Support undo using lmi's @file{gnus-undo.el}.

@item
Make it possible to append to `choice', `radio', and `set' options.

@end itemize

@contents
@bye