Latex-workshop: Proposal - help users keep magic comments in order? Or set root file config? Or both?

[jabooth]

Following the discussion in #101 I got thinking about the best way latex workshop can help users choose root files.

I can see a few ways to take this:

Provide tools to help users manage magic comments

Magic comment is really the 'standard' way to choose the root file - it works across all latex tools. latex workshop could focus on helping users set magic comments and keep them up to date. This would be nice as LW would be encouraging a best practice, and users would be able to benefit from this when they use their tex files anywhere outside LW.

Some basic ideas of what could be done here:

1. If there is an ambiguous root, LW could show a warning, and ask users to choose the correct root file for the current document. After choosing, LW could insert the relevant magic comment at the top of the current file.

2. We could periodically check that all .tex files referenced from the current root document have a correct magic comment. LW could automatically show a problem when magic comments are missing or incorrect, and offer a code action to fix them. As they are fairly simple, we could have a command to run to fix all magic comments for the current root. Optionally, users could ask LW to automatically provide these fixes, so as they move files around LW works to ensure the magic file is always correctly set.

3. Of course, all this could be disabled by config.

Add a workspace setting for setting the root.

This is fine too, and is very easy to understand. However it adds another way the root file can be chosen (Another thing for users to debug if LW isn't behaving as they expect with root files) and is pretty hopeless if there are two latex documents in one workspace (which can be quite common with papers + supplimentary material).

[skamoen]

If the magic comment is the 'standard way' (I really wouldn't know), I think that's a better option than a custom config setting.

I didn't know about the magic comment until I ran into trouble which proved not very trivial to debug, so the magic comment proposal ideas would make the whole root document selection a lot more transparent :+1:

[jabooth]

Hmm it's funny @skamoen because I've seen a number of tools use these comments over the years and just figured it was 'official' - I don't think it is, but they seem to have quite broad support, more info here:

http://tex.stackexchange.com/questions/78101/when-and-why-should-i-use-tex-ts-program-and-tex-encoding

[jabooth]

Key bit from above link:

Editors that understand % ! TeX directives

              E P R S
TeXShop       x x x x
TeXStudio     x x x x
TextMate      ? x x ?
TeXworks      x x x x
SublimeText   o x x x
Atom          o x x o
Vim (vimtex)  o x x o
              | | | |
x = yes       | | | Spellcheck
o = no        | | Root
? = ?         | Program
              Encoding

And of course they should update with VS Code + LaTeX Workshop ;)

[specter119]

We really need support of % !TEX TS-program = xelatex as ESL users.

[flipphillips]

I agree with much of the above. These things have become pretty much defacto standards.

For whatever reason the above mentioned enhancement doesn't seem to do anything with the macOS setup I'm using. I've resorted to just doing this via a latexmkrc file which, I suppose, I should be doing anyway.

[flipphillips]

By the way- there was another attempt at magic comments. The preamble of a lot of my tex files have:

% -*- program: xelatex -*-
% -*- coding: utf-8 -*-
% -*- root: e1.tex -*-
%!TEX program = xelatex
%!TEX encoding = UTF-8 Unicode

Note also, %! instead of/in addition to %_! which is how I thought the original TexShop did it. Regardless, like I said above, none of these seem to work in the current release under macOS.

[bartosz-antosik]

Gentleman! I have found some inspiration in this thread and added support for LaTeX 'magic comment' in the form !TEX spellcheck = CODE where CODE is language code to Spell Right. It can exist multiple times in the document thus effectively switch between spelling in multiple languages in a single document. There already has been a switch with same semantics but this syntax feels much more appropriate in LaTex.