X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=man%2Fcustom.texi;h=fc3a9e46c9b93fdf4cc15c2d268bc643176f129f;hb=6cf5b62d9939d32852d58b425ee359c087e06856;hp=909c5a8136338628af0ddf99dfc87cc4d191b8ee;hpb=6883ee56ec887c2c48abe5b06b5e66aa74031910;p=chise%2Fxemacs-chise.git.1 diff --git a/man/custom.texi b/man/custom.texi index 909c5a8..fc3a9e4 100644 --- a/man/custom.texi +++ b/man/custom.texi @@ -1,7 +1,7 @@ \input texinfo.tex @c %**start of header -@setfilename ../info/custom +@setfilename ../info/custom.info @settitle The Customization Library @iftex @afourpaper @@ -9,6 +9,13 @@ @end iftex @c %**end of header +@ifinfo +@dircategory XEmacs Editor +@direntry +* Customizations: (custom). Customization Library. +@end direntry +@end ifinfo + @node Top, Declaring Groups, (dir), (dir) @comment node-name, next, previous, up @top The Customization Library @@ -18,13 +25,13 @@ and faces. It doesn't contain any examples, but please look at the file @file{cus-edit.el} which contains many declarations you can learn from. @menu -* Declaring Groups:: -* Declaring Variables:: -* Declaring Faces:: -* Usage for Package Authors:: -* Utilities:: -* The Init File:: -* Wishlist:: +* Declaring Groups:: +* Declaring Variables:: +* Declaring Faces:: +* Usage for Package Authors:: +* Utilities:: +* The Init File:: +* Wishlist:: @end menu All the customization declarations can be changes by keyword arguments. @@ -32,19 +39,19 @@ 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. +@var{value} should be a customization group. +Add @var{symbol} to that group. @item :link -@var{value} should be a widget type. +@var{value} should be a widget type. Add @var{value} to the external links for this customization option. Useful widget types include @code{custom-manual}, @code{info-link}, and -@code{url-link}. +@code{url-link}. @item :load Add @var{value} to the files that should be loaded before displaying this customization option. The value should be either 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}. +@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 @@ -55,10 +62,10 @@ automatically created from the options name. @comment node-name, next, previous, up @section Declaring Groups -Use @code{defgroup} to declare new customization 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}. +Declare @var{symbol} as a customization group containing @var{members}. @var{symbol} does not need to be quoted. @var{doc} is the group documentation. @@ -71,7 +78,7 @@ 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. +documentation string. The following additional @var{keyword}'s are defined: @@ -99,7 +106,7 @@ If @var{symbol} is not already bound, initialize it to @var{value}. The following additional @var{keyword}'s are defined: @table @code -@item :type +@item :type @var{value} should be a widget type. @item :options @@ -115,7 +122,7 @@ Some predefined functions are: @item custom-initialize-set Use the @code{:set} method to initialize the variable. Do not initialize it if already bound. This is the default @code{:initialize} -method. +method. @item custom-initialize-default Always use @code{set-default} to initialize the variable, even if a @@ -128,10 +135,10 @@ method with the value returned by the @code{:get} method. @item custom-initialize-changed Like @code{custom-initialize-reset}, but use @code{set-default} to initialize the variable if it is not bound and has not been set -already. +already. @end table -@item :set +@item :set @var{value} should be a function to set the value of the symbol. It takes two arguments, the symbol to set and the value to give it. The default is @code{set-default}. @@ -144,7 +151,7 @@ value for that symbol. The default is @code{default-value}. @item :require @var{value} should be a feature symbol. Each feature will be required when the `defcustom' is evaluated, or when Emacs is started if the user -has saved this option. +has saved this option. @end table @@ -158,13 +165,13 @@ 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 member of a hook. +useful as a member 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." +member. For other types of variables, the effect is undefined." @end defun @node Declaring Faces, Usage for Package Authors, Declaring Variables, Top @@ -173,7 +180,7 @@ member. For other types variables, the effect is undefined." Faces are declared with @code{defface}. -@defun defface face spec doc [keyword value]... +@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. @@ -211,7 +218,7 @@ Should be one of @code{color}, @code{grayscale}, or @code{mono}. (what color is used for the background text)@* Should be one of @code{light} or @code{dark}. @end table - + Internally, custom uses the symbol property @code{face-defface-spec} for the program specified default face properties, @code{saved-face} for properties saved by the user, and @code{face-documentation} for the @@ -233,13 +240,13 @@ The top level group for the package should itself be member of one or more of the standard customization groups. There exists a group for each @emph{finder} keyword. Press @kbd{C-h p} to see a list of finder keywords, and add you group to each of them, using the @code{:group} -keyword. +keyword. @node Utilities, The Init File, Usage for Package Authors, Top @comment node-name, next, previous, up @section Utilities -These utilities can come in handy when adding customization support. +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 @@ -262,7 +269,7 @@ To the custom option @var{symbol} add the dependency @var{load}. @defun customize-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. +If optional @var{name} is given, use that as the name of the menu. Otherwise the menu will be named `Customize'. The menu is in a format applicable to @code{easy-menu-define}. @end defun @@ -271,19 +278,31 @@ The menu is in a format applicable to @code{easy-menu-define}. @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. If you use another file, you must explicitly load it yourself. -The two functions will initialize variables and faces as you have -specified. +Customizations are saved to the file specified by @code{custom-file}, as +calls to @code{custom-set-variables} and @code{custom-set-faces}. + +When you save customizations, the current implementation removes the +calls to @code{custom-set-variables} and @code{custom-set-faces}, and +replaces them with code generated on the basis of the current +customization state in Emacs. + +By default @code{custom-file} is your @file{.emacs} file (for GNU Emacs +and older XEmacs) and is @file{custom.el} in the same directory as +@file{init.el} (in XEmacs 21.4 and later). If you use another file, you +must explicitly load it yourself. + +As of XEmacs 21.4.7, when @code{custom-file} is present, it is loaded +@emph{after} @file{init.el}. This is likely to change in the future, +because (1) actions in @file{init.el} often would like to depend on +customizations for consistent appearance and (2) Custom is quite brutal +about enforcing its idea of the correct values at initialization. @node Wishlist, , The Init File, Top @comment node-name, next, previous, up @section Wishlist @itemize @bullet -@item +@item Better support for keyboard operations in the customize buffer. @item @@ -294,7 +313,7 @@ convincing example. @item Add an `examples' section, with explained examples of custom type -definitions. +definitions. @item Support selectable color themes. I.e., change many faces by setting one @@ -309,13 +328,13 @@ Make it possible to append to `choice', `radio', and `set' options. @item Ask whether set or modified variables should be saved in -@code{kill-buffer-hook}. +@code{kill-buffer-hook}. Ditto for @code{kill-emacs-query-functions}. @item Command to check if there are any customization options that -does not belong to an existing group. +does not belong to an existing group. @item Optionally disable the point-cursor and instead highlight the selected @@ -328,13 +347,9 @@ Explain why it is necessary that all choices have different default values. @item -Make it possible to include a comment/remark/annotation when saving an -option. - -@item Add some direct support for meta variables, i.e. make it possible to specify that this variable should be reset when that variable is -changed. +changed. @item Add tutorial. @@ -375,7 +390,7 @@ Add an easy way to display the standard settings when an item is modified. @item See if it is feasible to scan files for customization information -instead of loading them, +instead of loading them, @item Add hint message when user push a non-pushable tag. @@ -389,11 +404,11 @@ Use checkboxes and radio buttons in the state menus. @item Add option to hide @samp{[hide]} for short options. Default, on. -@item +@item Add option to hide @samp{[state]} for options with their standard settings. -@item +@item There should be a way to specify site defaults for user options. @item