Upcoming merge of adaptive-wrap

Upcoming merge of adaptive-wrap

[Po Lu]

Several months ago I tried to contact the maintainer of adaptive-wrap
regarding the inclusion of his package into Emacs proper, who did not
respond over all the months that have since passed.  (In general I was
met with stony silence.  It's funny how pandemonium erupts when a minor
proposal to introduce _new_ code appears, but the same people wash their
hands of minor chores required for the code to remain useful.)  It's a
fair bet that the package maintainer is not actively engaged in its
development anymore, so if I hear no serious objections in the next few
days I will write the documentation and merge this invaluable feature
into master.

I think placing the package on ELPA was unwise and would not have taken
place but for our obsession with moving things to ELPA.  Minor features
will never justify the hassle of browsing through the package list,
downloading them from the Internet, and updating them with each new
release of Emacs that obsoletes this or that feature.  For the future,
could we please adopt at least the following two criteria for installing
packages in ELPA rather than Emacs?  They're not very precise but better
than nothing.

  - The package is of sufficient size to be worthy of Internet
    installation, and provides features in demand high enough that users
    proactively research and install them.

  - The package maintainer desires that it be distributed over ELPA.

Even those proprietary text editors developed behind closed doors do not
relegate useful text editing features to their extension repositories.
Users are forced to distribute small enhancements there, because the
developers of such text editors are not receptive to users acting on
their own initiatives.  We are not so conceited, and should make the
most of this advantage of ours.

Re: Upcoming merge of adaptive-wrap

[Adam Porter]

Far be it from me to open a bikeshedding on a package's name...  :)  But 
in light of this message, I can't help but wonder if a more descriptive 
name would be something like "visual-wrap" or "virtual-wrap".

To me, "adaptive-wrap" doesn't imply that its effects are only 
visual--rather, it seems to suggest that it wraps text based on some 
kind of adaptive criteria.

"visual-wrap" would seem like a natural counterpart to 
"visual-line-mode", implying that its effects are only visual in nature, 
leaving the underlying contents unchanged (which matches the package's 
description).

Just my two cents before the package is merged.

Re: Upcoming merge of adaptive-wrap

[Stephen Berman]

Sorry for not responding to your message from last August 10, which I
have just found again; FWIW I have these excuses for my negligence:
First, I was on vacation at the time and didn't see the message till
around two weeks later.  Second, you wrote in that message:

> Stefan, what do you say to this?  Since the package in ELPA, migrating
> it into Emacs should not pose any legal difficulties, so the only
> prerequisites are suitable entries in NEWS and the documentation,
> correct?

From this I thought you were addressing Stefan Monnier, who is nominally
the co-author of the package (but actually is responsible for the most
important part of the implementation).  Third, I didn't know (or had
forgotten) that I'm still listed as maintainer of the package, a role
that I've not wanted to have for a long time.  In fact, in a private
exchange in June 2020 as followup to bug#41810, Stefan asked Kévin Le
Gouguec if he would like to assume the maintainership, though AFAIK
neither that question nor the bug report have been resolved; I've added
both to the Cc:.

In any case, I have no objection to moving adaptive-wrap from GNU ELPA
to Emacs core; but whatever the outcome, I would like to be removed as
maintainer.

Thanks.

Steve Berman

On Thu, 25 Jan 2024 09:39:47 +0800 Po Lu <luangruo@yahoo.com> wrote:

> Several months ago I tried to contact the maintainer of adaptive-wrap
> regarding the inclusion of his package into Emacs proper, who did not
> respond over all the months that have since passed.  (In general I was
> met with stony silence.  It's funny how pandemonium erupts when a minor
> proposal to introduce _new_ code appears, but the same people wash their
> hands of minor chores required for the code to remain useful.)  It's a
> fair bet that the package maintainer is not actively engaged in its
> development anymore, so if I hear no serious objections in the next few
> days I will write the documentation and merge this invaluable feature
> into master.
>
> I think placing the package on ELPA was unwise and would not have taken
> place but for our obsession with moving things to ELPA.  Minor features
> will never justify the hassle of browsing through the package list,
> downloading them from the Internet, and updating them with each new
> release of Emacs that obsoletes this or that feature.  For the future,
> could we please adopt at least the following two criteria for installing
> packages in ELPA rather than Emacs?  They're not very precise but better
> than nothing.
>
>   - The package is of sufficient size to be worthy of Internet
>     installation, and provides features in demand high enough that users
>     proactively research and install them.
>
>   - The package maintainer desires that it be distributed over ELPA.
>
> Even those proprietary text editors developed behind closed doors do not
> relegate useful text editing features to their extension repositories.
> Users are forced to distribute small enhancements there, because the
> developers of such text editors are not receptive to users acting on
> their own initiatives.  We are not so conceited, and should make the
> most of this advantage of ours.

Re: Upcoming merge of adaptive-wrap

[Po Lu]

Stephen Berman <stephen.berman@gmx.net> writes:

> Sorry for not responding to your message from last August 10, which I
> have just found again; FWIW I have these excuses for my negligence:
> First, I was on vacation at the time and didn't see the message till
> around two weeks later.  Second, you wrote in that message:
>
>> Stefan, what do you say to this?  Since the package in ELPA, migrating
>> it into Emacs should not pose any legal difficulties, so the only
>> prerequisites are suitable entries in NEWS and the documentation,
>> correct?
>
> From this I thought you were addressing Stefan Monnier, who is nominally
> the co-author of the package (but actually is responsible for the most
> important part of the implementation).

