Subject: bug#56197: [PATCH v2] lisp: Introduce a `lisp-fill-paragraph-as-displayed' variable.

From: Eli Zaretskii <[email-masked]>
Date: Sun, 19 Jan 2025 15:13:21 +0200

> From: Maxim Cournoyer <[email-masked]>
> Cc: [email-masked],
> 	[email-masked],
> 	[email-masked],
> 	[email-masked],
> 	Maxim Cournoyer <[email-masked]>
> Date: Sun, 19 Jan 2025 21:51:56 +0900
> 
> Starting with Emacs 28, filling strings now happens in a narrowed scope,
> and looses the leading indentation and can cause the string to extend
> past the fill-column value.  Introduce `lisp-fill-paragraph-as-displayed'
> as a new variable allowing opting out of this new behavior in specific
> scenarios (such as when using the Scheme major mode, say).

Thanks, a few minor comments below.

> * lisp/emacs-lisp/lisp-mode.el (lisp-fill-paragraph-as-displayed): New
> variable.
> (lisp-fill-paragraph): Honor it, by avoiding the logic narrow to strings
> before applying fill-paragraph.
> * test/lisp/emacs-lisp/lisp-mode-tests.el
> (lisp-fill-paragraph-respects-fill-column): Test it.
> (lisp-fill-paragraph-docstring-boundaries): New test, as a safeguard to
> avoid regressions.

Please format these entries according to our conventions, mostly
regarding the line length (it should be at most 69 columns, preferably
no more than 64.

> -;; Copyright (C) 1985-1986, 1999-2024 Free Software Foundation, Inc.
> +;; Copyright (C) 1985-1986, 1999-2025 Free Software Foundation, Inc.

Please rebase on the current master branch, where the copyright years
were already updated.

> +(defvar lisp-fill-paragraph-as-displayed nil
> +  "This variable can be set to true to fill paragraphs as displayed in the
> +buffer, preserving surrounding context such as the leading indentation.
> +This is useful if respecting `fill-column' is more important than
> +preventing surrounding code from being filled, and makes
> +`lisp-fill-paragraph' behave as it used to in Emacs 27 and prior
> +versions.")

The first line of a doc string should be a single full sentence.
(This is because the various apropos commands show only the first
line.)

More importantly, I think this doc string should describe the main use
case for which the default behavior is tuned: filling Emacs Lisp doc
strings, with their special treatment of the first line.