Better titles for folds

[iyefrat]

First of all I want to thank you for making this amazing plugin. Every time i learn something new about vim I discover that it's already integrated in the plugin! It's awesome.

I recently discovered folding, and I only really have one problem with the vimtex implementation, which is that the titles usually don't contain all the information I would want, or are formatted inconsistently. The only folding related option I turned on in the .vimrc (I'm using neovim 0.3.1, but still) is:

let g:vimtex_fold_enabled = 1

I also didn't add the recommended

  set fillchars=vert:|,fold:\

line because when I do I get an error relating to the vert part, but I don't think that has anything to do with what I'm talking about here.

I'm using the following minimal .tex file to showcase what I'm talking about in the attached photos:

%! TEX program =pdflatex

\documentclass{article}

%packages
\usepackage[utf8]{inputenc}
\usepackage[a4paper, margin=1in]{geometry}

\title{Test}
\author{me}
\date{November 2018}

\begin{document}
\maketitle
\section{}

Lorem Ipsum blah blah

\section{name}

blah blah

\subsection{}

\begin{equation}
1+1=2
\end{equation}

\begin{equation}
2+2=4
\label{eq:5}
\end{equation}

\subsubsection{hi}
hop
\subsection{other name}

\end{document}

The suggestions/gripes I have are as follows:

1. The stopping point for the filler character (in my case dots) is inconsistent. In the preamble it starts right after the title, in unlabled equations it starts after a space, in labeled equations and sections it starts much after, which is nice for consistency (and would be my preference), but there the starting point is also off by one. I would suggest that the whitespace between the title and the filler characters be like in the section for all folds. If you disagree please tell my why, I'm interested.

2. Sections (and subsections, etc.) without titles are just listed as }. This may be intended but it's kind of confusing. Even when they are titled, there is nothing to suggest that a fold contains a section or an environment with the same name, except for the placement of the filler characters (is this the reason for the inconsistency?). The only thing hinting at the section indentation level (section vs subsection, etc) is the fold indentation level, but this puts subsections on the same footing as equations (or other environments). I suggest that section tiles are preceded by their numbering, similarly to in vimtex-toc. I think this would make figuring out which fold you want to open much easier, especially if you don't have section titles, because hopefully you could just have the section number instead of } as the fold title.

3. Display the number of lines in a given fold.

Thank you for reading!

[lervag]

First of all I want to thank you for making this amazing plugin. Every time i learn something new about vim I discover that it's already integrated in the plugin! It's awesome.

Thanks!

First, for your point 2: This was a bug. I've fixed it now (empty titles are now indicated with <untitled>. The section level should be indicated by the number of stars on the left-hand side. No stars indicate top level sections, then add one star for each sub level.

The reason you get an error with set fillchars=... is because the docs are wrong. The pipe has to be escaped, i.e. you need set fillchars=vert:\|,fold:\ [note the space after the \].

I'll comment on your remaining part tomorrow evening, if I get the time. I hope this helps somewhat already, though.

[lervag]

The stopping point for the filler character (in my case dots) is inconsistent. In the preamble it starts right after the title, in unlabled equations it starts after a space, in labeled equations and sections it starts much after, which is nice for consistency (and would be my preference), but there the starting point is also off by one. I would suggest that the whitespace between the title and the filler characters be like in the section for all folds. If you disagree please tell my why, I'm interested.

First, there is no reason for the consistency. I'm fixing that asap. However, the whitespace before the filler characters should not be there. How people want to fill in whatever follows the fold text should be up to the user with the fillchars option. I prefer to use whitespace as fillers, because I think that looks best.

Even when they are titled, there is nothing to suggest that a fold contains a section or an environment with the same name, ...

I agree, so I'm changing it. I'll instead make the fold text for environments more similar to regular commands. I still prefer to keep the labels on the right hand side and to include caption text if available in the "middle" section. Let me know what you think of the changes.

I suggest that section tiles are preceded by their numbering, similarly to in vimtex-toc. I think this would make figuring out which fold you want to open much easier, especially if you don't have section titles, because hopefully you could just have the section number instead of } as the fold title.

I agree that would be better, but it is difficult to implement. It is important that the folding is quick, and I don't quite see how to implement this. The current implementation indicates the level or depth of the fold by stars on the left-hand side. Top levels have no stars, and increasing levels get more stars.

