[vim/vim] feat: hide fold text line - proposal looking for feedback

[Jim Harkins]

I started by looking at the feasibility and wound up with a proof of concept, though I intended to get feedback earlier.

Feature Proposal

Enable fold text lines to be hidden, allowing more unfolded lines to be displayed.

Use Case

This feature pairs well with foldmethod=expr. With foldexpr that matches, for example, a variable name, only lines with that variable are displayed allowing rapid scanning. In this use case, the fold text tends to get in the way. If desired, the gaps can be made apparent by turning on line numbers, ":set nu".

Precedent

Xedit, Kedit, and THE editors implement the ALL command that shows only lines that match a target. By default. a "shadow line" is displayed to represent excluded lines. The shadow line can be disabled by "SET SHADOW OFF". I've seen other editors support this but I can't name them.

While searching for an existing workaround or prior attempt at implementing this feature, I easily found occasional requests for this functionality going back at least 20 years.

Status

I have a proof of concept that I think could be improved with feedback.

Implementation details:

I've implemented a boolean option with window scope provisionally named "foldline" (abbr. "fdln"). This defaults to TRUE, which enables current behavior. Setting foline to FALSE (:set nofoldline) suppresses the display of fold text lines. I also considered naming the option "showfoldline", but I think starting a fold related command with "fold" is expected. I'm not convinced "foldlin" is the best name, but ":set nofoldline" or ":set nofdln" has felt okay in use.

Documentation (could use improvement)

doc/quickref.txt:

'foldline'       'fdln'    set to display fold text line for a closed line

doc/options.txt

   *'foldline'* *'fdln'* *'nofoldline'* *'nov'*

'foldline' 'fdln' boolean (default on)

local to window

{not available when compiled without the |+folding|

feature}

When off, fold line is not displayed.

See |folding|.

Code

https://github.com/jimhark/vim/tree/foldline

Tests

Have not been implemented. If this feature is accepted I can write the tests. These would be a big help:

1. Pointer to your testing documentation and recommended resources
2. Example test code:
1. For a window scope boolean option.
2. For a feature that changes the way the screen is drawn.

I look forward to feedback and an opportunity to get this feature accepted.

Thanks,

Jim

[Christian Brabandt]

> 1. Pointer to your testing documentation and recommended resources 2.
> Example test code: 1. For a window scope boolean option. 2. For a

> feature that changes the way the screen is drawn.
>
> I look forward to feedback and an opportunity to get this feature
> accepted.

Hi,
thanks for that. I think this would match nicely with the existing
folding feature. For one, I think the option should be called
'foldshowline' or similar so that as suggested it matches the existing
'fold' options.

However, I'd strongly suggest to somehow mark those hidden lines (e.g.
by some different highlighting), to make it apparent to the user, that
the lines are really just hidden and they are not accidentally lost
their file content.

For precedent, you may want to check some of the existing local-window
option. See :h options.txt and search for "local to window".
Documentation for the option value should go to this help file and for
the specifics of hiding lines, please add something to fold.txt
For changing the way text is rendered, check the conceal feature in
win_line().

Thanks,
Christian
--
It is the quality rather than the quantity that matters.
-- Lucius Annaeus Seneca (4 B.C. - A.D. 65)

[Jim Harkins]

Christian,

Thanks, that is exactly the kind of feedback I was looking for. I should have some time to work on this tomorrow.

1. I agree  foldshowline  is a good name and I'll make that happen.
2. I will check existing local-window options in options.txt.
3. I will update my draft changes options.txt.
4. I will add a reasonable amount of documentation to fold.txt (thanks for the heads-up on that one) .

I left the one where I don't know what to do for last. You write:

However, I'd strongly suggest to somehow mark those hidden lines (e.g.

by some different highlighting), to make it apparent to the user, that

the lines are really just hidden and they are not accidentally lost

their file content.

I share this concern. As the feature I'm suggesting eliminates any fold line when activated there is no obvious place to mark hidden lines. If there were a prefix column we could leverage that. After decades of using the proposed feature, I mean foldshowline (it has a real name now, thanks), in the Kedit editor (and IBM's Xedit mainframe editor before that), I have a pretty strong mental model for how the lines are being filtered even without fold lines (Kedit calls them shadow lines.) Still, when I'm sharing my screen I know to turn on line numbers (in vim, :set number) so others can follow along. We both agree that providing some indication of hidden lines is desirable (to, and I'll say it, not freak out the user). I have been unable to come up with a fully satisfactory solution. My best idea is to automatically turn on line numbers when a window transitions to nofoldshowline.

If we can't come up with something better, I'm willing to:

1. Implement automatically turning on line numbering when a window transitions to nofoldshowline. (I know to do this right it gets a little tricky.)
1. We should probably cache the previous line numbering state and restore it when (if) the window transitions back to foldshowline.
2. If the user explicitly sets line numbering, foldshowline's cached line numbering state should probably be cleared. (I understand this could interact poorly with existing scripts.)
   
   
2. Create an option (I'd think a global one) to fully disable the automatic switching of line numbering.

Maybe this could all be better dealt with at the z command level. I have to admit I don't think I have enough experience with vim to be comfortable designing new z command behavior, I'm still learning the vim way. But I could probably implement the behavior. In fact, if you are willing to suggest a z command that would do something like:

  :set foldmethod=expr

  :set foldexpr=getline(v:lnum)!~#'target_text'

  :set foldlevel=0

I would implement that too, though it's probably better to save that for later.

Thanks again for your help.

Jim