14.2 Defining Custom Groups

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 :group keyword.

The way to declare new customization groups is with defgroup.

Macro: defgroup group members doc [keyword value]...

Declare group as a customization group containing members. Do not quote the symbol group. The argument doc specifies the documentation string for the group. It should not start with a `*' as in defcustom; that convention is for variables only.

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 :group keyword when defining those members.

If you want to specify group members through members, each element should have the form (name widget). Here name is a symbol, and widget is a widget type for editing that symbol. Useful widgets are custom-variable for a variable, custom-face for a face, and custom-group for a group.

When a new group is introduced into Emacs, use this keyword in defgroup:

:version version

This option specifies that the group was first introduced in Emacs version version. The value version must be a string.

Tag the group with a version like this when it is introduced, rather than the individual members (see section 14.3 Defining Customization Variables).

In addition to the common keywords (see section 14.1 Common Item Keywords), you can also use this keyword in defgroup:

:prefix prefix

If the name of an item in the group starts with prefix, then the tag for that item is constructed (by default) by omitting prefix.

One group can have any number of prefixes.

The prefix-discarding feature is currently turned off, which means that :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 :prefix 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 :prefix should not be used in that case.

It should be possible to recheck all the customization groups, delete the :prefix specifications which give unclear results, and then turn this feature back on, if someone would like to do the work.