GNU Info

(elisp)Group Definitions

---

Next: Variable Definitions Prev: Common Keywords Up: Customization

---

Enter node , (file) or (file)node

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 (Note: Variable Definitions).

     In addition to the common keywords (Note: Common 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.