I think I was addressing Stefan Kangas at the time, not you.  But I
could be mistaken.  I'm glad this misunderstanding is over with.

> Third, I didn't know (or had forgotten) that I'm still listed as
> maintainer of the package, a role that I've not wanted to have for a
> long time.  In fact, in a private exchange in June 2020 as followup to
> bug#41810, Stefan asked Kévin Le Gouguec if he would like to assume
> the maintainership, though AFAIK neither that question nor the bug
> report have been resolved; I've added both to the Cc:.
>
> In any case, I have no objection to moving adaptive-wrap from GNU ELPA
> to Emacs core; but whatever the outcome, I would like to be removed as
> maintainer.

OK, then the merge will take place in a few days, provided that no other
objections arise.

Re: Upcoming merge of adaptive-wrap

[Eli Zaretskii]

> From: Po Lu <luangruo@yahoo.com>
> Cc: emacs-devel@gnu.org,  Stefan Monnier <monnier@iro.umontreal.ca>,
>  Kévin Le Gouguec <kevin.legouguec@gmail.com>
> Date: Thu, 25 Jan 2024 19:32:07 +0800
> 
> > In any case, I have no objection to moving adaptive-wrap from GNU ELPA
> > to Emacs core; but whatever the outcome, I would like to be removed as
> > maintainer.
> 
> OK, then the merge will take place in a few days, provided that no other
> objections arise.

Please consider changing the name, as was suggested here (and I agree
that having "visual" in the name would be better).

Re: Upcoming merge of adaptive-wrap

[Po Lu]

Eli Zaretskii <eliz@gnu.org> writes:

> Please consider changing the name, as was suggested here (and I agree
> that having "visual" in the name would be better).

That email was caught in my spam filter, but I agree, so will do.

Re: Upcoming merge of adaptive-wrap

[Kévin Le Gouguec]

Hi,

Stephen Berman <stephen.berman@gmx.net> writes:

> Sorry for not responding to your message from last August 10, which I
> have just found again; FWIW I have these excuses for my negligence:
> First, I was on vacation at the time and didn't see the message till
> around two weeks later.  Second, you wrote in that message:
>
>> Stefan, what do you say to this?  Since the package in ELPA, migrating
>> it into Emacs should not pose any legal difficulties, so the only
>> prerequisites are suitable entries in NEWS and the documentation,
>> correct?
>
> From this I thought you were addressing Stefan Monnier, who is nominally
> the co-author of the package (but actually is responsible for the most
> important part of the implementation).  Third, I didn't know (or had
> forgotten) that I'm still listed as maintainer of the package, a role
> that I've not wanted to have for a long time.  In fact, in a private
> exchange in June 2020 as followup to bug#41810, Stefan asked Kévin Le
> Gouguec if he would like to assume the maintainership, though AFAIK
> neither that question nor the bug report have been resolved; I've added
> both to the Cc:.

Thanks for the reminder; my memory was that I had declined as politely
as I could, but re-reading my answer back then it was way too…  I'd say
"tongue-in-cheek", but it contained a character whose name actually
includes "STUCK-OUT TONGUE", so that does not sound right.

Jokes aside, I think my pattern of contribution to Emacs since then (or
lack thereof) confirms my unspoken concern at the time: I don't know
that I can give the time and attention maintainership deserves¹.
Certainly not in equal measure to the passion the OP has expressed for
this package.

(FWIW Po Lu, your message in August did not go unnoticed and has
remained "ticked" in my Gnus ever since, to watch for replies)

> In any case, I have no objection to moving adaptive-wrap from GNU ELPA
> to Emacs core; but whatever the outcome, I would like to be removed as
> maintainer.

No strong opinion.  Thoughts though:

* Since adaptive-wrap implicitly relies on adaptive-fill-regexp, it's
  been on my mind that the mode could achieve better visual results if
  major modes "cooperated" and adjusted that variable, yet a lot of
  modes (e.g. read-only special modes) have no incentive to do so, since
  they are not expected to "hard-fill" text.

  E.g. adaptive-wrap in diff-mode currently looks inconsistent because
  ?- is part of adaptive-fill-regexp, but not ?+.  This makes removed
  lines wrapped with extra indent, but not added lines.  diff-mode could
  solve this by adding "+" to adaptive-fill-regexp, but why should it?
  No-one runs M-q on patches.

  All that to say: I've been wondering whether having adaptive-wrap in
  core would be a "good enough" incentive to push for such mode-specific
  tweaks to adaptive-fill-regexp; maybe it's neither necessary nor
  sufficient.

* Catching up on the rest of the thread: if the goal is discoverability,
  I think the most likely remedy long-term (NEWS will only help in the
  "short" term, until it is rotated into NEWS.30) will be pointers from
  visual-line-mode's documentation (docstring and/or manual).

  Here too, I can't firmly conclude that moving to core is necessary;
  can the documentation of core features like visual-line-mode reference
  features found in GNU ELPA, like adaptive-wrap?  If so, I would expect
  that to offer all the visibility this package needs; at least, not
  much less than it will get by being moved to core.

tl;dr Sure why not maybe I don't know?

Anyhoo.  Got a couple of pandemonium eruptions to catch up with 😊


¹ I have accrued a laundry list of things I would like to fix with
adaptive-wrap (account for face backgrounds from overlays; account for
face foregrounds from prefixes; heed any prefix's 'display property;
play nice with whitespace-mode) and have no patch to show for it.

I still use that package daily, but given my track record at scratching
my own itches I don't think *stewardship* should be on the table.

Re: Upcoming merge of adaptive-wrap

