Mercurial > hg > xemacs-beta

comparison man/custom.texi @ 412:697ef44129c6 r21-2-14

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r21-2-14
author cvs
date Mon, 13 Aug 2007 11:20:41 +0200
parents 74fd4e045ea6
children da8ed4261e83
comparison
equal deleted inserted replaced
411:12e008d41344 412:697ef44129c6
1 \input texinfo.tex 1 \input texinfo.tex
2 2
3 @c %**start of header 3 @c %**start of header
4 @setfilename ../info/custom.info 4 @setfilename ../info/custom
5 @settitle The Customization Library 5 @settitle The Customization Library
6 @iftex 6 @iftex
7 @afourpaper 7 @afourpaper
8 @headings double 8 @headings double
9 @end iftex 9 @end iftex
11 11
12 @ifinfo 12 @ifinfo
13 @dircategory XEmacs Editor 13 @dircategory XEmacs Editor
14 @direntry 14 @direntry
15 * Customizations: (custom). Customization Library. 15 * Customizations: (custom). Customization Library.
16 package.
16 @end direntry 17 @end direntry
17 @end ifinfo 18 @end ifinfo
18 19
19 @node Top, Declaring Groups, (dir), (dir) 20 @node Top, Declaring Groups, (dir), (dir)
20 @comment node-name, next, previous, up 21 @comment node-name, next, previous, up
23 This manual describes how to declare customization groups, variables, 24 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 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 @file{cus-edit.el} which contains many declarations you can learn from.
26 27
27 @menu 28 @menu
28 * Declaring Groups:: 29 * Declaring Groups::
29 * Declaring Variables:: 30 * Declaring Variables::
30 * Declaring Faces:: 31 * Declaring Faces::
31 * Usage for Package Authors:: 32 * Usage for Package Authors::
32 * Utilities:: 33 * Utilities::
33 * The Init File:: 34 * The Init File::
34 * Wishlist:: 35 * Wishlist::
35 @end menu 36 @end menu
36 37
37 All the customization declarations can be changes by keyword arguments. 38 All the customization declarations can be changes by keyword arguments.
38 Groups, variables, and faces all share these common keywords: 39 Groups, variables, and faces all share these common keywords:
39 40
40 @table @code 41 @table @code
41 @item :group 42 @item :group
42 @var{value} should be a customization group. 43 @var{value} should be a customization group.
43 Add @var{symbol} to that group. 44 Add @var{symbol} to that group.
44 @item :link 45 @item :link
45 @var{value} should be a widget type. 46 @var{value} should be a widget type.
46 Add @var{value} to the external links for this customization option. 47 Add @var{value} to the external links for this customization option.
47 Useful widget types include @code{custom-manual}, @code{info-link}, and 48 Useful widget types include @code{custom-manual}, @code{info-link}, and
48 @code{url-link}. 49 @code{url-link}.
49 @item :load 50 @item :load
50 Add @var{value} to the files that should be loaded before displaying 51 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 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 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 present in @code{load-history}, or a symbol which will be loaded with
54 @code{require}. 55 @code{require}.
55 @item :tag 56 @item :tag
56 @var{Value} should be a short string used for identifying the option in 57 @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 customization menus and buffers. By default the tag will be
58 automatically created from the options name. 59 automatically created from the options name.
59 @end table 60 @end table
60 61
61 @node Declaring Groups, Declaring Variables, Top, Top 62 @node Declaring Groups, Declaring Variables, Top, Top
62 @comment node-name, next, previous, up 63 @comment node-name, next, previous, up
63 @section Declaring Groups 64 @section Declaring Groups
64 65
65 Use @code{defgroup} to declare new customization groups. 66 Use @code{defgroup} to declare new customization groups.
66 67
67 @defun defgroup symbol members doc [keyword value]... 68 @defun defgroup symbol members doc [keyword value]...
68 Declare @var{symbol} as a customization group containing @var{members}. 69 Declare @var{symbol} as a customization group containing @var{members}.
69 @var{symbol} does not need to be quoted. 70 @var{symbol} does not need to be quoted.
70 71
71 @var{doc} is the group documentation. 72 @var{doc} is the group documentation.
72 73
73 @var{members} should be an alist of the form ((@var{name} 74 @var{members} should be an alist of the form ((@var{name}
76 @code{custom-variable} for editing variables, @code{custom-face} for 77 @code{custom-variable} for editing variables, @code{custom-face} for
77 editing faces, and @code{custom-group} for editing groups.@refill 78 editing faces, and @code{custom-group} for editing groups.@refill
78 79
79 Internally, custom uses the symbol property @code{custom-group} to keep 80 Internally, custom uses the symbol property @code{custom-group} to keep
80 track of the group members, and @code{group-documentation} for the 81 track of the group members, and @code{group-documentation} for the
81 documentation string. 82 documentation string.
82 83
83 The following additional @var{keyword}'s are defined: 84 The following additional @var{keyword}'s are defined:
84 85
85 @table @code 86 @table @code
86 @item :prefix 87 @item :prefix
104 @var{doc} is the variable documentation. 105 @var{doc} is the variable documentation.
105 106
106 The following additional @var{keyword}'s are defined: 107 The following additional @var{keyword}'s are defined:
107 108
108 @table @code 109 @table @code
109 @item :type 110 @item :type
110 @var{value} should be a widget type. 111 @var{value} should be a widget type.
111 112
112 @item :options 113 @item :options
113 @var{value} should be a list of possible members of the specified type. 114 @var{value} should be a list of possible members of the specified type.
114 For hooks, this is a list of function names. 115 For hooks, this is a list of function names.
120 121
121 @table @code 122 @table @code
122 @item custom-initialize-set 123 @item custom-initialize-set
123 Use the @code{:set} method to initialize the variable. Do not 124 Use the @code{:set} method to initialize the variable. Do not
124 initialize it if already bound. This is the default @code{:initialize} 125 initialize it if already bound. This is the default @code{:initialize}
125 method. 126 method.
126 127
127 @item custom-initialize-default 128 @item custom-initialize-default
128 Always use @code{set-default} to initialize the variable, even if a 129 Always use @code{set-default} to initialize the variable, even if a
129 @code{:set} method has been specified. 130 @code{:set} method has been specified.
130 131
133 method with the value returned by the @code{:get} method. 134 method with the value returned by the @code{:get} method.
134 135
135 @item custom-initialize-changed 136 @item custom-initialize-changed
136 Like @code{custom-initialize-reset}, but use @code{set-default} to 137 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 initialize the variable if it is not bound and has not been set
138 already. 139 already.
139 @end table 140 @end table
140 141
141 @item :set 142 @item :set
142 @var{value} should be a function to set the value of the symbol. It 143 @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 takes two arguments, the symbol to set and the value to give it. The
144 default is @code{set-default}. 145 default is @code{set-default}.
145 146
146 @item :get 147 @item :get
149 value for that symbol. The default is @code{default-value}. 150 value for that symbol. The default is @code{default-value}.
150 151
151 @item :require 152 @item :require
152 @var{value} should be a feature symbol. Each feature will be required 153 @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 when the `defcustom' is evaluated, or when Emacs is started if the user
154 has saved this option. 155 has saved this option.
155 156
156 @end table 157 @end table
157 158
158 @xref{Sexp Types,,,widget,The Widget Library}, for information about 159 @xref{Sexp Types,,,widget,The Widget Library}, for information about
159 widgets to use together with the @code{:type} keyword. 160 widgets to use together with the @code{:type} keyword.
178 @comment node-name, next, previous, up 179 @comment node-name, next, previous, up
179 @section Declaring Faces 180 @section Declaring Faces
180 181
181 Faces are declared with @code{defface}. 182 Faces are declared with @code{defface}.
182 183
183 @defun defface face spec doc [keyword value]... 184 @defun defface face spec doc [keyword value]...
184 185
185 Declare @var{face} as a customizable face that defaults to @var{spec}. 186 Declare @var{face} as a customizable face that defaults to @var{spec}.
186 @var{face} does not need to be quoted. 187 @var{face} does not need to be quoted.
187 188
188 If @var{face} has been set with `custom-set-face', set the face attributes 189 If @var{face} has been set with `custom-set-face', set the face attributes
216 217
217 @item background 218 @item background
218 (what color is used for the background text)@* 219 (what color is used for the background text)@*
219 Should be one of @code{light} or @code{dark}. 220 Should be one of @code{light} or @code{dark}.
220 @end table 221 @end table
221 222
222 Internally, custom uses the symbol property @code{face-defface-spec} for 223 Internally, custom uses the symbol property @code{face-defface-spec} for
223 the program specified default face properties, @code{saved-face} for 224 the program specified default face properties, @code{saved-face} for
224 properties saved by the user, and @code{face-documentation} for the 225 properties saved by the user, and @code{face-documentation} for the
225 documentation string.@refill 226 documentation string.@refill
226 227
238 239
239 The top level group for the package should itself be member of one or 240 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 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 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 keywords, and add you group to each of them, using the @code{:group}
243 keyword. 244 keyword.
244 245
245 @node Utilities, The Init File, Usage for Package Authors, Top 246 @node Utilities, The Init File, Usage for Package Authors, Top
246 @comment node-name, next, previous, up 247 @comment node-name, next, previous, up
247 @section Utilities 248 @section Utilities
248 249
249 These utilities can come in handy when adding customization support. 250 These utilities can come in handy when adding customization support.
250 251
251 @deffn Widget custom-manual 252 @deffn Widget custom-manual
252 Widget type for specifying the info manual entry for a customization 253 Widget type for specifying the info manual entry for a customization
253 option. It takes one argument, an info address. 254 option. It takes one argument, an info address.
254 @end deffn 255 @end deffn
267 @var{load} should be either a library file name, or a feature name. 268 @var{load} should be either a library file name, or a feature name.
268 @end defun 269 @end defun
269 270
270 @defun customize-menu-create symbol &optional name 271 @defun customize-menu-create symbol &optional name
271 Create menu for customization group @var{symbol}. 272 Create menu for customization group @var{symbol}.
272 If optional @var{name} is given, use that as the name of the menu. 273 If optional @var{name} is given, use that as the name of the menu.
273 Otherwise the menu will be named `Customize'. 274 Otherwise the menu will be named `Customize'.
274 The menu is in a format applicable to @code{easy-menu-define}. 275 The menu is in a format applicable to @code{easy-menu-define}.
275 @end defun 276 @end defun
276 277
277 @node The Init File, Wishlist, Utilities, Top 278 @node The Init File, Wishlist, Utilities, Top
288 @node Wishlist, , The Init File, Top 289 @node Wishlist, , The Init File, Top
289 @comment node-name, next, previous, up 290 @comment node-name, next, previous, up
290 @section Wishlist 291 @section Wishlist
291 292
292 @itemize @bullet 293 @itemize @bullet
293 @item 294 @item
294 Better support for keyboard operations in the customize buffer. 295 Better support for keyboard operations in the customize buffer.
295 296
296 @item 297 @item
297 Integrate with @file{w3} so you can get customization buffers with much 298 Integrate with @file{w3} so you can get customization buffers with much
298 better formatting. I'm thinking about adding a <custom>name</custom> 299 better formatting. I'm thinking about adding a <custom>name</custom>
299 tag. The latest w3 have some support for this, so come up with a 300 tag. The latest w3 have some support for this, so come up with a
300 convincing example. 301 convincing example.
301 302
302 @item 303 @item
303 Add an `examples' section, with explained examples of custom type 304 Add an `examples' section, with explained examples of custom type
304 definitions. 305 definitions.
305 306
306 @item 307 @item
307 Support selectable color themes. I.e., change many faces by setting one 308 Support selectable color themes. I.e., change many faces by setting one
308 variable. 309 variable.
309 310
314 @item 315 @item
315 Make it possible to append to `choice', `radio', and `set' options. 316 Make it possible to append to `choice', `radio', and `set' options.
316 317
317 @item 318 @item
318 Ask whether set or modified variables should be saved in 319 Ask whether set or modified variables should be saved in
319 @code{kill-buffer-hook}. 320 @code{kill-buffer-hook}.
320 321
321 Ditto for @code{kill-emacs-query-functions}. 322 Ditto for @code{kill-emacs-query-functions}.
322 323
323 @item 324 @item
324 Command to check if there are any customization options that 325 Command to check if there are any customization options that
325 does not belong to an existing group. 326 does not belong to an existing group.
326 327
327 @item 328 @item
328 Optionally disable the point-cursor and instead highlight the selected 329 Optionally disable the point-cursor and instead highlight the selected
329 item in XEmacs. This is like the *Completions* buffer in XEmacs. 330 item in XEmacs. This is like the *Completions* buffer in XEmacs.
330 Suggested by Jens Lautenbacher 331 Suggested by Jens Lautenbacher
333 @item 334 @item
334 Explain why it is necessary that all choices have different default 335 Explain why it is necessary that all choices have different default
335 values. 336 values.
336 337
337 @item 338 @item
339 Make it possible to include a comment/remark/annotation when saving an
340 option.
341
342 @item
338 Add some direct support for meta variables, i.e. make it possible to 343 Add some direct support for meta variables, i.e. make it possible to
339 specify that this variable should be reset when that variable is 344 specify that this variable should be reset when that variable is
340 changed. 345 changed.
341 346
342 @item 347 @item
343 Add tutorial. 348 Add tutorial.
344 349
345 @item 350 @item
376 @item 381 @item
377 Add an easy way to display the standard settings when an item is modified. 382 Add an easy way to display the standard settings when an item is modified.
378 383
379 @item 384 @item
380 See if it is feasible to scan files for customization information 385 See if it is feasible to scan files for customization information
381 instead of loading them, 386 instead of loading them,
382 387
383 @item 388 @item
384 Add hint message when user push a non-pushable tag. 389 Add hint message when user push a non-pushable tag.
385 390
386 Suggest that the user unhide if hidden, and edit the value directly 391 Suggest that the user unhide if hidden, and edit the value directly
390 Use checkboxes and radio buttons in the state menus. 395 Use checkboxes and radio buttons in the state menus.
391 396
392 @item 397 @item
393 Add option to hide @samp{[hide]} for short options. Default, on. 398 Add option to hide @samp{[hide]} for short options. Default, on.
394 399
395 @item 400 @item
396 Add option to hide @samp{[state]} for options with their standard 401 Add option to hide @samp{[state]} for options with their standard
397 settings. 402 settings.
398 403
399 @item 404 @item
400 There should be a way to specify site defaults for user options. 405 There should be a way to specify site defaults for user options.
401 406
402 @item 407 @item
403 There should be more buffer styles. The default `nested style, the old 408 There should be more buffer styles. The default `nested style, the old
404 `outline' style, a `numeric' style with numbers instead of stars, an 409 `outline' style, a `numeric' style with numbers instead of stars, an