bug#42397: [PATCH 00/14] Use outline headings and some cosmetics

bug#42397: [PATCH 00/14] Use outline headings and some cosmetics

[Jonas Bernoulli]

This patch series adds outline-minor-mode compatible headers to some
libraries.  In some cases that is done by increasing the number of
semicolons from two to the necessary three.  In other cases completely
new headings had to be added.

Also included are some cleanup commits.

[Note that this patch series was created using git-format-patch.
The subjects are the commit summaries.  I am the author of these
changes.]

Jonas Bernoulli (14):
  ; * lisp/epg.el (epg-signature-to-string): Use cl-case.
  ; * lisp/epg.el (epg-signature-to-string): Tiny refactor.
  ; * lisp/epg.el (epg-no-data-reason-alist): Fix typo in message.
  * lisp/epa.el (epa--derived-mode-p): Remove unnecessary alias.
  Split EasyPG libraries into outline sections
  * lisp/emacs-lisp/eldoc.el (eldoc-minibuffer-message): Fix
    indentation.
  * lisp/progmodes/compile.el: Remove unnecessary comments.
  ; * lisp/whitespace.el: Capitalize "Code" section heading.
  * lisp/mail/smtpmail.el: Use outline headings.
  * test/src/emacs-module-tests.el: Use proper outline headings.
  * lisp/obsolete/longlines.el: Use proper outline headings.
  * lisp/net/imap.el: Use proper outline headings
  * lisp/font-lock.el: Split the Commentary into subsections.
  * lisp/font-lock.el: No longer mark each end of a section explicitly.

 lisp/emacs-lisp/eldoc.el       | 14 +++---
 lisp/epa-dired.el              |  1 +
 lisp/epa-file.el               |  9 ++++
 lisp/epa-hook.el               |  1 +
 lisp/epa-mail.el               |  9 ++++
 lisp/epa.el                    | 37 ++++++++++------
 lisp/epg-config.el             |  6 +++
 lisp/epg.el                    | 79 ++++++++++++++++++++--------------
 lisp/font-lock.el              | 22 +++-------
 lisp/mail/smtpmail.el          |  9 ++--
 lisp/net/imap.el               | 29 +++++++------
 lisp/obsolete/longlines.el     | 18 ++++----
 lisp/progmodes/compile.el      |  2 -
 lisp/whitespace.el             |  2 +-
 test/src/emacs-module-tests.el | 20 +++------
 15 files changed, 149 insertions(+), 109 deletions(-)

-- 
2.26.0

bug#42397: [PATCH 01/14] ; * lisp/epg.el (epg-signature-to-string): Use cl-case.

[Jonas Bernoulli]

In this case we can greatly increase readability by using `cl-case'
instead of `cond'.
---
 lisp/epg.el | 19 +++++++------------
 1 file changed, 7 insertions(+), 12 deletions(-)