[Po Lu]

Kévin Le Gouguec <kevin.legouguec@gmail.com> writes:

> * Catching up on the rest of the thread: if the goal is discoverability,
>   I think the most likely remedy long-term (NEWS will only help in the
>   "short" term, until it is rotated into NEWS.30) will be pointers from
>   visual-line-mode's documentation (docstring and/or manual).

I did mention that when I started this thread, didn't I?  :-)

>   Here too, I can't firmly conclude that moving to core is necessary;
>   can the documentation of core features like visual-line-mode reference
>   features found in GNU ELPA, like adaptive-wrap?  If so, I would expect
>   that to offer all the visibility this package needs; at least, not
>   much less than it will get by being moved to core.

There's also the deterrent effect of requiring a download over the
Internet and updates separate from Emacs.

Re: Upcoming merge of adaptive-wrap

[Joost Kremers]

On Fri, Jan 26 2024, Kévin Le Gouguec wrote:
> * Catching up on the rest of the thread: if the goal is discoverability,
>   I think the most likely remedy long-term (NEWS will only help in the
>   "short" term, until it is rotated into NEWS.30) will be pointers from
>   visual-line-mode's documentation (docstring and/or manual).

Wouldn't it make more sense to make this simply a configurable option in
visual-line-mode, that defaults to "on"? From a user's perspective, I think that
makes the most sense, doesn't it? At least I personally have always wondered why
this is a separate package and not part of visual-line-mode.


-- 
Joost Kremers
Life has its moments

Re: Upcoming merge of adaptive-wrap

[Eli Zaretskii]

> From: Joost Kremers <joostkremers@fastmail.fm>
> Cc: Stephen Berman <stephen.berman@gmx.net>, Po Lu <luangruo@yahoo.com>,
>  Stefan Monnier <monnier@iro.umontreal.ca>, emacs-devel@gnu.org
> Date: Fri, 26 Jan 2024 12:26:17 +0100
> 
> 
> On Fri, Jan 26 2024, Kévin Le Gouguec wrote:
> > * Catching up on the rest of the thread: if the goal is discoverability,
> >   I think the most likely remedy long-term (NEWS will only help in the
> >   "short" term, until it is rotated into NEWS.30) will be pointers from
> >   visual-line-mode's documentation (docstring and/or manual).
> 
> Wouldn't it make more sense to make this simply a configurable option in
> visual-line-mode, that defaults to "on"? From a user's perspective, I think that
> makes the most sense, doesn't it? At least I personally have always wondered why
> this is a separate package and not part of visual-line-mode.

What does it mean for this to be a configurable option of
visual-line-mode?  How is it different from turning on another minor
mode?

Re: Upcoming merge of adaptive-wrap

[Joost Kremers]

On Fri, Jan 26 2024, Eli Zaretskii wrote:
>> From: Joost Kremers <joostkremers@fastmail.fm>
>> Wouldn't it make more sense to make this simply a configurable option in
>> visual-line-mode, that defaults to "on"? From a user's perspective, I think
>> that makes the most sense, doesn't it? At least I personally have always
>> wondered why this is a separate package and not part of visual-line-mode.
>
> What does it mean for this to be a configurable option of
> visual-line-mode?  How is it different from turning on another minor
> mode?

My thinking was that this is something a user would probably want to have
enabled by default (I do, anyway), and for that, a Configure option seems the
logical choice.

-- 
Joost Kremers
Life has its moments

Re: Upcoming merge of adaptive-wrap

[Stefan Monnier]

Joost Kremers [2024-01-26 14:47:42] wrote:
> On Fri, Jan 26 2024, Eli Zaretskii wrote:
>>> From: Joost Kremers <joostkremers@fastmail.fm>
>>> Wouldn't it make more sense to make this simply a configurable option in
>>> visual-line-mode, that defaults to "on"? From a user's perspective, I think
>>> that makes the most sense, doesn't it? At least I personally have always
>>> wondered why this is a separate package and not part of visual-line-mode.
>> What does it mean for this to be a configurable option of
>> visual-line-mode?  How is it different from turning on another minor
>> mode?
> My thinking was that this is something a user would probably want to have
> enabled by default (I do, anyway), and for that, a Configure option seems the
> logical choice.

[ A global minor mode also gives you a Configure option :-)  ]

But should it be tied to `visual-line-mode` (as opposed to, say, the
value of `word-wrap`)?


        Stefan

Re: Upcoming merge of adaptive-wrap

[Madhu]

* Stefan Monnier <jwvwmrptivv.fsf-monnier+emacs @gnu.org> :
Wrote on Wed, 31 Jan 2024 14:18:46 -0500:
> Joost Kremers [2024-01-26 14:47:42] wrote:
>> On Fri, Jan 26 2024, Eli Zaretskii wrote:
>>>> From: Joost Kremers <joostkremers@fastmail.fm>
>>>> Wouldn't it make more sense to make this simply a configurable option in
>>>> visual-line-mode, that defaults to "on"? From a user's perspective, I think
>>>> that makes the most sense, doesn't it? At least I personally have always
>>>> wondered why this is a separate package and not part of visual-line-mode.
>>> What does it mean for this to be a configurable option of
>>> visual-line-mode?  How is it different from turning on another minor
>>> mode?
>> My thinking was that this is something a user would probably want to have
>> enabled by default (I do, anyway), and for that, a Configure option seems the
>> logical choice.
>
> [ A global minor mode also gives you a Configure option :-)  ]
>
> But should it be tied to `visual-line-mode` (as opposed to, say, the
> value of `word-wrap`)?

