Root detection fails when file contains the strings `\documentclass[` and `\begin{document}` even if they are commented

[rrueger]

Edit: The issue is incorrectly described in this post. See below for correct description.

I have a unified preamble that I use for many projects at $LATEXTEMPLATES/preamble.tex.

I initialise new projects as follows

mkdir project
cp $LATEXTEMPLATES/main.tex project/project-name.tex
ln -s $LATEXTEMPLATES/preamble.tex project/preamble.tex
# edit project/project-name.tex with project specific content

It is important that preamble.tex is a symbolic link here to observe the unwanted behaviour.
Obviously project/project-name.tex should not be a symbolic link, because the content is different for each project.

(I use a symbolic link for preamble.tex so that any changes that I make to the preamble.tex in any individual project will be observed globally. For my workflow, this makes sense.)

At the moment, when I edit preamble.tex VimTeX tries to compile preamble.tex as a standalone file.
The auto-root-detection seems to fail.

I would expect one of two things to happen, when I edit project/preamble.tex -> $LATEXTEMPLATES/preamble.tex

1. VimTeX follows the symbolic link, and sees that $LATEXTEMPLATES/main.tex imports $LATEXTEMPLATES/preamble.tex so it successfully compiles $LATEXTEMPLATES/main.tex.
2. VimTeX doesn't follow the symbolic link, and sees that project/project-name.tex imports project/preamble.tex so it successfully compiles project/main.tex.

Since project/project-name.tex is different for each project, I cannot add a vimtex-tex ROOT directive to preamble.tex. On the other hand, it seems like kind of a hack to add $LATEXTEMPLATEX/main.tex as the ROOT in the unified preamble.

I think there are two options for fixing this unwanted behaviour:

1. "Fixing" the root detection, so that VimTeX doesn't follow the symbolic link, and realises that project/project-name.tex imports project/preamble.tex. I think it is important that VimTeX doesn't follow the symbolic link, because it (imho) be an entirely legal and sensible approach to keep a unified preamble without a corresponding main.tex that imports it.
2. Adding a VIMTEX_DISABLE directive, to disable VimTeX for this specific file.

I hope this makes sense!
Perhaps I have missed something in the documentation?

[lervag]

At the moment, when I edit preamble.tex VimTeX tries to compile preamble.tex as a standalone file. The auto-root-detection seems to fail.

I'm trying to reproduce this. I created these files:

.
├── global
│   └── preamble.tex
└── local
    ├── main.tex
    └── preamble.tex -> ../global/preamble.tex

2 directories, 3 files

% preamble.tex
\newcommand{\testx}{xx}

% main.tex
\documentclass{article}
\usepackage[utf8]{inputenc}
\usepackage{graphicx}

\input{preamble}

\begin{document}

Hello world.

\end{document}

Then I edit local/preamble.tex. \li now shows that the project is main.tex as expected.

I may have misunderstood something, so can you please provide a simple set of example files and the steps you use when you have the issue?

[rrueger]

Thank you for your fast and detailed reply!

Your example works the same way in my environment, so I dug deeper.

It turns out that the "symbolic link" avenue of thinking was a red herring. (I should have tested that, sorry!)

I have found the issue: my preamble file contained the following snippet: (verbatim)

 % Here is a boilerplate example for using this preamble.
 %
 % The \documentclass is purposely _not_ defined in this preamble, and thus must
 % be defined in the document before \inputing the preamble.
 %
 % \documentclass[11pt,a4paper,oneside]{article}
 % \input{preamble}
 % \begin{document}
 % ...
 % \end{document}

