Re: Upcoming merge of adaptive-wrap

[Dmitry Gutov <dmitry@gutov.dev>]

On 26/01/2024 06:03, Po Lu wrote:
> Dmitry Gutov <dmitry@gutov.dev> writes:
> 
>> If you're talking about getting a feature known to the maximum number
>> of users possible (and not just hardcore ones who are with us for
>> decades and scrutinize every new release), a lot of those potential
>> users either have been using Emacs a while and don't read NEWS for
>> every release, or will install their first Emacs of some later version
>> than the one that the feature X has been added (and thus will miss all
>> older NEWS files).
> 
> I have been using Emacs for "a while", and I read NEWS with every new
> release with no difficulty whatsoever.  Regardless of the extent of our
> users' inclination to read NEWS, Emacs's facilities for searching
> through multiple files are more than adequate for locating features
> there, and even if not, it is not reasonable to argue that a drastic
> difference in detail is nullified by arranging items in a one-line
> format.

But would they, largely? You actually have to visit the directory which 
hosts NEWS on your system (where is it installed to?), mark all previous 
NEWS files and do the search. That's non-trivial.

> Compare:
> 
>    adaptive-wrap  Smart line-wrapping with wrap-prefix
> 
> with:
> 
> * Editing Changes in Emacs 30.1
> 
> ** New minor mode 'visual-wrap-prefix-mode'.
> 
> When enabled, continuation lines displayed for a folded long line will
> receive a 'wrap-prefix' automatically computed from surrounding context
> by the function 'fill-context-prefix', which generally indents
> continuation lines as if the line were filled with 'M-q', or similar.
> 
> I don't think any of us are capable of arguing with a straight face that
> the first example will earn adaptive-wrap more users than will the
> second.

If you sit every user behind a screen and force them to read either of 
the texts entirely, sure. But that's not how it usually works.

> Not to mention that other documentation will be installed to
> accommodate users who are not upgrading Emacs, which you have not taken
> into account at all.

It's a good explanation (easier to understand than the summary, I 
agree), but I'm curious what would you improve in the summary to make it 
more recognizable. Any particular keywords? From where I'm standing, 
even after reading the description, all the important ones seem to be 
there: "wrap", "adaptive", "line-wrapping", "wrap-prefix".

Even if you're reading the NEWS, you probably don't carefully scan every 
entry, so there must be some particular words which might have piqued 
your interest in the way that the current summary does not.

>> 1139 one-liner summaries, OTOH, are always searchable with C-s.
> 
> And how do you suggest users search for adaptive-wrap, armed with little
> information beyond that feature's behavior?  For the terse descriptions
> in the package list to be useful, the user must already be aware of the
> name of the package being sought or the description its author has
> chosen.

The one-liner description indeed needs to be recognizable enough.