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

[Jim Porter <jporterbugs@gmail.com>]

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.