diff --git a/lisp/epg.el b/lisp/epg.el
index 222fd913e1..e97db65b60 100644
--- a/lisp/epg.el
+++ b/lisp/epg.el
@@ -404,18 +404,13 @@ epg-signature-to-string
 	 (pubkey-algorithm (epg-signature-pubkey-algorithm signature))
 	 (key-id (epg-signature-key-id signature)))
     (concat
-     (cond ((eq (epg-signature-status signature) 'good)
-	    "Good signature from ")
-	   ((eq (epg-signature-status signature) 'bad)
-	    "Bad signature from ")
-	   ((eq (epg-signature-status signature) 'expired)
-	    "Expired signature from ")
-	   ((eq (epg-signature-status signature) 'expired-key)
-	    "Signature made by expired key ")
-	   ((eq (epg-signature-status signature) 'revoked-key)
-	    "Signature made by revoked key ")
-	   ((eq (epg-signature-status signature) 'no-pubkey)
-	    "No public key for "))
+     (cl-case signature
+       (good "Good signature from ")
+       (bad  "Bad signature from ")
+       (expired "Expired signature from ")
+       (expired-key "Signature made by expired key ")
+       (revoked-key "Signature made by revoked key ")
+       (no-pubkey "No public key for "))
      key-id
      (if user-id
 	 (concat " "
-- 
2.26.0

bug#42397: [PATCH 02/14] ; * lisp/epg.el (epg-signature-to-string): Tiny refactor.

[Jonas Bernoulli]

`concat' treats arguments that are nil as if they were empty strings.
We therefore do not have to write (if TEST THEN "") and can just use
(and TEST THEN).
---
 lisp/epg.el | 32 ++++++++++++++------------------
 1 file changed, 14 insertions(+), 18 deletions(-)

diff --git a/lisp/epg.el b/lisp/epg.el
index e97db65b60..c10eb4f06c 100644
--- a/lisp/epg.el
+++ b/lisp/epg.el
@@ -412,24 +412,20 @@ epg-signature-to-string
        (revoked-key "Signature made by revoked key ")
        (no-pubkey "No public key for "))
      key-id
-     (if user-id
-	 (concat " "
-		 (if (stringp user-id)
-		     (epg--decode-percent-escape-as-utf-8 user-id)
-		   (epg-decode-dn user-id)))
-       "")
-     (if (epg-signature-validity signature)
-	 (format " (trust %s)"  (epg-signature-validity signature))
-       "")
-     (if (epg-signature-creation-time signature)
-	 (format-time-string " created at %Y-%m-%dT%T%z"
-			     (epg-signature-creation-time signature))
-       "")
-     (if pubkey-algorithm
-	 (concat " using "
-		 (or (cdr (assq pubkey-algorithm epg-pubkey-algorithm-alist))
-		     (format "(unknown algorithm %d)" pubkey-algorithm)))
-       ""))))
+     (and user-id
+	  (concat " "
+		  (if (stringp user-id)
+		      (epg--decode-percent-escape-as-utf-8 user-id)
+		    (epg-decode-dn user-id))))
+     (and (epg-signature-validity signature)
+	  (format " (trust %s)"  (epg-signature-validity signature)))
+     (and (epg-signature-creation-time signature)
+	  (format-time-string " created at %Y-%m-%dT%T%z"
+			      (epg-signature-creation-time signature)))
+     (and pubkey-algorithm
+	  (concat " using "
+		  (or (cdr (assq pubkey-algorithm epg-pubkey-algorithm-alist))
+		      (format "(unknown algorithm %d)" pubkey-algorithm)))))))
 
 (defun epg-verify-result-to-string (verify-result)
   "Convert VERIFY-RESULT to a human readable string."
-- 
2.26.0

bug#42397: [PATCH 03/14] ; * lisp/epg.el (epg-no-data-reason-alist): Fix typo in message.

[Jonas Bernoulli]

---
 lisp/epg.el | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lisp/epg.el b/lisp/epg.el
index c10eb4f06c..2e092acc6a 100644
--- a/lisp/epg.el
+++ b/lisp/epg.el
@@ -123,7 +123,7 @@ epg-import-problem-reason-alist
 
 (defconst epg-no-data-reason-alist
   '((1 . "No armored data")
-    (2 . "Expected a packet but did not found one")
+    (2 . "Expected a packet but did not find one")
     (3 . "Invalid packet found, this may indicate a non OpenPGP message")
     (4 . "Signature expected but not found")))
 
-- 
2.26.0

bug#42397: [PATCH 04/14] * lisp/epa.el (epa--derived-mode-p): Remove unnecessary alias.

[Jonas Bernoulli]

`derived-mode-p' was added twenty years ago in
6ad501012b9a9ddc26dd8ce1cef8332ee16d87df and by
now we can just assume that it exists.
---
 lisp/epa.el | 14 +-------------
 1 file changed, 1 insertion(+), 13 deletions(-)

diff --git a/lisp/epa.el b/lisp/epa.el
index 3c7dd8309a..fc7ad5efab 100644
--- a/lisp/epa.el
+++ b/lisp/epa.el
@@ -1105,17 +1105,6 @@ epa-sign-region
 				 'start-open t
 				 'end-open t)))))
 
-(defalias 'epa--derived-mode-p
-  (if (fboundp 'derived-mode-p)
-      #'derived-mode-p
-    (lambda (&rest modes)
-      "Non-nil if the current major mode is derived from one of MODES.
-Uses the `derived-mode-parent' property of the symbol to trace backwards."
-      (let ((parent major-mode))
-        (while (and (not (memq parent modes))
-                    (setq parent (get parent 'derived-mode-parent))))
-        parent))))
-
 ;;;###autoload
 (defun epa-encrypt-region (start end recipients sign signers)
   "Encrypt the current region between START and END for RECIPIENTS.
@@ -1227,8 +1216,7 @@ epa-import-keys
     (if (epg-context-result-for context 'import)
 	(epa-display-info (epg-import-result-to-string
 			   (epg-context-result-for context 'import))))
-    ;; FIXME: Why not use the (otherwise unused) epa--derived-mode-p?
-    (if (eq major-mode 'epa-key-list-mode)
+    (if (derived-mode-p 'epa-key-list-mode)
 	(apply #'epa--list-keys epa-list-keys-arguments))))
 
 ;;;###autoload
-- 
2.26.0

bug#42397: [PATCH 05/14] Split EasyPG libraries into outline sections

[Jonas Bernoulli]

* lisp/epa-dired.el:
lisp/epa-file.el:
lisp/epa-hook.el:
lisp/epa-mail.el:
lisp/epa.el:
lisp/epg-config.el:
lisp/epg.el: Split into outline sections.
* lisp/epg.el (epg-error): Move definition.
---
 lisp/epa-dired.el  |  1 +
 lisp/epa-file.el   |  9 +++++++++
 lisp/epa-hook.el   |  1 +
 lisp/epa-mail.el   |  9 +++++++++
 lisp/epa.el        | 23 +++++++++++++++++++++++
 lisp/epg-config.el |  6 ++++++
 lisp/epg.el        | 26 +++++++++++++++++++++++++-
 7 files changed, 74 insertions(+), 1 deletion(-)

diff --git a/lisp/epa-dired.el b/lisp/epa-dired.el
index 9269ea9707..4ff1ba3394 100644
--- a/lisp/epa-dired.el
+++ b/lisp/epa-dired.el
@@ -1,4 +1,5 @@
 ;;; epa-dired.el --- the EasyPG Assistant, dired extension -*- lexical-binding: t -*-
+
 ;; Copyright (C) 2006-2020 Free Software Foundation, Inc.
 
 ;; Author: Daiki Ueno <ueno@unixuser.org>
diff --git a/lisp/epa-file.el b/lisp/epa-file.el
index 20043a9eae..de51c59c34 100644
--- a/lisp/epa-file.el
+++ b/lisp/epa-file.el
@@ -1,4 +1,5 @@
 ;;; epa-file.el --- the EasyPG Assistant, transparent file encryption -*- lexical-binding: t -*-
+
 ;; Copyright (C) 2006-2020 Free Software Foundation, Inc.
 
 ;; Author: Daiki Ueno <ueno@unixuser.org>
@@ -25,6 +26,8 @@
 (require 'epa)
 (require 'epa-hook)
 
+;;; Options
+
 (defcustom epa-file-cache-passphrase-for-symmetric-encryption nil
   "If non-nil, cache passphrase for symmetric encryption.
 
@@ -49,6 +52,8 @@ epa-file-select-keys
 		 (const :tag "Don't ask" silent))
   :group 'epa-file)
 
+;;; Other
+
 (defvar epa-file-passphrase-alist nil)
 
 (defun epa-file-passphrase-callback-function (context key-id file)
@@ -72,6 +77,8 @@ epa-file-passphrase-callback-function
 		passphrase))))
     (epa-passphrase-callback-function context key-id file)))
 
+;;; File Handler
+
 (defvar epa-inhibit nil
   "Non-nil means don't try to decrypt .gpg files when operating on them.")
 
@@ -303,6 +310,8 @@ epa-file-write-region
 	(message "Wrote %s" buffer-file-name))))
 (put 'write-region 'epa-file 'epa-file-write-region)
 
+;;; Commands
+
 (defun epa-file-select-keys ()
   "Select recipients for encryption."
   (interactive)
diff --git a/lisp/epa-hook.el b/lisp/epa-hook.el
index a86f23eb68..6f12f8a6bf 100644
--- a/lisp/epa-hook.el
+++ b/lisp/epa-hook.el
@@ -1,4 +1,5 @@
 ;;; epa-hook.el --- preloaded code to enable epa-file.el -*- lexical-binding: t -*-
+
 ;; Copyright (C) 2006-2020 Free Software Foundation, Inc.
 
 ;; Author: Daiki Ueno <ueno@unixuser.org>
diff --git a/lisp/epa-mail.el b/lisp/epa-mail.el
index 00f560af0b..4c57235394 100644
--- a/lisp/epa-mail.el
+++ b/lisp/epa-mail.el
@@ -1,4 +1,5 @@
 ;;; epa-mail.el --- the EasyPG Assistant, minor-mode for mail composer -*- lexical-binding: t -*-
+
 ;; Copyright (C) 2006-2020 Free Software Foundation, Inc.
 
 ;; Author: Daiki Ueno <ueno@unixuser.org>
@@ -25,6 +26,8 @@
 (require 'epa)
 (require 'mail-utils)
 
+;;; Local Mode
+
 (defvar epa-mail-mode-map
   (let ((keymap (make-sparse-keymap)))
     (define-key keymap "\C-c\C-ed" 'epa-mail-decrypt)
@@ -50,6 +53,8 @@ epa-mail-mode
   "A minor-mode for composing encrypted/clearsigned mails."
   nil " epa-mail" epa-mail-mode-map)
 
+;;; Utilities
+
 (defun epa-mail--find-usable-key (keys usage)
   "Find a usable key from KEYS for USAGE.
 USAGE would be `sign' or `encrypt'."
@@ -64,6 +69,8 @@ epa-mail--find-usable-key
 	  (setq pointer (cdr pointer))))
       (setq keys (cdr keys)))))
 
+;;; Commands
+
 ;;;###autoload
 (defun epa-mail-decrypt ()
   "Decrypt OpenPGP armors in the current buffer.
@@ -238,6 +245,8 @@ epa-mail-import-keys
   (interactive)
   (epa-import-armor-in-region (point-min) (point-max)))
 
+;;; Global Mode
+
 ;;;###autoload
 (define-minor-mode epa-global-mail-mode
   "Minor mode to hook EasyPG into Mail mode."
diff --git a/lisp/epa.el b/lisp/epa.el
index fc7ad5efab..a63dc18fdb 100644
--- a/lisp/epa.el
+++ b/lisp/epa.el
@@ -30,6 +30,8 @@
   (require 'wid-edit))
 (require 'derived)
 
+;;; Options
+
 (defgroup epa nil
   "The EasyPG Assistant"
   :version "23.1"
@@ -73,6 +75,8 @@ epa-mail-aliases
   :group 'epa
   :version "24.4")
 
+;;; Faces
+
 (defgroup epa-faces nil
   "Faces for epa-mode."
   :version "23.1"
@@ -146,6 +150,8 @@ epa-validity-face-alist
   :type '(repeat (cons symbol face))
   :group 'epa-faces)
 
+;;; Variables
+
 (defvar epa-font-lock-keywords
   '(("^\\*"
      (0 'epa-mark))
@@ -252,6 +258,8 @@ epa-info-mode-map
 
 (defvar epa-exit-buffer-function #'quit-window)
 
+;;; Key Widget
+
 (define-widget 'epa-key 'push-button
   "Button for representing an epg-key object."
   :format "%[%v%]"
@@ -293,6 +301,8 @@ epa--key-widget-help-echo
 	  (epg-sub-key-id (car (epg-key-sub-key-list
 				(widget-get widget :value))))))
 
+;;; Modes
+
 (define-derived-mode epa-key-list-mode special-mode "EPA Keys"
   "Major mode for `epa-list-keys'."
   (buffer-disable-undo)
@@ -316,6 +326,9 @@ epa-info-mode
   (setq truncate-lines t
 	buffer-read-only t))
 
+;;; Commands
+;;;; Marking
+
 (defun epa-mark-key (&optional arg)
   "Mark a key on the current line.
 If ARG is non-nil, unmark the key."
@@ -338,11 +351,15 @@ epa-unmark-key
   (interactive "P")
   (epa-mark-key (not arg)))
 
+;;;; Quitting
+
 (defun epa-exit-buffer ()
   "Exit the current buffer using `epa-exit-buffer-function'."
   (interactive)
   (funcall epa-exit-buffer-function))
 
+;;;; Listing and Selecting
+
 (defun epa--insert-keys (keys)
   (save-excursion
     (save-restriction
@@ -505,6 +522,8 @@ epa-select-keys
   (let ((keys (epg-list-keys context names secret)))
     (epa--select-keys prompt keys)))
 
+;;;; Key Details
+
 (defun epa-show-key ()
   "Show a key on the current line."
   (interactive)
@@ -591,6 +610,8 @@ epa--show-key
     (goto-char (point-min))
     (pop-to-buffer (current-buffer))))
 
+;;;; Encryption and Signatures
+
 (defun epa-display-info (info)
   (if epa-popup-info-window
       (save-selected-window
@@ -1180,6 +1201,8 @@ epa-encrypt-region
 				 'start-open t
 				 'end-open t)))))
 
+;;;; Key Management
+
 ;;;###autoload
 (defun epa-delete-keys (keys &optional allow-secret)
   "Delete selected KEYS."
diff --git a/lisp/epg-config.el b/lisp/epg-config.el
index 1c42924652..e7f9d303ad 100644
--- a/lisp/epg-config.el
+++ b/lisp/epg-config.el
@@ -34,6 +34,8 @@ epg-version-number
 (define-obsolete-variable-alias 'epg-bug-report-address
   'report-emacs-bug-address "27.1")
 
+;;; Options
+
 (defgroup epg ()
   "Interface to the GNU Privacy Guard (GnuPG)."
   :tag "EasyPG"
@@ -106,6 +108,8 @@ epg-debug
 Note that the buffer name starts with a space."
   :type 'boolean)
 
+;;; Constants
+
 (defconst epg-gpg-minimum-version "1.4.3")
 (defconst epg-gpg2-minimum-version "2.1.6")
 
@@ -133,6 +137,8 @@ epg-config--configuration-constructor-alist
 either `OpenPGP' or `CMS'.  The second element is a function
 which constructs a configuration object (actually a plist).")
 
+;;; "Configuration"
+
 (defvar epg--configurations nil)
 
 ;;;###autoload
diff --git a/lisp/epg.el b/lisp/epg.el
index 2e092acc6a..9909b819e4 100644
--- a/lisp/epg.el
+++ b/lisp/epg.el
@@ -1,4 +1,5 @@
 ;;; epg.el --- the EasyPG Library -*- lexical-binding: t -*-
+
 ;; Copyright (C) 1999-2000, 2002-2020 Free Software Foundation, Inc.
 
 ;; Author: Daiki Ueno <ueno@unixuser.org>
@@ -25,6 +26,10 @@
 (require 'epg-config)
 (eval-when-compile (require 'cl-lib))
 
+(define-error 'epg-error "GPG error")
+
+;;; Variables
+
 (defvar epg-user-id nil
   "GnuPG ID of your default identity.")
 
@@ -41,6 +46,8 @@ epg-debug-buffer
 (defvar epg-agent-file nil)
 (defvar epg-agent-mtime nil)
 
+;;; Enums
+
 ;; from gnupg/common/openpgpdefs.h
 (defconst epg-cipher-algorithm-alist
   '((0 . "NONE")
@@ -169,7 +176,8 @@ epg-dn-type-alist
 
 (defvar epg-prompt-alist nil)
 
-(define-error 'epg-error "GPG error")
+;;; Structs
+;;;; Data Struct
 
 (cl-defstruct (epg-data
                (:constructor nil)
@@ -180,6 +188,8 @@ 'epg-error
   (file nil :read-only t)
   (string nil :read-only t))
 
+;;;; Context Struct
+
 (cl-defstruct (epg-context
                (:constructor nil)
                (:constructor epg-context--make
@@ -218,6 +228,8 @@ 'epg-error
   (error-output "")
   error-buffer)
 
+;;;; Context Methods
+
 ;; This is not an alias, just so we can mark it as autoloaded.
 ;;;###autoload
 (defun epg-make-context (&optional protocol armor textmode include-certs
@@ -281,6 +293,8 @@ epg-context-set-signers
   (declare (obsolete setf "25.1"))
   (setf (epg-context-signers context) signers))
 
+;;;; Other Structs
+
 (cl-defstruct (epg-signature
                (:constructor nil)
                (:constructor epg-make-signature
@@ -385,6 +399,8 @@ epg-context-set-signers
   secret-unchanged not-imported
   imports)
 
+;;; Functions
+
 (defun epg-context-result-for (context name)
   "Return the result of CONTEXT associated with NAME."
   (cdr (assq name (epg-context-result context))))
@@ -850,6 +866,8 @@ epg--prompt-GET_BOOL-untrusted_key.override
 		  (format "Untrusted key %s %s.  Use anyway? " key-id user-id))
 	      "Use untrusted key anyway? ")))
 
+;;; Status Functions
+
 (defun epg--status-GET_BOOL (context string)
   (let (inhibit-quit)
     (condition-case nil
@@ -1225,6 +1243,8 @@ epg--status-IMPORT_RES
 			     (epg-context-result-for context 'import-status)))
     (epg-context-set-result-for context 'import-status nil)))
 
+;;; Functions
+
 (defun epg-passphrase-callback-function (context key-id _handback)
   (declare (obsolete epa-passphrase-callback-function "23.1"))
   (if (eq key-id 'SYM)
@@ -1294,6 +1314,8 @@ epg--make-sub-key-1
    (if (aref line 6)
        (epg--time-from-seconds (aref line 6)))))
 
+;;; Public Functions
+
 (defun epg-list-keys (context &optional name mode)
   "Return a list of epg-key objects matched with NAME.
 If MODE is nil or `public', only public keyring should be searched.
@@ -2022,6 +2044,8 @@ epg-edit-key
 			    (epg-errors-to-string errors))))))
     (epg-reset context)))
 
+;;; Decode Functions
+
 (defun epg--decode-percent-escape (string)
   (setq string (encode-coding-string string 'raw-text))
   (let ((index 0))
-- 
2.26.0

bug#42397: [PATCH 06/14] * lisp/emacs-lisp/eldoc.el (eldoc-minibuffer-message): Fix indentation.

[Jonas Bernoulli]

---
 lisp/emacs-lisp/eldoc.el | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/lisp/emacs-lisp/eldoc.el b/lisp/emacs-lisp/eldoc.el
index 510dff9ed0..90dce4a317 100644
--- a/lisp/emacs-lisp/eldoc.el
+++ b/lisp/emacs-lisp/eldoc.el
@@ -285,13 +285,13 @@ eldoc-minibuffer-message
 	     (or (window-in-direction 'above (minibuffer-window))
 		 (minibuffer-selected-window)
 		 (get-largest-window)))
-    (when mode-line-format
-	  (unless (and (listp mode-line-format)
-		       (assq 'eldoc-mode-line-string mode-line-format))
-	    (setq mode-line-format
-		  (list "" '(eldoc-mode-line-string
-			     (" " eldoc-mode-line-string " "))
-			mode-line-format))))
+	  (when mode-line-format
+	    (unless (and (listp mode-line-format)
+			 (assq 'eldoc-mode-line-string mode-line-format))
+	      (setq mode-line-format
+		    (list "" '(eldoc-mode-line-string
+			       (" " eldoc-mode-line-string " "))
+			  mode-line-format))))
           (setq eldoc-mode-line-string
                 (when (stringp format-string)
                   (apply #'format-message format-string args)))
-- 
2.26.0

bug#42397: [PATCH 07/14] * lisp/progmodes/compile.el: Remove unnecessary comments.

[Jonas Bernoulli]

These comments are unnecessary because the doc-strings that follow
already cover the same ground, while being more concise.  These
comments were also prefixed with too many semicolons, causing them
to be treated as outline headings.
---
 lisp/progmodes/compile.el | 2 --
 1 file changed, 2 deletions(-)

diff --git a/lisp/progmodes/compile.el b/lisp/progmodes/compile.el
index a76a3c44a3..0b9f417845 100644
--- a/lisp/progmodes/compile.el
+++ b/lisp/progmodes/compile.el
@@ -2373,12 +2373,10 @@ compilation-filter
 	  (set-marker min nil)
 	  (set-marker max nil))))))
 
-;;; test if a buffer is a compilation buffer, assuming we're in the buffer
 (defsubst compilation-buffer-internal-p ()
   "Test if inside a compilation buffer."
   (local-variable-p 'compilation-locs))
 
-;;; test if a buffer is a compilation buffer, using compilation-buffer-internal-p
 (defsubst compilation-buffer-p (buffer)
   "Test if BUFFER is a compilation buffer."
   (with-current-buffer buffer
-- 
2.26.0

bug#42397: [PATCH 08/14] ; * lisp/whitespace.el: Capitalize "Code" section heading.

[Jonas Bernoulli]

---
 lisp/whitespace.el | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lisp/whitespace.el b/lisp/whitespace.el
index 47434bf3d2..0f5901b0cf 100644
--- a/lisp/whitespace.el
+++ b/lisp/whitespace.el
@@ -262,7 +262,7 @@
 ;;
 ;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
-;;; code:
+;;; Code:
 
 \f
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
-- 
2.26.0

bug#42397: [PATCH 09/14] * lisp/mail/smtpmail.el: Use outline headings.

[Jonas Bernoulli]

---
 lisp/mail/smtpmail.el | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/lisp/mail/smtpmail.el b/lisp/mail/smtpmail.el
index f5c9432879..cf08bd742f 100644
--- a/lisp/mail/smtpmail.el
+++ b/lisp/mail/smtpmail.el
@@ -61,12 +61,12 @@
 (autoload 'message-make-message-id "message")
 (autoload 'rfc2104-hash "rfc2104")
 
-;;;
+;;; Options
+
 (defgroup smtpmail nil
   "SMTP protocol for sending mail."
   :group 'mail)
 
-
 (defcustom smtpmail-default-smtp-server nil
   "Specify default SMTP server.
 This only has effect if you specify it before loading the smtpmail library."
@@ -172,8 +172,7 @@ smtpmail-retries
   :type 'integer
   :version "27.1")
 
-;; End of customizable variables.
-
+;;; Variables
 
 (defvar smtpmail-address-buffer)
 (defvar smtpmail-recipient-address-list)
@@ -192,6 +191,8 @@ smtpmail-auth-supported
 (defvar smtpmail-mail-address nil
   "Value to use for envelope-from address for mail from ambient buffer.")
 
+;;; Functions
+
 ;;;###autoload
 (defun smtpmail-send-it ()
   (let ((errbuf (if mail-interactive
-- 
2.26.0

bug#42397: [PATCH 10/14] * test/src/emacs-module-tests.el: Use proper outline headings.

[Jonas Bernoulli]

This library already used section headings but it used just two
instead of three semicolons, making them indistinguishable from
plain comments.
---
 test/src/emacs-module-tests.el | 20 +++++---------------
 1 file changed, 5 insertions(+), 15 deletions(-)

diff --git a/test/src/emacs-module-tests.el b/test/src/emacs-module-tests.el
index 411b4505da..905a0ae546 100644
--- a/test/src/emacs-module-tests.el
+++ b/test/src/emacs-module-tests.el
@@ -48,9 +48,7 @@ emacs-module-tests--generic
 (cl-defmethod emacs-module-tests--generic ((_ user-ptr))
   'user-ptr)
 
-;;
-;; Basic tests.
-;;
+;;; Basic tests.
 
 (ert-deftest mod-test-sum-test ()
   (should (= (mod-test-sum 1 2) 3))
@@ -103,9 +101,7 @@ module-function-object
                  ">" eos)
              (prin1-to-string func)))))
 
-;;
-;; Non-local exists (throw, signal).
-;;
+;;; Non-local exists (throw, signal).
 
 (ert-deftest mod-test-non-local-exit-signal-test ()
   (should-error (mod-test-signal))
@@ -142,9 +138,7 @@ mod-test-non-local-exit-funcall-throw
   (should (equal (mod-test-non-local-exit-funcall (lambda () (throw 'tag 32)))
                  '(throw tag 32))))
 
-;;
-;; String tests.
-;;
+;;; String tests.
 
 (defun multiply-string (s n)
   "Return N copies of S concatenated together."
@@ -165,9 +159,7 @@ mod-test-globref-free-test
 (ert-deftest mod-test-string-a-to-b-test ()
   (should (string= (mod-test-string-a-to-b "aaa") "bbb")))
 
-;;
-;; User-pointer tests.
-;;
+;;; User-pointer tests.
 
 (ert-deftest mod-test-userptr-fun-test ()
   (let* ((n 42)
@@ -181,9 +173,7 @@ mod-test-userptr-fun-test
 
 ;; TODO: try to test finalizer
 
-;;
-;; Vector tests.
-;;
+;;; Vector tests.
 
 (ert-deftest mod-test-vector-test ()
   (dolist (s '(2 10 100 1000))
-- 
2.26.0

bug#42397: [PATCH 11/14] * lisp/obsolete/longlines.el: Use proper outline headings.

[Jonas Bernoulli]

This library already used section headings but it used just two
instead of three semicolons, making them indistinguishable from
plain comments.  One heading is new.
---
 lisp/obsolete/longlines.el | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/lisp/obsolete/longlines.el b/lisp/obsolete/longlines.el
index 2fba49f402..11e167aa18 100644
--- a/lisp/obsolete/longlines.el
+++ b/lisp/obsolete/longlines.el
@@ -38,6 +38,8 @@
 
 ;;; Code:
 
+;;; Options
+
 (defgroup longlines nil
   "Automatic wrapping of long lines when loading files."
   :group 'fill)
@@ -76,7 +78,7 @@ longlines-show-effect
   :group 'longlines
   :type 'string)
 
-;; Internal variables
+;;; Internal variables
 
 (defvar longlines-wrap-beg nil)
 (defvar longlines-wrap-end nil)
@@ -90,7 +92,7 @@ longlines-decoded
 (make-variable-buffer-local 'longlines-showing)
 (make-variable-buffer-local 'longlines-decoded)
 
-;; Mode
+;;; Mode
 
 (defvar message-indent-citation-function)
 
@@ -210,7 +212,7 @@ longlines-mode-off
 major mode changes."
   (longlines-mode 0))
 
-;; Showing the effect of hard newlines in the buffer
+;;; Showing the effect of hard newlines in the buffer
 
 (defun longlines-show-hard-newlines (&optional arg)
   "Make hard newlines visible by adding a face.
@@ -252,7 +254,7 @@ longlines-unshow-hard-newlines
       (setq pos (text-property-not-all (1+ pos) (point-max) 'hard nil)))
     (restore-buffer-modified-p mod)))
 
-;; Wrapping the paragraphs.
+;;; Wrapping the paragraphs
 
 (defun longlines-wrap-region (beg end)
   "Wrap each successive line, starting with the line before BEG.
@@ -402,7 +404,7 @@ longlines-encode-string
       (setq pos (string-match "\n" str (1+ pos))))
     str))
 
-;; Auto wrap
+;;; Auto wrap
 
 (defun longlines-auto-wrap (&optional arg)
   "Toggle automatic line wrapping.
@@ -457,7 +459,7 @@ longlines-window-change-function
       (setq fill-column (- (window-width) dw))
       (longlines-wrap-region (point-min) (point-max)))))
 
-;; Isearch
+;;; Isearch
 
 (defun longlines-search-function ()
   (cond
@@ -477,7 +479,7 @@ longlines-re-search-forward
   (let ((search-spaces-regexp " *[ \n]"))
     (re-search-forward string bound noerror count)))
 
-;; Loading and saving
+;;; Loading and saving
 
 (defun longlines-before-revert-hook ()
   (add-hook 'after-revert-hook 'longlines-after-revert-hook nil t)
@@ -492,7 +494,7 @@ longlines-after-revert-hook
  (list 'longlines "Automatically wrap long lines." nil nil
        'longlines-encode-region t nil))
 
-;; Unloading
+;;; Unloading
 
 (defun longlines-unload-function ()
   "Unload the longlines library."
-- 
2.26.0

bug#42397: [PATCH 12/14] * lisp/net/imap.el: Use proper outline headings

[Jonas Bernoulli]

This library already used section headings but it used just two
instead of three semicolons, making them indistinguishable from
plain comments.  One heading is new.
---
 lisp/net/imap.el | 29 +++++++++++++++++------------
 1 file changed, 17 insertions(+), 12 deletions(-)

diff --git a/lisp/net/imap.el b/lisp/net/imap.el
index a492dc8c79..6e6c2e4aeb 100644
--- a/lisp/net/imap.el
+++ b/lisp/net/imap.el
@@ -145,7 +145,7 @@
 (declare-function digest-md5-digest-uri "ext:digest-md5")
 (declare-function digest-md5-challenge "ext:digest-md5")
 
-;; User variables.
+;;; User variables.
 
 (defgroup imap nil
   "Low-level IMAP issues."
@@ -257,7 +257,7 @@ imap-store-password
   :group 'imap
   :type 'boolean)
 
-;; Various variables.
+;;; Various variables.
 
 (defvar imap-fetch-data-hook nil
   "Hooks called after receiving each FETCH response.")
@@ -316,7 +316,9 @@ imap-logout-timeout
 an application program that uses this module specifies on a per-server
 basis.")
 
-;; Internal constants.  Change these and die.
+;;; Internal constants
+
+;; Change these and die.
 
 (defconst imap-default-port 143)
 (defconst imap-default-ssl-port 993)
@@ -348,7 +350,7 @@ imap-local-variables
 (defconst imap-log-buffer "*imap-log*")
 (defconst imap-debug-buffer "*imap-debug*")
 
-;; Internal variables.
+;;; Internal variables.
 
 (defvar imap-stream nil)
 (defvar imap-auth nil)
@@ -437,7 +439,7 @@ imap-enable-exchange-bug-workaround
 canonical form fails.")
 
 \f
-;; Utility functions:
+;;; Utility functions
 
 (defun imap-remassoc (key alist)
   "Delete by side effect any elements of ALIST whose car is `equal' to KEY.
@@ -489,7 +491,8 @@ imap-error-text
     (nth 3 (car imap-failed-tags))))
 
 \f
-;; Server functions; stream stuff:
+;;; Server functions
+;;;; Stream functions
 
 (defun imap-log (string-or-buffer)
   (when imap-log
@@ -747,7 +750,7 @@ imap-starttls-open
     (message "imap: Connecting with STARTTLS...%s" (if done "done" "failed"))
     done))
 
-;; Server functions; authenticator stuff:
+;;;; Authenticator functions
 
 (defun imap-interactive-login (buffer loginfunc)
   "Login to server in BUFFER.
@@ -969,7 +972,7 @@ imap-digest-md5-auth
 	 (imap-send-command-1 "")
 	 (imap-ok-p (imap-wait-for-tag tag)))))))
 
-;; Server functions:
+;;; Server functions
 
 (defun imap-open-1 (buffer)
   (with-current-buffer buffer
@@ -1228,7 +1231,7 @@ imap-logout-wait
     (imap-send-command-wait "LOGOUT" buffer)))
 
 \f
-;; Mailbox functions:
+;;; Mailbox functions
 
 (defun imap-mailbox-put (propname value &optional mailbox buffer)
   (with-current-buffer (or buffer (current-buffer))
@@ -1520,7 +1523,7 @@ imap-mailbox-acl-delete
 				     identifier))))))
 
 \f
-;; Message functions:
+;;; Message functions
 
 (defun imap-current-message (&optional buffer)
   (with-current-buffer (or buffer (current-buffer))
@@ -1832,7 +1835,7 @@ imap-envelope-from
 	       (if (aref from 0) ">"))))
 
 \f
-;; Internal functions.
+;;; Internal functions.
 
 (defun imap-add-callback (tag func)
   (setq imap-callbacks (append (list (cons tag func)) imap-callbacks)))
@@ -1969,7 +1972,7 @@ imap-arrival-filter
 	      (delete-region (point-min) (point-max)))))))))
 
 \f
-;; Imap parser.
+;;; Imap parser.
 
 (defsubst imap-forward ()
   (or (eobp) (forward-char)))
@@ -2850,6 +2853,8 @@ imap-parse-body
 	(imap-forward)
 	(nreverse body)))))
 
+;;; Debug
+
 (when imap-debug			; (untrace-all)
   (require 'trace)
   (buffer-disable-undo (get-buffer-create imap-debug-buffer))
-- 
2.26.0

bug#42397: [PATCH 13/14] * lisp/font-lock.el: Split the Commentary into subsections.

[Jonas Bernoulli]

The "Commentary" was already split into multiple sections, but
these sections where on the same level as "Commentary" itself,
which is less convenient for users of `outline-minor-mode'.
---
 lisp/font-lock.el | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/lisp/font-lock.el b/lisp/font-lock.el
index 5cda4a693d..cf88100ab5 100644
--- a/lisp/font-lock.el
+++ b/lisp/font-lock.el
@@ -51,7 +51,7 @@
 ;; also the variable `font-lock-maximum-size'.  Support modes for Font Lock
 ;; mode can be used to speed up Font Lock mode.  See `font-lock-support-mode'.
 \f
-;;; How Font Lock mode fontifies:
+;;;; How Font Lock mode fontifies:
 
 ;; When Font Lock mode is turned on in a buffer, it (a) fontifies the entire
 ;; buffer and (b) installs one of its fontification functions on one of the
@@ -96,7 +96,7 @@
 ;; some syntactic parsers for common languages and a son-of-font-lock.el could
 ;; use them rather then relying so heavily on the keyword (regexp) pass.
 
-;;; How Font Lock mode supports modes or is supported by modes:
+;;;; How Font Lock mode supports modes or is supported by modes:
 
 ;; Modes that support Font Lock mode do so by defining one or more variables
 ;; whose values specify the fontification.  Font Lock mode knows of these
@@ -112,7 +112,7 @@
 ;; Font Lock mode fontification behavior can be modified in a number of ways.
 ;; See the below comments and the comments distributed throughout this file.
 
-;;; Constructing patterns:
+;;;; Constructing patterns:
 
 ;; See the documentation for the variable `font-lock-keywords'.
 ;;
@@ -120,7 +120,7 @@
 ;; `font-lock-syntactic-keywords' can be generated via the function
 ;; `regexp-opt'.
 
-;;; Adding patterns for modes that already support Font Lock:
+;;;; Adding patterns for modes that already support Font Lock:
 
 ;; Though Font Lock highlighting patterns already exist for many modes, it's
 ;; likely there's something that you want fontified that currently isn't, even
@@ -135,7 +135,7 @@
 ;; other variables.  For example, additional C types can be specified via the
 ;; variable `c-font-lock-extra-types'.
 
-;;; Adding patterns for modes that do not support Font Lock:
+;;;; Adding patterns for modes that do not support Font Lock:
 
 ;; Not all modes support Font Lock mode.  If you (as a user of the mode) add
 ;; patterns for a new mode, you must define in your ~/.emacs a variable or
@@ -155,7 +155,7 @@
 ;;     (set (make-local-variable 'font-lock-defaults)
 ;;          '(foo-font-lock-keywords t))))
 
-;;; Adding Font Lock support for modes:
+;;;; Adding Font Lock support for modes:
 
 ;; Of course, it would be better that the mode already supports Font Lock mode.
 ;; The package author would do something similar to above.  The mode must
-- 
2.26.0

bug#42397: [PATCH 14/14] * lisp/font-lock.el: No longer mark each end of a section explicitly.

[Jonas Bernoulli]

Each section ends right before the following section begins.  It is
therefore unnecessary to mark the end of sections.  The end of section
headings made the result of invoking `outline-hide-sublevels' much
less readable than what we get after this change.
---
 lisp/font-lock.el | 10 +---------
 1 file changed, 1 insertion(+), 9 deletions(-)

diff --git a/lisp/font-lock.el b/lisp/font-lock.el
index cf88100ab5..2d2a7e0f7b 100644
--- a/lisp/font-lock.el
+++ b/lisp/font-lock.el
@@ -986,7 +986,6 @@ font-lock-after-unfontify-buffer
 	((bound-and-true-p lazy-lock-mode)
 	 (lazy-lock-after-unfontify-buffer))))
 
-;;; End of Font Lock Support mode.
 \f
 ;;; Fontification functions.
 
@@ -1393,7 +1392,6 @@ font-lock-fontify-block
 	      (font-lock-fontify-region (point) (mark)))
 	  ((error quit) (message "Fontifying block...%s" error-data)))))))
 
-;;; End of Fontification functions.
 \f
 ;;; Additional text property functions.
 
@@ -1485,7 +1483,6 @@ font-lock--remove-face-from-text-property
 		      (put-text-property start next prop new object))))))
       (setq start (text-property-not-all next end prop nil object)))))
 
