Increase `emacs-lisp-docstring-fill-column` to 72

Monitors are wider now than when these defaults were first set, and it
is useful to take better advantage of that, to fit text on fewer lines.
Yet, it has repeatedly been shown that overly long lines reduce
readability:
   "A reasonable guideline would be 55 to 75 characters per line."[1]

We also don't want to disfavor narrow displays, like mobile phones; a
more promising direction here might be to automatically word wrap
docstrings and make their maximum width customizable.  That might
require a new docstring format, however.

Bumping it by 7 characters, from 65 to 72, seems a reasonable compromise
for now.  Consideration was given to increasing it to 70 or 75, but 72
happens to be a commonly recommended maximum line width elsewhere (see
Fortran 66, Python docstrings, commit message recommendations, etc.),
and we might as well do the same.

This change was discussed in:
https://lists.gnu.org/r/emacs-devel/2022-07/msg00217.html

[1] "Optimal Line Length in Reading — A Literature Review", Nanavati and
    Bias, Visible Language, Vol. 39 No. 2 (2005).
    https://journals.uc.edu/index.php/vl/article/view/5765

* lisp/emacs-lisp/lisp-mode.el (emacs-lisp-docstring-fill-column):
* .dir-locals.el (fill-column, emacs-lisp-docstring-fill-column):
Bump default to 72.

(cherry picked from commit 72b1379f0795a5e2e9c57615c0b1d78c0b97cd1f)

diff --git a/.dir-locals.el b/.dir-locals.el
index ce7febca851592db48f35e4419f87f45bf582402..1f08c882e0bed0e48c46515e8832bd6eace4d9ac 100644 (file)
--- a/.dir-locals.el
+++ b/.dir-locals.el
@@ -3,8 +3,8 @@
 
 ((nil . ((tab-width . 8)
          (sentence-end-double-space . t)
-         (fill-column . 70)
-        (emacs-lisp-docstring-fill-column . 65)
+         (fill-column . 72)
+        (emacs-lisp-docstring-fill-column . 72)
          (vc-git-annotate-switches . "-w")
          (bug-reference-url-format . "https://debbugs.gnu.org/%s")
         (diff-add-log-use-relative-names . t)

diff --git a/etc/NEWS b/etc/NEWS
index 62175c6a82b2f45b3fab0c37051a33d0cda8d0ee..d87b9162b31c15fc7269476910088785cd257af6 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1262,6 +1262,11 @@ Previously, the '@' character, which normally has 'symbol' syntax,
 would combine with a following Lisp symbol and interfere with symbol
 searching.
 
+---
+*** 'emacs-lisp-docstring-fill-column' now defaults to 72.
+It was previously 65.  The new default formats documentation strings to
+fit on fewer lines without negatively impacting readability.
+
 ** CPerl mode
 
 ---

diff --git a/lisp/emacs-lisp/lisp-mode.el b/lisp/emacs-lisp/lisp-mode.el
index ca207ff548d53299d66584ee73ea2b425d3f9529..ad0525e24be36d964d94586ac06f60112a5fe117 100644 (file)
--- a/lisp/emacs-lisp/lisp-mode.el
+++ b/lisp/emacs-lisp/lisp-mode.el
@@ -1420,14 +1420,15 @@ A prefix argument specifies pretty-printing."
 
 ;;;; Lisp paragraph filling commands.
 
-(defcustom emacs-lisp-docstring-fill-column 65
+(defcustom emacs-lisp-docstring-fill-column 72
   "Value of `fill-column' to use when filling a docstring.
 Any non-integer value means do not use a different value of
 `fill-column' when filling docstrings."
   :type '(choice (integer)
                  (const :tag "Use the current `fill-column'" t))
   :safe (lambda (x) (or (eq x t) (integerp x)))
-  :group 'lisp)
+  :group 'lisp
+  :version "30.1")
 
 (defun lisp-fill-paragraph (&optional justify)
   "Like \\[fill-paragraph], but handle Emacs Lisp comments and docstrings.