elisp: Common Keywords
14.1 Common Item Keywords
=========================
The customization declarations that we will describe in the next few
sections—‘defcustom’, ‘defgroup’, etc.—all accept keyword arguments
(
Constant Variables) for specifying various information. This
section describes keywords that apply to all types of customization
declarations.
All of these keywords, except ‘:tag’, can be used more than once in a
given item. Each use of the keyword has an independent effect. The
keyword ‘:tag’ is an exception because any given item can only display
one name.
‘:tag LABEL’
Use LABEL, a string, instead of the item’s name, to label the item
in customization menus and buffers. *Don’t use a tag which is
substantially different from the item’s real name; that would cause
confusion.*
‘:group GROUP’
Put this customization item in group GROUP. If this keyword is
missing from a customization item, it’ll be placed in the same
group that was last defined (in the current file).
When you use ‘:group’ in a ‘defgroup’, it makes the new group a
subgroup of GROUP.
If you use this keyword more than once, you can put a single item
into more than one group. Displaying any of those groups will show
this item. Please don’t overdo this, since the result would be
annoying.
‘:link LINK-DATA’
Include an external link after the documentation string for this
item. This is a sentence containing a button that references some
other documentation.
There are several alternatives you can use for LINK-DATA:
‘(custom-manual INFO-NODE)’
Link to an Info node; INFO-NODE is a string which specifies
the node name, as in ‘"(emacs)Top"’. The link appears as
‘[Manual]’ in the customization buffer and enters the built-in
Info reader on INFO-NODE.
‘(info-link INFO-NODE)’
Like ‘custom-manual’ except that the link appears in the
customization buffer with the Info node name.
‘(url-link URL)’
Link to a web page; URL is a string which specifies the URL.
The link appears in the customization buffer as URL and
invokes the WWW browser specified by
‘browse-url-browser-function’.
‘(emacs-commentary-link LIBRARY)’
Link to the commentary section of a library; LIBRARY is a
string which specifies the library name. Library
Headers.
‘(emacs-library-link LIBRARY)’
Link to an Emacs Lisp library file; LIBRARY is a string which
specifies the library name.
‘(file-link FILE)’
Link to a file; FILE is a string which specifies the name of
the file to visit with ‘find-file’ when the user invokes this
link.
‘(function-link FUNCTION)’
Link to the documentation of a function; FUNCTION is a string
which specifies the name of the function to describe with
‘describe-function’ when the user invokes this link.
‘(variable-link VARIABLE)’
Link to the documentation of a variable; VARIABLE is a string
which specifies the name of the variable to describe with
‘describe-variable’ when the user invokes this link.
‘(custom-group-link GROUP)’
Link to another customization group. Invoking it creates a
new customization buffer for GROUP.
You can specify the text to use in the customization buffer by
adding ‘:tag NAME’ after the first element of the LINK-DATA; for
example, ‘(info-link :tag "foo" "(emacs)Top")’ makes a link to the
Emacs manual which appears in the buffer as ‘foo’.
You can use this keyword more than once, to add multiple links.
‘:load FILE’
Load file FILE (a string) before displaying this customization item
(Loading). Loading is done with ‘load’, and only if the
file is not already loaded.
‘:require FEATURE’
Execute ‘(require 'FEATURE)’ when your saved customizations set the
value of this item. FEATURE should be a symbol.
The most common reason to use ‘:require’ is when a variable enables
a feature such as a minor mode, and just setting the variable won’t
have any effect unless the code which implements the mode is
loaded.
‘:version VERSION’
This keyword specifies that the item was first introduced in Emacs
version VERSION, or that its default value was changed in that
version. The value VERSION must be a string.
‘:package-version '(PACKAGE . VERSION)’
This keyword specifies that the item was first introduced in
PACKAGE version VERSION, or that its meaning or default value was
changed in that version. This keyword takes priority over
‘:version’.
PACKAGE should be the official name of the package, as a symbol
(e.g., ‘MH-E’). VERSION should be a string. If the package
PACKAGE is released as part of Emacs, PACKAGE and VERSION should
appear in the value of ‘customize-package-emacs-version-alist’.
Packages distributed as part of Emacs that use the ‘:package-version’
keyword must also update the ‘customize-package-emacs-version-alist’
variable.
-- Variable: customize-package-emacs-version-alist
This alist provides a mapping for the versions of Emacs that are
associated with versions of a package listed in the
‘:package-version’ keyword. Its elements are:
(PACKAGE (PVERSION . EVERSION)...)
For each PACKAGE, which is a symbol, there are one or more elements
that contain a package version PVERSION with an associated Emacs
version EVERSION. These versions are strings. For example, the
MH-E package updates this alist with the following:
(add-to-list 'customize-package-emacs-version-alist
'(MH-E ("6.0" . "22.1") ("6.1" . "22.1") ("7.0" . "22.1")
("7.1" . "22.1") ("7.2" . "22.1") ("7.3" . "22.1")
("7.4" . "22.1") ("8.0" . "22.1")))
The value of PACKAGE needs to be unique and it needs to match the
PACKAGE value appearing in the ‘:package-version’ keyword. Since
the user might see the value in an error message, a good choice is
the official name of the package, such as MH-E or Gnus.
Info Catalog
elisp: Customization
elisp: Group Definitions