Mercurial > hg > xemacs-beta

comparison man/custom.texi @ 398:74fd4e045ea6 r21-2-29

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