-;;; End of Additional text property functions.
 \f
 ;;; Syntactic regexp fontification functions.
 
@@ -1591,7 +1588,6 @@ font-lock-fontify-syntactic-keywords-region
 	  (setq highlights (cdr highlights))))
       (setq keywords (cdr keywords)))))
 
-;;; End of Syntactic regexp fontification functions.
 \f
 ;;; Syntactic fontification functions.
 
@@ -1650,7 +1646,6 @@ font-lock-fontify-syntactically-region
         (setq state (parse-partial-sexp (point) end nil nil state
 				        'syntax-table))))))
 
-;;; End of Syntactic fontification functions.
 \f
 ;;; Keyword regexp fontification functions.
 
@@ -1784,9 +1779,8 @@ font-lock-fontify-keywords-region
       (setq keywords (cdr keywords)))
     (set-marker pos nil)))
 
-;;; End of Keyword regexp fontification functions.
 \f
-;; Various functions.
+;;; Various functions.
 
 (defun font-lock-compile-keywords (keywords &optional syntactic-keywords)
   "Compile KEYWORDS into the form (t KEYWORDS COMPILED...)
@@ -2102,7 +2096,6 @@ font-lock-regexp-grouping-construct
   "Font Lock mode face used to highlight grouping constructs in Lisp regexps."
   :group 'font-lock-faces)
 
-;;; End of Color etc. support.
 \f
 ;;; Menu support.
 
@@ -2204,7 +2197,6 @@ font-lock-regexp-grouping-construct
 ;;  ;; Deactivate less/more fontification entries.
 ;;  (setq font-lock-fontify-level nil))
 
-;;; End of Menu support.
 \f
 ;;; Various regexp information shared by several modes.
 ;; ;; Information specific to a single mode should go in its load library.
-- 
2.26.0

bug#42397: [PATCH 14/14] * lisp/font-lock.el: No longer mark each end of a section explicitly.

[Eli Zaretskii]

> Date: Thu, 16 Jul 2020 16:54:56 +0200
> Cc: jonas@bernoul.li
> 
> Each section ends right before the following section begins.  It is
> therefore unnecessary to mark the end of sections.  The end of section
> headings made the result of invoking `outline-hide-sublevels' much
> less readable than what we get after this change.

It might sometimes be useful if a section is very long, and the file
isn't placed under Outline.  If we are going to remove these as a
matter of policy, I think we should first discuss that on emacs-devel,
to see if there are people who might want those "end" markers.

bug#42397: [PATCH 06/14] * lisp/emacs-lisp/eldoc.el (eldoc-minibuffer-message): Fix indentation.

[Eli Zaretskii]

> From: Jonas Bernoulli <jonas@bernoul.li>
> Date: Thu, 16 Jul 2020 16:54:48 +0200
> Cc: jonas@bernoul.li
> 
> ---
>  lisp/emacs-lisp/eldoc.el | 14 +++++++-------
>  1 file changed, 7 insertions(+), 7 deletions(-)

When you fix indentation, make sure to use our .dir-locals.el
settings, to produce canonical whitespace.  In this case, we use only
spaces in Lisp files, not TABs and spaces.

Thanks.

P.S. Why do you CC yourself on every message?  It causes the Reply to
name you twice, so you will get 2 copies of them.  Is this what you
want?

bug#42397: [PATCH 06/14] * lisp/emacs-lisp/eldoc.el (eldoc-minibuffer-message): Fix indentation.

[Jonas Bernoulli]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Jonas Bernoulli <jonas@bernoul.li>
>> Date: Thu, 16 Jul 2020 16:54:48 +0200
>> Cc: jonas@bernoul.li
>> 
>> ---
>>  lisp/emacs-lisp/eldoc.el | 14 +++++++-------
>>  1 file changed, 7 insertions(+), 7 deletions(-)
>
> When you fix indentation, make sure to use our .dir-locals.el
> settings, to produce canonical whitespace.  In this case, we use only
> spaces in Lisp files, not TABs and spaces.

Gladly!  In fact while I was just taking a bath, I was drafting
a message in my head explaining why such a file should be added!

The reason that I was not aware that the local value is explicitly set
now, is (aside from simply not having checked) that the indentation in
Emacs is so inconsistent that I did occur to me that it might be set
after all.

I did just dig a bit and found bug#20323.  So it turns out we did
eventually set the variable, but we did not adjust existing code to
conform to that setting.

I do care a lot about consistency so I did in fact look at the
surrounding code to determine what style to use.  It was not an easy
decision in this case because both styles are being within this one
function!  I went with tabs because more existing lines did that. ;D

I'll change that before pushing obviously.  And since this commit is
already about *fixing* whitespace, I will also *adjust* the remaining
lines to use the preferred style.

It might be time to revisit the decision to not fix indentation in
bulk.  Since version Git 2.23 "git blame" can ignore the effect and
presence of certain commits.  We could make the whitespace change in
one huge commit and then ignore that commit using the Git variable
"blame.ignoreRevsFile".

> P.S. Why do you CC yourself on every message?  It causes the Reply to
> name you twice, so you will get 2 copies of them.  Is this what you
> want?

Hmmm.  Because that's not the behavior I experience.  Without that
explicit CC I get the message zero times (git send-email does not put
them into the local maildir and debbugs does not appear to be echoing my
own messages back to me).  With that CC I get the messages exactly once.
Maybe you experience something else because debbugs sends *all* message
to you, not just your own?

bug#42397: [PATCH 06/14] * lisp/emacs-lisp/eldoc.el (eldoc-minibuffer-message): Fix indentation.

[Robert Pluim]

>>>>> On Thu, 16 Jul 2020 18:56:20 +0200, Jonas Bernoulli <jonas@bernoul.li> said:
    >> P.S. Why do you CC yourself on every message?  It causes the Reply to
    >> name you twice, so you will get 2 copies of them.  Is this what you
    >> want?

    Jonas> Hmmm.  Because that's not the behavior I experience.  Without that
    Jonas> explicit CC I get the message zero times (git send-email does not put
    Jonas> them into the local maildir and debbugs does not appear to be echoing my
    Jonas> own messages back to me).  With that CC I get the messages exactly once.
    Jonas> Maybe you experience something else because debbugs sends *all* message
    Jonas> to you, not just your own?

On a related note: would you consider using '--no-chain-reply-to' [1]?
Your patch series march off the right edge of my screen :-)

Robert

Footnotes:
[1]  I think thatʼs the right one; the git documentation of that
     option makes my head hurt.

bug#42397: [PATCH 06/14] * lisp/emacs-lisp/eldoc.el (eldoc-minibuffer-message): Fix indentation.

[Jonas Bernoulli]

Robert Pluim <rpluim@gmail.com> writes:

> On a related note: would you consider using '--no-chain-reply-to' [1]?
> Your patch series march off the right edge of my screen :-)

And again, that was intentional.  I actually used "--chain-reply-to"
explicitly because when I didn't then mails were displayed in the wrong
order in the web interface.  Though thinking about that again, I now
think that wasn't actually the reason.  Maybe.

The next patch series I am going to send without that argument.  Since
I don't have my own private debbugs instance, I have to do these
experiments in public.  On the plus side, once I have arrived at a
suitable incarnation will blog about it and/or teach Magit about it.

For this series I used:

,----
| git send-email 0000-cover-letter.patch \
|   --to=bug-gnu-emacs@gnu.org \
|   --suppress-cc=all --cc=jonas@bernoul.li &&
| rm 0000-cover-letter.patch
| 
| BUG_ID=42397 # Check inbox to determine that value
| 
| git send-email 00* \
|   --to=$BUG_ID@debbugs.gnu.org \
|   --suppress-cc=all --cc=jonas@bernoul.li \
|   --thread \
|   --chain-reply-to \                   # make sure order is correct
|   --batch-size=1 --relogin-delay=5     # make sure some other way
`----

