[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#22043: 25.0.50; search-forward and char folding
From: |
Mike Kupfer |
Subject: |
bug#22043: 25.0.50; search-forward and char folding |
Date: |
Mon, 30 Nov 2015 12:31:43 -0800 |
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
- bug#22043: 25.0.50; search-forward and char folding, (continued)
- bug#22043: 25.0.50; search-forward and char folding, Eli Zaretskii, 2015/11/29
- bug#22043: 25.0.50; search-forward and char folding, Mike Kupfer, 2015/11/29
- bug#22043: 25.0.50; search-forward and char folding, Drew Adams, 2015/11/29
- bug#22043: 25.0.50; search-forward and char folding, Eli Zaretskii, 2015/11/29
- bug#22043: 25.0.50; search-forward and char folding, Drew Adams, 2015/11/29
- bug#22043: 25.0.50; search-forward and char folding, Mike Kupfer, 2015/11/29
- bug#22043: 25.0.50; search-forward and char folding, Eli Zaretskii, 2015/11/30
- bug#22043: 25.0.50; search-forward and char folding, Artur Malabarba, 2015/11/30
- bug#22043: 25.0.50; search-forward and char folding, Eli Zaretskii, 2015/11/30
- bug#22043: 25.0.50; search-forward and char folding,
Mike Kupfer <=
- bug#22043: 25.0.50; search-forward and char folding, Eli Zaretskii, 2015/11/30
- bug#22043: 25.0.50; search-forward and char folding, Artur Malabarba, 2015/11/29
- bug#22043: 25.0.50; search-forward and char folding, Eli Zaretskii, 2015/11/29