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.