bug#62677: 30.0.50; Need to find a better name for flyspell-prog-mode

bug#62677: 30.0.50; Need to find a better name for flyspell-prog-mode

[Michael Heerdegen]

Hello,

`flyspell-prog-mode' is a variant of `flyspell-mode' for editing
programs: it limits spell checking to areas of text fontified with
certain faces (`flyspell-prog-text-faces', normally strings and
comments).  The intention is obviously to skip keywords and tags that
are used by the programming language itself.

However, the name is confusing and undiscoverable: the name suggests
that `flyspell-prog-mode' has a direct relation to `prog-mode' or that
it would be a major mode (like `prog-mode').

`flyspell-prog-mode' seems to be much older than `prog-mode', but since
we have added `prog-mode' the name "flyspell-prog-mode" is kind of a
"false friend".  AFAIU there is no relation between the two names at all
but an etymological one.  In particular it is not necessary for
`flyspell-prog-mode' that the current major mode derives from
`prog-mode'.

In sum the name "flyspell-prog-mode" has become a very bad one.  We
should obsolete it and find a better one.


TIA,

Michael.


In GNU Emacs 30.0.50 (build 7, x86_64-pc-linux-gnu, cairo version
 1.16.0) of 2023-04-04 built on drachen
Repository revision: e1e4974862517ad5df2831508c39179ce178e0ef
Repository branch: master
Windowing system distributor 'The X.Org Foundation', version 11.0.12011000
System Description: Debian GNU/Linux 11 (bullseye)

bug#62677: 30.0.50; Need to find a better name for flyspell-prog-mode

[Payas Relekar]

Michael Heerdegen <michael_heerdegen@web.de> writes:

> `flyspell-prog-mode' is a variant of `flyspell-mode' for editing
> programs: it limits spell checking to areas of text fontified with
> certain faces (`flyspell-prog-text-faces', normally strings and
> comments).  The intention is obviously to skip keywords and tags that
> are used by the programming language itself.
>
> In sum the name "flyspell-prog-mode" has become a very bad one.  We
> should obsolete it and find a better one.

flyspell-limit-region-mode ?
--

bug#62677: 30.0.50; Need to find a better name for flyspell-prog-mode

[Akib Azmain Turja via Bug reports for GNU Emacs, the Swiss army knife of text editors]

[-- Attachment #1: Type: text/plain, Size: 950 bytes --]

Payas Relekar <relekarpayas@gmail.com> writes:

> Michael Heerdegen <michael_heerdegen@web.de> writes:
>
>> `flyspell-prog-mode' is a variant of `flyspell-mode' for editing
>> programs: it limits spell checking to areas of text fontified with
>> certain faces (`flyspell-prog-text-faces', normally strings and
>> comments).  The intention is obviously to skip keywords and tags that
>> are used by the programming language itself.
>>
>> In sum the name "flyspell-prog-mode" has become a very bad one.  We
>> should obsolete it and find a better one.

flyspell-human-text-mode?
flyspell-comment-and-string-mode?

>
> flyspell-limit-region-mode ?
> --

flyspell-limited-mode?
flyspell-ltd-mode?
flyspell-co-mode?
flyspell-inc-mode?

-- 
Akib Azmain Turja, GPG key: 70018CE5819F17A3BBA666AFE74F0EFA922AE7F5
Fediverse: akib@hostux.social
Codeberg: akib
emailselfdefense.fsf.org | "Nothing can be secure without encryption."

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

bug#62677: 30.0.50; Need to find a better name for flyspell-prog-mode

[Eli Zaretskii]

> Cc: Michael Heerdegen <michael_heerdegen@web.de>, 62677@debbugs.gnu.org
> Date: Wed, 05 Apr 2023 21:04:38 +0600
> From:  Akib Azmain Turja via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> >> In sum the name "flyspell-prog-mode" has become a very bad one.  We
> >> should obsolete it and find a better one.
> 
> flyspell-human-text-mode?
> flyspell-comment-and-string-mode?
> 
> >
> > flyspell-limit-region-mode ?
> > --
> 
> flyspell-limited-mode?
> flyspell-ltd-mode?
> flyspell-co-mode?
> flyspell-inc-mode?

flyspell-skip-keywords-mode
flyspell-ignore-keywords-mode

bug#62677: 30.0.50; Need to find a better name for flyspell-prog-mode

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > flyspell-skip-keywords-mode
  > flyspell-ignore-keywords-mode

I don't think that name correctly describes what the function does.
Its code suggests that it limits spell checking to string constants
and comments.  That means, if I understand it right, that keywords
won't be spell checked, and symbol names also won't be spell checked.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

bug#62677: 30.0.50; Need to find a better name for flyspell-prog-mode

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: 62677@debbugs.gnu.org
> Date: Thu, 06 Apr 2023 22:43:01 -0400
> 
>   > flyspell-skip-keywords-mode
>   > flyspell-ignore-keywords-mode
> 
> I don't think that name correctly describes what the function does.
> Its code suggests that it limits spell checking to string constants
> and comments.

??? Where do you see a reference to strings and comments in the two
names I suggested?

> That means, if I understand it right, that keywords
> won't be spell checked, and symbol names also won't be spell checked.

"Symbol" has no meaning for descendants of Text mode which use markup
commands.  It is only meaningful for programming language modes.  And
this feature is not limited to programming languages, that's the
source of the original confusing name to begin with.

bug#62677: 30.0.50; Need to find a better name for flyspell-prog-mode

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > >   > flyspell-skip-keywords-mode
  > >   > flyspell-ignore-keywords-mode
  > > 
  > > I don't think that name correctly describes what the function does.
  > > Its code suggests that it limits spell checking to string constants
  > > and comments.

  > ??? Where do you see a reference to strings and comments in the two
  > names I suggested?

I saw that in a diff that was in one of the emails in this thread.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

bug#62677: 30.0.50; Need to find a better name for flyspell-prog-mode

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: 62677@debbugs.gnu.org
> Date: Sun, 09 Apr 2023 22:53:25 -0400
> 
>   > >   > flyspell-skip-keywords-mode
>   > >   > flyspell-ignore-keywords-mode
>   > > 
>   > > I don't think that name correctly describes what the function does.
>   > > Its code suggests that it limits spell checking to string constants
>   > > and comments.
> 
>   > ??? Where do you see a reference to strings and comments in the two
>   > names I suggested?
> 
> I saw that in a diff that was in one of the emails in this thread.

That was a suggestion from someone else, and I agree that it is
sub-optimal, for the reasons you gave.  Which is why I suggested
different names, without a reference to comments or strings.

bug#62677: 30.0.50; Need to find a better name for flyspell-prog-mode

[Dmitry Gutov]

On 05/04/2023 18:04, Akib Azmain Turja via Bug reports for GNU Emacs, 
the Swiss army knife of text editors wrote:

> flyspell-comment-and-string-mode?

I like this one.

bug#62677: 30.0.50; Need to find a better name for flyspell-prog-mode

[Juri Linkov]

> We should obsolete it and find a better one.

Too late to rename it because it runs 'flyspell-prog-mode-hook'
customized by users.

bug#62677: 30.0.50; Need to find a better name for flyspell-prog-mode

[Michael Heerdegen]

Juri Linkov <juri@linkov.net> writes:

> > We should obsolete it and find a better one.
>
> Too late to rename it because it runs 'flyspell-prog-mode-hook'
> customized by users.

Can't we use a `defvaralias' like in other places?

Michael.

bug#62677: 30.0.50; Need to find a better name for flyspell-prog-mode

[Augusto Stoffel]

On Wed,  5 Apr 2023 at 19:44, Michael Heerdegen wrote:

> Juri Linkov <juri@linkov.net> writes:
>
>> > We should obsolete it and find a better one.
>>
>> Too late to rename it because it runs 'flyspell-prog-mode-hook'
>> customized by users.
>
> Can't we use a `defvaralias' like in other places?
>
> Michael.

I don't think a name tweak is useful.  If an improvement is at all
necessary, then just get rid of flyspell-prog-mode, that is, make
flyspell-mode skip keywords and the like by default in prog-derived
modes.  This is what is intended 99.7% of the time.

For the remaining 0.3% of the cases, it's more productive to provide an
easier way to customize what is ignored by Flyspell, using e.g. the
`spelling-ignore-functions' hook I suggested in the emacs-devel thread.

bug#62677: 30.0.50; Need to find a better name for flyspell-prog-mode

[Eli Zaretskii]

> Cc: 62677@debbugs.gnu.org
> From: Juri Linkov <juri@linkov.net>
> Date: Wed, 05 Apr 2023 19:17:46 +0300
> 
> > We should obsolete it and find a better one.
> 
> Too late to rename it because it runs 'flyspell-prog-mode-hook'
> customized by users.

We could keep the hook name, with or without an alias.

bug#62677: 30.0.50; Need to find a better name for flyspell-prog-mode

[Jim Porter]

On 4/5/2023 6:13 AM, Michael Heerdegen wrote:
> `flyspell-prog-mode' is a variant of `flyspell-mode' for editing
> programs: it limits spell checking to areas of text fontified with
> certain faces (`flyspell-prog-text-faces', normally strings and
> comments).  The intention is obviously to skip keywords and tags that
> are used by the programming language itself.

For what it's worth, when I started using flyspell-mode last year and 
subsequently discovered flyspell-prog-mode, I immediately understood 
what its intent was from the name. So from my perspective, it's actually 
a very good name. In particular, I never got the sense that it was a 
major mode or that it was *directly* tied to prog-mode; only that 
flyspell-prog-mode is most useful for programming-like modes (which are 
usually, but not always, derived from prog-mode).

It's possible there's a better name, but is the name really the main 
problem for discoverability? As far as discoverability goes, I believe I 
found out about flyspell-prog-mode via flyspell-mode's docstring:

> This mode is geared toward text modes.  In buffers that contain
> code, ‘flyspell-prog-mode’ is usually a better choice.

If there are still discoverability issues, then I think we should try to 
provide appropriate keywords in manuals, etc so that it's easier to find 
this. The problem of undiscoverable/misleading/opaque names in Emacs 
comes up fairly regularly (e.g. with Eglot), and while clear naming is 
helpful, I think it would be more helpful to make it easier for users to 
search for packages, modes, etc using whatever keywords make sense to 
them. Then discoverability is more about ensuring that we specify an 
appropriate set of keywords.

bug#62677: 30.0.50; Need to find a better name for flyspell-prog-mode

[Eli Zaretskii]

> Date: Wed, 5 Apr 2023 13:29:59 -0700
> From: Jim Porter <jporterbugs@gmail.com>
> 
> On 4/5/2023 6:13 AM, Michael Heerdegen wrote:
> > `flyspell-prog-mode' is a variant of `flyspell-mode' for editing
> > programs: it limits spell checking to areas of text fontified with
> > certain faces (`flyspell-prog-text-faces', normally strings and
> > comments).  The intention is obviously to skip keywords and tags that
> > are used by the programming language itself.
> 
> For what it's worth, when I started using flyspell-mode last year and 
> subsequently discovered flyspell-prog-mode, I immediately understood 
> what its intent was from the name. So from my perspective, it's actually 
> a very good name.

That depends on what you understood ;-)  It could be that you
understood it immediately, but incorrectly or inaccurately.

> > This mode is geared toward text modes.  In buffers that contain
> > code, ‘flyspell-prog-mode’ is usually a better choice.

The above is inaccurate as well: text-derived modes for markup text
can also benefit.  Basically, anything where you have keywords that
are not necessarily words in a human language.

> If there are still discoverability issues, then I think we should try to 
> provide appropriate keywords in manuals, etc so that it's easier to find 
> this.

IMO, we should start with what the manual says:

     Flyspell Prog mode works just like ordinary Flyspell mode, except
  that it only checks words in comments and string constants.  This
  feature is useful for editing programs.

Which might try to explain the name, but in doing so, it misses the
opportunity to let the readers discover what that mode truly is and
what it can do.

bug#62677: 30.0.50; Need to find a better name for flyspell-prog-mode

[Jim Porter]

On 4/5/2023 11:24 PM, Eli Zaretskii wrote:
>> Date: Wed, 5 Apr 2023 13:29:59 -0700
>> From: Jim Porter <jporterbugs@gmail.com>
>>
>> On 4/5/2023 6:13 AM, Michael Heerdegen wrote:
>>> `flyspell-prog-mode' is a variant of `flyspell-mode' for editing
>>> programs: it limits spell checking to areas of text fontified with
>>> certain faces (`flyspell-prog-text-faces', normally strings and
>>> comments).  The intention is obviously to skip keywords and tags that
>>> are used by the programming language itself.
>>
>> For what it's worth, when I started using flyspell-mode last year and
>> subsequently discovered flyspell-prog-mode, I immediately understood
>> what its intent was from the name. So from my perspective, it's actually
>> a very good name.
> 
> That depends on what you understood ;-)  It could be that you
> understood it immediately, but incorrectly or inaccurately.

To be clear, my understanding was that 'flyspell-prog-mode' is what you 
should use for modes where some text should be ignored for 
spell-checking. (Code is the most obvious example, but not the only one.)

>>> This mode is geared toward text modes.  In buffers that contain
>>> code, ‘flyspell-prog-mode’ is usually a better choice.
> 
> The above is inaccurate as well: text-derived modes for markup text
> can also benefit.  Basically, anything where you have keywords that
> are not necessarily words in a human language.

Maybe something like this would be more-precise?

"This mode spell checks all the text in a buffer.  In buffers that 
contain text that shouldn't be spell-checked (such as code or markup), 
'flyspell-prog-mode' is usually a better choice."

Then, we could expand on the docstring for 'flyspell-prog-mode', since 
it's pretty short right now.

> IMO, we should start with what the manual says:
> 
>       Flyspell Prog mode works just like ordinary Flyspell mode, except
>    that it only checks words in comments and string constants.  This
>    feature is useful for editing programs.
> 
> Which might try to explain the name, but in doing so, it misses the
> opportunity to let the readers discover what that mode truly is and
> what it can do.

Yeah, this could probably use a bit of expansion too. It does a 
reasonable job of explaining why you'd use it in a programming mode, but 
that's (arguably) already obvious from the name.

bug#62677: 30.0.50; Need to find a better name for flyspell-prog-mode

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> > This mode is geared toward text modes.  In buffers that contain
>> > code, ‘flyspell-prog-mode’ is usually a better choice.
>
> The above is inaccurate as well: text-derived modes for markup text
> can also benefit.  Basically, anything where you have keywords that
> are not necessarily words in a human language.

FWIW, that's actually not been clear to me.  I've only use it in
`prog-mode' derived modes so far.

But perhaps this goes even deeper:

I'm not sure why I can't just enable `flymake-mode' and have it do the
right thing, which IMO would be to enable `flymake-prog-mode' in modes
where it might make sense to have that behavior.  Major modes can tell
us what makes sense themselves, and if there are modes where the
decision is not clear-cut, they could make it into a user option.

Enabling something like `flymake-global-mode' and have it just work
would be pretty neat.

bug#62677: 30.0.50; Need to find a better name for flyspell-prog-mode

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Tue, 5 Sep 2023 13:57:50 -0700
> Cc: Jim Porter <jporterbugs@gmail.com>, michael_heerdegen@web.de, 62677@debbugs.gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> > This mode is geared toward text modes.  In buffers that contain
> >> > code, ‘flyspell-prog-mode’ is usually a better choice.
> >
> > The above is inaccurate as well: text-derived modes for markup text
> > can also benefit.  Basically, anything where you have keywords that
> > are not necessarily words in a human language.
> 
> FWIW, that's actually not been clear to me.  I've only use it in
> `prog-mode' derived modes so far.
> 
> But perhaps this goes even deeper:
> 
> I'm not sure why I can't just enable `flymake-mode' and have it do the
> right thing, which IMO would be to enable `flymake-prog-mode' in modes
> where it might make sense to have that behavior.  Major modes can tell
> us what makes sense themselves, and if there are modes where the
> decision is not clear-cut, they could make it into a user option.
> 
> Enabling something like `flymake-global-mode' and have it just work
> would be pretty neat.

I guess you mean flyspell-mode.

Yes, having the command automatically DTRT is always best.  So if we
can do that in at least some significant proportion of cases, I think
we should.

bug#62677: 30.0.50; Need to find a better name for flyspell-prog-mode

[Stefan Kangas]

retitle 62677 Merge flyspell-mode with flyspell-prog-mode
tags 62677 + easy
thanks

Eli Zaretskii <eliz@gnu.org> writes:

>> I'm not sure why I can't just enable `flymake-mode' and have it do the
>> right thing, which IMO would be to enable `flymake-prog-mode' in modes
>> where it might make sense to have that behavior.  Major modes can tell
>> us what makes sense themselves, and if there are modes where the
>> decision is not clear-cut, they could make it into a user option.
>>
>> Enabling something like `flymake-global-mode' and have it just work
>> would be pretty neat.
>
> I guess you mean flyspell-mode.
>
> Yes, having the command automatically DTRT is always best.  So if we
> can do that in at least some significant proportion of cases, I think
> we should.

I took a look, and it seems like it would be a relatively
straightforward addition to `flyspell-mode'.  I'm adding the tag "easy",
as this seems like a pretty good introductory project.

Here's the plan I'd propose: Add a new defvar-local
`flyspell-use-prog-mode' or somesuch that major modes can set.  Now,
when a user enables `flymake-mode' in a buffer where that variable is
non-nil, the extra stuff done in `flyspell-prog-mode' gets done too.
Then decide which built-in major modes that would benefit, and set that
variable in them.

Would `prog-mode' be a candidate though, or do we expect any modes
inheriting from it to want the regular `flyspell-mode'?

bug#62677: 30.0.50; Need to find a better name for flyspell-prog-mode

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Wed, 6 Sep 2023 11:51:14 -0700
> Cc: jporterbugs@gmail.com, michael_heerdegen@web.de, 62677@debbugs.gnu.org
> 
> Here's the plan I'd propose: Add a new defvar-local
> `flyspell-use-prog-mode' or somesuch that major modes can set.  Now,
> when a user enables `flymake-mode' in a buffer where that variable is
> non-nil, the extra stuff done in `flyspell-prog-mode' gets done too.
> Then decide which built-in major modes that would benefit, and set that
> variable in them.

SGTM.

> Would `prog-mode' be a candidate though, or do we expect any modes
> inheriting from it to want the regular `flyspell-mode'?

The former, I guess?

bug#62677: Merge flyspell-mode with flyspell-prog-mode

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 785 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Stefan Kangas <stefankangas@gmail.com>
>> Date: Wed, 6 Sep 2023 11:51:14 -0700
>> Cc: jporterbugs@gmail.com, michael_heerdegen@web.de, 62677@debbugs.gnu.org
>>
>> Here's the plan I'd propose: Add a new defvar-local
>> `flyspell-use-prog-mode' or somesuch that major modes can set.  Now,
>> when a user enables `flymake-mode' in a buffer where that variable is
>> non-nil, the extra stuff done in `flyspell-prog-mode' gets done too.
>> Then decide which built-in major modes that would benefit, and set that
>> variable in them.
>
> SGTM.
>
>> Would `prog-mode' be a candidate though, or do we expect any modes
>> inheriting from it to want the regular `flyspell-mode'?
>
> The former, I guess?

Thanks.  How does the attached patch look?

[-- Attachment #2: 0001-Make-flyspell-mode-DWIM-in-prog-mode-buffers.patch --]
[-- Type: text/x-patch, Size: 9490 bytes --]

From a922af5bf37ffd9ec27bac0413d4a01c5b5bbfec Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Sun, 24 Sep 2023 15:32:42 +0200
Subject: [PATCH] Make flyspell-mode DWIM in prog-mode buffers

* lisp/textmodes/flyspell.el: Doc fixes.
(flyspell-programming-mode-list): New variable.
(flyspell--enable-programming-mode): New helper function.
(flyspell-prog-mode): Use above new helper function, and document
as being deprecated.
(flyspell-mode): Use above new helper function.
* lisp/progmodes/prog-mode.el (prog-mode-hook): Replace
'flyspell-prog-mode' with 'flyspell-mode'.
* lisp/emacs-lisp/checkdoc.el:
* doc/emacs/fixit.texi (Spelling): Document the above.  (Bug#62677)
---
 doc/emacs/fixit.texi        | 24 ++++++---------
 etc/NEWS                    | 11 +++++++
 lisp/emacs-lisp/checkdoc.el |  2 +-
 lisp/progmodes/prog-mode.el |  7 +++--
 lisp/textmodes/flyspell.el  | 60 +++++++++++++++++++++++++++++++------
 5 files changed, 76 insertions(+), 28 deletions(-)

diff --git a/doc/emacs/fixit.texi b/doc/emacs/fixit.texi
index 78503d31a38..75d38adf35d 100644
--- a/doc/emacs/fixit.texi
+++ b/doc/emacs/fixit.texi
@@ -299,8 +299,6 @@ Spelling
 (@code{ispell-complete-word}).
 @item M-x flyspell-mode
 Enable Flyspell mode, which highlights all misspelled words.
-@item M-x flyspell-prog-mode
-Enable Flyspell mode for comments and strings only.
 @end table
 
 @kindex M-$
@@ -450,11 +448,15 @@ Spelling
 does not recognize, it highlights that word.  Type @w{@kbd{M-x
 flyspell-mode}} to toggle Flyspell mode in the current buffer.  To
 enable Flyspell mode in all text mode buffers, add
-@code{flyspell-mode} to @code{text-mode-hook}.  @xref{Hooks}.  Note
-that, as Flyspell mode needs to check each word across which you move,
-it will slow down cursor motion and scrolling commands.  It also
-doesn't automatically check the text you didn't type or move across;
-use @code{flyspell-region} or @code{flyspell-buffer} for that.
+@code{flyspell-mode} to @code{text-mode-hook}.  To enable it in
+programming language modes, add @code{flyspell-mode} to
+@code{prog-mode-hook}.  @xref{Hooks}.  In programming language modes,
+Flyspell mode will only check comments and string literals.
+
+  Note that, as Flyspell mode needs to check each word across which
+you move, it will slow down cursor motion and scrolling commands.  It
+also doesn't automatically check text that you didn't type or move
+across; use @code{flyspell-region} or @code{flyspell-buffer} for that.
 
 @findex flyspell-correct-word
 @findex flyspell-auto-correct-word
@@ -468,11 +470,3 @@ Spelling
 @w{@kbd{C-c $}} (@code{flyspell-correct-word-before-point}) will pop
 up a menu of possible corrections.  Of course, you can always correct
 the misspelled word by editing it manually in any way you like.
-
-@findex flyspell-prog-mode
-  Flyspell Prog mode works just like ordinary Flyspell mode, except
-that it only checks words in comments and string constants.  This
-feature is useful for editing programs.  Type @w{@kbd{M-x
-flyspell-prog-mode}} to enable or disable this mode in the current
-buffer.  To enable this mode in all programming mode buffers, add
-@code{flyspell-prog-mode} to @code{prog-mode-hook} (@pxref{Hooks}).
diff --git a/etc/NEWS b/etc/NEWS
index 53c8451dc19..cb4a1e9a73e 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -628,6 +628,17 @@ distracting and easily confused with actual code, or a significant
 early aid that relieves you from moving the buffer or reaching for the
 mouse to consult an error message.
 
+** Flyspell
+
++++
+*** 'flyspell-prog-mode' is now deprecated.
+Use 'flyspell-mode' instead, which will now automatically ensure that
+only text in strings and comments is spell checked in relevant modes.
+This includes any mode that inherits 'prog-mode'.  Major mode authors
+should consider adding their mode to 'flyspell-programming-mode-list',
+if it does not inherit 'prog-mode'.  'flyspell-prog-mode' will be
+marked obsolete in a future version of Emacs.
+
 ** Python Mode
 
 ---
diff --git a/lisp/emacs-lisp/checkdoc.el b/lisp/emacs-lisp/checkdoc.el
index cf7b7c318f6..a28cc45742c 100644
--- a/lisp/emacs-lisp/checkdoc.el
+++ b/lisp/emacs-lisp/checkdoc.el
@@ -106,7 +106,7 @@
 ;; install into Ispell on the fly, but only if Ispell is not already
 ;; running.  Use `ispell-kill-ispell' to make checkdoc restart it with
 ;; these words enabled.
-;;   See also the `flyspell-prog-mode' minor mode.
+;;   See also the `flyspell-mode' minor mode.
 ;;
 ;; Checking parameters:
 ;;
diff --git a/lisp/progmodes/prog-mode.el b/lisp/progmodes/prog-mode.el
index 37c54a90f42..35d57b34857 100644
--- a/lisp/progmodes/prog-mode.el
+++ b/lisp/progmodes/prog-mode.el
@@ -46,9 +46,10 @@ prog-mode
 (defcustom prog-mode-hook nil
   "Normal hook run when entering programming modes."
   :type 'hook
-  :options '(flyspell-prog-mode abbrev-mode flymake-mode
-                                display-line-numbers-mode
-                                prettify-symbols-mode))
+  :options '( flyspell-mode abbrev-mode flymake-mode
+              display-line-numbers-mode
+              prettify-symbols-mode)
+  :version "30.1")
 
 (defun prog-context-menu (menu click)
   "Populate MENU with xref commands at CLICK."
diff --git a/lisp/textmodes/flyspell.el b/lisp/textmodes/flyspell.el
index 1ca508e14ef..e61b01e90b1 100644
--- a/lisp/textmodes/flyspell.el
+++ b/lisp/textmodes/flyspell.el
@@ -26,14 +26,37 @@
 ;; Flyspell is a minor Emacs mode performing on-the-fly spelling
 ;; checking.
 ;;
-;; To enable Flyspell minor mode, type M-x flyspell-mode.
+;; To enable Flyspell minor mode, type `M-x flyspell-mode'.
 ;; This applies only to the current buffer.
 ;;
-;; To enable Flyspell in text representing computer programs, type
-;; M-x flyspell-prog-mode.
-;; In that mode only text inside comments and strings is checked.
+;; To automatically enable flyspell-mode in all buffers using a
+;; certain mode, add something like the following to your init file:
+;;
+;;     (add-to-hook 'text-mode-hook 'flyspell-mode)
+;;
+;; For example, to enable it in programming language modes, you can
+;; use:
+;;
+;;     (add-to-hook 'prog-mode-hook 'flyspell-mode)
+;;
+;; When spell checking source code, it doesn't necessarily make sense
+;; to spell check things like names of variables and functions.  In
+;; such modes, flycheck will therefore automatically restrict itself
+;; to checking only text in strings and comments.
 ;;
 ;; Use `M-x customize-group RET flyspell RET' to customize flyspell.
+;;
+;; * `flyspell-prog-mode' is deprecated
+;;
+;; Note that `flyspell-prog-mode' is deprecated starting with Emacs
+;; 30.1.  Use 'flyspell-mode' instead, which will now automatically
+;; ensure that only text in strings and comments is spell checked in
+;; relevant modes.  This includes any mode that inherits 'prog-mode'.
+;;
+;; Major mode authors should consider adding their mode to
+;; 'flyspell-programming-mode-list', if it does not inherit
+;; 'prog-mode'.  'flyspell-prog-mode' will be marked obsolete in a
+;; future version of Emacs.
 
 ;;; Code:
 
@@ -385,6 +408,7 @@ sgml-mode-flyspell-verify
 ;;*---------------------------------------------------------------------*/
 ;;*    Programming mode                                                 */
 ;;*---------------------------------------------------------------------*/
+
 (defcustom flyspell-prog-text-faces
   '(font-lock-string-face font-lock-comment-face font-lock-doc-face)
   "Faces corresponding to text in programming-mode buffers."
@@ -393,6 +417,18 @@ flyspell-prog-text-faces
               (const font-lock-doc-face))
   :version "28.1")
 
+(defvar flyspell-programming-mode-list '(prog-mode)
+  "List of modes for which programming language semantics will be applied.
+If a mode is in this list, only strings and comments will be
+spell checked by 'flyspell-mode' in buffers using that mode.
+
+This is same behavior as if using the old `flyspell-prog-mode',
+which is deprecated starting with Emacs 30.1.")
+
+(defun flyspell--enable-programming-mode ()
+  (setq flyspell-generic-check-word-predicate
+        #'flyspell-generic-progmode-verify))
+
 (defun flyspell-generic-progmode-verify ()
   "Used for `flyspell-generic-check-word-predicate' in programming modes."
   (unless (eql (point) (point-min))
@@ -402,10 +438,13 @@ flyspell-generic-progmode-verify
 
 ;;;###autoload
 (defun flyspell-prog-mode ()
-  "Turn on `flyspell-mode' for comments and strings."
+  "Turn on `flyspell-mode' for comments and strings.
+
+This function is deprecated starting with Emacs 30.1.
+Instead of using this, add the relevant major mode to
+`flyspell-programming-mode-list' and invoke `flymake-mode'."
   (interactive)
-  (setq flyspell-generic-check-word-predicate
-        #'flyspell-generic-progmode-verify)
+  (flyspell--enable-programming-mode)
   (flyspell-mode 1)
   (run-hooks 'flyspell-prog-mode-hook))
 
@@ -516,8 +555,11 @@ flyspell-mode
   :group 'flyspell
   (if flyspell-mode
       (condition-case err
-          (flyspell--mode-on (called-interactively-p 'interactive))
-	(error (message "Error enabling Flyspell mode:\n%s" (cdr err))
+          (progn
+            (when (derived-mode-p flyspell-programming-mode-list)
+              (flyspell--enable-programming-mode))
+            (flyspell--mode-on (called-interactively-p 'interactive)))
+        (error (message "Error enabling Flyspell mode:\n%s" (cdr err))
 	       (flyspell-mode -1)))
     (flyspell--mode-off)))
 
-- 
2.42.0

bug#62677: Merge flyspell-mode with flyspell-prog-mode

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Sun, 24 Sep 2023 07:08:56 -0700
> Cc: michael_heerdegen@web.de, jporterbugs@gmail.com, 62677@debbugs.gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> From: Stefan Kangas <stefankangas@gmail.com>
> >> Date: Wed, 6 Sep 2023 11:51:14 -0700
> >> Cc: jporterbugs@gmail.com, michael_heerdegen@web.de, 62677@debbugs.gnu.org
> >>
> >> Here's the plan I'd propose: Add a new defvar-local
> >> `flyspell-use-prog-mode' or somesuch that major modes can set.  Now,
> >> when a user enables `flymake-mode' in a buffer where that variable is
> >> non-nil, the extra stuff done in `flyspell-prog-mode' gets done too.
> >> Then decide which built-in major modes that would benefit, and set that
> >> variable in them.
> >
> > SGTM.
> >
> >> Would `prog-mode' be a candidate though, or do we expect any modes
> >> inheriting from it to want the regular `flyspell-mode'?
> >
> > The former, I guess?
> 
> Thanks.  How does the attached patch look?

Looks good in general, but why deprecate and de-document
flyspell-prog-mode?  I can easily envision a major mode that doesn't
inherit from prog-mode, but still has defined syntax for comments and
strings: why not let users invoke flyspell-prog-mode in those cases?
Moreover, users might have customizations that reference
flyspell-prog-mode, and I see no reason to annoy them with obsoletion
warnings.

IOW, we just made the users' lives easier by automatically activating
flyspell-prog-mode when we know it's appropriate, we are not saying
that what flyspell-prog-mode does is incorrect or suboptimal.

bug#62677: Merge flyspell-mode with flyspell-prog-mode

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> Looks good in general, but why deprecate and de-document
> flyspell-prog-mode?  I can easily envision a major mode that doesn't
> inherit from prog-mode, but still has defined syntax for comments and
> strings: why not let users invoke flyspell-prog-mode in those cases?

Shouldn't such modes simply be added to the new
`flyspell-programming-mode-list' variable?

Or do you envision situations where which one is "best" will be a matter
of user preference?  If yes, we should of course keep them both.

If not, I think it makes sense to have just the one command, because it
is simpler.  This is what I had in mind.

> Moreover, users might have customizations that reference
> flyspell-prog-mode, and I see no reason to annoy them with obsoletion
> warnings.

This will not be relevant if we're keeping both commands, but just in
case:

You're right that such warnings would be a nuisance, and not really
worth it.  That's why I chose to document it as deprecated, without any
warnings.  We could also remove the sentence saying that it will be
marked as obsolete.

> IOW, we just made the users' lives easier by automatically activating
> flyspell-prog-mode when we know it's appropriate, we are not saying
> that what flyspell-prog-mode does is incorrect or suboptimal.

This seems to suggest that you envision that users might want to use one
or the other, at least in some cases.  That's perfectly fine by me, if
that's the case.

bug#62677: Merge flyspell-mode with flyspell-prog-mode

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Sun, 24 Sep 2023 09:29:23 -0700
> Cc: michael_heerdegen@web.de, jporterbugs@gmail.com, 62677@debbugs.gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Looks good in general, but why deprecate and de-document
> > flyspell-prog-mode?  I can easily envision a major mode that doesn't
> > inherit from prog-mode, but still has defined syntax for comments and
> > strings: why not let users invoke flyspell-prog-mode in those cases?
> 
> Shouldn't such modes simply be added to the new
> `flyspell-programming-mode-list' variable?

Why introduce this new variable at all?  It urges people to migrate,
for no good reason: this variable and what it does is IMO no more
elegant or easier to maintain than what we have now.  I thought we
would just turn flyspell-prog-mode automatically in descendants of
prog-mode, and leave the rest to users and authors of major modes.
What you seem to be suggesting is a much more radical change, and I'm
not sure it's justified, especially since it comes with deprecation
and user annoyance.

> Or do you envision situations where which one is "best" will be a matter
> of user preference?  If yes, we should of course keep them both.

That, too, could be possible, yes.

> If not, I think it makes sense to have just the one command, because it
> is simpler.

Is it, though?  It doesn't seem simpler for us: we still need to
maintain and document the facilities for programming modes, just
different facilities from what we have now.  And it definitely isn't
simpler for users, because what worked in Emacs 29 and before will
suddenly start producing warnings in Emacs 30.

> This is what I had in mind.

Well, AFAICT, it was never said in the discussion until now.  Which is
why I'm surprised to see this.

> > Moreover, users might have customizations that reference
> > flyspell-prog-mode, and I see no reason to annoy them with obsoletion
> > warnings.
> 
> This will not be relevant if we're keeping both commands, but just in
> case:
> 
> You're right that such warnings would be a nuisance, and not really
> worth it.  That's why I chose to document it as deprecated, without any
> warnings.  We could also remove the sentence saying that it will be
> marked as obsolete.

If we do not obsolete flyspell-prog-mode, I'm okay with the changes,
although I still think we could do equally well by just turning on
flyspell-prog-mode automatically in prog-mode descendants.

> > IOW, we just made the users' lives easier by automatically activating
> > flyspell-prog-mode when we know it's appropriate, we are not saying
> > that what flyspell-prog-mode does is incorrect or suboptimal.
> 
> This seems to suggest that you envision that users might want to use one
> or the other, at least in some cases.  That's perfectly fine by me, if
> that's the case.

Maybe, I don't know.  What I know is that every change can potentially
break someone's setup, so we should avoid making changes that are not
really necessary.

bug#62677: 30.0.50; Need to find a better name for flyspell-prog-mode

[Juri Linkov]

> Here's the plan I'd propose: Add a new defvar-local
> `flyspell-use-prog-mode' or somesuch that major modes can set.  Now,
> when a user enables `flymake-mode' in a buffer where that variable is
> non-nil, the extra stuff done in `flyspell-prog-mode' gets done too.
> Then decide which built-in major modes that would benefit, and set that
> variable in them.
>
> Would `prog-mode' be a candidate though, or do we expect any modes
> inheriting from it to want the regular `flyspell-mode'?

Removing flyspell-prog-mode will break a lot of user configs
that often contain such a pair:

  (add-hook 'text-mode-hook 'flyspell-mode)
  (add-hook 'prog-mode-hook 'flyspell-prog-mode)

bug#62677: 30.0.50; Need to find a better name for flyspell-prog-mode

[Eli Zaretskii]

> From: Juri Linkov <juri@linkov.net>
> Cc: Eli Zaretskii <eliz@gnu.org>,  michael_heerdegen@web.de,
>   jporterbugs@gmail.com,  62677@debbugs.gnu.org
> Date: Thu, 07 Sep 2023 09:30:16 +0300
> 
> > Here's the plan I'd propose: Add a new defvar-local
> > `flyspell-use-prog-mode' or somesuch that major modes can set.  Now,
> > when a user enables `flymake-mode' in a buffer where that variable is
> > non-nil, the extra stuff done in `flyspell-prog-mode' gets done too.
> > Then decide which built-in major modes that would benefit, and set that
> > variable in them.
> >
> > Would `prog-mode' be a candidate though, or do we expect any modes
> > inheriting from it to want the regular `flyspell-mode'?
> 
> Removing flyspell-prog-mode will break a lot of user configs
> that often contain such a pair:
> 
>   (add-hook 'text-mode-hook 'flyspell-mode)
>   (add-hook 'prog-mode-hook 'flyspell-prog-mode)

There's no intent to remove flyspell-prog-mode, just to make
flyspell-mode more intelligent.