Unfortunately I did not use:

,----
| # Check inbox to determine this value as well:
| FIRST_MSG_ID="<20200716144707.16857-1-jonas@bernoul.li>"
| 
| git ... --in-reply-to=$FIRST_MSG_ID
`----

I used the "This message is a test" mail to try whether using that
argument helps.  It does.

> Robert
>
> Footnotes:
> [1]  I think thatʼs the right one; the git documentation of that
>      option makes my head hurt.

It's a bit weird.

So far I am not a fan of debbugs and its documentation either. ;D

Anyway... I am afraid I'll have to keep experimenting publicly for
a while, but please feel free to point out any observations; they
might speed up things.

     Jonas

bug#42397: [PATCH 06/14] * lisp/emacs-lisp/eldoc.el (eldoc-minibuffer-message): Fix indentation.

[Noam Postavsky]

On Thu, 16 Jul 2020 at 13:55, Jonas Bernoulli <jonas@bernoul.li> wrote:
>
> Robert Pluim <rpluim@gmail.com> writes:
>
> > On a related note: would you consider using '--no-chain-reply-to' [1]?
> > Your patch series march off the right edge of my screen :-)
>
> And again, that was intentional.  I actually used "--chain-reply-to"
> explicitly because when I didn't then mails were displayed in the wrong
> order in the web interface.  Though thinking about that again, I now
> think that wasn't actually the reason.  Maybe.

As far as I know, the order of display in the web interface is based
solely on the order of arrival, not the headers (chaining does help
for the debbugs.el interface, which shows things properly threaded.
Except it can also hurt, as Robert points out).

bug#42397: [PATCH 06/14] * lisp/emacs-lisp/eldoc.el (eldoc-minibuffer-message): Fix indentation.

[Jonas Bernoulli]

Noam Postavsky <npostavs@gmail.com> writes:

> On Thu, 16 Jul 2020 at 13:55, Jonas Bernoulli <jonas@bernoul.li> wrote:
>>
>> Robert Pluim <rpluim@gmail.com> writes:
>>
>> > On a related note: would you consider using '--no-chain-reply-to' [1]?
>> > Your patch series march off the right edge of my screen :-)
>>
>> And again, that was intentional.  I actually used "--chain-reply-to"
>> explicitly because when I didn't then mails were displayed in the wrong
>> order in the web interface.  Though thinking about that again, I now
>> think that wasn't actually the reason.  Maybe.
>
> As far as I know, the order of display in the web interface is based
> solely on the order of arrival,

My limited experience seems to confirm that.  That's pretty nasty IMO.

> not the headers (chaining does help
> for the debbugs.el interface, which shows things properly threaded.
> Except it can also hurt, as Robert points out).

Unfortunately my experiments so far have not been very scientific and I
will have to repeat some of them.  Next thing I will try is to use only

1) --batch-size=1 --relogin-delay=5

but not

2)  --chain-reply-to

If it turns out that (1) by itself works reliable, then I will gladly
drop (2).

bug#42397: [PATCH 06/14] * lisp/emacs-lisp/eldoc.el (eldoc-minibuffer-message): Fix indentation.

[Eli Zaretskii]

> From: Jonas Bernoulli <jonas@bernoul.li>
> Cc: 42397@debbugs.gnu.org
> Date: Thu, 16 Jul 2020 18:56:20 +0200
> 
> I did just dig a bit and found bug#20323.  So it turns out we did
> eventually set the variable, but we did not adjust existing code to
> conform to that setting.

Yes, because doing that would just cause a lot of "no-op" changes,
which affect the output of 'annotate', but otherwise have no real
gains.

Instead, we tell people to modify the whitespace as part of changes to
the code they do anyway.  This way, the attribution stays significant,
and we eventually will get to our goal, albeit slower.

> I'll change that before pushing obviously.  And since this commit is
> already about *fixing* whitespace, I will also *adjust* the remaining
> lines to use the preferred style.

Please only change the whitespace where you do make changes, for the
reasons mentioned above.

> It might be time to revisit the decision to not fix indentation in
> bulk.  Since version Git 2.23 "git blame" can ignore the effect and
> presence of certain commits.

I don't think we want to assume 2.23 yet.  I still use 2.10 on one of
my machines, and fencepost.gnu.org has 2.3.5(!).

> > P.S. Why do you CC yourself on every message?  It causes the Reply to
> > name you twice, so you will get 2 copies of them.  Is this what you
> > want?
> 
> Hmmm.  Because that's not the behavior I experience.  Without that
> explicit CC I get the message zero times (git send-email does not put
> them into the local maildir and debbugs does not appear to be echoing my
> own messages back to me).  With that CC I get the messages exactly once.
> Maybe you experience something else because debbugs sends *all* message
> to you, not just your own?

I was talking about the responses.  The response goes to the address
in From and also to those in CC.  Thus, responding to messages sent by
you will always send you a copy, because you appear in From.

bug#42397: [PATCH 06/14] * lisp/emacs-lisp/eldoc.el (eldoc-minibuffer-message): Fix indentation.

[Jonas Bernoulli]

Eli Zaretskii <eliz@gnu.org> writes:

> Instead, we tell people to modify the whitespace as part of changes to
> the code they do anyway.  This way, the attribution stays significant,
> and we eventually will get to our goal, albeit slower.
>
>> I'll change that before pushing obviously.  And since this commit is
>> already about *fixing* whitespace, I will also *adjust* the remaining
>> lines to use the preferred style.
>
> Please only change the whitespace where you do make changes, for the
> reasons mentioned above.

Just to make sure: I was talking about potentially changing other lines
*within the same function* that I am already touching, and that is what
I am not supposed to do, right?

Okay I will commit that rule to memory.

>> It might be time to revisit the decision to not fix indentation in
>> bulk.  Since version Git 2.23 "git blame" can ignore the effect and
>> presence of certain commits.
>
> I don't think we want to assume 2.23 yet.  I still use 2.10 on one of
> my machines, and fencepost.gnu.org has 2.3.5(!).

One day, one day.

>> > P.S. Why do you CC yourself on every message?  It causes the Reply to
>> > name you twice, so you will get 2 copies of them.  Is this what you
>> > want?
>> 
>> Hmmm.  Because that's not the behavior I experience.  Without that
>> explicit CC I get the message zero times (git send-email does not put
>> them into the local maildir and debbugs does not appear to be echoing my
>> own messages back to me).  With that CC I get the messages exactly once.
>> Maybe you experience something else because debbugs sends *all* message
>> to you, not just your own?
>
> I was talking about the responses.  The response goes to the address
> in From and also to those in CC.  Thus, responding to messages sent by
> you will always send you a copy, because you appear in From.

Are you talking about the responses that other humans write?  E.g when
you reply to

  From: Jonas, Cc: Jonas

and you do a "reply all", then that results in

  To: Jonas, Cc: Jonas

Since I cannot find such a message, I assume you manually modified those
messages before sending.  Otherwise please give me an example of such a
message, so that I can inspect it.

My current understanding is that even if this is the case I don't really
have a choice.  I need the messages that I send using "git send-email"
to appear in my email client.  That only happens if I CC the message to
me.  If that results in the replies to those messages arriving twice in
my inbox, then that is unfortunate but the lesser evil.  (But please
enlighten me if I still get something wrong.)

bug#42397: [PATCH 06/14] * lisp/emacs-lisp/eldoc.el (eldoc-minibuffer-message): Fix indentation.

[Eli Zaretskii]

> From: Jonas Bernoulli <jonas@bernoul.li>
> Cc: 42397@debbugs.gnu.org
> Date: Thu, 16 Jul 2020 23:52:44 +0200
> 
> >> I'll change that before pushing obviously.  And since this commit is
> >> already about *fixing* whitespace, I will also *adjust* the remaining
> >> lines to use the preferred style.
> >
> > Please only change the whitespace where you do make changes, for the
> > reasons mentioned above.
> 
> Just to make sure: I was talking about potentially changing other lines
> *within the same function* that I am already touching, and that is what
> I am not supposed to do, right?

Well, if those other lines are close to the ones you modify (i.e. the
function is small enough), perhaps you can do that as well.  It's a
judgment call: the important thing is not to make too many changes
that are outside of the main change's locus and only change the
whitespace.

> >> It might be time to revisit the decision to not fix indentation in
> >> bulk.  Since version Git 2.23 "git blame" can ignore the effect and
> >> presence of certain commits.
> >
> > I don't think we want to assume 2.23 yet.  I still use 2.10 on one of
> > my machines, and fencepost.gnu.org has 2.3.5(!).
> 
> One day, one day.

Yes, definitely.

> > I was talking about the responses.  The response goes to the address
> > in From and also to those in CC.  Thus, responding to messages sent by
> > you will always send you a copy, because you appear in From.
> 
> Are you talking about the responses that other humans write?  E.g when
> you reply to
> 
>   From: Jonas, Cc: Jonas
> 
> and you do a "reply all", then that results in
> 
>   To: Jonas, Cc: Jonas

Yes.

> Since I cannot find such a message, I assume you manually modified those
> messages before sending.

Right.  And that is a mild annoyance, because it makes responding
slower, and I need to pay attention to the address headers, something
I'd rather not do.

> My current understanding is that even if this is the case I don't really
> have a choice.  I need the messages that I send using "git send-email"
> to appear in my email client.  That only happens if I CC the message to
> me.  If that results in the replies to those messages arriving twice in
> my inbox, then that is unfortunate but the lesser evil.  (But please
> enlighten me if I still get something wrong.)

Can't you use BCC for that?  (I'm not familiar with "git send-email"
enough to tell if this is possible.)

bug#42397: [PATCH 06/14] * lisp/emacs-lisp/eldoc.el (eldoc-minibuffer-message): Fix indentation.

[Jonas Bernoulli]

Eli Zaretskii <eliz@gnu.org> writes:

>> Since I cannot find such a message, I assume you manually modified those
>> messages before sending.
>
> Right.  And that is a mild annoyance, because it makes responding
> slower, and I need to pay attention to the address headers, something
> I'd rather not do.

Sorry about that.

> Can't you use BCC for that?  (I'm not familiar with "git send-email"
> enough to tell if this is possible.)

Duh! That's what I should have done to begin with.

bug#42397: [PATCH 06/14] * lisp/emacs-lisp/eldoc.el (eldoc-minibuffer-message): Fix indentation.

[Basil L. Contovounesios]

Jonas Bernoulli <jonas@bernoul.li> writes:

> ---
>  lisp/emacs-lisp/eldoc.el | 14 +++++++-------
>  1 file changed, 7 insertions(+), 7 deletions(-)
>
> diff --git a/lisp/emacs-lisp/eldoc.el b/lisp/emacs-lisp/eldoc.el
> index 510dff9ed0..90dce4a317 100644
> --- a/lisp/emacs-lisp/eldoc.el
> +++ b/lisp/emacs-lisp/eldoc.el
> @@ -285,13 +285,13 @@ eldoc-minibuffer-message
>  	     (or (window-in-direction 'above (minibuffer-window))
>  		 (minibuffer-selected-window)
>  		 (get-largest-window)))
> -    (when mode-line-format
> -	  (unless (and (listp mode-line-format)
> -		       (assq 'eldoc-mode-line-string mode-line-format))
> -	    (setq mode-line-format
> -		  (list "" '(eldoc-mode-line-string
> -			     (" " eldoc-mode-line-string " "))
> -			mode-line-format))))
> +	  (when mode-line-format
> +	    (unless (and (listp mode-line-format)
> +			 (assq 'eldoc-mode-line-string mode-line-format))
> +	      (setq mode-line-format
> +		    (list "" '(eldoc-mode-line-string
> +			       (" " eldoc-mode-line-string " "))
> +			  mode-line-format))))

You can avoid reindenting this whole block by merging the conditions of
the redundantly nested when and unless:

  (unless (if (consp mode-line-format)
              (assq 'eldoc-mode-line-string mode-line-format)
            (not mode-line-format))
    (setq mode-line-format
          (list "" '(eldoc-mode-line-string
                     (" " eldoc-mode-line-string " "))
                mode-line-format)))

or similar.

>            (setq eldoc-mode-line-string
>                  (when (stringp format-string)
>                    (apply #'format-message format-string args)))

Thanks,

-- 
Basil

bug#42397: [PATCH 06/14] * lisp/emacs-lisp/eldoc.el (eldoc-minibuffer-message): Fix indentation.

[Jonas Bernoulli]

"Basil L. Contovounesios" <contovob@tcd.ie> writes:

> Jonas Bernoulli <jonas@bernoul.li> writes:

>> +	  (when mode-line-format
>> +	    (unless (and (listp mode-line-format)
>> +			 (assq 'eldoc-mode-line-string mode-line-format))
>> +	      (setq mode-line-format ...)))
>
> You can avoid reindenting this whole block by merging the conditions of
> the redundantly nested when and unless:
>
>   (unless (if (consp mode-line-format)
>               (assq 'eldoc-mode-line-string mode-line-format)
>             (not mode-line-format))
>     (setq mode-line-format ...))

I suppose; but IMO this variant is trying to hard to be smart.

> or similar.

I think I will go with:

  (when (and mode-line-format
             (not (and (listp mode-line-format)
                       (assq 'eldoc-mode-line-string mode-line-format))))
    (setq mode-line-format ...))

bug#42397: [PATCH 03/14] ; * lisp/epg.el (epg-no-data-reason-alist): Fix typo in message.

[Eli Zaretskii]

> From: Jonas Bernoulli <jonas@bernoul.li>
> Date: Thu, 16 Jul 2020 16:54:45 +0200
> Cc: jonas@bernoul.li
> 
> ---
>  lisp/epg.el | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/lisp/epg.el b/lisp/epg.el
> index c10eb4f06c..2e092acc6a 100644
> --- a/lisp/epg.el
> +++ b/lisp/epg.el
> @@ -123,7 +123,7 @@ epg-import-problem-reason-alist
>  
>  (defconst epg-no-data-reason-alist
>    '((1 . "No armored data")
> -    (2 . "Expected a packet but did not found one")
> +    (2 . "Expected a packet but did not find one")
>      (3 . "Invalid packet found, this may indicate a non OpenPGP message")
>      (4 . "Signature expected but not found")))

Thanks.

There's no need to post typo corrections for review, you can simply go
ahead and push.

bug#42397: [PATCH 03/14] ; * lisp/epg.el (epg-no-data-reason-alist): Fix typo in message.

[Jonas Bernoulli]

Eli Zaretskii <eliz@gnu.org> writes:
> There's no need to post typo corrections for review, you can simply go
> ahead and push.

Okay, will do.

bug#42397: [PATCH 02/14] ; * lisp/epg.el (epg-signature-to-string): Tiny refactor.

[Robert Pluim]

>>>>> On Thu, 16 Jul 2020 16:54:44 +0200, Jonas Bernoulli <jonas@bernoul.li> said:

    Jonas> `concat' treats arguments that are nil as if they were empty strings.
    Jonas> We therefore do not have to write (if TEST THEN "") and can just use
    Jonas> (and TEST THEN).

