Subject: Re: bug#67848: 29.1; Fix usage of `setq-default' and add explanation

From: Xiyue Deng <[email-masked]>
Date: Sat, 23 Dec 2023 23:00:59 -0800

Eli Zaretskii <[email-masked]> writes:

>> From: Xiyue Deng <[email-masked]>
>> Cc: [email-masked]
>> Date: Sat, 23 Dec 2023 02:09:29 -0800
>> 
>> Eli Zaretskii <[email-masked]> writes:
>> 
>> >> From: Xiyue Deng <[email-masked]>
>> >> Date: Sat, 16 Dec 2023 03:18:20 -0800
>> >> 
>> >> 
>> > Thanks, but I think it's wrong to use setq-default here, since that
>> > makes Text mode the default major-mode (instead of Fundamental), which
>> > is not what most people would want.
>> 
>> Actually making text-mode the default mode for new files is exactly what
>> the author intended based on the text from an earlier section[1].
>
> I know, but I don't want that to be said without reservations, or not
> at all.  The author's hope was that there will be many readers of this
> manual who are not programmers, and who would then prefer Text mode as
> the default.  We are now a few decades wiser, and we know that hope
> didn't really materialize.  So we should not advertise such a setting
> without some explanations.

While I kind of agree with what you said here, this requires a much
larger rewrite of the text, because there are several paragraphs that
span several sections that follows the author's original advice of
making newly opened files to use text-mode instead of fundamental mode
by default.  Neither being a writer, nor even a native English speaker,
I don't consider myself a good candidate to make such a drastic change
to this classic book.

So instead I added another footnote at the first sentence of this
section to suggest that the suggestion was aimed for writers and the
reader can feel free not to do this.  The new patch is attached.  PTAL.

-- 
Xiyue Deng

>From d5e89a19ee7fcfe2aa6bb35f5ad84eb17819408b Mon Sep 17 00:00:00 2001
From: Xiyue Deng <[email-masked]>
Date: Sat, 23 Dec 2023 16:12:44 -0800
Subject: [PATCH] Fix usage of `setq-default' and offer more suggestions

cd61af0 changed from default-major-mode to major-mode in the first
code sample but didn't change the rest.  This patch fixes this and add
some explanations of why use `setq-default' instead of `setq'.  In
addition, it gives background on suggesting using text-mode as default
mode and suggest other alternatives.

* doc/lispintro/emacs-lisp-intro.texi (Text and Auto-fill): Fix usage
of `setq-default' and offer more suggestions.  (Bug#67848)
---
 doc/lispintro/emacs-lisp-intro.texi | 20 ++++++++++++++------
 1 file changed, 14 insertions(+), 6 deletions(-)

diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi
index 4a0e8dfa1fc..26a405361de 100644
--- a/doc/lispintro/emacs-lisp-intro.texi
+++ b/doc/lispintro/emacs-lisp-intro.texi
@@ -16892,8 +16892,12 @@ remember to look here to remind myself.
 @node Text and Auto-fill
 @section Text and Auto Fill Mode
 
-Now we come to the part that turns on Text mode and
-Auto Fill mode.
+Now we come to the part that turns on Text mode and Auto Fill
+mode.@footnote{This section suggests settings that are more suitable
+for writers.  For programmers, the default mode will be set to the
+corresponding prog-mode automatically based on the type of the file.
+And it's perfectly fine if you want to keep the fundamental mode as
+the default mode.}
 
 @smallexample
 @group
@@ -16945,15 +16949,19 @@ Here is the line again; how does it work?
 
 @cindex Text Mode turned on
 @smallexample
-(setq major-mode 'text-mode)
+(setq-default major-mode 'text-mode)
 @end smallexample
 
 @noindent
 This line is a short, but complete Emacs Lisp expression.
 
-We are already familiar with @code{setq}.  It sets the following
-variable, @code{major-mode}, to the subsequent value, which is
-@code{text-mode}.  The single-quote before @code{text-mode} tells
+We are already familiar with @code{setq}.  We use a similar macro
+@code{setq-default} to set the following variable,
+@code{major-mode}@footnote{We use @code{setq-default} because
+@code{text-mode} is buffer local.  If we use @code{setq} it will only
+apply to the current buffer, and using @code{setq-default} will also
+apply this to newly created buffers.}, to the subsequent value, which
+is @code{text-mode}.  The single-quote before @code{text-mode} tells
 Emacs to deal directly with the @code{text-mode} symbol, not with
 whatever it might stand for.  @xref{setq, , Setting the Value of
 a Variable}, for a reminder of how @code{setq} works.  The main point
-- 
2.39.2