|
98
|
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
|
|
120
|
16 Version: 1.74
|
|
98
|
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
|
|
120
|
275 color device, and bold on a monochrome device. You do this by
|
|
|
276 activating `Edit All' in the state menu.
|
|
98
|
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)
|
|
120
|
286 State: this item is unchanged from its factory setting.
|
|
98
|
287 [ ] Face used when the customize item is invalid.
|
|
120
|
288 [INS] [DEL] Display: [ ] Type: [ ] X [ ] PM [ ] Win32 [ ] DOS [ ] TTY
|
|
98
|
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
|
|
120
|
308 displays, independently on what window system the device belongs to, and
|
|
98
|
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
|
|
120
|
323 match all device types, also device types other than those listed.
|
|
98
|
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
|
|
108
|
399 [Set] [Save] [Reset] [Done]
|
|
98
|
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
|
|
108
|
404 the buffer. @samp{[Done]} will bury the buffer.
|
|
98
|
405
|
|
|
406 @node Declarations, Utilities, The Customization Buffer, Top
|
|
|
407 @comment node-name, next, previous, up
|
|
|
408 @section Declarations
|
|
|
409
|
|
120
|
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
|
|
98
|
414 @menu
|
|
|
415 * Declaring Groups::
|
|
|
416 * Declaring Variables::
|
|
|
417 * Declaring Faces::
|
|
102
|
418 * Usage for Package Authors::
|
|
98
|
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
|
|
102
|
519 @node Declaring Faces, Usage for Package Authors, Declaring Variables, Declarations
|
|
98
|
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
|
|
108
|
554 (the value of (window-system))@*
|
|
98
|
555 Should be one of @code{x} or @code{tty}.
|
|
|
556
|
|
|
557 @item class
|
|
108
|
558 (the frame's color support)@*
|
|
98
|
559 Should be one of @code{color}, @code{grayscale}, or @code{mono}.
|
|
|
560
|
|
|
561 @item background
|
|
108
|
562 (what color is used for the background text)@*
|
|
98
|
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
|
|
108
|
568 properties saved by the user, and @code{face-doc-string} for the
|
|
98
|
569 documentation string.@refill
|
|
|
570
|
|
|
571 @end defun
|
|
|
572
|
|
102
|
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
|
|
98
|
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}
|
|
116
|
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.
|
|
98
|
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
|
|
120
|
643 Better support for keyboard operations in the customize buffer.
|
|
98
|
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>
|
|
108
|
648 tag. The latest w3 have some support for this, so come up with a
|
|
|
649 convincing example.
|
|
98
|
650
|
|
|
651 @item
|
|
|
652 Add an `examples' section, with explained examples of custom type
|
|
|
653 definitions.
|
|
|
654
|
|
|
655 @item
|
|
110
|
656 Support selectable color themes. I.e., change many faces by setting one
|
|
|
657 variable.
|
|
|
658
|
|
|
659 @item
|
|
98
|
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
|
|
120
|
666 Make it possible to customize code, for example to enable or disable a
|
|
|
667 global minor mode.
|
|
|
668
|
|
|
669 @item
|
|
98
|
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
|
|
120
|
685 @item
|
|
|
686 Empty customization groups should start open (harder than it looks).
|
|
|
687
|
|
98
|
688 @end itemize
|
|
|
689
|
|
|
690 @contents
|
|
|
691 @bye
|