Or (if TEST THEN), but I guess thatʼs just a matter of preferred style.

bug#42397: [PATCH 02/14] ; * lisp/epg.el (epg-signature-to-string): Tiny refactor.

[Jonas Bernoulli]

Robert Pluim <rpluim@gmail.com> writes:

>>>>>> On Thu, 16 Jul 2020 16:54:44 +0200, Jonas Bernoulli <jonas@bernoul.li> said:
>
>     Jonas> `concat' treats arguments that are nil as if they were empty strings.
>     Jonas> We therefore do not have to write (if TEST THEN "") and can just use
>     Jonas> (and TEST THEN).
>
> Or (if TEST THEN), but I guess thatʼs just a matter of preferred style.

Indeed. I am aware that at least some of Emacs' developers prefer
to use `if' always, but I always use "when" when there is no else
and "and" (instead of "when") when the returned value is used.  I
can live with other people doing it differently, but I don't like
it.

bug#42397: [PATCH 01/14] ; * lisp/epg.el (epg-signature-to-string): Use cl-case.

[Robert Pluim]

>>>>> On Thu, 16 Jul 2020 16:54:43 +0200, Jonas Bernoulli <jonas@bernoul.li> said:

    Jonas> In this case we can greatly increase readability by using `cl-case'
    Jonas> instead of `cond'.
    Jonas> ---
    Jonas>  lisp/epg.el | 19 +++++++------------
    Jonas>  1 file changed, 7 insertions(+), 12 deletions(-)

    Jonas> diff --git a/lisp/epg.el b/lisp/epg.el
    Jonas> index 222fd913e1..e97db65b60 100644
    Jonas> --- a/lisp/epg.el
    Jonas> +++ b/lisp/epg.el
    Jonas> @@ -404,18 +404,13 @@ epg-signature-to-string
    Jonas>  	 (pubkey-algorithm (epg-signature-pubkey-algorithm signature))
    Jonas>  	 (key-id (epg-signature-key-id signature)))
    Jonas>      (concat
    Jonas> -     (cond ((eq (epg-signature-status signature) 'good)
    Jonas> -	    "Good signature from ")
    Jonas> -	   ((eq (epg-signature-status signature) 'bad)
    Jonas> -	    "Bad signature from ")
    Jonas> -	   ((eq (epg-signature-status signature) 'expired)
    Jonas> -	    "Expired signature from ")
    Jonas> -	   ((eq (epg-signature-status signature) 'expired-key)
    Jonas> -	    "Signature made by expired key ")
    Jonas> -	   ((eq (epg-signature-status signature) 'revoked-key)
    Jonas> -	    "Signature made by revoked key ")
    Jonas> -	   ((eq (epg-signature-status signature) 'no-pubkey)
    Jonas> -	    "No public key for "))
    Jonas> +     (cl-case signature
    Jonas> +       (good "Good signature from ")
    Jonas> +       (bad  "Bad signature from ")
    Jonas> +       (expired "Expired signature from ")
    Jonas> +       (expired-key "Signature made by expired key ")
    Jonas> +       (revoked-key "Signature made by revoked key ")
    Jonas> +       (no-pubkey "No public key for "))

Did you drop the `epg-signature-status' accessor on purpose here?

Robert

bug#42397: [PATCH 01/14] ; * lisp/epg.el (epg-signature-to-string): Use cl-case.

[Jonas Bernoulli]

> Did you drop the `epg-signature-status' accessor on purpose here?

Eeeep!  No.  Thanks for review!

bug#42397: This message is a test

[Jonas Bernoulli]

[Ignore this particular message (only).  I am testing something.]

bug#42397: [PATCH 00/14] Use outline headings and some cosmetics

[Drew Adams]

I thought we had a pretty standard header format.
I've been respecting that for decades in my own
libraries.  Now it's changed?

My understanding has been:

3 ; for the first header line.
3 ; for a ;;; Commentary: line.
3 ; for a ;;; Change Log: line.  (Used to be Chang log.)
3 ; for a ;;; Code: line.

More than 3 ; for any "separator" line.

2 ; for all other header lines.
____

And 3 ; for the file footer.  E.g.:

;;; foo-lib.el ends here
____

And within the code, whatever you want, per
convention (3 for major, 2 for minor, 1 at eol).
____

Further, I thought the convention called for
2 SPC after the initial 3 ; or 2 ;, except
for 4 SPC before the first Commentary text,
i.e., the file description.  E.g.:

;;; Commentary:
;;
;;    Here is a one-line library description.
;;
;;  Here are any commentary details that might
;;  be present - anything at all.
____

Dunno whether such a convention is still
stated somewhere, but I'm pretty sure it
was in place in the past.

bug#42397: [PATCH 00/14] Use outline headings and some cosmetics

[Eli Zaretskii]

> Date: Thu, 16 Jul 2020 08:12:24 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> I thought we had a pretty standard header format.
> I've been respecting that for decades in my own
> libraries.  Now it's changed?

You have a point there.

Jonas, please compare what you propose with the tips we have in the
"Comment Tips" node of the ELisp manual, and seed if there's any
discrepancies.  If there are, I think we should discuss first (on
emacs-devel).

Thanks.

bug#42397: [PATCH 00/14] Use outline headings and some cosmetics

[Jonas Bernoulli]

Eli Zaretskii <eliz@gnu.org> writes:

>> Date: Thu, 16 Jul 2020 08:12:24 -0700 (PDT)
>> From: Drew Adams <drew.adams@oracle.com>
>> 
>> I thought we had a pretty standard header format.

I thought so too... and that I was following them.

Maybe it is just that our respective selective memory
focuses on a different aspect?

>> I've been respecting that for decades in my own
>> libraries.  Now it's changed?
>
> You have a point there.
>
> Jonas, please compare what you propose with the tips we have in the
> "Comment Tips" node of the ELisp manual, and seed if there's any
> discrepancies.  If there are, I think we should discuss first (on
> emacs-devel).

After reading (info "(elisp) Comment Tips") again, I think I remembered
correctly.  Quoting the ;;; entry in full:

> ‘;;;’
>      Comments that start with three semicolons, ‘;;;’, should start at
>      the left margin.  We use them for comments which should be
>      considered a heading by Outline minor mode.  By default, comments
>      starting with at least three semicolons (followed by a single space
>      and a non-whitespace character) are considered headings, comments
>      starting with two or fewer are not.  Historically, triple-semicolon
>      comments have also been used for commenting out lines within a
>      function, but this use is discouraged.
> 
>      When commenting out entire functions, use two semicolons.

This says that three semicolons are for "headings".
There is no mention of "separators".

And the only node to older conventions is about using three semicolons
to comment out parts of functions.

It seems pretty clear to me that the use of three or more semicolons is
now reserved for (outline) headings.  Of course there are also autoload
coolies but those don't have a space after the semicolons.

Do you still think this has to be discussed on emacs-devel?

Normally I don't divide the ";;; Commentary:" section into multiple
sub-sections.  In this particular case I have done so because (a) it
is long (b) splitting into sibling sections, as was done before, seems
wrong to me.

Also note that I don't turn all the sections that contain code and
follow the ";;; Code:" heading into sub-sections of that section.  I
don't think the "Comment Tips" are clear on that matter but it seems
to me that they imply that I should do so.  If so, then I disagree
based on my experience.

Seeing this

,----
| ;;; foo.el --- Foo bar baz
| ;;; Commentary:...
| ;;; Code:...
| ;;; foo.el ends here
`----

is almost entirely useless (because almost the same for all libraries
that do it like this), whereas

,----
| ;;; foo.el --- Foo bar baz
| ;;; Commentary:...
| ;;; Code:...
| ;;; Options...
| ;;; List Mode...
| ;;; List Commands...
| ;;; Integrations
| ;;; foo.el ends here
`----

is very useful in my experience as it instantly gives a quick overview
of how the code is structured etc.

Ps: I have written a few packages to make `outline-minor-mode' a
    bit nicer: mainly `bicycle', but also `outline-minor-faces'
    and `backline'.

    https://github.com/tarsius/bicycle
    https://github.com/tarsius/outline-minor-faces
    https://github.com/tarsius/backline

bug#42397: [PATCH 00/14] Use outline headings and some cosmetics

[Eli Zaretskii]

> From: Jonas Bernoulli <jonas@bernoul.li>
> Cc: 42397@debbugs.gnu.org
> Date: Thu, 16 Jul 2020 20:34:51 +0200
> 
> > ‘;;;’
> >      Comments that start with three semicolons, ‘;;;’, should start at
> >      the left margin.  We use them for comments which should be
> >      considered a heading by Outline minor mode.  By default, comments
> >      starting with at least three semicolons (followed by a single space
> >      and a non-whitespace character) are considered headings, comments
> >      starting with two or fewer are not.  Historically, triple-semicolon
> >      comments have also been used for commenting out lines within a
> >      function, but this use is discouraged.
> > 
> >      When commenting out entire functions, use two semicolons.
> 
> This says that three semicolons are for "headings".
> There is no mention of "separators".

Right.  Unless by "separators" we allude to headings of what the
manual calls "major sections of a program", see below.

> It seems pretty clear to me that the use of three or more semicolons is
> now reserved for (outline) headings.  Of course there are also autoload
> coolies but those don't have a space after the semicolons.
> 
> Do you still think this has to be discussed on emacs-devel?

Not the 3 semicolon issue, no.  However, this part might need
discussing:

> Also note that I don't turn all the sections that contain code and
> follow the ";;; Code:" heading into sub-sections of that section.  I
> don't think the "Comment Tips" are clear on that matter but it seems
> to me that they imply that I should do so.

Yes, I think that's what the manual says.

> If so, then I disagree based on my experience.

I don't have a strong opinion on this, but if we agree to do it your
way, we should amend the manual.

> Seeing this
> 
> ,----
> | ;;; foo.el --- Foo bar baz
> | ;;; Commentary:...
> | ;;; Code:...
> | ;;; foo.el ends here
> `----
> 
> is almost entirely useless (because almost the same for all libraries
> that do it like this), whereas
> 
> ,----
> | ;;; foo.el --- Foo bar baz
> | ;;; Commentary:...
> | ;;; Code:...
> | ;;; Options...
> | ;;; List Mode...
> | ;;; List Commands...
> | ;;; Integrations
> | ;;; foo.el ends here
> `----
> 
> is very useful in my experience as it instantly gives a quick overview
> of how the code is structured etc.

But the above seems to say that Options, List Mode, List Commands
etc. are on the same level as Code, whereas in reality they are
subsections of Code, no?

Anyway, like I said: we should make the manual describe our
practices.  Are you saying that the subsections with 4 semicolons are
never actually used in Emacs?

bug#42397: [PATCH v2 00/16] Use outline headings and some cosmetics

[Jonas Bernoulli]

Here's v2.

I believe I have addressed all the feedback.

* Updated the heading conventions/tips in the manual to take the
  discussion that we had about "Code" on emacs-devel into account.

* Made "Code" section empty accordingly in commits that call for
  that.

* Adjusted the commit that removed some "end-of-section" headings to
  instead turn them into non-heading comments.  See respective commit.

* Fixed the regression pointed out by Robert.

* Drew's question has been answered.

* Took Basil's feedback into account.

* Making an effort to send the patches in a less noisy fashion this
  time around.

     Cheers,
     Jonas

Jonas Bernoulli (16):
  ; * lisp/epg.el (epg-signature-to-string): Use cl-case.
  ; * lisp/epg.el (epg-signature-to-string): Tiny refactor.
  ; * lisp/epg.el (epg-no-data-reason-alist): Fix typo in message.
  * lisp/epa.el (epa--derived-mode-p): Remove unnecessary alias.
  Split EasyPG libraries into outline sections
  Merge two conditions and fix indentation
  * lisp/progmodes/compile.el: Remove unnecessary comments.
  ; * lisp/whitespace.el: Capitalize "Code" section heading.
  * lisp/mail/smtpmail.el: Use outline headings.
  * test/src/emacs-module-tests.el: Use proper outline headings.
  * lisp/obsolete/longlines.el: Use proper outline headings.
  * lisp/net/imap.el: Use proper outline headings
  * lisp/font-lock.el: Split the Commentary into subsections.
  * lisp/font-lock.el: No longer use headings as end of section markers.
  ; * lisp/emacs-lisp/autoload.el: Begin summary line with three
    semicolons.
  Update section heading conventions for libraries

 doc/lispref/tips.texi          | 65 +++++++++++++++++++--------
 lisp/emacs-lisp/autoload.el    |  2 +-
 lisp/emacs-lisp/eldoc.el       |  8 ++--
 lisp/epa-dired.el              |  1 +
 lisp/epa-file.el               | 10 +++++
 lisp/epa-hook.el               |  1 +
 lisp/epa-mail.el               | 10 +++++
 lisp/epa.el                    | 38 ++++++++++------
 lisp/epg-config.el             |  7 +++
 lisp/epg.el                    | 80 ++++++++++++++++++++--------------
 lisp/font-lock.el              | 30 ++++++-------
 lisp/mail/smtpmail.el          | 10 +++--
 lisp/net/imap.el               | 30 ++++++++-----
 lisp/obsolete/longlines.el     | 17 ++++----
 lisp/progmodes/compile.el      |  2 -
 lisp/whitespace.el             |  2 +-
 test/src/emacs-module-tests.el | 21 +++------
 17 files changed, 208 insertions(+), 126 deletions(-)

-- 
2.28.0

bug#42397: [PATCH v2 01/16] ; * lisp/epg.el (epg-signature-to-string): Use cl-case.

[Jonas Bernoulli]

In this case we can greatly increase readability by using `cl-case'
instead of `cond'.
---
 lisp/epg.el | 19 +++++++------------
 1 file changed, 7 insertions(+), 12 deletions(-)

diff --git a/lisp/epg.el b/lisp/epg.el
index 5b90bc290a..65decf3cf5 100644
--- a/lisp/epg.el
+++ b/lisp/epg.el
@@ -404,18 +404,13 @@ epg-signature-to-string
 	 (pubkey-algorithm (epg-signature-pubkey-algorithm signature))
 	 (key-id (epg-signature-key-id signature)))
     (concat
-     (cond ((eq (epg-signature-status signature) 'good)
-	    "Good signature from ")
-	   ((eq (epg-signature-status signature) 'bad)
-	    "Bad signature from ")
-	   ((eq (epg-signature-status signature) 'expired)
-	    "Expired signature from ")
-	   ((eq (epg-signature-status signature) 'expired-key)
-	    "Signature made by expired key ")
-	   ((eq (epg-signature-status signature) 'revoked-key)
-	    "Signature made by revoked key ")
-	   ((eq (epg-signature-status signature) 'no-pubkey)
-	    "No public key for "))
+     (cl-case (epg-signature-status signature)
+       (good "Good signature from ")
+       (bad "Bad signature from ")
+       (expired "Expired signature from ")
+       (expired-key "Signature made by expired key ")
+       (revoked-key "Signature made by revoked key ")
+       (no-pubkey "No public key for "))
      key-id
      (if user-id
 	 (concat " "
-- 
2.28.0

bug#42397: [PATCH v2 02/16] ; * lisp/epg.el (epg-signature-to-string): Tiny refactor.

[Jonas Bernoulli]

`concat' treats arguments that are nil as if they were empty strings.
We therefore do not have to write (if TEST THEN "") and can just use
(and TEST THEN).
---
 lisp/epg.el | 32 ++++++++++++++------------------
 1 file changed, 14 insertions(+), 18 deletions(-)

diff --git a/lisp/epg.el b/lisp/epg.el
index 65decf3cf5..e53aa8caaa 100644
--- a/lisp/epg.el
+++ b/lisp/epg.el
@@ -412,24 +412,20 @@ epg-signature-to-string
        (revoked-key "Signature made by revoked key ")
        (no-pubkey "No public key for "))
      key-id
-     (if user-id
-	 (concat " "
-		 (if (stringp user-id)
-		     (epg--decode-percent-escape-as-utf-8 user-id)
-		   (epg-decode-dn user-id)))
-       "")
-     (if (epg-signature-validity signature)
-	 (format " (trust %s)"  (epg-signature-validity signature))
-       "")
-     (if (epg-signature-creation-time signature)
-	 (format-time-string " created at %Y-%m-%dT%T%z"
-			     (epg-signature-creation-time signature))
-       "")
-     (if pubkey-algorithm
-	 (concat " using "
-		 (or (cdr (assq pubkey-algorithm epg-pubkey-algorithm-alist))
-		     (format "(unknown algorithm %d)" pubkey-algorithm)))
-       ""))))
+     (and user-id
+	  (concat " "
+		  (if (stringp user-id)
+		      (epg--decode-percent-escape-as-utf-8 user-id)
+		    (epg-decode-dn user-id))))
+     (and (epg-signature-validity signature)
+	  (format " (trust %s)"  (epg-signature-validity signature)))
+     (and (epg-signature-creation-time signature)
+	  (format-time-string " created at %Y-%m-%dT%T%z"
+			      (epg-signature-creation-time signature)))
+     (and pubkey-algorithm
+	  (concat " using "
+		  (or (cdr (assq pubkey-algorithm epg-pubkey-algorithm-alist))
+		      (format "(unknown algorithm %d)" pubkey-algorithm)))))))
 
 (defun epg-verify-result-to-string (verify-result)
   "Convert VERIFY-RESULT to a human readable string."
-- 
2.28.0

bug#42397: [PATCH v2 03/16] ; * lisp/epg.el (epg-no-data-reason-alist): Fix typo in message.

[Jonas Bernoulli]

---
 lisp/epg.el | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lisp/epg.el b/lisp/epg.el
index e53aa8caaa..df79988c48 100644
--- a/lisp/epg.el
+++ b/lisp/epg.el
@@ -123,7 +123,7 @@ epg-import-problem-reason-alist
 
 (defconst epg-no-data-reason-alist
   '((1 . "No armored data")
-    (2 . "Expected a packet but did not found one")
+    (2 . "Expected a packet but did not find one")
     (3 . "Invalid packet found, this may indicate a non OpenPGP message")
     (4 . "Signature expected but not found")))
 
