Disregard contents of "comment" environment

[boolanger]

Issue

Vimtex currently treats \section{...}, \subsection{...}, and \subsubsection{..} commands inside the comment environment as if they were real sections in at least these ways (I may have missed others):

• It folds them as (sub)sections.
• It lists them in the table of contents (vimtex-toc).
• It navigates to them with [[, ]], [], and ][ in normal mode.
• It selects up to such commands with the aP and iP text objects.

To reproduce, open the following with vim:

\documentclass{article}
\usepackage{comment}
\begin{document}
\section{Real section}
\begin{comment}
\section{Commented section}
\subsection{Commented subsection}
\subsubsection{Commented subsubsection}
\end{comment}
\end{document}

with .vimrc

call plug#begin('~/.vim/plugged')
Plug 'lervag/vimtex'
call plug#end()
let g:vimtex_fold_enabled=1

Proposed Solution

I think that it would be better to disregard commented (sub)section commands, since they are not part of the structure of the document. That would mean:

• They are not folded as (sub)sections.
• They are not listed in vimtex-toc, and don't affect the (sub)section count.
• [[, ]], [], and ][ skips over them.
• Similarly, iP and aP skips over them.

Personally, I like the ability to comment out entire sections, and this would help me do that without messing up document navigation.

By the way, thanks for all your work on vimtex, it's much appreciated!

Edit: For clarity, and I've also added some more features that are affected by this.

[boolanger]

After looking at this a little more, this issue isn't just about sections; vimtex fails to ignore the contents of the comment environment in other cases, too. My preference would be for the contents of comments to be completely ignored, i.e. treated as just text for all purposes. I hope it wouldn't be too difficult to solve these issues together; otherwise I apologize for bringing up so many things at once!

Here are the issues I've found. I'm sure there are others.

• Motions are affected by comment contents.

  E.g. in this snippet, pressing ]M at the second line takes you to the \end{quote} inside the comment (I would expect it to take me to the final line).

  \begin{quote}
  Ask what
  \begin{comment}
  your country can do for you.
  \end{quote}
  \end{comment}
  you can do for your country.
  \end{quote}

  Other motions are similarly affected.

• Text objects are affected by the comment contents.

  In the example above, vie selects lines 2-5 (I would expect this to select everything except the first and last lines), and vae selects lines 2-6 (I would expect this to select all lines).

• In syntax highlighting, the wrong environment boundaries and delimiters are highlighted.

  In the example above, if the cursor is on the first line, \end{comment} is highlighted (I would expect the last line to be highlighted). The same goes for math environment boundaries.

• The table of contents (vimtex-toc) also lists figures and tables inside comments

  E.g. this figure is listed in the TOC:

  \begin{comment}
  \begin{figure} \label{fig}
  \end{figure}
  \end{comment}

[lervag]

Interesting issue. I believe some of these fixes can be quite straightforward, but not all of them. It would be helpful if you could update your list in your original post with all of the issues you've noticed; perhaps you could also make it a check list with + [ ] ..., then I could check off items as I've looked into and fixed/considered them?

[lervag]

I believe I've solved the folding and toc issues now; please update and test. So, the motions remain; I believe these may be more tricky. But I'll have a look when I get the time.

[boolanger]

Thanks a lot for the quick fixes! There's still a minor issue with folding (noted below) but the TOC seems to be solved.

Below are the issues that I've been able to find. Personally, the fixes that I'd appreciate the most are those for the TOC (done), folds, as well as motions and text objects for (sub)sections. I don't often have multiline comments inside other environments or inside equations, and unbalanced delimiters or environment boundaries inside comments are even rarer, so while I'd appreciate fixes to the other issues, they would have much lower priority for me.

• Don't fold inside the comment environment.
  • The comment_pkg commit almost fixes the problem for me except that I still get strange behaviour when I've just entered text in comments, exit to normal mode, and then toggle fold with za. It doesn't reproduce if you just copy the text into vim, though. Here's an example:
    
• Commented (sub)sections, tables, and figures appear in vimtex-toc.
• Motions are affected by the contents of comment environments. This applies to all motions except those for comment boundaries, as far as I can see.
• Text objects.
• Syntax highlighting. Matching environment boundaries and delimiters are misidentified when comments appear between them. The examples for motions also show this.
• Other mappings. I've only been able to find problems with some.
  • Change surrounding environment (cse)
  • Change surrounding delimiter (cs$)
  • Delete surrounding environment (dse)
  • Delete surrounding delimiter (ds$)
  • Close current delimiter with ]] in insert mode.
  • Toggle between inline and displayed math (ts$)

Examples:

• Sections

  \begin{comment}
  \section{commented section}
  \subsection{commented subsection}
  \subsubsection{commented subsubsection}
  \end{comment}

• Frames and other environments

  \begin{frame}
  Ask what
  \begin{comment}
  your country can do for you.
  \end{frame}
  \end{comment}
  you can do for your country.
  \end{frame}

• Delimiters:

  \[ E = 
  \begin{comment}
          1/2mv^2 \]
  \end{comment}
  mc^2 
  \]

[lervag]

• Don't fold inside the comment environment. The comment_pkg commit almost fixes the problem for me except that I still get strange behaviour when I've just entered text in comments, exit to normal mode, and then toggle fold with za. It doesn't reproduce if you just copy the text into vim, though. Here's an example:

I'm having a hard time fixing this without changing the way to match comments entirely. I'm pushing a PR for this because I want some help testing if it causes significantly slower fold performance. Could you pull the branch and test? See #2884.

[lervag]

Reg. #2884; I believe it should fix your folding issue. However, as I wrote, I'm using a different method now. It would be very nice if you could test it on some large documents and report if you find it has a negative performance impact.