(Specifically, these are commented lines). Looking at autoload/vimtex/state.vim lines 485 and 488, I suspect VimTeX thinks my preamble.tex file is the root TeX file simply because it found the strings \documentclass[ and \begin{document}.

This is reproducible in your example. Adding the lines

% \documentclass[
% \begin{document}

to preamble.tex causes \li to output that preamble.tex is the root file, although main.tex includes it. If either of these lines is removed, VimTeX correctly finds the root to be main.tex.

So I suppose this is fixed, by changing the regexes to be more careful when looking for \documentclass and \begin{document} to determine whether the current file is a root file or not. (That is, prepend the regexes with ^\s* in the correct VimScript flavour for regexes).

However, I still think that it is a good idea to add a directive to allow people to disable VimTeX for any given file. I think the use case of having templates that are not valid as standalone documents is legitimate. Simply put: I think it very ugly when I open a preamble without a main which then causes half my screen to fill with quickfix error messages.

On the other hand, I also understand supporting further options adds maintenance work for a legitimate, yet marginal use case.

Either way, my issue is resolved for now by removing those lines. Once the regexes are changed, I can add them again and all is good.

[lervag]

Thank you for your fast and detailed reply!

Your example works the same way in my environment, so I dug deeper.

Great!

This is reproducible in your example. Adding the lines

% \documentclass[
% \begin{document}

to preamble.tex causes \li to output that preamble.tex is the root file, although main.tex includes it. If either of these lines is removed, VimTeX correctly finds the root to be main.tex.

So I suppose this is fixed, by changing the regexes to be more careful when looking for \documentclass and \begin{document} to determine whether the current file is a root file or not. (That is, prepend the regexes with ^\s* in the correct VimScript flavour for regexes).

Yes, nice catch! Thanks! I'm pushing a fix for this now.

However, I still think that it is a good idea to add a directive to allow people to disable VimTeX for any given file. I think the use case of having templates that are not valid as standalone documents is legitimate. Simply put: I think it very ugly when I open a preamble without a main which then causes half my screen to fill with quickfix error messages.

Well, I'm not sure what benefit this would bring. I mean, for such a template file, you could still find many VimTeX features useful (e.g. syntax highlighing, motions, commands, etc). So, what is the problem of loading VimTeX even if the main file is not properly detected?

[rrueger]

I'm pushing a fix for this now.

Brilliant!

Well, I'm not sure what benefit this would bring. I mean, for such a template file, you could still find many VimTeX features useful (e.g. syntax highlighing, motions, commands, etc).

That is very true. Is there a way of turning off auto-compile-on-save for specific files? (To prevent lots of errors being generated).

This would be for the case in which VimTeX doesn't find a root, and realises this document is not a standalone TeX file, so it won't try to compile.

[lervag]

That is very true. Is there a way of turning off auto-compile-on-save for specific files? (To prevent lots of errors being generated).

VimTeX does not have auto compile. You toggle with \ll or :VimtexCompile. Perhaps you have an autocommand? You can make it slightly smarter by looking at the b:vimtex.main_parser. Notice that, for files where VimTeX was unable to find a main file and where the current file is not detected as a proper main file, b:vimtex.main_parser = "current file". On the other hand, if the current file was detected as the main file, it will say "current file verified".

[rrueger]

VimTeX does not have auto compile. You toggle with \ll or :VimtexCompile. Perhaps you have an autocommand?

Of course you are absolutely correct. My .vimrc has an autocommand to start the compiler by default.

I suppose what I meant, is that when continuous :VimtexCompile is enabled, and VimTeX cannot find a root file, it should perhaps print a single warning, instead of trying to compile it anyway and filling the quickfix window with lots of errors.

Thanks to your commit e5de00e, my issue is fixed. So I am closing this issue.

Thank you for your fast support and fixing the issue!

[lervag]

VimTeX does not have auto compile. You toggle with \ll or :VimtexCompile. Perhaps you have an autocommand?

Of course you are absolutely correct. My .vimrc has an autocommand to start the compiler by default.

:)

I suppose what I meant, is that when continuous :VimtexCompile is enabled, and VimTeX cannot find a root file, it should perhaps print a single warning, instead of trying to compile it anyway and filling the quickfix window with lots of errors.

I actually agree here. Could you reopen the issue, then I can close it when I've updated accordingly?

Thanks to your commit e5de00e, my issue is fixed. So I am closing this issue.

Thank you for your fast support and fixing the issue!

I'm glad to hear that! :)

[rrueger]

I actually agree here. Could you reopen the issue, then I can close it when I've updated accordingly?

Sure. I’d be glad to see this improvement!

Thank you

[lervag]

There, I think that should do the trick.