-- 
2.28.0

bug#42397: [PATCH v2 04/16] * lisp/epa.el (epa--derived-mode-p): Remove unnecessary alias.

[Jonas Bernoulli]

`derived-mode-p' was added twenty years ago in
6ad501012b9a9ddc26dd8ce1cef8332ee16d87df and by
now we can just assume that it exists.
---
 lisp/epa.el | 14 +-------------
 1 file changed, 1 insertion(+), 13 deletions(-)

diff --git a/lisp/epa.el b/lisp/epa.el
index 3c7dd8309a..fc7ad5efab 100644
--- a/lisp/epa.el
+++ b/lisp/epa.el
@@ -1105,17 +1105,6 @@ epa-sign-region
 				 'start-open t
 				 'end-open t)))))
 
-(defalias 'epa--derived-mode-p
-  (if (fboundp 'derived-mode-p)
-      #'derived-mode-p
-    (lambda (&rest modes)
-      "Non-nil if the current major mode is derived from one of MODES.
-Uses the `derived-mode-parent' property of the symbol to trace backwards."
-      (let ((parent major-mode))
-        (while (and (not (memq parent modes))
-                    (setq parent (get parent 'derived-mode-parent))))
-        parent))))
-
 ;;;###autoload
 (defun epa-encrypt-region (start end recipients sign signers)
   "Encrypt the current region between START and END for RECIPIENTS.
@@ -1227,8 +1216,7 @@ epa-import-keys
     (if (epg-context-result-for context 'import)
 	(epa-display-info (epg-import-result-to-string
 			   (epg-context-result-for context 'import))))
-    ;; FIXME: Why not use the (otherwise unused) epa--derived-mode-p?
-    (if (eq major-mode 'epa-key-list-mode)
+    (if (derived-mode-p 'epa-key-list-mode)
 	(apply #'epa--list-keys epa-list-keys-arguments))))
 
 ;;;###autoload
-- 
2.28.0

bug#42397: [PATCH v2 05/16] Split EasyPG libraries into outline sections

[Jonas Bernoulli]

* lisp/epa-dired.el:
lisp/epa-file.el:
lisp/epa-hook.el:
lisp/epa-mail.el:
lisp/epa.el:
lisp/epg-config.el:
lisp/epg.el: Split into outline sections.
* lisp/epg.el (epg-error): Move definition.
---
 lisp/epa-dired.el  |  1 +
 lisp/epa-file.el   | 10 ++++++++++
 lisp/epa-hook.el   |  1 +
 lisp/epa-mail.el   | 10 ++++++++++
 lisp/epa.el        | 24 ++++++++++++++++++++++++
 lisp/epg-config.el |  7 +++++++
 lisp/epg.el        | 27 ++++++++++++++++++++++++++-
 7 files changed, 79 insertions(+), 1 deletion(-)

diff --git a/lisp/epa-dired.el b/lisp/epa-dired.el
index 9269ea9707..4ff1ba3394 100644
--- a/lisp/epa-dired.el
+++ b/lisp/epa-dired.el
@@ -1,4 +1,5 @@
 ;;; epa-dired.el --- the EasyPG Assistant, dired extension -*- lexical-binding: t -*-
+
 ;; Copyright (C) 2006-2020 Free Software Foundation, Inc.
 
 ;; Author: Daiki Ueno <ueno@unixuser.org>
diff --git a/lisp/epa-file.el b/lisp/epa-file.el
index bbd9279a9a..3b0cc84e5f 100644
--- a/lisp/epa-file.el
+++ b/lisp/epa-file.el
@@ -1,4 +1,5 @@
 ;;; epa-file.el --- the EasyPG Assistant, transparent file encryption -*- lexical-binding: t -*-
+
 ;; Copyright (C) 2006-2020 Free Software Foundation, Inc.
 
 ;; Author: Daiki Ueno <ueno@unixuser.org>
@@ -21,10 +22,13 @@
 ;; along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
 
 ;;; Code:
+;;; Dependencies
 
 (require 'epa)
 (require 'epa-hook)
 
+;;; Options
+
 (defcustom epa-file-cache-passphrase-for-symmetric-encryption nil
   "If non-nil, cache passphrase for symmetric encryption.
 
@@ -49,6 +53,8 @@ epa-file-select-keys
 		 (const :tag "Don't ask" silent))
   :group 'epa-file)
 
+;;; Other
+
 (defvar epa-file-passphrase-alist nil)
 
 (defun epa-file-passphrase-callback-function (context key-id file)
@@ -72,6 +78,8 @@ epa-file-passphrase-callback-function
 		passphrase))))
     (epa-passphrase-callback-function context key-id file)))
 
+;;; File Handler
+
 (defvar epa-inhibit nil
   "Non-nil means don't try to decrypt .gpg files when operating on them.")
 
@@ -311,6 +319,8 @@ epa-file-write-region
 	(message "Wrote %s" buffer-file-name))))
 (put 'write-region 'epa-file 'epa-file-write-region)
 
+;;; Commands
+
 (defun epa-file-select-keys ()
   "Select recipients for encryption."
   (interactive)
diff --git a/lisp/epa-hook.el b/lisp/epa-hook.el
index a86f23eb68..6f12f8a6bf 100644
--- a/lisp/epa-hook.el
+++ b/lisp/epa-hook.el
@@ -1,4 +1,5 @@
 ;;; epa-hook.el --- preloaded code to enable epa-file.el -*- lexical-binding: t -*-
+
 ;; Copyright (C) 2006-2020 Free Software Foundation, Inc.
 
 ;; Author: Daiki Ueno <ueno@unixuser.org>
diff --git a/lisp/epa-mail.el b/lisp/epa-mail.el
index 63475256ca..6e6c0a498d 100644
--- a/lisp/epa-mail.el
+++ b/lisp/epa-mail.el
@@ -1,4 +1,5 @@
 ;;; epa-mail.el --- the EasyPG Assistant, minor-mode for mail composer -*- lexical-binding: t -*-
+
 ;; Copyright (C) 2006-2020 Free Software Foundation, Inc.
 
 ;; Author: Daiki Ueno <ueno@unixuser.org>
@@ -21,10 +22,13 @@
 ;; along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
 
 ;;; Code:
+;;; Dependencies
 
 (require 'epa)
 (require 'mail-utils)
 
+;;; Local Mode
+
 (defvar epa-mail-mode-map
   (let ((keymap (make-sparse-keymap)))
     (define-key keymap "\C-c\C-ed" 'epa-mail-decrypt)
@@ -50,6 +54,8 @@ epa-mail-mode
   "A minor-mode for composing encrypted/clearsigned mails."
   nil " epa-mail" epa-mail-mode-map)
 
+;;; Utilities
+
 (defun epa-mail--find-usable-key (keys usage)
   "Find a usable key from KEYS for USAGE.
 USAGE would be `sign' or `encrypt'."
@@ -64,6 +70,8 @@ epa-mail--find-usable-key
 	  (setq pointer (cdr pointer))))
       (setq keys (cdr keys)))))
 
+;;; Commands
+
 ;;;###autoload
 (defun epa-mail-decrypt ()
   "Decrypt OpenPGP armors in the current buffer.
@@ -241,6 +249,8 @@ epa-mail-import-keys
   (interactive)
   (epa-import-armor-in-region (point-min) (point-max)))
 
+;;; Global Mode
+
 ;;;###autoload
 (define-minor-mode epa-global-mail-mode
   "Minor mode to hook EasyPG into Mail mode."
diff --git a/lisp/epa.el b/lisp/epa.el
index fc7ad5efab..713708f0c1 100644
--- a/lisp/epa.el
+++ b/lisp/epa.el
@@ -21,6 +21,7 @@
 ;; along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
 
 ;;; Code:
+;;; Dependencies
 
 (require 'epg)
 (require 'font-lock)
@@ -30,6 +31,8 @@
   (require 'wid-edit))
 (require 'derived)
 
+;;; Options
+
 (defgroup epa nil
   "The EasyPG Assistant"
   :version "23.1"
@@ -73,6 +76,8 @@ epa-mail-aliases
   :group 'epa
   :version "24.4")
 
+;;; Faces
+
 (defgroup epa-faces nil
   "Faces for epa-mode."
   :version "23.1"
@@ -146,6 +151,8 @@ epa-validity-face-alist
   :type '(repeat (cons symbol face))
   :group 'epa-faces)
 
+;;; Variables
+
 (defvar epa-font-lock-keywords
   '(("^\\*"
      (0 'epa-mark))
@@ -252,6 +259,8 @@ epa-info-mode-map
 
 (defvar epa-exit-buffer-function #'quit-window)
 
+;;; Key Widget
+
 (define-widget 'epa-key 'push-button
   "Button for representing an epg-key object."
   :format "%[%v%]"
@@ -293,6 +302,8 @@ epa--key-widget-help-echo
 	  (epg-sub-key-id (car (epg-key-sub-key-list
 				(widget-get widget :value))))))
 
+;;; Modes
+
 (define-derived-mode epa-key-list-mode special-mode "EPA Keys"
   "Major mode for `epa-list-keys'."
   (buffer-disable-undo)
@@ -316,6 +327,9 @@ epa-info-mode
   (setq truncate-lines t
 	buffer-read-only t))
 
+;;; Commands
+;;;; Marking
+
 (defun epa-mark-key (&optional arg)
   "Mark a key on the current line.
 If ARG is non-nil, unmark the key."
@@ -338,11 +352,15 @@ epa-unmark-key
   (interactive "P")
   (epa-mark-key (not arg)))
 
+;;;; Quitting
+
 (defun epa-exit-buffer ()
   "Exit the current buffer using `epa-exit-buffer-function'."
   (interactive)
   (funcall epa-exit-buffer-function))
 
+;;;; Listing and Selecting
+
 (defun epa--insert-keys (keys)
   (save-excursion
     (save-restriction
@@ -505,6 +523,8 @@ epa-select-keys
   (let ((keys (epg-list-keys context names secret)))
     (epa--select-keys prompt keys)))
 
+;;;; Key Details
+
 (defun epa-show-key ()
   "Show a key on the current line."
   (interactive)
@@ -591,6 +611,8 @@ epa--show-key
     (goto-char (point-min))
     (pop-to-buffer (current-buffer))))
 
+;;;; Encryption and Signatures
+
 (defun epa-display-info (info)
   (if epa-popup-info-window
       (save-selected-window
@@ -1180,6 +1202,8 @@ epa-encrypt-region
 				 'start-open t
 				 'end-open t)))))
 
+;;;; Key Management
+
 ;;;###autoload
 (defun epa-delete-keys (keys &optional allow-secret)
   "Delete selected KEYS."
diff --git a/lisp/epg-config.el b/lisp/epg-config.el
index 1c42924652..9f0c7e4c50 100644
--- a/lisp/epg-config.el
+++ b/lisp/epg-config.el
@@ -22,6 +22,7 @@
 ;; along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
 
 ;;; Code:
+;;; Prelude
 
 (eval-when-compile (require 'cl-lib))
 
@@ -34,6 +35,8 @@ epg-version-number
 (define-obsolete-variable-alias 'epg-bug-report-address
   'report-emacs-bug-address "27.1")
 
+;;; Options
+
 (defgroup epg ()
   "Interface to the GNU Privacy Guard (GnuPG)."
   :tag "EasyPG"
@@ -106,6 +109,8 @@ epg-debug
 Note that the buffer name starts with a space."
   :type 'boolean)
 
+;;; Constants
+
 (defconst epg-gpg-minimum-version "1.4.3")
 (defconst epg-gpg2-minimum-version "2.1.6")
 
@@ -133,6 +138,8 @@ epg-config--configuration-constructor-alist
 either `OpenPGP' or `CMS'.  The second element is a function
 which constructs a configuration object (actually a plist).")
 
+;;; "Configuration"
+
 (defvar epg--configurations nil)
 
 ;;;###autoload
diff --git a/lisp/epg.el b/lisp/epg.el
index df79988c48..96af3ad4bc 100644
--- a/lisp/epg.el
+++ b/lisp/epg.el
@@ -1,4 +1,5 @@
 ;;; epg.el --- the EasyPG Library -*- lexical-binding: t -*-
+
 ;; Copyright (C) 1999-2000, 2002-2020 Free Software Foundation, Inc.
 
 ;; Author: Daiki Ueno <ueno@unixuser.org>
@@ -21,10 +22,15 @@
 ;; along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
 
 ;;; Code:
+;;; Prelude
 
 (require 'epg-config)
 (eval-when-compile (require 'cl-lib))
 
+(define-error 'epg-error "GPG error")
+
+;;; Variables
+
 (defvar epg-user-id nil
   "GnuPG ID of your default identity.")
 
@@ -41,6 +47,8 @@ epg-debug-buffer
 (defvar epg-agent-file nil)
 (defvar epg-agent-mtime nil)
 
+;;; Enums
+
 ;; from gnupg/common/openpgpdefs.h
 (defconst epg-cipher-algorithm-alist
   '((0 . "NONE")
@@ -169,7 +177,8 @@ epg-dn-type-alist
 
 (defvar epg-prompt-alist nil)
 
-(define-error 'epg-error "GPG error")
+;;; Structs
+;;;; Data Struct
 
 (cl-defstruct (epg-data
                (:constructor nil)
@@ -180,6 +189,8 @@ 'epg-error
   (file nil :read-only t)
   (string nil :read-only t))
 
+;;;; Context Struct
+
 (cl-defstruct (epg-context
                (:constructor nil)
                (:constructor epg-context--make
@@ -218,6 +229,8 @@ 'epg-error
   (error-output "")
   error-buffer)
 
+;;;; Context Methods
+
 ;; This is not an alias, just so we can mark it as autoloaded.
 ;;;###autoload
 (defun epg-make-context (&optional protocol armor textmode include-certs
@@ -281,6 +294,8 @@ epg-context-set-signers
   (declare (obsolete setf "25.1"))
   (setf (epg-context-signers context) signers))
 
+;;;; Other Structs
+
 (cl-defstruct (epg-signature
                (:constructor nil)
                (:constructor epg-make-signature
@@ -385,6 +400,8 @@ epg-context-set-signers
   secret-unchanged not-imported
   imports)
 
+;;; Functions
+
 (defun epg-context-result-for (context name)
   "Return the result of CONTEXT associated with NAME."
   (cdr (assq name (epg-context-result context))))
@@ -850,6 +867,8 @@ epg--prompt-GET_BOOL-untrusted_key.override
 		  (format "Untrusted key %s %s.  Use anyway? " key-id user-id))
 	      "Use untrusted key anyway? ")))
 
+;;; Status Functions
+
 (defun epg--status-GET_BOOL (context string)
   (let (inhibit-quit)
     (condition-case nil
@@ -1225,6 +1244,8 @@ epg--status-IMPORT_RES
 			     (epg-context-result-for context 'import-status)))
     (epg-context-set-result-for context 'import-status nil)))
 
+;;; Functions
+
 (defun epg-passphrase-callback-function (context key-id _handback)
   (declare (obsolete epa-passphrase-callback-function "23.1"))
   (if (eq key-id 'SYM)
@@ -1294,6 +1315,8 @@ epg--make-sub-key-1
    (if (aref line 6)
        (epg--time-from-seconds (aref line 6)))))
 
+;;; Public Functions
+
 (defun epg-list-keys (context &optional name mode)
   "Return a list of epg-key objects matched with NAME.
 If MODE is nil or `public', only public keyring should be searched.
@@ -2023,6 +2046,8 @@ epg-edit-key
 			    (epg-errors-to-string errors))))))
     (epg-reset context)))
 
+;;; Decode Functions
+
 (defun epg--decode-percent-escape (string)
   (setq string (encode-coding-string string 'raw-text))
   (let ((index 0))
-- 
2.28.0

bug#42397: [PATCH v2 06/16] Merge two conditions and fix indentation

[Jonas Bernoulli]

The motivation behind this change is that the indentation of some
lines was outright wrong.  If we address that issue, then we might
as well also address the issue that some code is needlessly nested
an additional level.  That we can fix by merging the conditions.

By doing these two changes in on commit we have to change the fewest
lines.  Even though we are moving to using just spaces for indentation
of the modified lines, other lines in the same function are left alone
and continue to us tabs+spaces for indentation.  That is not "wrong",
but just the style we are slowly migrating away from when touching
lines for other reasons.

Discussed in bug#42397.

* lisp/emacs-lisp/eldoc.el (eldoc-minibuffer-message): Merge two
conditions and fix indentation.
---
 lisp/emacs-lisp/eldoc.el | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/lisp/emacs-lisp/eldoc.el b/lisp/emacs-lisp/eldoc.el
index 19b3bd78ae..4825b5c5e6 100644
--- a/lisp/emacs-lisp/eldoc.el
+++ b/lisp/emacs-lisp/eldoc.el
@@ -289,13 +289,13 @@ eldoc-minibuffer-message
 	     (or (window-in-direction 'above (minibuffer-window))
 		 (minibuffer-selected-window)
 		 (get-largest-window)))
-    (when mode-line-format
-	  (unless (and (listp mode-line-format)
-		       (assq 'eldoc-mode-line-string mode-line-format))
+          (when (and mode-line-format
+                     (not (and (listp mode-line-format)
+                               (assq 'eldoc-mode-line-string mode-line-format))))
 	    (setq mode-line-format
 		  (list "" '(eldoc-mode-line-string
 			     (" " eldoc-mode-line-string " "))
-			mode-line-format))))
+			mode-line-format)))
           (setq eldoc-mode-line-string
                 (when (stringp format-string)
                   (apply #'format-message format-string args)))
-- 
2.28.0

bug#42397: [PATCH v2 07/16] * lisp/progmodes/compile.el: Remove unnecessary comments.

[Jonas Bernoulli]

These comments are unnecessary because the doc-strings that follow
already cover the same ground, while being more concise.  These
comments were also prefixed with too many semicolons, causing them
to be treated as outline headings.
---
 lisp/progmodes/compile.el | 2 --
 1 file changed, 2 deletions(-)

diff --git a/lisp/progmodes/compile.el b/lisp/progmodes/compile.el
index a76a3c44a3..0b9f417845 100644
--- a/lisp/progmodes/compile.el
+++ b/lisp/progmodes/compile.el
@@ -2373,12 +2373,10 @@ compilation-filter
 	  (set-marker min nil)
 	  (set-marker max nil))))))
 
-;;; test if a buffer is a compilation buffer, assuming we're in the buffer
 (defsubst compilation-buffer-internal-p ()
   "Test if inside a compilation buffer."
   (local-variable-p 'compilation-locs))
 
-;;; test if a buffer is a compilation buffer, using compilation-buffer-internal-p
 (defsubst compilation-buffer-p (buffer)
   "Test if BUFFER is a compilation buffer."
   (with-current-buffer buffer
-- 
2.28.0

bug#42397: [PATCH v2 08/16] ; * lisp/whitespace.el: Capitalize "Code" section heading.

[Jonas Bernoulli]

---
 lisp/whitespace.el | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lisp/whitespace.el b/lisp/whitespace.el
index 42c4b61daf..8a1bb8ade8 100644
--- a/lisp/whitespace.el
+++ b/lisp/whitespace.el
@@ -262,7 +262,7 @@
 ;;
 ;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
-;;; code:
+;;; Code:
 
 \f
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
-- 
2.28.0

bug#42397: [PATCH v2 09/16] * lisp/mail/smtpmail.el: Use outline headings.

[Jonas Bernoulli]

---
 lisp/mail/smtpmail.el | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/lisp/mail/smtpmail.el b/lisp/mail/smtpmail.el
index f5c9432879..666395e0b9 100644
--- a/lisp/mail/smtpmail.el
+++ b/lisp/mail/smtpmail.el
@@ -53,6 +53,7 @@
 ;; See http://www.ietf.org/rfc/rfc2554.txt
 
 ;;; Code:
+;;; Dependencies
 
 (require 'sendmail)
 (require 'auth-source)
@@ -61,12 +62,12 @@
 (autoload 'message-make-message-id "message")
 (autoload 'rfc2104-hash "rfc2104")
 
-;;;
+;;; Options
+
 (defgroup smtpmail nil
   "SMTP protocol for sending mail."
   :group 'mail)
 
-
 (defcustom smtpmail-default-smtp-server nil
   "Specify default SMTP server.
 This only has effect if you specify it before loading the smtpmail library."
@@ -172,8 +173,7 @@ smtpmail-retries
   :type 'integer
   :version "27.1")
 
-;; End of customizable variables.
-
+;;; Variables
 
 (defvar smtpmail-address-buffer)
 (defvar smtpmail-recipient-address-list)
@@ -192,6 +192,8 @@ smtpmail-auth-supported
 (defvar smtpmail-mail-address nil
   "Value to use for envelope-from address for mail from ambient buffer.")
 
+;;; Functions
+
 ;;;###autoload
 (defun smtpmail-send-it ()
   (let ((errbuf (if mail-interactive
-- 
2.28.0

bug#42397: [PATCH v2 10/16] * test/src/emacs-module-tests.el: Use proper outline headings.

[Jonas Bernoulli]

This library already used section headings but it used just two
instead of three semicolons, making them indistinguishable from
plain comments.
---
 test/src/emacs-module-tests.el | 21 ++++++---------------
 1 file changed, 6 insertions(+), 15 deletions(-)

diff --git a/test/src/emacs-module-tests.el b/test/src/emacs-module-tests.el
index 51b2ca0cd5..0fd8e1db49 100644
--- a/test/src/emacs-module-tests.el
+++ b/test/src/emacs-module-tests.el
@@ -24,6 +24,7 @@
 ;; module in test/data/emacs-module.
 
 ;;; Code:
+;;; Prelude
 
 (require 'cl-lib)
 (require 'ert)
@@ -48,9 +49,7 @@ emacs-module-tests--generic
 (cl-defmethod emacs-module-tests--generic ((_ user-ptr))
   'user-ptr)
 
-;;
-;; Basic tests.
-;;
+;;; Basic tests
 
 (ert-deftest mod-test-sum-test ()
   (should (= (mod-test-sum 1 2) 3))
@@ -103,9 +102,7 @@ module-function-object
                  ">" eos)
              (prin1-to-string func)))))
 
-;;
-;; Non-local exists (throw, signal).
-;;
+;;; Non-local exists (throw, signal)
 
 (ert-deftest mod-test-non-local-exit-signal-test ()
   (should-error (mod-test-signal))
@@ -142,9 +139,7 @@ mod-test-non-local-exit-funcall-throw
   (should (equal (mod-test-non-local-exit-funcall (lambda () (throw 'tag 32)))
                  '(throw tag 32))))
 
-;;
-;; String tests.
-;;
+;;; String tests
 
 (defun multiply-string (s n)
   "Return N copies of S concatenated together."
@@ -168,9 +163,7 @@ mod-test-globref-reordered
 (ert-deftest mod-test-string-a-to-b-test ()
   (should (string= (mod-test-string-a-to-b "aaa") "bbb")))
 
-;;
-;; User-pointer tests.
-;;
+;;; User-pointer tests
 
 (ert-deftest mod-test-userptr-fun-test ()
   (let* ((n 42)
@@ -184,9 +177,7 @@ mod-test-userptr-fun-test
 
 ;; TODO: try to test finalizer
 
-;;
-;; Vector tests.
-;;
+;;; Vector tests
 
 (ert-deftest mod-test-vector-test ()
   (dolist (s '(2 10 100 1000))
-- 
2.28.0

bug#42397: [PATCH v2 11/16] * lisp/obsolete/longlines.el: Use proper outline headings.

[Jonas Bernoulli]

This library already used section headings but it used just two
instead of three semicolons, making them indistinguishable from
plain comments.  One heading is new.
---
 lisp/obsolete/longlines.el | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

diff --git a/lisp/obsolete/longlines.el b/lisp/obsolete/longlines.el
index 2fba49f402..cbe453aa6b 100644
--- a/lisp/obsolete/longlines.el
+++ b/lisp/obsolete/longlines.el
@@ -37,6 +37,7 @@
 ;; Special thanks to Rod Smith for many useful bug reports.
 
 ;;; Code:
+;;; Options
 
 (defgroup longlines nil
   "Automatic wrapping of long lines when loading files."
@@ -76,7 +77,7 @@ longlines-show-effect
   :group 'longlines
   :type 'string)
 
-;; Internal variables
+;;; Internal variables
 
 (defvar longlines-wrap-beg nil)
 (defvar longlines-wrap-end nil)
@@ -90,7 +91,7 @@ longlines-decoded
 (make-variable-buffer-local 'longlines-showing)
 (make-variable-buffer-local 'longlines-decoded)
 
-;; Mode
+;;; Mode
 
 (defvar message-indent-citation-function)
 
@@ -210,7 +211,7 @@ longlines-mode-off
 major mode changes."
   (longlines-mode 0))
 
-;; Showing the effect of hard newlines in the buffer
+;;; Showing the effect of hard newlines in the buffer
 
 (defun longlines-show-hard-newlines (&optional arg)
   "Make hard newlines visible by adding a face.
@@ -252,7 +253,7 @@ longlines-unshow-hard-newlines
       (setq pos (text-property-not-all (1+ pos) (point-max) 'hard nil)))
     (restore-buffer-modified-p mod)))
 
-;; Wrapping the paragraphs.
+;;; Wrapping the paragraphs
 
 (defun longlines-wrap-region (beg end)
   "Wrap each successive line, starting with the line before BEG.
@@ -402,7 +403,7 @@ longlines-encode-string
       (setq pos (string-match "\n" str (1+ pos))))
     str))
 
-;; Auto wrap
+;;; Auto wrap
 
 (defun longlines-auto-wrap (&optional arg)
   "Toggle automatic line wrapping.
@@ -457,7 +458,7 @@ longlines-window-change-function
       (setq fill-column (- (window-width) dw))
       (longlines-wrap-region (point-min) (point-max)))))
 
-;; Isearch
+;;; Isearch
 
 (defun longlines-search-function ()
   (cond
@@ -477,7 +478,7 @@ longlines-re-search-forward
   (let ((search-spaces-regexp " *[ \n]"))
     (re-search-forward string bound noerror count)))
 
-;; Loading and saving
+;;; Loading and saving
 
 (defun longlines-before-revert-hook ()
   (add-hook 'after-revert-hook 'longlines-after-revert-hook nil t)
@@ -492,7 +493,7 @@ longlines-after-revert-hook
  (list 'longlines "Automatically wrap long lines." nil nil
        'longlines-encode-region t nil))
 
-;; Unloading
+;;; Unloading
 
 (defun longlines-unload-function ()
   "Unload the longlines library."
-- 
2.28.0

bug#42397: [PATCH v2 12/16] * lisp/net/imap.el: Use proper outline headings

[Jonas Bernoulli]

This library already used section headings but it used just two
instead of three semicolons, making them indistinguishable from
plain comments.  One heading is new.
---
 lisp/net/imap.el | 30 ++++++++++++++++++------------
 1 file changed, 18 insertions(+), 12 deletions(-)

diff --git a/lisp/net/imap.el b/lisp/net/imap.el
index a492dc8c79..add19c5882 100644
--- a/lisp/net/imap.el
+++ b/lisp/net/imap.el
@@ -134,6 +134,7 @@
 ;;
 
 ;;; Code:
+;;; Dependencies
 
 (eval-when-compile (require 'cl-lib))
 (require 'utf7)
@@ -145,7 +146,7 @@
 (declare-function digest-md5-digest-uri "ext:digest-md5")
 (declare-function digest-md5-challenge "ext:digest-md5")
 
-;; User variables.
+;;; User variables.
 
 (defgroup imap nil
   "Low-level IMAP issues."
@@ -257,7 +258,7 @@ imap-store-password
   :group 'imap
   :type 'boolean)
 
-;; Various variables.
+;;; Various variables.
 
 (defvar imap-fetch-data-hook nil
   "Hooks called after receiving each FETCH response.")
@@ -316,7 +317,9 @@ imap-logout-timeout
 an application program that uses this module specifies on a per-server
 basis.")
 
-;; Internal constants.  Change these and die.
+;;; Internal constants
+
+;; Change these and die.
 
 (defconst imap-default-port 143)
 (defconst imap-default-ssl-port 993)
@@ -348,7 +351,7 @@ imap-local-variables
 (defconst imap-log-buffer "*imap-log*")
 (defconst imap-debug-buffer "*imap-debug*")
 
-;; Internal variables.
+;;; Internal variables.
 
 (defvar imap-stream nil)
 (defvar imap-auth nil)
@@ -437,7 +440,7 @@ imap-enable-exchange-bug-workaround
 canonical form fails.")
 
 \f
-;; Utility functions:
+;;; Utility functions
 
 (defun imap-remassoc (key alist)
   "Delete by side effect any elements of ALIST whose car is `equal' to KEY.
@@ -489,7 +492,8 @@ imap-error-text
     (nth 3 (car imap-failed-tags))))
 
 \f
-;; Server functions; stream stuff:
+;;; Server functions
+;;;; Stream functions
 
 (defun imap-log (string-or-buffer)
   (when imap-log
@@ -747,7 +751,7 @@ imap-starttls-open
     (message "imap: Connecting with STARTTLS...%s" (if done "done" "failed"))
     done))
 
-;; Server functions; authenticator stuff:
+;;;; Authenticator functions
 
 (defun imap-interactive-login (buffer loginfunc)
   "Login to server in BUFFER.
@@ -969,7 +973,7 @@ imap-digest-md5-auth
 	 (imap-send-command-1 "")
 	 (imap-ok-p (imap-wait-for-tag tag)))))))
 
-;; Server functions:
+;;; Server functions
 
 (defun imap-open-1 (buffer)
   (with-current-buffer buffer
@@ -1228,7 +1232,7 @@ imap-logout-wait
     (imap-send-command-wait "LOGOUT" buffer)))
 
 \f
-;; Mailbox functions:
+;;; Mailbox functions
 
 (defun imap-mailbox-put (propname value &optional mailbox buffer)
   (with-current-buffer (or buffer (current-buffer))
@@ -1520,7 +1524,7 @@ imap-mailbox-acl-delete
 				     identifier))))))
 
 \f
-;; Message functions:
+;;; Message functions
 
 (defun imap-current-message (&optional buffer)
   (with-current-buffer (or buffer (current-buffer))
@@ -1832,7 +1836,7 @@ imap-envelope-from
 	       (if (aref from 0) ">"))))
 
 \f
-;; Internal functions.
+;;; Internal functions.
 
 (defun imap-add-callback (tag func)
   (setq imap-callbacks (append (list (cons tag func)) imap-callbacks)))
@@ -1969,7 +1973,7 @@ imap-arrival-filter
 	      (delete-region (point-min) (point-max)))))))))
 
 \f
-;; Imap parser.
+;;; Imap parser.
 
 (defsubst imap-forward ()
   (or (eobp) (forward-char)))
@@ -2850,6 +2854,8 @@ imap-parse-body
 	(imap-forward)
 	(nreverse body)))))
 
+;;; Debug
+
 (when imap-debug			; (untrace-all)
   (require 'trace)
   (buffer-disable-undo (get-buffer-create imap-debug-buffer))
-- 
2.28.0

bug#42397: [PATCH v2 13/16] * lisp/font-lock.el: Split the Commentary into subsections.

[Jonas Bernoulli]

The "Commentary" was already split into multiple sections, but
these sections where on the same level as "Commentary" itself,
which is less convenient for users of `outline-minor-mode'.
---
 lisp/font-lock.el | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/lisp/font-lock.el b/lisp/font-lock.el
index 5cda4a693d..cf88100ab5 100644
--- a/lisp/font-lock.el
+++ b/lisp/font-lock.el
@@ -51,7 +51,7 @@
 ;; also the variable `font-lock-maximum-size'.  Support modes for Font Lock
 ;; mode can be used to speed up Font Lock mode.  See `font-lock-support-mode'.
 \f
-;;; How Font Lock mode fontifies:
+;;;; How Font Lock mode fontifies:
 
 ;; When Font Lock mode is turned on in a buffer, it (a) fontifies the entire
 ;; buffer and (b) installs one of its fontification functions on one of the
@@ -96,7 +96,7 @@
 ;; some syntactic parsers for common languages and a son-of-font-lock.el could
 ;; use them rather then relying so heavily on the keyword (regexp) pass.
 
-;;; How Font Lock mode supports modes or is supported by modes:
+;;;; How Font Lock mode supports modes or is supported by modes:
 
 ;; Modes that support Font Lock mode do so by defining one or more variables
 ;; whose values specify the fontification.  Font Lock mode knows of these
@@ -112,7 +112,7 @@
 ;; Font Lock mode fontification behavior can be modified in a number of ways.
 ;; See the below comments and the comments distributed throughout this file.
 
-;;; Constructing patterns:
+;;;; Constructing patterns:
 
 ;; See the documentation for the variable `font-lock-keywords'.
 ;;
@@ -120,7 +120,7 @@
 ;; `font-lock-syntactic-keywords' can be generated via the function
 ;; `regexp-opt'.
 
-;;; Adding patterns for modes that already support Font Lock:
+;;;; Adding patterns for modes that already support Font Lock:
 
 ;; Though Font Lock highlighting patterns already exist for many modes, it's
 ;; likely there's something that you want fontified that currently isn't, even
@@ -135,7 +135,7 @@
 ;; other variables.  For example, additional C types can be specified via the
 ;; variable `c-font-lock-extra-types'.
 
-;;; Adding patterns for modes that do not support Font Lock:
+;;;; Adding patterns for modes that do not support Font Lock:
 
 ;; Not all modes support Font Lock mode.  If you (as a user of the mode) add
 ;; patterns for a new mode, you must define in your ~/.emacs a variable or
@@ -155,7 +155,7 @@
 ;;     (set (make-local-variable 'font-lock-defaults)
 ;;          '(foo-font-lock-keywords t))))
 
-;;; Adding Font Lock support for modes:
+;;;; Adding Font Lock support for modes:
 
 ;; Of course, it would be better that the mode already supports Font Lock mode.
 ;; The package author would do something similar to above.  The mode must
-- 
2.28.0

bug#42397: [PATCH v2 14/16] * lisp/font-lock.el: No longer use headings as end of section markers.

[Jonas Bernoulli]

Each section ends right before the following section begins and IMO
that means that it is unnecessary to mark the end of sections.

For users of `outline-minor-mode' the old end-of-section markers were
a distraction.  They made it much harder to parse the overview outline
state because each section heading was followed by a end-of-section
marker that was formatted as a section heading.  Because of this I
wanted to remove the end-of-section markers.

But as Eli pointed out these sections are long and not everyone uses
`outline-minor-mode'.

So instead of removing them, I am turning the end-of-section markers
into regular comments (beginning with just two semicolons) instead of
section headings (beginning with tree semicolons).  That way users of
`outline-minor-mode' won't be distracted by them and others can still
benefit from the markers as before.
---
 lisp/font-lock.el | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/lisp/font-lock.el b/lisp/font-lock.el
index cf88100ab5..c633877e64 100644
--- a/lisp/font-lock.el
+++ b/lisp/font-lock.el
@@ -986,7 +986,7 @@ font-lock-after-unfontify-buffer
 	((bound-and-true-p lazy-lock-mode)
 	 (lazy-lock-after-unfontify-buffer))))
 
-;;; End of Font Lock Support mode.
+;; End of Font Lock Support mode.
 \f
 ;;; Fontification functions.
 
@@ -1393,7 +1393,7 @@ font-lock-fontify-block
 	      (font-lock-fontify-region (point) (mark)))
 	  ((error quit) (message "Fontifying block...%s" error-data)))))))
 
-;;; End of Fontification functions.
+;; End of Fontification functions.
 \f
 ;;; Additional text property functions.
 
@@ -1485,7 +1485,7 @@ font-lock--remove-face-from-text-property
 		      (put-text-property start next prop new object))))))
       (setq start (text-property-not-all next end prop nil object)))))
 
-;;; End of Additional text property functions.
+;; End of Additional text property functions.
 \f
 ;;; Syntactic regexp fontification functions.
 
@@ -1591,7 +1591,7 @@ font-lock-fontify-syntactic-keywords-region
 	  (setq highlights (cdr highlights))))
       (setq keywords (cdr keywords)))))
 
