emacs: logically group def{custom,face}s

To allow for expansion whilst keeping everything tidy and organized,
move all defcustom/defface variables to the following subgroups,
defined in notmuch-lib.el:

- Hello
- Search
- Show
- Send
- Crypto
- Hooks
- External Commands
- Appearance

As an added benefit, defcustom keyword args are now consistently
ordered as they appear @ defcustom's docstring (OCD much?).

Proper defgroup docstrings and various other improvements
by courtesy of Austin Clements.

9 files changed, 124 insertions, 69 deletions

diff --git a/emacs/notmuch-address.el b/emacs/notmuch-address.el
index 8eba7a0b..2e8b8402 100644
--- a/emacs/notmuch-address.el
+++ b/emacs/notmuch-address.el
@@ -28,7 +28,8 @@
 single argument and output a list of possible matches, one per
 line."
   :type 'string
-  :group 'notmuch)
+  :group 'notmuch-send
+  :group 'notmuch-external)
 
 (defvar notmuch-address-message-alist-member
   '("^\\(Resent-\\)?\\(To\\|B?Cc\\|Reply-To\\|From\\|Mail-Followup-To\\|Mail-Copies-To\\):"
diff --git a/emacs/notmuch-crypto.el b/emacs/notmuch-crypto.el
index ac300987..80ac350e 100644
--- a/emacs/notmuch-crypto.el
+++ b/emacs/notmuch-crypto.el
@@ -34,38 +34,44 @@ The effect of setting this variable can be seen temporarily by
 providing a prefix when viewing a signed or encrypted message, or
 by providing a prefix when reloading the message in notmuch-show
 mode."
-  :group 'notmuch
-  :type 'boolean)
+  :type 'boolean
+  :group 'notmuch-crypto)
 
 (defface notmuch-crypto-part-header
   '((t (:foreground "blue")))
   "Face used for crypto parts headers."
-  :group 'notmuch)
+  :group 'notmuch-crypto
+  :group 'notmuch-faces)
 
 (defface notmuch-crypto-signature-good
   '((t (:background "green" :foreground "black")))
   "Face used for good signatures."
-  :group 'notmuch)
+  :group 'notmuch-crypto
+  :group 'notmuch-faces)
 
 (defface notmuch-crypto-signature-good-key
   '((t (:background "orange" :foreground "black")))
   "Face used for good signatures."
-  :group 'notmuch)
+  :group 'notmuch-crypto
+  :group 'notmuch-faces)
 
 (defface notmuch-crypto-signature-bad
   '((t (:background "red" :foreground "black")))
   "Face used for bad signatures."
-  :group 'notmuch)
+  :group 'notmuch-crypto
+  :group 'notmuch-faces)
 
 (defface notmuch-crypto-signature-unknown
   '((t (:background "red" :foreground "black")))
   "Face used for signatures of unknown status."
-  :group 'notmuch)
+  :group 'notmuch-crypto
+  :group 'notmuch-faces)
 
 (defface notmuch-crypto-decryption
   '((t (:background "purple" :foreground "black")))
   "Face used for encryption/decryption status messages."
-  :group 'notmuch)
+  :group 'notmuch-crypto
+  :group 'notmuch-faces)
 
 (define-button-type 'notmuch-crypto-status-button-type
   'action (lambda (button) (message (button-get button 'help-echo)))
diff --git a/emacs/notmuch-hello.el b/emacs/notmuch-hello.el
index 02017ce5..bff95acc 100644
--- a/emacs/notmuch-hello.el
+++ b/emacs/notmuch-hello.el
@@ -35,12 +35,12 @@
 (defcustom notmuch-recent-searches-max 10
   "The number of recent searches to store and display."
   :type 'integer
-  :group 'notmuch)
+  :group 'notmuch-hello)
 
 (defcustom notmuch-show-empty-saved-searches nil
   "Should saved searches with no messages be listed?"
   :type 'boolean
-  :group 'notmuch)
+  :group 'notmuch-hello)
 
 (defun notmuch-sort-saved-searches (alist)
   "Generate an alphabetically sorted saved searches alist."
@@ -60,7 +60,7 @@ alist to be used."
 		 (const :tag "Sort alphabetically" notmuch-sort-saved-searches)
 		 (function :tag "Custom sort function"
 			   :value notmuch-sort-saved-searches))
-  :group 'notmuch)
+  :group 'notmuch-hello)
 
 (defvar notmuch-hello-indent 4
   "How much to indent non-headers.")
@@ -68,12 +68,12 @@ alist to be used."
 (defcustom notmuch-show-logo t
   "Should the notmuch logo be shown?"
   :type 'boolean
-  :group 'notmuch)
+  :group 'notmuch-hello)
 
 (defcustom notmuch-show-all-tags-list nil
   "Should all tags be shown in the notmuch-hello view?"
   :type 'boolean
-  :group 'notmuch)
+  :group 'notmuch-hello)
 
 (defcustom notmuch-hello-tag-list-make-query nil
   "Function or string to generate queries for the all tags list.
@@ -89,12 +89,12 @@ should return a filter for that tag, or nil to hide the tag."
 		 (string :tag "Custom filter"
 			 :value "tag:unread")
 		 (function :tag "Custom filter function"))
-  :group 'notmuch)
+  :group 'notmuch-hello)
 
 (defcustom notmuch-hello-hide-tags nil
   "List of tags to be hidden in the \"all tags\"-section."
   :type '(repeat string)
-  :group 'notmuch)
+  :group 'notmuch-hello)
 
 (defface notmuch-hello-logo-background
   '((((class color)
@@ -104,7 +104,8 @@ should return a filter for that tag, or nil to hide the tag."
       (background light))
      (:background "white")))
   "Background colour for the notmuch logo."
-  :group 'notmuch)
+  :group 'notmuch-hello
+  :group 'notmuch-faces)
 
 (defcustom notmuch-column-control t
   "Controls the number of columns for saved searches/tags in notmuch view.
@@ -126,11 +127,11 @@ So:
   30.
 - if you don't want to worry about all of this nonsense, leave
   this set to `t'."
-  :group 'notmuch
   :type '(choice
 	  (const :tag "Automatically calculated" t)
 	  (integer :tag "Number of characters")
-	  (float :tag "Fraction of window")))
+	  (float :tag "Fraction of window"))
+  :group 'notmuch-hello)
 
 (defcustom notmuch-hello-thousands-separator " "
   "The string used as a thousands separator.
@@ -138,18 +139,20 @@ So:
 Typically \",\" in the US and UK and \".\" or \" \" in Europe.
 The latter is recommended in the SI/ISO 31-0 standard and by the
 International Bureau of Weights and Measures."
-  :group 'notmuch
-  :type 'string)
+  :type 'string
+  :group 'notmuch-hello)
 
 (defcustom notmuch-hello-mode-hook nil
   "Functions called after entering `notmuch-hello-mode'."
-  :group 'notmuch
-  :type 'hook)
+  :type 'hook
+  :group 'notmuch-hello
+  :group 'notmuch-hooks)
 
 (defcustom notmuch-hello-refresh-hook nil
   "Functions called after updating a `notmuch-hello' buffer."
   :type 'hook
-  :group 'notmuch)
+  :group 'notmuch-hello
+  :group 'notmuch-hooks)
 
 (defvar notmuch-hello-url "http://notmuchmail.org"
   "The `notmuch' web site.")
diff --git a/emacs/notmuch-lib.el b/emacs/notmuch-lib.el
index 0f856bf0..92425373 100644
--- a/emacs/notmuch-lib.el
+++ b/emacs/notmuch-lib.el
@@ -28,17 +28,50 @@
   "Notmuch mail reader for Emacs."
   :group 'mail)
 
+(defgroup notmuch-hello nil
+  "Overview of saved searches, tags, etc."
+  :group 'notmuch)
+
+(defgroup notmuch-search nil
+  "Searching and sorting mail."
+  :group 'notmuch)
+
+(defgroup notmuch-show nil
+  "Showing messages and threads."
+  :group 'notmuch)
+
+(defgroup notmuch-send nil
+  "Sending messages from Notmuch."
+  :group 'notmuch
+  :group 'message)
+
+(defgroup notmuch-crypto nil
+  "Processing and display of cryptographic MIME parts."
+  :group 'notmuch)
+
+(defgroup notmuch-hooks nil
+  "Running custom code on well-defined occasions."
+  :group 'notmuch)
+
+(defgroup notmuch-external nil
+  "Running external commands from within Notmuch."
+  :group 'notmuch)
+
+(defgroup notmuch-faces nil
+  "Graphical attributes for displaying text"
+  :group 'notmuch)
+
 (defcustom notmuch-search-oldest-first t
   "Show the oldest mail first when searching."
   :type 'boolean
-  :group 'notmuch)
+  :group 'notmuch-search)
 
 ;;
 
 (defcustom notmuch-saved-searches nil
   "A list of saved searches to display."
   :type '(alist :key-type string :value-type string)
-  :group 'notmuch)
+  :group 'notmuch-hello)
 
 (defvar notmuch-folders nil
   "Deprecated name for what is now known as `notmuch-saved-searches'.")
diff --git a/emacs/notmuch-maildir-fcc.el b/emacs/notmuch-maildir-fcc.el
index 6fbf82d2..dcfbc4b3 100644
--- a/emacs/notmuch-maildir-fcc.el
+++ b/emacs/notmuch-maildir-fcc.el
@@ -51,13 +51,13 @@ the database.path option in the notmuch configuration file).
 You will be prompted to create the directory if it does not exist
 yet when sending a mail."
 
- :require 'notmuch-fcc-initialization
- :group 'notmuch
  :type '(choice
 	 (const :tag "No FCC header" nil)
 	 (string :tag "A single folder")
 	 (repeat :tag "A folder based on the From header"
-		 (cons regexp (string :tag "Folder")))))
+		 (cons regexp (string :tag "Folder"))))
+ :require 'notmuch-fcc-initialization
+ :group 'notmuch-send)
 
 (defun notmuch-fcc-initialization ()
   "If notmuch-fcc-directories is set,
diff --git a/emacs/notmuch-message.el b/emacs/notmuch-message.el
index 08e5b174..264a5b9b 100644
--- a/emacs/notmuch-message.el
+++ b/emacs/notmuch-message.el
@@ -31,7 +31,7 @@ For example, if you wanted to add a \"replied\" tag and remove
 the \"inbox\" and \"todo\", you would set
     (\"replied\" \"-inbox\" \"-todo\"\)"
   :type 'list
-  :group 'notmuch)
+  :group 'notmuch-send)
 
 (defun notmuch-message-mark-replied ()
   ;; get the in-reply-to header and parse it for the message id.
diff --git a/emacs/notmuch-mua.el b/emacs/notmuch-mua.el
index d8ab822a..023645e3 100644
--- a/emacs/notmuch-mua.el
+++ b/emacs/notmuch-mua.el
@@ -28,25 +28,26 @@
 
 (defcustom notmuch-mua-send-hook '(notmuch-mua-message-send-hook)
   "Hook run before sending messages."
-  :group 'notmuch
-  :type 'hook)
+  :type 'hook
+  :group 'notmuch-send
+  :group 'notmuch-hooks)
 
 (defcustom notmuch-mua-user-agent-function 'notmuch-mua-user-agent-full
   "Function used to generate a `User-Agent:' string. If this is
 `nil' then no `User-Agent:' will be generated."
-  :group 'notmuch
   :type '(choice (const :tag "No user agent string" nil)
 		 (const :tag "Full" notmuch-mua-user-agent-full)
 		 (const :tag "Notmuch" notmuch-mua-user-agent-notmuch)
 		 (const :tag "Emacs" notmuch-mua-user-agent-emacs)
 		 (function :tag "Custom user agent function"
-			   :value notmuch-mua-user-agent-full)))
+			   :value notmuch-mua-user-agent-full))
+  :group 'notmuch-send)
 
 (defcustom notmuch-mua-hidden-headers '("^User-Agent:")
   "Headers that are added to the `message-mode' hidden headers
 list."
-  :group 'notmuch
-  :type '(repeat string))
+  :type '(repeat string)
+  :group 'notmuch-send)
 
 ;;
 
@@ -157,16 +158,16 @@ OTHER-ARGS are passed through to `message-mail'."
 
 If this variable is left unset, then a list will be constructed from the
 name and addresses configured in the notmuch configuration file."
-  :group 'notmuch
-  :type '(repeat string))
+  :type '(repeat string)
+  :group 'notmuch-send)
 
 (defcustom notmuch-always-prompt-for-sender nil
   "Always prompt for the From: address when composing or forwarding a message.
 
 This is not taken into account when replying to a message, because in that case
 the From: header is already filled in by notmuch."
-  :group 'notmuch
-  :type 'boolean)
+  :type 'boolean
+  :group 'notmuch-send)
 
 (defvar notmuch-mua-sender-history nil)
 
diff --git a/emacs/notmuch-show.el b/emacs/notmuch-show.el
index 03c1f6b7..fc134627 100644
--- a/emacs/notmuch-show.el
+++ b/emacs/notmuch-show.el
@@ -47,8 +47,8 @@ For an open message, all of these headers will be made visible
 according to `notmuch-message-headers-visible' or can be toggled
 with `notmuch-show-toggle-headers'. For a closed message, only
 the first header in the list will be visible."
-  :group 'notmuch
-  :type '(repeat string))
+  :type '(repeat string)
+  :group 'notmuch-show)
 
 (defcustom notmuch-message-headers-visible t
   "Should the headers be visible by default?
@@ -58,13 +58,13 @@ If this value is non-nil, then all of the headers defined in
 of each message. Otherwise, these headers will be hidden and
 `notmuch-show-toggle-headers' can be used to make the visible for
 any given message."
-  :group 'notmuch
-  :type 'boolean)
+  :type 'boolean
+  :group 'notmuch-show)
 
 (defcustom notmuch-show-relative-dates t
   "Display relative dates in the message summary line."
-  :group 'notmuch
-  :type 'boolean)
+  :type 'boolean
+  :group 'notmuch-show)
 
 (defvar notmuch-show-markup-headers-hook '(notmuch-show-colour-headers)
   "A list of functions called to decorate the headers listed in
@@ -72,27 +72,29 @@ any given message."
 
 (defcustom notmuch-show-hook nil
   "Functions called after populating a `notmuch-show' buffer."
-  :group 'notmuch
-  :type 'hook)
+  :type 'hook
+  :group 'notmuch-show
+  :group 'notmuch-hooks)
 
 (defcustom notmuch-show-insert-text/plain-hook '(notmuch-wash-wrap-long-lines
 						 notmuch-wash-tidy-citations
 						 notmuch-wash-elide-blank-lines
 						 notmuch-wash-excerpt-citations)
   "Functions used to improve the display of text/plain parts."
-  :group 'notmuch
   :type 'hook
   :options '(notmuch-wash-convert-inline-patch-to-part
 	     notmuch-wash-wrap-long-lines
 	     notmuch-wash-tidy-citations
 	     notmuch-wash-elide-blank-lines
-	     notmuch-wash-excerpt-citations))
+	     notmuch-wash-excerpt-citations)
+  :group 'notmuch-show
+  :group 'notmuch-hooks)
 
 ;; Mostly useful for debugging.
 (defcustom notmuch-show-all-multipart/alternative-parts t
   "Should all parts of multipart/alternative parts be shown?"
-  :group 'notmuch
-  :type 'boolean)
+  :type 'boolean
+  :group 'notmuch-show)
 
 (defcustom notmuch-show-indent-messages-width 1
   "Width of message indentation in threads.
@@ -101,14 +103,14 @@ Messages are shown indented according to their depth in a thread.
 This variable determines the width of this indentation measured
 in number of blanks.  Defaults to `1', choose `0' to disable
 indentation."
-  :group 'notmuch
-  :type 'integer)
+  :type 'integer
+  :group 'notmuch-show)
 
 (defcustom notmuch-show-indent-multipart nil
   "Should the sub-parts of a multipart/* part be indented?"
   ;; dme: Not sure which is a good default.
-  :group 'notmuch
-  :type 'boolean)
+  :type 'boolean
+  :group 'notmuch-show)
 
 (defmacro with-current-notmuch-show-message (&rest body)
   "Evaluate body with current buffer set to the text of current message"
diff --git a/emacs/notmuch.el b/emacs/notmuch.el
index ef4dcc78..3602361b 100644
--- a/emacs/notmuch.el
+++ b/emacs/notmuch.el
@@ -70,7 +70,7 @@ For example:
 	(setq notmuch-search-result-format \(\(\"authors\" . \"%-40s\"\)
 					     \(\"subject\" . \"%s\"\)\)\)"
   :type '(alist :key-type (string) :value-type (string))
-  :group 'notmuch)
+  :group 'notmuch-search)
 
 (defvar notmuch-query-history nil
   "Variable to store minibuffer history for notmuch queries")
@@ -199,7 +199,8 @@ For a mouse binding, return nil."
   "List of functions to call when notmuch displays the search results."
   :type 'hook
   :options '(hl-line-mode)
-  :group 'notmuch)
+  :group 'notmuch-search
+  :group 'notmuch-hooks)
 
 (defvar notmuch-search-mode-map
   (let ((map (make-sparse-keymap)))
@@ -307,27 +308,32 @@ For a mouse binding, return nil."
  '((((class color) (background light)) (:background "#f0f0f0"))
    (((class color) (background dark)) (:background "#303030")))
  "Face for the single-line message summary in notmuch-show-mode."
- :group 'notmuch)
+ :group 'notmuch-show
+ :group 'notmuch-faces)
 
 (defface notmuch-search-date
   '((t :inherit default))
   "Face used in search mode for dates."
-  :group 'notmuch)
+  :group 'notmuch-search
+  :group 'notmuch-faces)
 
 (defface notmuch-search-count
   '((t :inherit default))
   "Face used in search mode for the count matching the query."
-  :group 'notmuch)
+  :group 'notmuch-search
+  :group 'notmuch-faces)
 
 (defface notmuch-search-subject
   '((t :inherit default))
   "Face used in search mode for subjects."
-  :group 'notmuch)
+  :group 'notmuch-search
+  :group 'notmuch-faces)
 
 (defface notmuch-search-matching-authors
   '((t :inherit default))
   "Face used in search mode for authors matching the query."
-  :group 'notmuch)
+  :group 'notmuch-search
+  :group 'notmuch-faces)
 
 (defface notmuch-search-non-matching-authors
   '((((class color)
@@ -339,7 +345,8 @@ For a mouse binding, return nil."
     (t
      (:italic t)))
   "Face used in search mode for authors not matching the query."
-  :group 'notmuch)
+  :group 'notmuch-search
+  :group 'notmuch-faces)
 
 (defface notmuch-tag-face
   '((((class color)
@@ -351,7 +358,8 @@ For a mouse binding, return nil."
     (t
      (:bold t)))
   "Face used in search mode face for tags."
-  :group 'notmuch)
+  :group 'notmuch-search
+  :group 'notmuch-faces)
 
 (defun notmuch-search-mode ()
   "Major mode displaying results of a notmuch search.
@@ -502,7 +510,7 @@ the messages that are about to be tagged"
 
   :type 'hook
   :options '(hl-line-mode)
-  :group 'notmuch)
+  :group 'notmuch-hooks)
 
 (defcustom notmuch-after-tag-hook nil
   "Hooks that are run after tags of a message are modified.
@@ -513,7 +521,7 @@ a list of strings of the form \"+TAG\" or \"-TAG\".
 the messages that were tagged"
   :type 'hook
   :options '(hl-line-mode)
-  :group 'notmuch)
+  :group 'notmuch-hooks)
 
 (defun notmuch-search-set-tags (tags)
   (save-excursion
@@ -669,7 +677,8 @@ attributes overriding earlier. A message having both \"delete\"
 and \"unread\" tags with the above settings would have a green
 foreground and blue background."
   :type '(alist :key-type (string) :value-type (custom-face-edit))
-  :group 'notmuch)
+  :group 'notmuch-search
+  :group 'notmuch-faces)
 
 (defun notmuch-search-color-line (start end line-tag-list)
   "Colorize lines in `notmuch-show' based on tags."
@@ -1004,7 +1013,7 @@ Note that the recommended way of achieving the same is using
   :type '(choice (const :tag "notmuch new" nil)
 		 (const :tag "Disabled" "")
 		 (string :tag "Custom script"))
-  :group 'notmuch)
+  :group 'notmuch-external)
 
 (defun notmuch-poll ()
   "Run \"notmuch new\" or an external script to import mail.