From: Lars Ingebrigtsen <larsi@gnus.org>
Date: Wed, 8 Sep 2021 06:50:27 +0000 (+0200)
Subject: Move the indented *Help* block to after the doc string
X-Git-Tag: emacs-28.0.90~1111
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=53edc2ba8ec9bf13706cd99ae00107d38bec00cc;p=emacs.git

Move the indented *Help* block to after the doc string

* lisp/help-fns.el (describe-function-1): Move indented admin
block to the end (bug#50463).
(describe-variable): Ditto (bug#50463).
---

diff --git a/etc/NEWS b/etc/NEWS
index 2275fa43a6d..f43fa741566 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -513,6 +513,12 @@ built without SVG support, the old icons will be used instead.
 
 ** Help
 
+---
+*** The order things are displayed in the *Help* buffer has been changed.
+The indented "administrative" block (containing the "probably
+introduced" and "other relevant functions" (and similar things) has
+been moved to after the doc string.
+
 +++
 *** New command 'describe-command' shows help for a command.
 This can be used instead of 'describe-function' for interactive
diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index 3eefdd13d2d..756eb83b503 100644
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -960,10 +960,9 @@ Returns a list of the form (REAL-FUNCTION DEF ALIASED REAL-DEF)."
                    ;; E.g. an alias for a not yet defined function.
                    ((invalid-function void-function) doc-raw))))
         (help-fns--ensure-empty-line)
+        (insert (or doc "Not documented."))
         (help-fns--run-describe-functions
-         help-fns-describe-function-functions function)
-        (help-fns--ensure-empty-line)
-        (insert (or doc "Not documented.")))
+         help-fns-describe-function-functions function))
       ;; Avoid asking the user annoying questions if she decides
       ;; to save the help buffer, when her locale's codeset
       ;; isn't UTF-8.
@@ -1197,10 +1196,6 @@ it is displayed along with the global value."
 		;; of a symbol.
 		(set-syntax-table emacs-lisp-mode-syntax-table)
 		(goto-char val-start-pos)
-		;; The line below previously read as
-		;; (delete-region (point) (progn (end-of-line) (point)))
-		;; which suppressed display of the buffer local value for
-		;; large values.
 		(when (looking-at "value is") (replace-match ""))
 		(save-excursion
 		  (insert "\n\nValue:")
@@ -1221,27 +1216,32 @@ it is displayed along with the global value."
                             (documentation-property
                              alias 'variable-documentation))))
 
+	      (with-current-buffer standard-output
+		(insert (or doc "Not documented as a variable.")))
+
+              ;; Output the indented administrative bits.
               (with-current-buffer buffer
                 (help-fns--run-describe-functions
-                 help-fns-describe-variable-functions variable))
-
-              (with-current-buffer standard-output
-                (help-fns--ensure-empty-line))
-	      (with-current-buffer standard-output
-		(insert (or doc "Not documented as a variable."))))
+                 help-fns-describe-variable-functions variable)))
 
 	    (with-current-buffer standard-output
 	      ;; Return the text we displayed.
 	      (buffer-string))))))))
 
 (defun help-fns--run-describe-functions (functions &rest args)
+  (with-current-buffer standard-output
+    (unless (bolp)
+      (insert "\n"))
+    (help-fns--ensure-empty-line))
   (let ((help-fns--activated-functions nil))
     (dolist (func functions)
       (let ((size (buffer-size standard-output)))
         (apply func args)
         ;; This function inserted something, so register it.
         (when (> (buffer-size) size)
-          (push func help-fns--activated-functions))))))
+          (push func help-fns--activated-functions)))))
+  (with-current-buffer standard-output
+    (help-fns--ensure-empty-line)))
 
 (add-hook 'help-fns-describe-variable-functions #'help-fns--customize-variable)
 (defun help-fns--customize-variable (variable &optional text)