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
