bug#22043: 25.0.50; search-forward and char folding

[Mike Kupfer <m.kupfer@acm.org>]

Eli Zaretskii wrote:

> Anyway, if I return to the original issue, the section with the
> offending "Search commands in Emacs by default perform character
> folding" sentence has its main focus on explaining what is character
> folding and how to enable/disable it; it does not focus on the
> specific commands.

Well, the explanation of what character folding is actually happens in
the previous paragraph.  The one that starts with "Search commands in
Emacs by default perform character folding" is just about enabling or
disabling character folding.

I agree with your point about flow and not distracting the reader by
throwing multiple issues together.  And I think that for most users,
information about enabling/disabling char folding is more important than
knowing which functions do folding, so I think that paragraph should (as
it does) come next after the description of what char folding is.

> This is standard practice in user-level documentation, when
> describing complex issues: you first provide an overview that might
> not be 100% accurate, but should give the reader a clear and simple
> enough idea of the subject, leaving the more accurate details for
> later in-depth coverage.

Yes, but when I'm reading documentation, if I see what looks like a
definite statement and then I find something else that appears to
contradict the first statement, my first reaction is to start doubting
the documentation as a whole.  The way I usually handle this when I'm
writing is to insert a "weasel word".  What do you think about changing
the first phrase to

  Search commands in Emacs generally perform character folding by
  default

(or maybe "commonly" instead of "generally").  As a reader, this tells
me that there are exceptions but I shouldn't worry about them at this
point in the text.

As an alternative: sometimes in documentation I'll see a definite
statement, followed later by an explicit acknowledgement that the
statement was a simplification.  I'd be okay with that approach, too.
As a reader, it tells me that the first statement was deliberately
chosen, not an oversight.

regards,
mike