Syntax highlighting for fixme package

[lambtho12]

Problem

When using the fixme package, the commands have no special highlights in the text. Besides that, when the related entry is shown in the TOC, it is in the same formatting as regular headings and hard to distinguish.

Solution

It would be nice to highlight the various fixme commands in the same way as the \todo command is highlighted in the text. Indeed, they are usually not meant for final material and it would be much easier to spot them in the text.

As for the TOC, it would be really nice to have the "fxnote:", "fxwarning:", "fxerror:" and "fxfatal:" highlighted properly so they can stand out better, as it is already the case with the "TODO" notes. A simple solution would be to apply the same highlight as for the TODO. A more elaborate one would be to use specific colors in the TOC based on the importance of the note (regular for note, yellow for warning, orange for error, red for fatal)

[huweiATgithub]

maybe some configurations similar to
https://github.com/lervag/vimtex/blob/master/autoload/vimtex/syntax/p/todonotes.vim

[lervag]

When using the fixme package, the commands have no special highlights in the text. Besides that, when the related entry is shown in the TOC, it is in the same formatting as regular headings and hard to distinguish.

I don't mind working on both the syntax and TOC features, but could we take one at a time? I don't have so much time, so doing it that way will be helpful for keeping focus for me. So, could I kindly ask we consider first the syntax highlighting part, then you could open a new issue for the TOC part?

It would be nice to highlight the various fixme commands in the same way as the \todo command is highlighted in the text. Indeed, they are usually not meant for final material and it would be much easier to spot them in the text.

Yes, sounds good. It would be helpful if you could provide a short .tex example of all the relevant comments, including a description of how they should be highlighted.

@huweiATgithub
maybe some configurations similar to https://github.com/lervag/vimtex/blob/master/autoload/vimtex/syntax/p/todonotes.vim

Yes, definitely. That's how I will address the syntax highlighting.

[lambtho12]

I don't mind working on both the syntax and TOC features, but could we take one at a time?

Sure! 😄
I will open a second issue for the TOC feature. I may have some time on Tuesday and try to do a PR for the syntax highlighting part if you don't have time to look at it in the meantime. The TOC highlight seems too complicated for my skills unfortunately.

Yes, sounds good. It would be helpful if you could provide a short .tex example of all the relevant comments, including a description of how they should be highlighted.

I can definitely do that. Although the most common commands are already in the TOC parser test. The original issue for fixme support also summarizes them.

Fixme has quite an interesting feature where users can define easily different commands for different authors (the call it the signature feature). The most common way to do is to prefix the usual commands by the author initials. E.g., John Doe would use \jdnote, \jderror, \jdwarning and \jdfatal instead of the defaults \fxnote, \fxerror, etc. Support for that specificity would be awesome but trickier (especially avoiding false positive). A possibility could be to let the user declare the specific fixme commands they are using in the vimtex options.

Edit: Regarding the signature feature, fixme uses a command to declare the new authors \FXRegisterAuthor{jd}{ajd}{JD} where the first two arguments are the prefix to add to the base note, error, warning and fata commands. So if we go the option route, the user just needs to tell vimtex which prefix should be added to the regex to detect the fixme commands.

[lambtho12]

Fixme base commands

• \fxnote, \fxwarning, \fxerror, \fxfatal
• Starred versions of the same commands
• (deprecated \fixme which is equivalent to \fxfatal)

Fixme base environments

• anfxnote, anfxwarning, anfxerror, anfxfatal
• Starred versions of the same environments
• (deprecated \afixme which is equivalent to \anfxfatal)

Multi-author scenario (icing on the cake)

Note: This may call for a separate feature request as it should also impact the TOC parsing?

In case of multiple authors, fixme allows to register variations of the base commands and environments using a different prefix for each author.
This is done by declaring the author with

% \FXRegisterAuthor{<cmdPrefix>}{<envPrefix>}{<initials>}
\FXRegisterAuthor{jd}{ajd}{JD} % For John Doe

This will then automatically create the commands \jdnote, \jdwarning, etc. and the environments ajdnote, ajdwarning, etc.

[lervag]

I've pushed an initial version of this now. The multi-author is not included for now. Let me know what you think so far.

[lervag]

In the related issue, you suggest to possibly use custom highlights for the various "severities". That's definitely a possibility. I'll look into that as well.

[lambtho12]

Let me know what you think so far.

AWESOME! Very nice decision to have the first argument highlighted as well, this really makes the annotation stand out in the text.

The multi-author is not included for now

This could be left for a completely separate feature request, no real rush.

You suggest to possibly use custom highlights for the various "severities". That's definitely a possibility.

Indeed, however, I am not sure this is really something desirable for syntax highlighting. This may add some confusion with other elements that would share similar colors (headings, specific commands, etc.). Not sure.
This comment was more specific to the TOC, where the colors used and the number of different elements are a bit more limited.

[lervag]

AWESOME! Very nice decision to have the first argument highlighted as well, this really makes the annotation stand out in the text.

Great, I'm happy you like it!

The multi-author is not included for now

This could be left for a completely separate feature request, no real rush.

Yes, let's do that. If you open a new feature request for this, it would be helpful with a sample LaTeX file (that is compileable) with a few examples of the specific feature. Then I could use that while developing it.

Indeed, however, I am not sure this is really something desirable for syntax highlighting. This may add some confusion with other elements that would share similar colors (headings, specific commands, etc.). Not sure. This comment was more specific to the TOC, where the colors used and the number of different elements are a bit more limited.

Ah, ok. I was thinking to reuse the highlight groups to avoid duplications. It feels more consistent to use the same concept within the TOC and inside the LaTeX file. So I would perhaps be inclined to think we should either use more colors both places, or just the TODO color in both places.

In any case, if you think this is already sufficient for the syntax highlighting, then perhaps we should consider the current issue closed?

[lambtho12]

Yes, let's do that. If you open a new feature request for this, it would be helpful with a sample LaTeX file (that is compileable) with a few examples of the specific feature. Then I could use that while developing it.

Ok. I will open a new FR for that tomorrow and I will extend the test file already used to add the custom author stuff.

Ah, ok. I was thinking to reuse the highlight groups to avoid duplications. It feels more consistent to use the same concept within the TOC and inside the LaTeX file. So I would perhaps be inclined to think we should either use more colors both places, or just the TODO color in both places.

This makes sense as well. I am not really sure where I stand on that without actually seeing the stuff properly colored... But so far I am quite happy with the same color for all annotations.

In any case, if you think this is already sufficient for the syntax highlighting, then perhaps we should consider the current issue closed?

Sure!

[lervag]

Creat. I'll look into the TOC stuff when I get the time. I'll begin with single color version, then we can consider adding multiple colors later.