-;;; End of Syntactic regexp fontification functions.
+;; End of Syntactic regexp fontification functions.
 \f
 ;;; Syntactic fontification functions.
 
@@ -1650,7 +1650,7 @@ font-lock-fontify-syntactically-region
         (setq state (parse-partial-sexp (point) end nil nil state
 				        'syntax-table))))))
 
-;;; End of Syntactic fontification functions.
+;; End of Syntactic fontification functions.
 \f
 ;;; Keyword regexp fontification functions.
 
@@ -1784,9 +1784,9 @@ font-lock-fontify-keywords-region
       (setq keywords (cdr keywords)))
     (set-marker pos nil)))
 
-;;; End of Keyword regexp fontification functions.
+;; End of Keyword regexp fontification functions.
 \f
-;; Various functions.
+;;; Various functions.
 
 (defun font-lock-compile-keywords (keywords &optional syntactic-keywords)
   "Compile KEYWORDS into the form (t KEYWORDS COMPILED...)
@@ -2102,7 +2102,7 @@ font-lock-regexp-grouping-construct
   "Font Lock mode face used to highlight grouping constructs in Lisp regexps."
   :group 'font-lock-faces)
 
-;;; End of Color etc. support.
+;; End of Color etc. support.
 \f
 ;;; Menu support.
 
@@ -2204,7 +2204,7 @@ font-lock-regexp-grouping-construct
 ;;  ;; Deactivate less/more fontification entries.
 ;;  (setq font-lock-fontify-level nil))
 