Does this mode do what obsolete/longlines.el used to be able to do? (set
a column and "visually" wrap to that without changing the underlying
buffer)?

BTW I've had some strange behaviour when reading this tread on this on
gmane a number of articles seem to have come with all new-lines removed

article numbers (around Jan 28). the first article seems to be gone from
gmane.

315402~  ;; <871qa4oo40.fsf@yahoo.com>
315461~
315492~
315499~
315505~

Re: Upcoming merge of adaptive-wrap

[Eli Zaretskii]

> From: Madhu <enometh@meer.net>
> Date: Fri, 02 Feb 2024 10:11:01 +0530
> 
> Does this mode do what obsolete/longlines.el used to be able to do? (set
> a column and "visually" wrap to that without changing the underlying
> buffer)?

Something like that.  Only it is not about wrapping, it's about
line-prefix.

> BTW I've had some strange behaviour when reading this tread on this on
> gmane a number of articles seem to have come with all new-lines removed
> 
> article numbers (around Jan 28). the first article seems to be gone from
> gmane.
> 
> 315402~  ;; <871qa4oo40.fsf@yahoo.com>
> 315461~
> 315492~
> 315499~
> 315505~

We do not maintain gmane, so I suggest that you take this up with the
gmane folks.

Re: Upcoming merge of adaptive-wrap

[Dmitry Gutov]

On 25/01/2024 03:39, Po Lu wrote:
> Several months ago I tried to contact the maintainer of adaptive-wrap
> regarding the inclusion of his package into Emacs proper, who did not
> respond over all the months that have since passed.  (In general I was
> met with stony silence.  It's funny how pandemonium erupts when a minor
> proposal to introduce _new_ code appears, but the same people wash their
> hands of minor chores required for the code to remain useful.

One goes well in hand with the other: more code means more code for 
somebody to maintain.

>)  It's a
> fair bet that the package maintainer is not actively engaged in its
> development anymore, so if I hear no serious objections in the next few
> days I will write the documentation and merge this invaluable feature
> into master.

So... your plan it to merge an unmaintained piece of code into master?

If your intention was to contribute fixes, I think you have commit 
access to the ELPA repository.

> I think placing the package on ELPA was unwise and would not have taken
> place but for our obsession with moving things to ELPA.  Minor features
> will never justify the hassle of browsing through the package list,
> downloading them from the Internet, and updating them with each new
> release of Emacs that obsoletes this or that feature.

There is a particular advantage for optional features being in ELPA: 
people can browse it and search the list of keywords. It serves as a 
tool for discovery for many.

When the package is in the core, it doesn't appear in any of similar 
structured lists, you really have to hunt around for discover those 
features.

> For the future,
> could we please adopt at least the following two criteria for installing
> packages in ELPA rather than Emacs?  They're not very precise but better
> than nothing.
> 
>    - The package is of sufficient size to be worthy of Internet
>      installation, and provides features in demand high enough that users
>      proactively research and install them.
> 
>    - The package maintainer desires that it be distributed over ELPA.
> 
> Even those proprietary text editors developed behind closed doors do not
> relegate useful text editing features to their extension repositories.

That's incorrect.

And we also have the example of the popular open source text editor 
(which is dominating the rating on stackoverflow, etc) which puts a lot 
of language features in the packages' repository.

Re: Upcoming merge of adaptive-wrap

[Stefan Kangas]

Dmitry Gutov <dmitry@gutov.dev> writes:

> There is a particular advantage for optional features being in ELPA:
> people can browse it and search the list of keywords. It serves as a
> tool for discovery for many.
>
> When the package is in the core, it doesn't appear in any of similar
> structured lists, you really have to hunt around for discover those
> features.

Maybe more "optional but built-in" packages should be visible in `M-x
list-packages'?  Would that help?  It's not hard to do: we just add a
"Version" header and that's it, I think.

Re: Upcoming merge of adaptive-wrap

[Dmitry Gutov]

On 25/01/2024 22:01, Stefan Kangas wrote:
> Dmitry Gutov<dmitry@gutov.dev>  writes:
> 
>> There is a particular advantage for optional features being in ELPA:
>> people can browse it and search the list of keywords. It serves as a
>> tool for discovery for many.
>>
>> When the package is in the core, it doesn't appear in any of similar
>> structured lists, you really have to hunt around for discover those
>> features.
> Maybe more "optional but built-in" packages should be visible in `M-x
> list-packages'?  Would that help?  It's not hard to do: we just add a
> "Version" header and that's it, I think.

Maybe. They will join the part of the list tagged as "built-in".

Re: Upcoming merge of adaptive-wrap

[Po Lu]

Dmitry Gutov <dmitry@gutov.dev> writes:

> One goes well in hand with the other: more code means more code for
> somebody to maintain.

"Maintain" in this context means "running admin/update-copyright every
year", which task I am more than happy to take on.

> So... your plan it to merge an unmaintained piece of code into master?

"Unmaintained" is a very loaded word.  I would rather describe it as
"working."

But the implications of your sentence aside, that is precisely my plan,
yes.

> If your intention was to contribute fixes, I think you have commit
> access to the ELPA repository.

My intention is to guarantee that this feature is known to the maximum
number of users possible, that it may actually be _useful_, rather than
languishing in ELPA.  I'd been passively searching for such a feature
since the time not filling columns to a reasonable width became popular
with a certain programmer demographic, yet learned of adaptive-wrap from
word-of-mouth, not the package list, gnu-emacs-sources, or the like.

