bug#49274: [PATCH] lisp/cus-theme: retain documentation string when customizing theme

[Christopher League <league@contrapunctus.net>]

When editing an existing theme using `custom-theme-visit-theme`, the
theme's documentation string would always be discarded and replaced
with "Created DATE."

With this improvement, the existing theme documentation string (if
available) will be presented and editable in the widget, and emitted
in the `deftheme` declaration when saved. A newly-created theme or an
existing theme with no documentation string will get the "Created
DATE" as before.

*Implementation details:* we had to move the chunk marked "Load the
theme settings" earlier in the function `customize-create-theme`. Then
the `custom-theme-description` widget was made an `editable-field`
whose value comes from `theme-documentation` if available, else
`format-time-string`. The rest of the patch is reindentation due to
the larger scope of the let that holds the theme settings.

*Steps to reproduce the issue:*

```
% emacs -Q
M-x custom-theme-visit-theme RET tango RET
```

*Result before this patch:* In the Custom Theme buffer, the
Description field has the text `Created 2021-06-29.` followed by the
editable widget containing the same string a second time.

*Result after this patch:* The Description field has the text "Face
colors using the Tango palette (light background) ..." -- the
documentation string provided to `deftheme` in
`etc/themes/tango-theme.el`.
---
 lisp/cus-theme.el | 100 +++++++++++++++++++++++-----------------------
 1 file changed, 50 insertions(+), 50 deletions(-)

diff --git a/lisp/cus-theme.el b/lisp/cus-theme.el
index dfa2226403..3741f286e9 100644
--- a/lisp/cus-theme.el
+++ b/lisp/cus-theme.el
@@ -108,60 +108,16 @@ named *Custom Theme*."
     (unless (y-or-n-p "Include basic face customizations in this theme? ")
       (setq custom-theme--listed-faces nil)))
 
-  (if (eq theme 'user)
-      (widget-insert "This buffer contains all the Custom settings you have made.
-You can convert them into a new custom theme, and optionally
-remove them from your saved Custom file.\n\n"))
-
-  (widget-create 'push-button
-		 :tag " Visit Theme "
-		 :help-echo "Insert the settings of a pre-defined theme."
-		 :action (lambda (_widget &optional _event)
-                           (call-interactively #'custom-theme-visit-theme)))
-  (widget-insert "  ")
-  (widget-create 'push-button
-		 :tag " Merge Theme "
-		 :help-echo "Merge in the settings of a pre-defined theme."
-		 :action (lambda (_widget &optional _event)
-                           (call-interactively #'custom-theme-merge-theme)))
-  (widget-insert "  ")
-  (widget-create 'push-button
-		 :tag " Revert "
-		 :help-echo "Revert this buffer to its original state."
-		 :action (lambda (&rest ignored) (revert-buffer)))
-
-  (widget-insert "\n\nTheme name : ")
-  (setq custom-theme-name
-	(widget-create 'editable-field
-		       :value (if (and theme (not (eq theme 'user)))
-				  (symbol-name theme)
-				"")))
-  (widget-insert "Description: ")
-  (setq custom-theme-description
-	(widget-create 'text
-		       :value (format-time-string "Created %Y-%m-%d.")))
-  (widget-create 'push-button
-                 :notify #'custom-theme-write
-     		 " Save Theme ")
-  (when (eq theme 'user)
-    (setq custom-theme--migrate-settings t)
-    (widget-insert "  ")
-    (widget-create 'checkbox
-		   :value custom-theme--migrate-settings
-		   :action (lambda (widget &optional event)
-			     (when (widget-value widget)
-			       (widget-toggle-action widget event)
-			       (setq custom-theme--migrate-settings
-				     (widget-value widget)))))
-    (widget-insert (propertize " Remove saved theme settings from Custom save file."
-			       'face '(variable-pitch (:height 0.9)))))
-
   (let (vars values faces face-specs)
 
     ;; Load the theme settings.
     (when theme
-      (unless (eq theme 'user)
-	(load-theme theme nil t))
+      (if (eq theme 'user)
+          (widget-insert "This buffer contains all the Custom settings you have made.
+You can convert them into a new custom theme, and optionally
+remove them from your saved Custom file.\n\n")
+        (load-theme theme nil t))
+
       (dolist (setting (get theme 'theme-settings))
 	(if (eq (car setting) 'theme-value)
 	    (progn (push (nth 1 setting) vars)
@@ -169,6 +125,50 @@ remove them from your saved Custom file.\n\n"))
 	  (push (nth 1 setting) faces)
 	  (push (nth 3 setting) face-specs))))
 
+    (widget-create 'push-button
+		   :tag " Visit Theme "
+		   :help-echo "Insert the settings of a pre-defined theme."
+		   :action (lambda (_widget &optional _event)
+                             (call-interactively #'custom-theme-visit-theme)))
+    (widget-insert "  ")
+    (widget-create 'push-button
+		   :tag " Merge Theme "
+		   :help-echo "Merge in the settings of a pre-defined theme."
+		   :action (lambda (_widget &optional _event)
+                             (call-interactively #'custom-theme-merge-theme)))
+    (widget-insert "  ")
+    (widget-create 'push-button
+		   :tag " Revert "
+		   :help-echo "Revert this buffer to its original state."
+		   :action (lambda (&rest ignored) (revert-buffer)))
+
+    (widget-insert "\n\nTheme name : ")
+    (setq custom-theme-name
+	  (widget-create 'editable-field
+		         :value (if (and theme (not (eq theme 'user)))
+				    (symbol-name theme)
+				  "")))
+    (widget-insert "Description: ")
+    (setq custom-theme-description
+	  (widget-create 'editable-field
+		         :value (or (get theme 'theme-documentation)
+				    (format-time-string "Created %Y-%m-%d."))))
+    (widget-create 'push-button
+                   :notify #'custom-theme-write
+     		   " Save Theme ")
+    (when (eq theme 'user)
+      (setq custom-theme--migrate-settings t)
+      (widget-insert "  ")
+      (widget-create 'checkbox
+		     :value custom-theme--migrate-settings
+		     :action (lambda (widget &optional event)
+			       (when (widget-value widget)
+			         (widget-toggle-action widget event)
+			         (setq custom-theme--migrate-settings
+				       (widget-value widget)))))
+      (widget-insert (propertize " Remove saved theme settings from Custom save file."
+			         'face '(variable-pitch (:height 0.9)))))
+
     ;; If THEME is non-nil, insert all of that theme's faces.
     ;; Otherwise, insert those in `custom-theme--listed-faces'.
     (widget-insert "\n\n  Theme faces:\n ")
-- 
2.31.1