Tweaks to Customize interface. Set custom-reset-button-menu to t.

* cus-edit.el (custom-commands, custom-reset-menu)
(Custom-reset-standard): Tweak labels.
(custom-reset-button-menu): Change default to t.
(custom-buffer-create-internal): For the custom-reset-button-menu
case, put the revert button first.
(custom-group-subtitle): New face.
(custom-group-value-create): Align docstring to a specific column.

* wid-edit.el (widget-documentation-link-add): Don't handle
indentation in this function.
(widget-documentation-string-indent-to): New function.
(widget-documentation-string-value-create): Use it.

* autorevert.el (auto-revert):
* epg-config.el (epg):
* ibuffer.el (ibuffer):
* mpc.el (mpc):
* ses.el (ses):
* eshell/eshell.el (eshell):
* net/ange-ftp.el (ange-ftp):
* progmodes/ebnf2ps.el (postscript):
* progmodes/flymake.el (flymake):
* progmodes/prolog.el (prolog):
* progmodes/verilog-mode.el (verilog-mode):
* progmodes/which-func.el (which-func):
* textmodes/picture.el (picture):
* textmodes/tildify.el (tildify):
* vc/ediff.el (ediff): Tweak defgroups to improve presentation in
customization buffers.

24 files changed, 165 insertions, 111 deletions

diff --git a/etc/NEWS b/etc/NEWS
index b2c487ba15b..298a87c1f08 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -74,7 +74,9 @@ character when doing minibuffer filename prompts.
 
 * Changes in Specialized Modes and Packages in Emacs 24.2
 
