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

From: Eli Zaretskii <[email-masked]>
Date: Thu, 06 Apr 2023 09:24:46 +0300

> Date: Wed, 5 Apr 2023 13:29:59 -0700
> From: Jim Porter <[email-masked]>
> 
> 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.