Re: emacs-30 9adb05422ea: ; Improve obsolescence of 'text-mode-variant'

[Stephen Berman]

On Tue, 29 Apr 2025 17:15:16 +0300 Eli Zaretskii <eliz@gnu.org> wrote:

>> From: Stephen Berman <stephen.berman@gmx.net>
>> Cc: Eli Zaretskii <eliz@gnu.org>
>> Date: Tue, 29 Apr 2025 12:13:49 +0200
>> 
>> On Tue, 29 Apr 2025 03:11:14 -0400 (EDT) Eli Zaretskii <eliz@gnu.org> wrote:
>> 
>> > branch: emacs-30
>> > commit 9adb05422eaaa290a6a0542ba8862b806b34fe7c
>> > Author: Eli Zaretskii <eliz@gnu.org>
>> > Commit: Eli Zaretskii <eliz@gnu.org>
>> >
>> >     ; Improve obsolescence of 'text-mode-variant'
>> >     
>> >     * lisp/textmodes/text-mode.el (text-mode-variant): Improve
>> >     obsolescence announcement text.
>> >     
>> >     * doc/lispref/modes.texi (Example Major Modes): Update example.
>> >     (Bug#78125).
>> > ---
>> >  doc/lispref/modes.texi      | 3 ---
>> >  lisp/textmodes/text-mode.el | 4 +++-
>> >  2 files changed, 3 insertions(+), 4 deletions(-)
>> >
>> > diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
>> > index 31d420eedb6..3a6b163c81c 100644
>> > --- a/doc/lispref/modes.texi
>> > +++ b/doc/lispref/modes.texi
>> > @@ -1509,9 +1509,6 @@ You can thus get the full benefit of adaptive filling
>> >   (see the variable `adaptive-fill-mode').
>> >  \\@{text-mode-map@}
>> >  Turning on Text mode runs the normal hook `text-mode-hook'."
>> > -@end group
>> > -@group
>> > -  (setq-local text-mode-variant t)
>> >    (setq-local require-final-newline mode-require-final-newline))
>> >  @end group
>> >  @end smallexample
>> 
>> With this change, the statement just before the example ("Here is how
>> the actual mode command is defined now:") is now false and the second
>> sentence in the node (beginning "Here are excerpts from ‘text-mode.el’
>> [...]") is at least misleading.
>
> I think these minor issues are a fair price for being much more
> future-proof.  Do we really want to remember updating this example
> when the variable is removed from Emacs?

That sounds like something that a suitable script under admin/ could be
useful for.  Alternatively, what about changing the above statements to
something like the following: "Here is a lightly simplified/modified
definition of the actual mode command:" and "Here are lightly
simplified/modified excerpts from ‘text-mode.el [...]’.  There are other
examples like that in the Elisp manual, e.g. in (elisp) Mode Line
Variables: "Here is a simplified version of the default value of
‘mode-line-format’.  The real default value also specifies addition of
text properties."

Steve Berman