I've pushed some changes that I personally think improves things. Feel free to comment!

[lervag]

Oh, and:

Display the number of lines in a given fold.

I'd rather not. For me, it is only distracting and does not really tell me anything I need to know. If I want to know how many lines, I can easily find it with visual mode g<c-g>. That is, select a fold and then type g + CTRL-g.

[iyefrat]

Wow, this was very quick!

First, for your point 2: This was a bug. I've fixed it now (empty titles are now indicated with . The section level should be indicated by the number of stars on the left-hand side. No stars indicate top level sections, then add one star for each sub level.

I'm going to be a bit pedantic just to make sure that this is intended behavior. Subsubsections are indicated by -* and not of ** which is what you're implying.

Regarding the fix to the fillchars, I'd suggest stating explicitly in the docs that there is an escaped space there, because if you type the command in the vimrc rather than copying it it's not obvious (I was wondering why having a bunch of slashes as filler characters was cleaner than dots the first time I tried typing just the void part).

I agree, so I'm changing it. I'll instead make the fold text for environments more similar to regular commands. I still prefer to keep the labels on the right hand side and to include caption text if available in the "middle" section. Let me know what you think of the changes.

I like the changes! It's also nice to know that the empty space between the fold name and label is reserved for captions, I was wondering what was up with that. However after the pushed change the label is pushed all the way to the right of the screen (the caption is fine), as seen in the attached pictures.

I suggest that section tiles are preceded by their numbering, similarly to in vimtex-toc. I think this would make figuring out which fold you want to open much easier, especially if you don't have section titles, because hopefully you could just have the section number instead of } as the fold title.

I agree that would be better, but it is difficult to implement. It is important that the folding is quick, and I don't quite see how to implement this. The current implementation indicates the level or depth of the fold by stars on the left-hand side. Top levels have no stars, and increasing levels get more stars.

That's fair, personally I haven't really seen any slowness in the folding, but I've been working with documents that end up being less than 10 pdf pages, so I presume it's only relevant for longer documents. Is using the same mechanism that generates the section numbers in vimtex-toc not viable? The creation of the table of contents seems instantaneous. The folds for sections only seem to be generated when opening the document, are the titles dynamically generated or saved in a text file somewhere? What causes folding to be noticeably slow in general?

I'd rather not. For me, it is only distracting and does not really tell me anything I need to know. If I want to know how many lines, I can easily find it with visual mode g. That is, select a fold and then type g + CTRL-g.

Yeah this basically solves the problem, neat.

[lervag]

I'm going to be a bit pedantic just to make sure that this is intended behavior. Subsubsections are indicated by -* and not of ** which is what you're implying.

Yes, you're right. The point was that the section levels are indicated.

Regarding the fix to the fillchars, I'd suggest stating explicitly in the docs that there is an escaped space there, because if you type the command in the vimrc rather than copying it it's not obvious (I was wondering why having a bunch of slashes as filler characters was cleaner than dots the first time I tried typing just the void part).

Good point. I agree.

That's fair, personally I haven't really seen any slowness in the folding, but I've been working with documents that end up being less than 10 pdf pages, so I presume it's only relevant for longer documents. Is using the same mechanism that generates the section numbers in vimtex-toc not viable? The creation of the table of contents seems instantaneous. The folds for sections only seem to be generated when opening the document, are the titles dynamically generated or saved in a text file somewhere? What causes folding to be noticeably slow in general?

The problem is that the table of contents is generated by parsing the entire manuscript from A to Z, including all included files, once. However, the folding levels are generated by parsing each line of the current file in order. The foldexpr function is called on each line. The implementations are very different in nature, and it would be a large job to change/update things so they could benefit from the same methods. I'm not saying it is impossible, but I don't think the benefits are worth the effort.

But, if someone should know or come up with a simple way of translating a given file and line to it's correct section number, then it should not be difficult to improve the fold text in such a way.

Yeah this basically solves the problem, neat.

Great, I'm happy you agree :)

[lervag]

Ok, I've tried to implement the smarter section levels. It seems to work quite well, actually. It is disabled by default, because I suspect it may be slow for large documents. To enable, you can use this:

