Support magic syntax comments

[Aerijo]

Already, packages such as latex recognise comments of the form % !TeX key = value. This is also true of several TeX editors (I know of at least TeXShop).

I suggest adding a new one, called % !TeX syntax = value*. This would be used to change the syntax highlighting style for select parts of the document, to one that has been predefined by this (or other) packages.

For example, the recent >{\(}c<{\)} issue; though a fix is possible, the user has to wait until it is made, merged, and eventually released, all the while putting up with incorrect syntax highlighting or disabling it altogether (or introducing incorrect syntax to counteract it and removing it each time they compile. ugh 😒 ). And that was an actual bug; what if the user has legitimate LaTeX code that happens to be somewhat ... quirky.

This could be fixed (at least temporarily) by issuing a % !TeX syntax = plain magic comment above the offending location. Then, after the issue was dealt with, a % !TeX syntax = normal | default command could be used to resume normal scoping.

This could cause problems with end patterns not being found, but careful and judicious use should mitigate this. For example, if the syntax is set to plain within an environment, it should be set back to default before the end pattern, lest the rest of the file be considered part of the environment. I believe this an acceptable drawback, considering the alternative is broken highlighting anyway. It would be too difficult to add % !TeX syntax = plain as an alternative the the end pattern of every single begin/end pair, just to make it not break this way.

* The names are open to debate. Above I use syntax as the key and plain as one of the potential values. Other potential keys could be grammar or highlighting, but I believe these are not as good. Other values could be

• math: for mathmode
• text: to get out of mathmode
• none: to disable it entirely
• verbatim: to treat as verbatim
• comment: to treat as comment

[Aerijo]

@Evpok Is there a reason in particular you don't support this feature? I understand it is a lot of work to implement, but I believe the idea itself to be useful. As I pointed out, there will be cases where the syntax highligting fails. Instead of making the user add changes that must be removed each compile time, this is an unobtrusive patch.

It is not meant to be a substitute for proper syntax rules. Rather, it is really intended for the extreme cases where the alternative is a green document because a dollar sign was not 'properly' closed.

[Evpok]

I don't really oppose it (and removed the reaction accordingly). That said, I feel it would take less work to fix the actual issues than to provide this functionality.

[Aerijo]

@Evpok I've already tried to implement this, and can confirm it is not a simple feature. But when you say

it would take less work to fix the actual issues than to provide this functionality

the problem is that sometimes it's just not something we can account for. An author might have some crazy setup commands in a section, that don't follow normal LaTeX conventions. For example (not that I know any real cases of this), they might change the catcodes of several characters and do some voodoo magic, before reverting everything and continuing like normal.

It's easy to condemn them for bad practices (maybe they should make a separate file and \input it), but I feel that we shouldn't force authors to use one particular approach. With this, they could nest the crazy part between two syntax comments, temporarily disabling highlighting.

Additionally, the issue backlog is piling up (admittedly, half of them are snippet related). There is no guarantee a fix will be released in a timely manor, if at all.

I would also like to reiterate I understand this feature would take a lot of work to get right. I don't expect it to get implemented anytime soon (if at all). I would like to leave it here though, as a reminder and potential project for anyone looking for some way to contribute. It also allows comments for changes and suggestions.

[yudai-nkt]

While I understand the motivation, I would agree with @Evpok. Other magic comments have practical purpose such as to tell which engine should be used or what is the master LaTeX file, but the TeX syntax comment is just a cosmetic workaround and not essentially important IMHO.