-;;; End of Menu support.
+;; End of Menu support.
 \f
 ;;; Various regexp information shared by several modes.
 ;; ;; Information specific to a single mode should go in its load library.
-- 
2.28.0

bug#42397: [PATCH v2 15/16] ; * lisp/emacs-lisp/autoload.el: Begin summary line with three semicolons.

[Jonas Bernoulli]

---
 lisp/emacs-lisp/autoload.el | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lisp/emacs-lisp/autoload.el b/lisp/emacs-lisp/autoload.el
index c76de43be9..ab5f9de891 100644
--- a/lisp/emacs-lisp/autoload.el
+++ b/lisp/emacs-lisp/autoload.el
@@ -1,4 +1,4 @@
-;; autoload.el --- maintain autoloads in loaddefs.el  -*- lexical-binding: t -*-
+;;; autoload.el --- maintain autoloads in loaddefs.el  -*- lexical-binding: t -*-
 
 ;; Copyright (C) 1991-1997, 2001-2020 Free Software Foundation, Inc.
 
-- 
2.28.0

bug#42397: [PATCH v2 16/16] Update section heading conventions for libraries

[Jonas Bernoulli]

* doc/lispref/tips.texi (Comment Tips): Update information on section
  headings to reflect common usage.

Previously the tips stated that if the code is split up into multiple
sections, then that should be done by splitting up the ";;; Code:"
section into multiple sub-sections.

However about half the libraries in Emacs instead use multiple
top-level sections.  We update the tips (aka conventions) to allow
this common usage, but because it is awkward if there is a section
named "Code", which contains only some of the code instead of all of
it, we now recommend that that section should be empty in this case.

We cannot just give up on the "Code:" section/heading because that is
an old convention that is followed be nearly every library and because
it is likely that there are some utilities out there that depend on
its presence.

This was discussed in
https://lists.gnu.org/archive/html/emacs-devel/2020-07/msg00444.html
https://lists.gnu.org/archive/html/emacs-devel/2020-08/msg00001.html
---
 doc/lispref/tips.texi | 65 ++++++++++++++++++++++++++++++-------------
 1 file changed, 46 insertions(+), 19 deletions(-)

diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index 5b09b2ccea..6292054d30 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -918,29 +918,56 @@ Comment Tips
 strings, though.
 
 @item ;;;
-Comments that start with three semicolons, @samp{;;;}, should start at
-the left margin.  We use them
-for comments which should be considered a
-heading by Outline minor mode.  By default, comments starting with
-at least three semicolons (followed by a single space and a
-non-whitespace character) are considered headings, comments starting
-with two or fewer are not.  Historically, triple-semicolon comments have
-also been used for commenting out lines within a function, but this use
-is discouraged.
-
-When commenting out entire functions, use two semicolons.
-
-@item ;;;;
-Comments that start with four (or more) semicolons, @samp{;;;;},
-should be aligned to the left margin and are used for headings of
-major sections of a program.  For example:
+
+Comments that start with three (or more) semicolons, @samp{;;;},
+should start at the left margin.  We use them for comments that should
+be considered a heading by Outline minor mode.  By default, comments
+starting with at least three semicolons (followed by a single space
+and a non-whitespace character) are considered section headings,
+comments starting with two or fewer are not.
+
+(Historically, triple-semicolon comments have also been used for
+commenting out lines within a function, but this use is discouraged in
+favor of using just two semicolons.  This also applies when commenting
+out entire functions; when doing that use two semicolons as well.)
+
+Three semicolons are used for top-level sections, four for
+sub-sections, five for sub-sub-sections and so on.
+
+Typically libraries have at least four top-level sections.  For
+example when the bodies of all of these sections are hidden:
 
 @smallexample
-;;;; The kill ring
+@group
+;;; backquote.el --- implement the ` Lisp construct...
+;;; Commentary:...
+;;; Code:...
+;;; backquote.el ends here
+@end group
 @end smallexample
 
-If you wish to have sub-headings under these heading, use more
-semicolons to nest these sub-headings.
+(In a sense the last line is not a section heading as it must
+never be followed by any text; after all it marks the end of the
+file.)
+
+For longer libraries it is advisable to split the code into multiple
+sections.  This can be done by splitting the @samp{Code:} section into
+multiple sub-sections.  Even though that was the only recommended
+approach for a long time, many people have chosen to use multiple
+top-level code sections instead.  You may chose either style.
+
+Using multiple top-level code sections has the advanatage that it
+avoids introducing an additional nesting level but it also means that
+the section named @samp{Code} does not contain all the code, which is
+awkward.  To avoid that, you should put no code at all inside that
+section; that way it can be considered a seperator instead of a
+section heading.
+
+Finally, we recommend that you don't end headings with a colon or any
+other punctuation for that matter.  For historic reasons the
+@samp{Code:} and @samp{Commentary:} headings end with a colon, but we
+recommend that you don't do the same for other headings anyway.
+
 @end table
 
 @noindent
-- 
2.28.0

bug#42397: [PATCH v2 16/16] Update section heading conventions for libraries

[Eli Zaretskii]

> From: Jonas Bernoulli <jonas@bernoul.li>
> Date: Mon, 10 Aug 2020 23:14:30 +0200
> 
> * doc/lispref/tips.texi (Comment Tips): Update information on section
>   headings to reflect common usage.

LGTM, thanks.

bug#42397: [PATCH 00/14] Use outline headings and some cosmetics

[Jonas Bernoulli]

I have pushed the last iteration to master,
so this issue can be closed.

     Thanks!
     Jonas

bug#42397: [PATCH 00/14] Use outline headings and some cosmetics

[Stefan Kangas]

close 42397 28.1
thanks

Jonas Bernoulli <jonas@bernoul.li> writes:

> I have pushed the last iteration to master,
> so this issue can be closed.

Thanks.  Closing the bug now.

Best regards,
Stefan Kangas