-** which-function-mode now applies to all applicable major modes by default.
+** Customize
+
+*** `custom-reset-button-menu' now defaults to t.
 
 ** erc will look up server/channel names via auth-source and use the
 channel keys found, if any.
@@ -87,6 +89,8 @@ closing brackets to be aligned with the line of the opening bracket.
 
 ** FIXME something happened to ses.el, 2012-04-17.
 
+** which-function-mode now applies to all applicable major modes by default.
+
 ** Obsolete packages:
 
 *** mailpost.el
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index d5576370727..14a83de342a 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,36 @@
+2012-04-22  Chong Yidong  <cyd@gnu.org>
+
+        * cus-edit.el (custom-commands, custom-reset-menu)
+        (Custom-reset-standard): Tweak labels.
+        (custom-reset-button-menu): Change default to t.
+        (custom-buffer-create-internal): For the custom-reset-button-menu
+        case, put the revert button first.
+        (custom-group-subtitle): New face.
+        (custom-group-value-create): Align docstring to a specific column.
+
+        * wid-edit.el (widget-documentation-link-add): Don't handle
+        indentation in this function.
+        (widget-documentation-string-indent-to): New function.
+        (widget-documentation-string-value-create): Use it.
+
+        * autorevert.el (auto-revert):
+        * epg-config.el (epg):
+        * ibuffer.el (ibuffer):
+        * mpc.el (mpc):
+        * ses.el (ses):
+        * eshell/eshell.el (eshell):
+        * net/ange-ftp.el (ange-ftp):
+        * progmodes/ebnf2ps.el (postscript):
+        * progmodes/flymake.el (flymake):
+        * progmodes/prolog.el (prolog):
+        * progmodes/verilog-mode.el (verilog-mode):
+        * progmodes/which-func.el (which-func):
+        * term/xterm.el (xterm):
+        * textmodes/picture.el (picture):
+        * textmodes/tildify.el (tildify):
+        * vc/ediff.el (ediff): Tweak defgroups to improve presentation in
+        customization buffers.
+
 2012-04-22  Alan Mackenzie  <acm@muc.de>
 
         * progmodes/cc-engine.el (c-append-lower-brace-pair-to-state-cache):
diff --git a/lisp/autorevert.el b/lisp/autorevert.el
index e0bde7c6dc5..11005f49f44 100644
--- a/lisp/autorevert.el
+++ b/lisp/autorevert.el
@@ -104,9 +104,8 @@
 
 (defgroup auto-revert nil
   "Revert individual buffers when files on disk change.
-
-Auto-Revert Mode can be activated for individual buffer.
-Global Auto-Revert Mode applies to all buffers."
+Auto-Revert mode enables auto-revert in individual buffers.
+Global Auto-Revert mode does so in all buffers."
   :group 'files
   :group 'convenience)
 
diff --git a/lisp/calc/calc.el b/lisp/calc/calc.el
index 5224d1aa4f8..c7cea5f0aef 100644
--- a/lisp/calc/calc.el
+++ b/lisp/calc/calc.el
@@ -222,7 +222,7 @@
 
 
 (defgroup calc nil
-  "GNU Calc."
+  "Advanced desk calculator and mathematical tool."
   :prefix "calc-"
   :tag    "Calc"
   :group  'applications)
diff --git a/lisp/cus-edit.el b/lisp/cus-edit.el
index 4ed72be06fb..d20403ad341 100644
--- a/lisp/cus-edit.el
+++ b/lisp/cus-edit.el
@@ -223,7 +223,7 @@
   :group 'emacs)
 
 (defgroup languages nil
-  "Specialized modes for editing programming languages."
+  "Modes for editing programming languages."
   :group 'programming)
 
 (defgroup lisp nil
@@ -255,7 +255,7 @@
   :group 'applications)
 
 (defgroup news nil
-  "Support for netnews reading and posting."
+  "Reading and posting to newsgroups."
   :link '(custom-manual "(gnus)")
   :group 'applications)
 
@@ -297,7 +297,7 @@
   :group 'environment)
 
 (defgroup unix nil
-  "Front-ends/assistants for, or emulators of, UNIX features."
+  "Interfaces, assistants, and emulators for UNIX features."
   :group 'environment)
 
 (defgroup i18n nil
@@ -544,12 +544,6 @@ WIDGET is the widget to apply the filter entries of MENU on."
            (erase-buffer)
            (princ symbol (current-buffer))
            (goto-char (point-min))
-           ;; FIXME: Boolean variables are not predicates, so they shouldn't
-           ;; end with `-p'.  -stef
-           ;; (when (and (eq (get symbol 'custom-type) 'boolean)
-           ;;         (re-search-forward "-p\\'" nil t))
-           ;;   (replace-match "" t t)
-           ;;   (goto-char (point-min)))
            (if custom-unlispify-remove-prefixes
                (let ((prefixes custom-prefix-list)
                      prefix)
@@ -732,26 +726,26 @@ groups after non-groups, if nil do not order groups at all."
 ;; `custom-buffer-create-internal' if `custom-buffer-verbose-help' is non-nil.
 
 (defvar custom-commands
-  '((" Set for current session " Custom-set t
-     "Apply all settings in this buffer to the current session"
+  '((" Apply " Custom-set t
+     "Apply settings (for the current session only)"
      "index"
      "Apply")
-    (" Save for future sessions " Custom-save
+    (" Apply and Save " Custom-save
      (or custom-file user-init-file)
-     "Apply all settings in this buffer and save them for future Emacs sessions."
+     "Apply settings and save for future sessions."
      "save"
      "Save")
-    (" Undo edits " Custom-reset-current t
-     "Restore all settings in this buffer to reflect their current values."
+    (" Undo Edits " Custom-reset-current t
+     "Restore customization buffer to reflect existing settings."
      "refresh"
      "Undo")
-    (" Reset to saved " Custom-reset-saved t
-     "Restore all settings in this buffer to their saved values (if any)."
+    (" Reset Customizations " Custom-reset-saved t
+     "Undo any settings applied only for the current session."
      "undo"
      "Reset")
-    (" Erase customizations " Custom-reset-standard
+    (" Erase Customizations " Custom-reset-standard
      (or custom-file user-init-file)
-     "Un-customize all settings in this buffer and save them with standard values."
+     "Un-customize settings in this and future sessions."
      "delete"
      "Uncustomize")
     (" Help for Customize " Custom-help t
@@ -766,9 +760,9 @@ groups after non-groups, if nil do not order groups at all."
   (info "(emacs)Easy Customization"))
 
 (defvar custom-reset-menu
-  '(("Undo Edits" . Custom-reset-current)
-    ("Reset to Saved" . Custom-reset-saved)
-    ("Erase Customizations (use standard values)" . Custom-reset-standard))
+  '(("Undo Edits in Customization Buffer" . Custom-reset-current)
+    ("Revert This Session's Customizations" . Custom-reset-saved)
+    ("Erase Customizations" . Custom-reset-standard))
   "Alist of actions for the `Reset' button.
 The key is a string containing the name of the action, the value is a
 Lisp function taking the widget as an element which will be called
@@ -901,7 +895,8 @@ making them as if they had never been customized at all."
             (memq (widget-get widget :custom-state)
                   '(modified set changed saved rogue))
             (widget-apply widget :custom-mark-to-reset-standard)))
-     "Erase all customizations for settings in this buffer? " t)
+     "The settings will revert to their default values, in this
+and future sessions.  Really erase customizations? " t)
     (custom-reset-standard-save-and-update)))
 
 ;;; The Customize Commands
@@ -1552,11 +1547,12 @@ that option."
   (switch-to-buffer-other-window (custom-get-fresh-buffer name))
   (custom-buffer-create-internal options description))
 
-(defcustom custom-reset-button-menu nil
+(defcustom custom-reset-button-menu t
   "If non-nil, only show a single reset button in customize buffers.
 This button will have a menu with all three reset operations."
   :type 'boolean
-  :group 'custom-buffer)
+  :group 'custom-buffer
+  :version "24.2")
 
 (defcustom custom-buffer-verbose-help t
   "If non-nil, include explanatory text in the customization buffer."
@@ -1651,29 +1647,30 @@ or a regular expression.")
     ;; So now the buttons are always inserted in the buffer.  (Bug#1326)
     (if custom-buffer-verbose-help
         (widget-insert "
- Operate on all settings in this buffer:\n"))
+Operate on all settings in this buffer:\n"))
     (let ((button (lambda (tag action active help _icon _label)
                     (widget-insert " ")
                     (if (eval active)
                         (widget-create 'push-button :tag tag
                                        :help-echo help :action action))))
           (commands custom-commands))
-      (apply button (pop commands)) ; Set for current session
-      (apply button (pop commands)) ; Save for future sessions
       (if custom-reset-button-menu
           (progn
-            (widget-insert " ")
             (widget-create 'push-button
-                           :tag "Reset buffer"
+                           :tag " Revert... "
                            :help-echo "Show a menu with reset operations."
                            :mouse-down-action 'ignore
-                           :action 'custom-reset))
+                           :action 'custom-reset)
+            (apply button (pop commands))  ; Apply
+            (apply button (pop commands))) ; Apply and Save
+        (apply button (pop commands))   ; Apply
+        (apply button (pop commands))   ; Apply and Save
         (widget-insert "\n")
-        (apply button (pop commands)) ; Undo edits
-        (apply button (pop commands)) ; Reset to saved
-        (apply button (pop commands)) ; Erase customization
+        (apply button (pop commands))   ; Undo
+        (apply button (pop commands))   ; Reset
+        (apply button (pop commands))   ; Erase
         (widget-insert "  ")
-        (pop commands) ; Help (omitted)
+        (pop commands)                  ; Help (omitted)
         (apply button (pop commands)))) ; Exit
     (widget-insert "\n\n"))
 
@@ -2824,7 +2821,7 @@ If STATE is nil, the value is computed by `custom-variable-state'."
      (lambda (widget)
        (and (default-boundp (widget-value widget))
             (memq (widget-get widget :custom-state) '(modified changed)))))
-    ("Reset to Saved" custom-variable-reset-saved
+    ("Revert This Session's Customization" custom-variable-reset-saved
      (lambda (widget)
        (and (or (get (widget-value widget) 'saved-value)
                 (get (widget-value widget) 'saved-variable-comment))
@@ -3620,7 +3617,7 @@ the present value is saved to its :shown-value property instead."
     ("Undo Edits" custom-redraw
      (lambda (widget)
        (memq (widget-get widget :custom-state) '(modified changed))))
-    ("Reset to Saved" custom-face-reset-saved
+    ("Revert This Session's Customization" custom-face-reset-saved
      (lambda (widget)
        (or (get (widget-value widget) 'saved-face)
            (get (widget-value widget) 'saved-face-comment))))
@@ -3940,8 +3937,6 @@ restoring it to the state of a face that has never been customized."
 ;;; The `custom-group' Widget.
 
 (defcustom custom-group-tag-faces nil
-  ;; In XEmacs, this ought to play games with font size.
-  ;; Fixme: make it do so in Emacs.
   "Face used for group tags.
 The first member is used for level 1 groups, the second for level 2,
 and so forth.  The remaining group tags are shown with `custom-group-tag'."
@@ -3978,6 +3973,13 @@ and so forth.  The remaining group tags are shown with `custom-group-tag'."
   :group 'custom-faces)
 (define-obsolete-face-alias 'custom-group-tag-face 'custom-group-tag "22.1")
 
+(defface custom-group-subtitle
+  `((t (:weight bold)))
+  "Face for the \"Subgroups:\" subtitle in Custom buffers."
+  :group 'custom-faces)
+
+(defvar custom-group-doc-align-col 20)
+
 (define-widget 'custom-group 'custom
   "Customize group."
   :format "%v"
@@ -4043,11 +4045,9 @@ If GROUPS-ONLY non-nil, return only those members that are groups."
            (custom-browse-insert-prefix prefix)
            (push (widget-create-child-and-convert
                   widget 'custom-browse-visibility
-                  ;; :tag-glyph "plus"
                   :tag "+")
                  buttons)
            (insert "-- ")
-           ;; (widget-glyph-insert nil "-- " "horizontal")
            (push (widget-create-child-and-convert
                   widget 'custom-browse-group-tag)
                  buttons)
@@ -4057,8 +4057,6 @@ If GROUPS-ONLY non-nil, return only those members that are groups."
                 (zerop (length members)))
            (custom-browse-insert-prefix prefix)
            (insert "[ ]-- ")
-           ;; (widget-glyph-insert nil "[ ]" "empty")
-           ;; (widget-glyph-insert nil "-- " "horizontal")
            (push (widget-create-child-and-convert
                   widget 'custom-browse-group-tag)
                  buttons)
@@ -4136,7 +4134,8 @@ If GROUPS-ONLY non-nil, return only those members that are groups."
                     :action 'custom-toggle-parent
                     (not (eq state 'hidden)))
                    buttons))
-           (insert " : ")
+           (if (>= (current-column) custom-group-doc-align-col)
+               (insert "  "))
            ;; Create magic button.
            (let ((magic (widget-create-child-and-convert
                          widget 'custom-magic nil)))
@@ -4146,7 +4145,8 @@ If GROUPS-ONLY non-nil, return only those members that are groups."
            (widget-put widget :buttons buttons)
            ;; Insert documentation.
            (if (and (eq custom-buffer-style 'links) (> level 1))
-               (widget-put widget :documentation-indent 0))
+               (widget-put widget :documentation-indent
+                           custom-group-doc-align-col))
            (widget-add-documentation-string-button
             widget :visibility-widget 'custom-visibility))
 
@@ -4224,25 +4224,34 @@ If GROUPS-ONLY non-nil, return only those members that are groups."
                   (count 0)
                   (reporter (make-progress-reporter
                              "Creating group entries..." 0 len))
+                  (have-subtitle (and (not (eq symbol 'emacs))
+                                      (eq custom-buffer-order-groups 'last)))
+                  prev-type
                   children)
-             (setq children
-                   (mapcar
-                    (lambda (entry)
-                      (widget-insert "\n")
-                      (progress-reporter-update reporter (setq count (1+ count)))
-                      (let ((sym (nth 0 entry))
-                            (type (nth 1 entry)))
-                        (prog1
-                            (widget-create-child-and-convert
-                             widget type
-                             :group widget
-                             :tag (custom-unlispify-tag-name sym)
-                             :custom-prefixes custom-prefix-list
-                             :custom-level (1+ level)
-                             :value sym)
-                          (unless (eq (preceding-char) ?\n)
-                            (widget-insert "\n")))))
-                    members))
+
+             (dolist (entry members)
+               (unless (eq prev-type 'custom-group)
+                 (widget-insert "\n"))
+               (progress-reporter-update reporter (setq count (1+ count)))
+               (let ((sym (nth 0 entry))
+                     (type (nth 1 entry)))
+                 (when (and have-subtitle (eq type 'custom-group))
+                   (setq have-subtitle nil)
+                   (widget-insert
+                    (propertize "Subgroups:\n" 'face 'custom-group-subtitle)))
+                 (setq prev-type type)
+                 (push (widget-create-child-and-convert
+                        widget type
+                        :group widget
+                        :tag (custom-unlispify-tag-name sym)
+                        :custom-prefixes custom-prefix-list
+                        :custom-level (1+ level)
+                        :value sym)
+                       children)
+                 (unless (eq (preceding-char) ?\n)
+                   (widget-insert "\n"))))
+
+             (setq children (nreverse children))
              (mapc 'custom-magic-reset children)
              (widget-put widget :children children)
              (custom-group-state-update widget)
@@ -4267,7 +4276,7 @@ If GROUPS-ONLY non-nil, return only those members that are groups."
     ("Undo Edits" custom-group-reset-current
      (lambda (widget)
        (memq (widget-get widget :custom-state) '(modified))))
-    ("Reset to Saved" custom-group-reset-saved
+    ("Revert This Session's Customizations" custom-group-reset-saved
      (lambda (widget)
        (memq (widget-get widget :custom-state) '(modified set))))
     ,@(when (or custom-file init-file-user)
diff --git a/lisp/epg-config.el b/lisp/epg-config.el
index fd2468f9a4b..aa052206bec 100644
--- a/lisp/epg-config.el
+++ b/lisp/epg-config.el
@@ -33,9 +33,11 @@
   "Report bugs to this address.")
 
 (defgroup epg ()
-  "The EasyPG library."
+  "Interface to the GNU Privacy Guard (GnuPG)."
+  :tag "EasyPG"
   :version "23.1"
-  :group 'data)
+  :group 'data
+  :group 'external)
 
 (defcustom epg-gpg-program (or (executable-find "gpg")
                                (executable-find "gpg2")
diff --git a/lisp/eshell/eshell.el b/lisp/eshell/eshell.el
index 224451eacba..f8c9788b24d 100644
--- a/lisp/eshell/eshell.el
+++ b/lisp/eshell/eshell.el
@@ -228,11 +228,10 @@
 (require 'esh-mode)
 
 (defgroup eshell nil
-  "A command shell implemented entirely in Emacs Lisp.
+  "Command shell implemented entirely in Emacs Lisp.
 It invokes no external processes beyond those requested by the
 user, and is intended to be a functional replacement for command
 shells such as bash, zsh, rc, 4dos."
-  :tag "The Emacs shell"
   :link '(info-link "(eshell)Top")
   :version "21.1"
   :group 'applications)
diff --git a/lisp/ibuffer.el b/lisp/ibuffer.el
index 536992f5bc8..464b35fc3a6 100644
--- a/lisp/ibuffer.el
+++ b/lisp/ibuffer.el
@@ -60,11 +60,10 @@
 (declare-function ibuffer-format-filter-group-data "ibuf-ext" (filter))
 
 (defgroup ibuffer nil
-  "An advanced replacement for `buffer-menu'.
-
-Ibuffer allows you to operate on buffers in a manner much like Dired.
-Operations include sorting, marking by regular expression, and
-the ability to filter the displayed buffers by various criteria."
+  "Advanced replacement for `buffer-menu'.
+Ibuffer lets you operate on buffers in a Dired-like way,
+with the ability to sort, mark by regular expression,
+and filter displayed buffers by various criteria."
   :version "22.1"
   :group 'convenience)
 
diff --git a/lisp/mpc.el b/lisp/mpc.el
index d2203a4deab..ea7f6793309 100644
--- a/lisp/mpc.el
+++ b/lisp/mpc.el
@@ -95,7 +95,7 @@
 (eval-when-compile (require 'cl))
 
 (defgroup mpc ()
-  "A Client for the Music Player Daemon."
+  "Client for the Music Player Daemon (mpd)."
   :prefix "mpc-"
   :group 'multimedia
   :group 'applications)
diff --git a/lisp/net/ange-ftp.el b/lisp/net/ange-ftp.el
index 455836fdae1..447549f58cd 100644
--- a/lisp/net/ange-ftp.el
+++ b/lisp/net/ange-ftp.el
@@ -671,8 +671,7 @@
 ;;;; ------------------------------------------------------------
 
 (defgroup ange-ftp nil
-  "Accessing remote files and directories using FTP
-   made as simple and transparent as possible."
+  "Accessing remote files and directories using FTP."
   :group 'files
   :group 'comm
   :prefix "ange-ftp-")
diff --git a/lisp/net/tramp.el b/lisp/net/tramp.el
index 95848ac34ea..beb97c6eb32 100644
--- a/lisp/net/tramp.el
+++ b/lisp/net/tramp.el
@@ -62,7 +62,7 @@
 ;;; User Customizable Internal Variables:
 
 (defgroup tramp nil
-  "Edit remote files with a combination of rsh and rcp or similar programs."
+  "Edit remote files with a combination of ssh, scp, etc."
   :group 'files
   :group 'comm
   :version "22.1")
diff --git a/lisp/progmodes/ebnf2ps.el b/lisp/progmodes/ebnf2ps.el
index 05c9e160ceb..b7cbdcc7018 100644
--- a/lisp/progmodes/ebnf2ps.el
+++ b/lisp/progmodes/ebnf2ps.el
@@ -1181,10 +1181,10 @@ Elements of ALIST that are not conses are ignored."
 ;;; Interface to the command system
 
 (defgroup postscript nil
-  "PostScript Group."
+  "Printing with PostScript"
   :tag "PostScript"
   :version "20"
-  :group 'emacs)
+  :group 'environment)
 
 
 (defgroup ebnf2ps nil
diff --git a/lisp/progmodes/flymake.el b/lisp/progmodes/flymake.el
index ed8eb81932e..96d4105f65b 100644
--- a/lisp/progmodes/flymake.el
+++ b/lisp/progmodes/flymake.el
@@ -253,7 +253,7 @@ are the string substitutions (see `format')."
 (make-variable-buffer-local 'flymake-output-residual)
 
 (defgroup flymake nil
-  "A universal on-the-fly syntax checker."
+  "Universal on-the-fly syntax checker."
   :version "23.1"
   :group 'tools)
 
diff --git a/lisp/progmodes/gud.el b/lisp/progmodes/gud.el
index 1f60c351252..7123a8dd7fc 100644
--- a/lisp/progmodes/gud.el
+++ b/lisp/progmodes/gud.el
@@ -58,8 +58,9 @@
 ;; GUD commands must be visible in C buffers visited by GUD
 
 (defgroup gud nil
-  "Grand Unified Debugger mode for gdb and other debuggers under Emacs.
-Supported debuggers include gdb, sdb, dbx, xdb, perldb, pdb (Python) and jdb."
+  "The \"Grand Unified Debugger\" interface.
+Supported debuggers include gdb, sdb, dbx, xdb, perldb,
+pdb (Python), and jdb."
   :group 'processes
   :group 'tools)
 
diff --git a/lisp/progmodes/prolog.el b/lisp/progmodes/prolog.el
index 74c8c31b425..4ef6c31442d 100644
--- a/lisp/progmodes/prolog.el
+++ b/lisp/progmodes/prolog.el
@@ -295,7 +295,7 @@
 
 
 (defgroup prolog nil
-  "Major modes for editing and running Prolog and Mercury files."
+  "Editing and running Prolog and Mercury files."
   :group 'languages)
 
 (defgroup prolog-faces nil
diff --git a/lisp/progmodes/verilog-mode.el b/lisp/progmodes/verilog-mode.el
index 0139795dd38..ad1dae9acf9 100644
--- a/lisp/progmodes/verilog-mode.el
+++ b/lisp/progmodes/verilog-mode.el
@@ -393,7 +393,7 @@ Set `verilog-in-hooks' during this time, to assist AUTO caches."
     (parse-partial-sexp (point-min) (or pos (point)))))
 
 (defgroup verilog-mode nil
-  "Facilitates easy editing of Verilog source text."
+  "Major mode for Verilog source code."
   :version "22.2"
   :group 'languages)
 
diff --git a/lisp/progmodes/which-func.el b/lisp/progmodes/which-func.el
index c8435c14ea2..cdaeadde906 100644
--- a/lisp/progmodes/which-func.el
+++ b/lisp/progmodes/which-func.el
@@ -68,7 +68,7 @@
   "String to display in the mode line when current function is unknown.")
 
 (defgroup which-func nil
-  "Mode to display the current function name in the modeline."
+  "Display the current function name in the modeline."
   :group 'tools
   :version "20.3")
 
diff --git a/lisp/ses.el b/lisp/ses.el
index da18046c953..876537413ca 100644
--- a/lisp/ses.el
+++ b/lisp/ses.el
@@ -65,6 +65,7 @@
 
 (defgroup ses nil
   "Simple Emacs Spreadsheet."
+  :tag "SES"
   :group  'applications
   :prefix "ses-"
   :version "21.1")
diff --git a/lisp/term/xterm.el b/lisp/term/xterm.el
index 7e56cd9fa1d..51e5aa5796d 100644
--- a/lisp/term/xterm.el
+++ b/lisp/term/xterm.el
@@ -27,7 +27,7 @@
 (defgroup xterm nil
   "XTerm support."
   :version "24.1"
-  :group 'emacs)
+  :group 'environment)
 
 (defcustom xterm-extra-capabilities 'check
   "Whether Xterm supports some additional, more modern, features.
diff --git a/lisp/textmodes/picture.el b/lisp/textmodes/picture.el
index 191e9f3672b..24a4ac1b033 100644
--- a/lisp/textmodes/picture.el
+++ b/lisp/textmodes/picture.el
@@ -31,7 +31,7 @@
 ;;; Code:
 
 (defgroup picture nil
-  "Picture mode --- editing using quarter-plane screen model."
+  "Editing text-based pictures (\"ASCII art\")."
   :prefix "picture-"
   :group 'wp)
 
diff --git a/lisp/textmodes/tildify.el b/lisp/textmodes/tildify.el
index 5552eff7186..583e4a4d35d 100644
--- a/lisp/textmodes/tildify.el
+++ b/lisp/textmodes/tildify.el
@@ -51,7 +51,7 @@
 
 
 (defgroup tildify nil
-  "Adding missing hard spaces or other text fragments into texts."
+  "Add hard spaces or other text fragments to text buffers."
   :version "21.1"
   :group 'wp)
 
diff --git a/lisp/vc/ediff.el b/lisp/vc/ediff.el
index 4d6afa96d64..a1d778beebc 100644
--- a/lisp/vc/ediff.el
+++ b/lisp/vc/ediff.el
@@ -127,7 +127,7 @@
 (require 'ediff-mult)  ; required because of the registry stuff
 
 (defgroup ediff nil
-  "A comprehensive visual interface to diff & patch."
+  "Comprehensive visual interface to `diff' and `patch'."
   :tag "Ediff"
   :group 'tools)
 
diff --git a/lisp/vc/vc.el b/lisp/vc/vc.el
index ab7e587eb79..9ca9e00b8af 100644
--- a/lisp/vc/vc.el
+++ b/lisp/vc/vc.el
@@ -667,7 +667,7 @@
 ;; General customization
 
 (defgroup vc nil
-  "Version-control system in Emacs."
+  "Emacs interface to version control systems."
   :group 'tools)
 
 (defcustom vc-initial-comment nil
diff --git a/lisp/wid-edit.el b/lisp/wid-edit.el
index b6feecebde5..9c5c6462bcc 100644
--- a/lisp/wid-edit.el
+++ b/lisp/wid-edit.el
@@ -2907,15 +2907,7 @@ link for that string."
               (push (widget-convert-button widget-documentation-link-type
                                            begin end :value name)
                     buttons)))))
-      (widget-put widget :buttons buttons)))
-  (let ((indent (widget-get widget :indent)))
-    (when (and indent (not (zerop indent)))
-      (save-excursion
-        (save-restriction
-          (narrow-to-region from to)
-          (goto-char (point-min))
-          (while (search-forward "\n" nil t)
-            (insert-char ?\s indent)))))))
+      (widget-put widget :buttons buttons))))
 
 ;;; The `documentation-string' Widget.
 
@@ -2934,10 +2926,9 @@ link for that string."
         (start (point)))
     (if (string-match "\n" doc)
         (let ((before (substring doc 0 (match-beginning 0)))
-              (after (substring doc (match-beginning 0)))
-              button)
-          (when (and indent (not (zerop indent)))
-            (insert-char ?\s indent))
+              (after (substring doc (match-end 0)))
+              button end)
+          (widget-documentation-string-indent-to indent)
           (insert before ?\s)
           (widget-documentation-link-add widget start (point))
           (setq button
@@ -2950,18 +2941,35 @@ link for that string."
                  :action 'widget-parent-action
                  shown))
           (when shown
+            (insert ?\n)
             (setq start (point))
             (when (and indent (not (zerop indent)))
               (insert-char ?\s indent))
             (insert after)
-            (widget-documentation-link-add widget start (point)))
+            (setq end (point))
+            (widget-documentation-link-add widget start end)
+            ;; Indent the subsequent lines.
+            (when (and indent (> indent 0))
+              (save-excursion
+                (save-restriction
+                  (narrow-to-region start end)
+                  (goto-char (point-min))
+                  (while (search-forward "\n" nil t)
+                    (widget-documentation-string-indent-to indent))))))
           (widget-put widget :buttons (list button)))
-      (when (and indent (not (zerop indent)))
-        (insert-char ?\s indent))
+      (widget-documentation-string-indent-to indent)
       (insert doc)
       (widget-documentation-link-add widget start (point))))
   (insert ?\n))
 
+(defun widget-documentation-string-indent-to (col)
+  (when (and (numberp col)
+             (> col 0))
+    (let ((opoint (point)))
+      (indent-to col)
+      (put-text-property opoint (point)
+                         'display `(space :align-to ,col)))))
+
 (defun widget-documentation-string-action (widget &rest _ignore)
   ;; Toggle documentation.
   (let ((parent (widget-get widget :parent)))