Had it been part of Emacs from the outset (thus documented, mentioned in
NEWS, and so on), it would undoubtedly be less obscure than it is now.

Re: Upcoming merge of adaptive-wrap

[Dmitry Gutov]

On 26/01/2024 03:45, Po Lu wrote:
>> If your intention was to contribute fixes, I think you have commit
>> access to the ELPA repository.
> My intention is to guarantee that this feature is known to the maximum
> number of users possible, that it may actually be_useful_, rather than
> languishing in ELPA.  I'd been passively searching for such a feature
> since the time not filling columns to a reasonable width became popular
> with a certain programmer demographic, yet learned of adaptive-wrap from
> word-of-mouth, not the package list, gnu-emacs-sources, or the like.
> 
> Had it been part of Emacs from the outset (thus documented, mentioned in
> NEWS, and so on), it would undoubtedly be less obscure than it is now.

Does that mean that you don't use ELPA (or 'M-x list-packages') yourself?

Scanning though the latter's output should be much easier (and faster) 
than going through the NEWS files several releases back, or reading 
through all the manuals that come with Emacs.

Re: Upcoming merge of adaptive-wrap

[Po Lu]

Dmitry Gutov <dmitry@gutov.dev> writes:

> Does that mean that you don't use ELPA (or 'M-x list-packages') yourself?

I do.

> Scanning though the latter's output should be much easier (and faster)
> than going through the NEWS files several releases back, or reading
> through all the manuals that come with Emacs.

It is much easier to overlook entries in a list of 1139 one-line
descriptions than in a document where each item is illustrated in
reasonable detail and grouped with related entries along semantic lines.
Moreover, it is only necessary to read NEWS once, after installing a new
release of Emacs.

Re: Upcoming merge of adaptive-wrap

[Dmitry Gutov]

On 26/01/2024 04:22, Po Lu wrote:
>> Scanning though the latter's output should be much easier (and faster)
>> than going through the NEWS files several releases back, or reading
>> through all the manuals that come with Emacs.
> It is much easier to overlook entries in a list of 1139 one-line
> descriptions than in a document where each item is illustrated in
> reasonable detail and grouped with related entries along semantic lines.
> Moreover, it is only necessary to read NEWS once, after installing a new
> release of Emacs.

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).

1139 one-liner summaries, OTOH, are always searchable with C-s.

Re: Upcoming merge of adaptive-wrap

[Po Lu]

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.  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.  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.

> 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.

Re: Upcoming merge of adaptive-wrap

[Dmitry Gutov]

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.

Re: Upcoming merge of adaptive-wrap

[Po Lu]

Dmitry Gutov <dmitry@gutov.dev> writes:

> 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.

Is this meant to imply that selecting "Help -> Emacs News", then typing
`C-x d' is non-trivial?  What about reading the manual, or any other of
Emacs's built-in facilities for assisting users?

When users are stumped, their first reactions are to reach for the
documentation, be that the manual, apropos or NEWS.  Perhaps there is a
breed of users for whom the package list is the first resort, but for
the reasons previously mentioned, the package list is unlikely to help
them.

The negligible portion of these users who give up after being frustrated
by the package list (if they exist at all) will never find the objects
of their searches, and won't be affected by decisions to place packages
in core or on ELPA.

It also stands to reason that users outside the first two categories are
more inclined to take to a search engine, and to them this thread will
be more enlightening than the package menu ever will.

> 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.

[...]

> 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".

I never proposed to improve the summary, since in my opinion, the
current package description is already the optimum under the limitations
of its format.

> 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.

The mental effort required to understand the NEWS and the documentation
I installed is so little that, truly, the only words left to be said are
"there are none so blind as those who will not see", assuming that the
reader is searching for this feature.

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

I cannot imagine how that might be accomplished.

Thanks.

Re: Upcoming merge of adaptive-wrap

[Dmitry Gutov]

On 27/01/2024 05:58, Po Lu wrote:
> Dmitry Gutov <dmitry@gutov.dev> writes:
> 
>> 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.
> 
> Is this meant to imply that selecting "Help -> Emacs News", then typing
> `C-x d' is non-trivial?  What about reading the manual, or any other of
> Emacs's built-in facilities for assisting users?

It's an order of a magnitude more involved than 'M-x list-packages' 
followed by C-s.

> When users are stumped, their first reactions are to reach for the
> documentation, be that the manual, apropos or NEWS.

Through Google -- maybe.

> It also stands to reason that users outside the first two categories are
> more inclined to take to a search engine, and to them this thread will
> be more enlightening than the package menu ever will.

Because its title is a good match for whatever the user would search 
for? What would they search for, BTW?

>> 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.
> 
> [...]
> 
>> 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".
> 
> I never proposed to improve the summary, since in my opinion, the
> current package description is already the optimum under the limitations
> of its format.

You renamed the package to visual-wrap, so perhaps the term "visual" 
could help (instead of "smart"?).

There's also a mistake in the description now: visual-fill-mode does not 
exist.

>> 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.
> 
> The mental effort required to understand the NEWS and the documentation
> I installed is so little that, truly, the only words left to be said are
> "there are none so blind as those who will not see", assuming that the
> reader is searching for this feature.

The issue is not reading a particular NEWS entry, but finding it.

Re: Upcoming merge of adaptive-wrap

[Stefan Kangas]

Dmitry Gutov <dmitry@gutov.dev> writes:

> On 27/01/2024 05:58, Po Lu wrote:
>> Is this meant to imply that selecting "Help -> Emacs News", then typing
>> `C-x d' is non-trivial?  What about reading the manual, or any other of
>> Emacs's built-in facilities for assisting users?
>
> It's an order of a magnitude more involved than 'M-x list-packages'
> followed by C-s.

Yeah, I don't think anyone will reach for `C-x d' in NEWS unless they
already know all about these files and how they are typically installed.
Most users don't know that.

In fact, I doubt that more than a fraction of users even read NEWS.  We
have discussed this in the past, but we don't know that there is
anything to be done about it.  Similarly, no one reads our very fine
documentation.

For these reasons, we must use multiple strategies to make features more
discoverable.  There is no silver bullet.

Therefore, I think Dmitry is right in insisting that we should continue
looking for ways to make built-in features more discoverable.  I propose
that we continue thinking about it, and stay open to new ideas.

RE: [External] : Re: Upcoming merge of adaptive-wrap

[Drew Adams]

> Similarly, no one reads our very fine documentation.

What makes you think that?

Re: [External] : Re: Upcoming merge of adaptive-wrap

[Michael Albinus]

Drew Adams <drew.adams@oracle.com> writes:

>> Similarly, no one reads our very fine documentation.
>
> What makes you think that?

Experience. In the Tramp case, about half of the reports are answered by
me quoting the Tramp manual.

Best regards, Michael.

Re: [External] : Re: Upcoming merge of adaptive-wrap

[Po Lu]

Michael Albinus <michael.albinus@gmx.de> writes:

> Experience. In the Tramp case, about half of the reports are answered by
> me quoting the Tramp manual.

This could well be a perverse survivorship bias: issues experienced by
users who scrupulously read documentation never survive to the Tramp bug
tracker...

Re: [External] : Re: Upcoming merge of adaptive-wrap

[Dmitry Gutov]

On 28/01/2024 11:36, Po Lu wrote:
> Michael Albinus<michael.albinus@gmx.de>  writes:
> 
>> Experience. In the Tramp case, about half of the reports are answered by
>> me quoting the Tramp manual.
> This could well be a perverse survivorship bias: issues experienced by
> users who scrupulously read documentation never survive to the Tramp bug
> tracker...

The whole Debbugs database is one big survivorship bias.

Re: [External] : Re: Upcoming merge of adaptive-wrap

[Po Lu]

Dmitry Gutov <dmitry@gutov.dev> writes:

> The whole Debbugs database is one big survivorship bias.

No doubt.  It's turtles all the way down.

RE: [External] : Re: Upcoming merge of adaptive-wrap

[Drew Adams]

> >> Similarly, no one reads our very fine documentation.
> >
> > What makes you think that?
> 
> Experience. In the Tramp case, about half of the reports are answered
> by me quoting the Tramp manual.

Thanks for providing a reason (sincerely).

That doesn't mean that the half you quoted
the manual to hadn't read any of the manual
- or even hadn't read any of the very text
you quoted to them.

A fortiori, it doesn't mean that the half
you didn't quote the manual to hadn't read
any of that either.

It's unfortunate that people don't read the
docs as much as might benefit them.  And
it's unfortunate that sometimes when people
do read it they don't read it well enough.

I know a valid point was trying to be made,
but it's clearly not the case that "no one"
reads any of the doc.  You and I do, for
starters. ;-)

Re: Upcoming merge of adaptive-wrap

[Po Lu]

Dmitry Gutov <dmitry@gutov.dev> writes:

> It's an order of a magnitude more involved than 'M-x list-packages'
> followed by C-s.

And installing Emacs was no doubt several orders of magnitude more so.

> Through Google -- maybe.

This assessment of our users' problem-solving capabilities is not the
correct attitude to take in developing Emacs, or any software that is
not expressly designed for such individuals, as from it the logical
conclusion to draw is that there is no value in documentation itself.

How would they learn of the existence of the package list, for instance,
or where to click and what to type to display it?

> Because its title is a good match for whatever the user would search
> for? What would they search for, BTW?

The emails in this thread contain every word present in the package list
summary, so presumably the same words they would search for within the
package list; but that was meant as a rhetorical statement, not to be
taken literally.

> You renamed the package to visual-wrap, so perhaps the term "visual"
> could help (instead of "smart"?).

Not really.  The room available in package descriptions is inadequate:
descriptions are more helpful than a list of keywords, which is the best
that can be hoped in that limited space.

> There's also a mistake in the description now: visual-fill-mode does
> not exist.

Thanks.

> The issue is not reading a particular NEWS entry, but finding it.

There are none so blind as those who will not venture to see.

But fortunately for us, incorrigibly blind (in this sense) individuals
are far and few between.

Re: Upcoming merge of adaptive-wrap

[Dmitry Gutov]

On 28/01/2024 11:34, Po Lu wrote:
> Dmitry Gutov <dmitry@gutov.dev> writes:
> 
>> It's an order of a magnitude more involved than 'M-x list-packages'
>> followed by C-s.
> 
> And installing Emacs was no doubt several orders of magnitude more so.

Ah, no. Installing software and browsing packages are both activities 
that most computer users are implicitly familiar with.

>> Through Google -- maybe.
> 
> This assessment of our users' problem-solving capabilities is not the
> correct attitude to take in developing Emacs, or any software that is
> not expressly designed for such individuals, as from it the logical
> conclusion to draw is that there is no value in documentation itself.

People's capabilities are not static, but designing features which 
impose fewer requirements on such is likely to help more people, altogether.

> How would they learn of the existence of the package list, for instance,
> or where to click and what to type to display it?

 From the menu? Options -> Manage Emacs Packages. Either way, the fact 