let g:vimtex_fold_types = {
      \ 'sections' : {'parse_levels': 1},
      \}

[lervag]

However after the pushed change the label is pushed all the way to the right of the screen (the caption is fine), as seen in the attached pictures.

Yes, I've right aligned the labels with respect to the window width. Perhaps one should allow more control over this, e.g. allow to set a manual width? I typically work within 80 columns, so for me it looks good like this. Do you have a better idea of how to "design" the fold text content when it can contain both a name, caption, and a label?

[iyefrat]

let g:vimtex_fold_types = {
     \ 'sections' : {'parse_levels': 1},
     \}

This works great.

Yes, I've right aligned the labels with respect to the window width. Perhaps one should allow more control over this, e.g. allow to set a manual width? I typically work within 80 columns, so for me it looks good like this. Do you have a better idea of how to "design" the fold text content when it can contain both a name, caption, and a label?

The problem is that in the current version, The label is not really right aligned, but rather aligned to 3 characters further than the right of the terminal, (you can see this in the attached screenshots in my last method. The label is cut off, it's seen as (lab instead of (label)) (This might happen because having 3 strings in the fold title thing gets you to window_width+3 somehow).

This wasn't the case before I opened the issue, as you can see in the attached screenshots in my first message. I'm not sure, but I think that might be right aligning the label to the 80 character column. I think this a good way to do it if there are more than 80 columns in the window, because after that there is too much whitespace.

So my suggestion would be to right-align it to the right most column if the window is less then 80 characters long, and to right-align it to the 80th column if there are more than 80 columns, and fill up the rest with filler characters.

The current behavior also seems to fix captions starting at 21 columns, and if the environment name is too long you just get \begin{long-nam...}. This is good because it keeps the captions aligned with eachother. This also almost happens the captions themselves, when they start to overtake the starting point of the label they just cut off, I'd suggest maybe having them end with ... as well.

[lervag]

The label is not really right aligned, but rather aligned to 3 characters further than the right of the terminal ...

Thanks, I've fixed this now. The math was off due to the number columns.

I've also used "..." for long captions as well, thanks for the suggestion.

However, I'm not sure about the limit of 80 columns for the total fold text width. I feel like the labels should either be fully right aligned, or we should have an option for setting the maximum width. I don't really want to add more options, though. A dilemma, you could say. Do you feel strongly about this?

[iyefrat]

Thanks, I've fixed this now. The math was off due to the number columns.

It seems that now there is a single filler character between the parentheses and the right side of the terminal, just a heads up.

However, I'm not sure about the limit of 80 columns for the total fold text width. I feel like the labels should either be fully right aligned, or we should have an option for setting the maximum width. I don't really want to add more options, though. A dilemma, you could say. Do you feel strongly about this?

I agree that adding it as an option wouldn't really be a good idea, because adding random options for everything would make the code hard to maintain and harder to use. I guess you could say I feel medium about this? The reason I suggested that in the first place stemmed from the idea that it would be a bit hard to match the label to the equation if you don't have a caption if you work with many many columns (like in my photo), but that is a bit of a red haring because during actual work (n)vim only takes up half the screen, with the other half having the pdf. You could also say that no one should be using that many columns (so that the amount of whitespace makes it harder to fit labels to environments in the absence of captions) anyway, because it makes the text a lot harder to read at a glance. Also you wouldn't really have many labeled equations in a row most of the time so the chances for the mix up are small any way. It seems to me that during actual use this is basically fine, and that having all the labels on the right of the screen makes it easier to do a quick scan of all the available labels. I think I basically talked myself out of it.

Also, sometimes the section numbers disappear on some of the folds after opening and closing them a lot, usually either on all of them or all of them except the first. I'll try to figure out under what circumstances this happens and get back to you.

[lervag]

Thanks, then I think the conclusion is clear that we'll leave things as they are for now.

Also, sometimes the section numbers disappear on some of the folds after opening and closing them a lot, usually either on all of them or all of them except the first. I'll try to figure out under what circumstances this happens and get back to you.

I assume this is because you have added or removed lines without saving the file. The method for parsing the section numbers works by reading the entire projects files and parsing them using the same method as the ToC parser. I think the fold text will be fixed when you save the document (perhaps you'll need to do zx to update the folds, though).