Adding indent-bars to ELPA

Adding indent-bars to ELPA

[JD Smith]

[-- Attachment #1: Type: text/plain, Size: 2757 bytes --]


I propose the addition of indent-bars to ELPA.

https://github.com/jdtsmith/indent-bars
jdtsmith/indent-bars: Fast, configurable indentation guide-bars for Emacs
github.com


This mode provides highly configurable indentation guide bars using stipple or character display.  Recent versions add optional treesitter-enabled local "scope" for additional focus.  There are many options to influence the behavior and appearance of the bars. 

A couple of issues relevant to developers: stipple support, and multi-backend jit-lock.

Stipple support:

During development, I was surprised to learn that not all emacsen support stipple display.  This situation is as far as I know not documented anywhere, though it does seem to be improving:

- PGTK builds had partially broken stipple support, but this was recently fixed (bug#64969)
- The NS port has had partial stipple support recently added, but this fix is incomplete — color is missing, for example (bug#70712). 
- Stipple support was added very recently to Windows (bug#71159).
- Cairo apparently interferes with/inhibits stipple display, based on a user report.
- Other builds AFAIK support stipple display, including unofficial builds like emacs-mac.

In any case, stipples aren't required for indent-bars to function, since character display can be used (also for terminal), but it seems like consistent stipple support across supported builds matching the docs would be worthwhile.  For now I have documented this issue and provided a test [1] to determine whether your emacs supports stipples correctly.  In case people are curious, I use window-filtered face-remapping to ensure stipples are displayed correctly on any window where they appear.  Updating these is very fast.

Multi-backend jit-lock:

Developing the full indent-bars feature set with good performance using font-lock was somewhat of a challenge, and I appreciate the good advice I received from many members of this list.  The current solution in indent-bars uses a roundabout approach to simulate multiple jit-lock backends, as we discussed in Bug#71345.  This allows position-dependent font-locking to be relatively efficient, since often only the positionally-aware highlighting needs to be updated.  This is working quite well, and to me indicates that a more formalized API for multiple jit-lock backends, all flexibly "sharing" the fontification redisplay invalidation it manages would be very useful.  Anyone interested should join the discussion there.

More generally, those who are interested in coupling position-dependent treesitter queries to font-lock may find indent-bars a useful example.

[1] https://github.com/jdtsmith/indent-bars/tree/main?tab=readme-ov-file#testing-stipples


[-- Attachment #2.1: Type: text/html, Size: 6601 bytes --]

[-- Attachment #2.2: indent-bars.png --]
[-- Type: image/png, Size: 130370 bytes --]

Re: Adding indent-bars to ELPA

[Eli Zaretskii]

> From: JD Smith <jdtsmith@gmail.com>
> Date: Wed, 24 Jul 2024 14:33:16 -0400
> 
> I propose the addition of indent-bars to ELPA.
> 
> https://github.com/jdtsmith/indent-bars
> jdtsmith/indent-bars: Fast, configurable indentation guide-bars for Emacs
> github.com
> 
> 
> This mode provides highly configurable indentation guide bars using stipple or character display.  Recent versions add optional treesitter-enabled local "scope" for additional focus.  There are many options to influence the behavior and appearance of the bars. 

Interesting feature.  FWIW, I think this should be built-in, and
implemented in the display engine, not as a Lisp add-on.

It seems to work well, but has some problems with RTL text.  To see
this, visit xdisp.c, turn on the mode, then go to around line 1900,
set bidi-paragraph-direction to 'right-to-left', and scroll up and
down several times: you will see broken bars, both with
indent-bars-prefer-character nil and non-nil.

RE: [External] : Re: Adding indent-bars to ELPA

[Drew Adams]

> > This mode provides highly configurable indentation guide bars using
> stipple or character display.  Recent versions add optional treesitter-
> enabled local "scope" for additional focus.  There are many options to
> influence the behavior and appearance of the bars.
> 
> Interesting feature.  FWIW, I think this should be built-in, and
> implemented in the display engine, not as a Lisp add-on.

+1.

Seems similar to the kind of indication provided
by `display-fill-column-indicator-mode'.

Re: Adding indent-bars to ELPA

[JD Smith]

> On Jul 24, 2024, at 3:08 PM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: JD Smith <jdtsmith@gmail.com>
>> Date: Wed, 24 Jul 2024 14:33:16 -0400
>> 
>> I propose the addition of indent-bars to ELPA.
>> 
>> https://github.com/jdtsmith/indent-bars
>> jdtsmith/indent-bars: Fast, configurable indentation guide-bars for Emacs
>> github.com
>> 
>> 
>> This mode provides highly configurable indentation guide bars using stipple or character display.  Recent versions add optional treesitter-enabled local "scope" for additional focus.  There are many options to influence the behavior and appearance of the bars.
> 
> Interesting feature.  FWIW, I think this should be built-in, and
> implemented in the display engine, not as a Lisp add-on.

Something to build towards for sure.  Perhaps internal display engine support for all the heavy graphics lifting, and lisp config for treesitter etc. would be an interesting model.  In any case it's working well now for lots of users for over a year, so ELPA seems like the next step.

> It seems to work well, but has some problems with RTL text.  To see
> this, visit xdisp.c, turn on the mode, then go to around line 1900,
> set bidi-paragraph-direction to 'right-to-left', and scroll up and
> down several times: you will see broken bars, both with
> indent-bars-prefer-character nil and non-nil.

Hmm, I can say it's definitely never been tested with RTL.  Is that a mode people typically use for column-oriented content like code or config files?  Do you mean broken bars in the top partially displayed line?  I don't see any artifacts in RTL other than this, but I can't rule out build-dependent issues of course.

Re: Adding indent-bars to ELPA

[Eli Zaretskii]

> From: JD Smith <jdtsmith@gmail.com>
> Date: Wed, 24 Jul 2024 15:32:21 -0400
> Cc: emacs-devel <emacs-devel@gnu.org>
> 
> > It seems to work well, but has some problems with RTL text.  To see
> > this, visit xdisp.c, turn on the mode, then go to around line 1900,
> > set bidi-paragraph-direction to 'right-to-left', and scroll up and
> > down several times: you will see broken bars, both with
> > indent-bars-prefer-character nil and non-nil.
> 
> Hmm, I can say it's definitely never been tested with RTL.  Is that a mode people typically use for column-oriented content like code or config files?  Do you mean broken bars in the top partially displayed line?  I don't see any artifacts in RTL other than this, but I can't rule out build-dependent issues of course.

RTL text is generally for human-readable text, not for program source.
But (a) I see no reason why this feature must never be supported for
text files (think Org, for example), and (b) these problems indicate
some subtle issues with display stuff in the package, so I'd suggest
at least to understand why they happen, if not fix them -- it could
well be that this is just a tip of some larger iceberg.

As for where I see broken bars: yes, they are at the top, but at least
with indent-bars-prefer-character I saw them crop up in the middle as
well, after I scrolled up and down several times.  I think I saw them
also with indent-bars-prefer-character nil, but I'm less sure.

Re: Adding indent-bars to ELPA

[JD Smith]

> On Jul 25, 2024, at 1:11 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: JD Smith <jdtsmith@gmail.com>
>> Date: Wed, 24 Jul 2024 15:32:21 -0400
>> Cc: emacs-devel <emacs-devel@gnu.org>
>> 
>>> It seems to work well, but has some problems with RTL text.  To see
>>> this, visit xdisp.c, turn on the mode, then go to around line 1900,
>>> set bidi-paragraph-direction to 'right-to-left', and scroll up and
>>> down several times: you will see broken bars, both with
>>> indent-bars-prefer-character nil and non-nil.
>> 
>> Hmm, I can say it's definitely never been tested with RTL.  Is that a mode people typically use for column-oriented content like code or config files?  Do you mean broken bars in the top partially displayed line?  I don't see any artifacts in RTL other than this, but I can't rule out build-dependent issues of course.

> these problems indicate
> some subtle issues with display stuff in the package, so I'd suggest
> at least to understand why they happen, if not fix them -- it could
> well be that this is just a tip of some larger iceberg.
> 
> As for where I see broken bars: yes, they are at the top, 

I took a look at the broken bars at the top, which are the only display artifact I see in while in RTL.  The problem turns out to be unrelated to indent-bars, but rather I believe has revealed an Emacs display bug in RTL mode pertaining to replacing display.  The behavior is that the left-to-right order of display replacing text remains incorrectly un-inverted on the 1st displayed line.  This is I believe what led to the broken (and left-right color swapped) bars you are seeing.

I've filed a bug report with a reproducer (not including stipples).

Re: Adding indent-bars to ELPA

[JD Smith]

[-- Attachment #1: Type: text/plain, Size: 327 bytes --]


> On Jul 24, 2024, at 2:33 PM, JD Smith <jdtsmith@gmail.com> wrote:
> 
> 
> I propose the addition of indent-bars to ELPA.
> 
> https://github.com/jdtsmith/indent-bars
> 

Following up this request to add indent-bars to ELPA.  The display issue in RTL mode which Eli mentioned was an Emacs bug, fixed in #72287.


[-- Attachment #2: Type: text/html, Size: 3403 bytes --]

Re: Adding indent-bars to ELPA

[Stefan Kangas]

JD Smith <jdtsmith@gmail.com> writes:

>> On Jul 24, 2024, at 2:33 PM, JD Smith <jdtsmith@gmail.com> wrote:
>>
>>
>> I propose the addition of indent-bars to ELPA.
>>
>> https://github.com/jdtsmith/indent-bars
>>
>
> Following up this request to add indent-bars to ELPA.  The display issue in RTL mode which Eli mentioned was an Emacs bug, fixed in #72287.

Philip, Stefan, WDYT?

Meanwhile, I can only echo Eli's sentiment that we should really have
this built-in and implemented in the display engine.  I've therefore
added this to etc/TODO on the release branch; further edits welcome.

Bar drawing in display engine, master indent-spacing variable

[JD Smith]

> On Sep 14, 2024, at 10:38 AM, Stefan Kangas <stefankangas@gmail.com> wrote:
> 
> JD Smith <jdtsmith@gmail.com> writes:
> 
>>> On Jul 24, 2024, at 2:33 PM, JD Smith <jdtsmith@gmail.com> wrote:
>>> 
>>> 
>>> I propose the addition of indent-bars to ELPA.
>>> 
>>> https://github.com/jdtsmith/indent-bars
>>> 
>> 
>> Following up this request to add indent-bars to ELPA.  The display issue in RTL mode which Eli mentioned was an Emacs bug, fixed in #72287.
> 
> Philip, Stefan, WDYT?
> 
> Meanwhile, I can only echo Eli's sentiment that we should really have
> this built-in and implemented in the display engine. 

Perhaps ideal would be to have low level drawing primitives available in the display engine (and automatically handling space vs. tab, blank/too-short lines, etc.).  Then lighter weight lisp packages can drive them.  Such packages can then get entirely out of the overlay/font-lock/stipple/replacing display-char business, and focus on the interesting logic (like treesitter scopes).  If these draw primitives are sufficiently generic, I suspect lots of different applications would occur to people, beyond just indentation guides.

One other very simple thing which would help here would be to have one master variable across all modes that sets (or is set to) the indentation spacing (`indent-spacing' ?).  Each mode pretty much goes its own way now.