that Emacs does have packages is a widely advertised fact, everywhere 
online.

And once you reach the packages' list, you can search across all of them 
(that appear there) using a uniform approach.

>> Because its title is a good match for whatever the user would search
>> for? What would they search for, BTW?
> 
> The emails in this thread contain every word present in the package list
> summary, so presumably the same words they would search for within the
> package list; but that was meant as a rhetorical statement, not to be
> taken literally.

I'm still unclear on what is missing from the summary, to be honest.

The NEWS entry is more verbose, sure, but that should also apply when 
the user finds a package based on the summary and clicks on it to read 
the full description to verify if that's what they wanted to use.

Re: Upcoming merge of adaptive-wrap

[Po Lu]

Dmitry Gutov <dmitry@gutov.dev> writes:

> Ah, no. Installing software and browsing packages are both activities
> that most computer users are implicitly familiar with.

Reading is an activity most literate _humans_ are intimately familar
with, but I'll humor you: the package list, in its present state as a
list of compact one-line descriptions, is not the sort of graphical
package manager computer users are well acquainted with.  The search
facilities available in such package managers source their results from
thorough descriptions provided by package authors at the time their
packages are submitted, most unlike our cascade of package names and
keywords.

> People's capabilities are not static, but designing features which
> impose fewer requirements on such is likely to help more people,
> altogether.

We are imposing no new requirements, but providing _new_ and _more
helpful_ venues through which adaptive-wrap might be discovered and
enabled.

> From the menu? Options -> Manage Emacs Packages. Either way, the fact

Why, you have neglected to mention Option -> Line Wrapping in This
Buffer -> Visual Wrap Prefix, complete with a tooltip describing its
function.

> that Emacs does have packages is a widely advertised fact, everywhere
> online.

And why is the fact that Emacs has a manual not suitably advertised?  It
is advertised on the splash screen, literally the first screen presented
to a new Emacs user.

> And once you reach the packages' list, you can search across all of
> them (that appear there) using a uniform approach.

No doubt, it will be an immeasurable relief to our users that the
technique for searching the package list is uniform, despite never
returning satisfactory results.  Over the course of my year-long tenure
as a moderator of an Emacs instant messenger group with roughly 1000
members, not once have I seen the package list credited with the
discovery of a package shared in the group.  Instead, the prevailing
sources for such discoveries, in no particular order, appear to be
Reddit, posts on both popular and obscure blogs with an interest in
Emacs, this list, NEWS, and reading the Emacs manual out of boredom,
while the package list is largely used by users to install packages
shared in the group.

> I'm still unclear on what is missing from the summary, to be honest.
>
> The NEWS entry is more verbose, sure, but that should also apply when
> the user finds a package based on the summary and clicks on it to read
> the full description to verify if that's what they wanted to use.

How about "source code comments", "unbroken appearance", or any of the
myriad of other applications for adaptive-wrap that users might seek
solutions for?

Re: Upcoming merge of adaptive-wrap

[Dmitry Gutov]

On 28/01/2024 16:25, Po Lu wrote:
> Dmitry Gutov <dmitry@gutov.dev> writes:
> 
>> Ah, no. Installing software and browsing packages are both activities
>> that most computer users are implicitly familiar with.
> 
> Reading is an activity most literate _humans_ are intimately familar
> with, but I'll humor you: the package list, in its present state as a
> list of compact one-line descriptions, is not the sort of graphical
> package manager computer users are well acquainted with.  The search
> facilities available in such package managers source their results from
> thorough descriptions provided by package authors at the time their
> packages are submitted, most unlike our cascade of package names and
> keywords.

Yeah, actually it could be a worthwhile addition. We have commands like 
package-menu-filter-by-description, but what they're actually filter by 
is the one-line summary, nor the full description from Commentary. This 
would require certain changes in the package archives, since currently 
those descriptions are fetched separately on-demand.

>> People's capabilities are not static, but designing features which
>> impose fewer requirements on such is likely to help more people,
>> altogether.
> 
> We are imposing no new requirements, but providing _new_ and _more
> helpful_ venues through which adaptive-wrap might be discovered and
> enabled.

I imagine the adaptive-wrap package will be removed from ELPA sooner or 
later. We might as well discuss the tradeoffs.

>>  From the menu? Options -> Manage Emacs Packages. Either way, the fact
> 
> Why, you have neglected to mention Option -> Line Wrapping in This
> Buffer -> Visual Wrap Prefix, complete with a tooltip describing its
> function.

This is another example where the user is supposed to recognize the 
feature by its short summary, right? "Visual Wrap Prefix Mode".

A the "tooltip describing its function" is

   Display continuation lines with visual context-dependent prefix

If you think it describes it well, seems like a good package summary?

>> that Emacs does have packages is a widely advertised fact, everywhere
>> online.
> 
> And why is the fact that Emacs has a manual not suitably advertised?  It
> is advertised on the splash screen, literally the first screen presented
> to a new Emacs user.

   Use this command and search the list for keywords

vs

   Open one of these big books and look for the thing you wanted

I wonder what would be considered easier (people go and Google instead).

>> And once you reach the packages' list, you can search across all of
>> them (that appear there) using a uniform approach.
> 
> No doubt, it will be an immeasurable relief to our users that the
> technique for searching the package list is uniform, despite never
> returning satisfactory results.  Over the course of my year-long tenure
> as a moderator of an Emacs instant messenger group with roughly 1000
> members, not once have I seen the package list credited with the
> discovery of a package shared in the group.

