Each Emacs Lisp package should have one main customization group which contains all the options, faces and other groups in the package. If the package has a small number of options and faces, use just one group and put everything in it. When there are more than twelve or so options and faces, then you should structure them into subgroups, and put the subgroups under the package's main customization group. It is OK to put some of the options and faces in the package's main group alongside the subgroups.
The package's main or only group should be a member of one or more of
the standard customization groups. (To display the full list of them,
use M-x customize.) Choose one or more of them (but not too
many), and add your group to each of them using the
The way to declare new customization groups is with
Declare group as a customization group containing members. Do not quote the symbol group. The argument doc specifies the documentation string for the group.
The argument members is a list specifying an initial set of customization items to be members of the group. However, most often members is
nil, and you specify the group's members by using the
:groupkeyword when defining those members.
If you want to specify group members through members, each element should have the form
). Here name is a symbol, and widget is a widget type for editing that symbol. Useful widgets are
custom-variablefor a variable,
custom-facefor a face, and
custom-groupfor a group.
When you introduce a new group into Emacs, use the
:versionkeyword in the
defgroup; then you need not use it for the individual members of the group.
In addition to the common keywords (see Common Keywords), you can also use this keyword in
The prefix-discarding feature is currently turned off, which means
:prefix currently has no effect. We did this because we
found that discarding the specified prefixes often led to confusing
names for options. This happened because the people who wrote the
defgroup definitions for various groups added
keywords whenever they make logical sense—that is, whenever the
variables in the library have a common prefix.
In order to obtain good results with
:prefix, it would be
necessary to check the specific effects of discarding a particular
prefix, given the specific items in a group and their names and
documentation. If the resulting text is not clear, then
should not be used in that case.
It should be possible to recheck all the customization groups, delete
:prefix specifications which give unclear results, and then
turn this feature back on, if someone would like to do the work.