Your group seems to have some particular qualities that go across most 
of my experience, and those experiences I've seen conveyed on the web. 
Perhaps it has to do something with the particular ecosystem (it is a 
company which has SunOS installed somewhere, right?).

The packages list even has a specific feature that highlights the 
packages that have been added recently (since your last viewing). All in 
the name of discovery. And I've taken advantage of it many times myself.

>> I'm still unclear on what is missing from the summary, to be honest.
>>
>> The NEWS entry is more verbose, sure, but that should also apply when
>> the user finds a package based on the summary and clicks on it to read
>> the full description to verify if that's what they wanted to use.
> 
> How about "source code comments", "unbroken appearance", or any of the
> myriad of other applications for adaptive-wrap that users might seek
> solutions for?

These seem like words for additional context, but not the terms for 
describing the thing to search for. Or I misunderstand something.

Re: Upcoming merge of adaptive-wrap

[Po Lu]

Dmitry Gutov <dmitry@gutov.dev> writes:

> Yeah, actually it could be a worthwhile addition. We have commands
> like package-menu-filter-by-description, but what they're actually
> filter by is the one-line summary, nor the full description from
> Commentary. This would require certain changes in the package
> archives, since currently those descriptions are fetched separately
> on-demand.

I won't object to this, but a feature yet to exist should not figure in
our judgement of the package list's usefulness.

> I imagine the adaptive-wrap package will be removed from ELPA sooner
> or later. We might as well discuss the tradeoffs.

There are no plans to remove it from ELPA, since users who don't upgrade
to Emacs 30 won't receive visual-wrap.

> This is another example where the user is supposed to recognize the
> feature by its short summary, right? "Visual Wrap Prefix Mode".
>
> A the "tooltip describing its function" is
>
>   Display continuation lines with visual context-dependent prefix
>
> If you think it describes it well, seems like a good package summary?

Obviously, it's insufficient for users to immediately conclude that it
is the option that satisfies their wishes, but it is easily located and
evaluated, as the number of surrounding menu items is small.

>   Use this command and search the list for keywords
>
> vs
>
>   Open one of these big books and look for the thing you wanted
>
> I wonder what would be considered easier (people go and Google instead).

Nothing on the splash screen suggests the manual is "one of these big
books", or that searching within the manual will be impossible, as it is
in a book.  Nor was my question answered.

> Your group seems to have some particular qualities that go across most
> of my experience, and those experiences I've seen conveyed on the
> web. Perhaps it has to do something with the particular ecosystem (it
> is a company which has SunOS installed somewhere, right?).
>
> The packages list even has a specific feature that highlights the
> packages that have been added recently (since your last viewing). All
> in the name of discovery. And I've taken advantage of it many times
> myself.

Going forward, it would serve you well not to dismiss my experiences on
the basis of backhanded preconceptions of the individuals with whom I
interact.  My words were "instant messenger group", not "my
organization's group", and they were meant literally.

> These seem like words for additional context, but not the terms for
> describing the thing to search for. Or I misunderstand something.

Users whose requirements are best met by adaptive-wrap will search for
text editing concepts it affects, not the precise function of the
package, which they do not understand concretely enough to frame in
words.

Re: Upcoming merge of adaptive-wrap

[Po Lu]

Dmitry Gutov <dmitry@gutov.dev> writes:

> There is a particular advantage for optional features being in ELPA:
> people can browse it and search the list of keywords. It serves as a
> tool for discovery for many.
>
> When the package is in the core, it doesn't appear in any of similar
> structured lists, you really have to hunt around for discover those
> features.

Such arguments can only be evaluated in the abstract, whereas I have one
concrete example of a counterproductive effect of ELPA at hand:
adaptive-wrap.  And several more I have observed anecdotally but have
never experienced myself.

> That's incorrect.
>
> And we also have the example of the popular open source text editor
> (which is dominating the rating on stackoverflow, etc) which puts a
> lot of language features in the packages' repository.

We are miscommunicating.  adaptive-wrap is decidedly not a language
feature, it is a text editing feature, such as is supposed to be the
part and parcel of Emacs.

Thanks for your input, but I'm not convinced and this collection of
largely irrelevant information will not affect the installation of
adaptive-wrap.

Re: Upcoming merge of adaptive-wrap

[Eli Zaretskii]

> From: Po Lu <luangruo@yahoo.com>
> Cc: emacs-devel@gnu.org,  Stephen Berman <stephen.berman@gmx.net>
> Date: Fri, 26 Jan 2024 09:54:55 +0800
> 
> Thanks for your input, but I'm not convinced and this collection of
> largely irrelevant information will not affect the installation of
> adaptive-wrap.

Please be kinder in your responses.  You can disagree and even
disregard something your opponents say, but there's definitely no need
to explicitly call that "largely irrelevant", as that is an
uncalled-for insult.

Re: Upcoming merge of adaptive-wrap

[Po Lu]

Eli Zaretskii <eliz@gnu.org> writes:

> Please be kinder in your responses.  You can disagree and even
> disregard something your opponents say, but there's definitely no need
> to explicitly call that "largely irrelevant", as that is an
> uncalled-for insult.

It was not meant as an insult, so I'm sorry if it sounded thus.

Re: Upcoming merge of adaptive-wrap

[Stefan Kangas]

Po Lu <luangruo@yahoo.com> writes:

> I think placing the package on ELPA was unwise and would not have taken
> place but for our obsession with moving things to ELPA.

I can only think of one example of a package that we have moved to GNU
ELPA.  But that was the decision by the package maintainer, not us.