Vimtex: Include label type in completion

[clason]

At the moment, vimtex shows, e.g., (3.1) in the menu field of the completion item for all labels that receive the number 3.1 -- equations, Theorems, Figures, etc. It would be nice to distinguish the type of reference here, i.e., printing Theorem 3.1 or Figure 3.1 in the menu field. This would also allow easily filtering on reference type (if no consistent label form is used).

I believe this is doable since this information is contained in the .aux file, e.g.,

\newlabel{lem:state_existence}{{2.1}{3}{}{theorem.2.1}{}}
\newlabel{fig:variation:lsc1}{{\relax 2.1a}{15}{<caption text>}{figure.caption.68}{}}

(the fact that the first shows the counter -- which here coincides with that for theorems even though it is a lemma -- would be acceptable to me; relying on cref to get the "correct" label name is probably not worth the added effort). I think it would be sufficient to extend tex2tree to include the additional field and use a more detailed case distinction in parse_number (also returning appropriately formatted numbers instead of deferring that to completer_ref.complete)?

[lervag]

Interesting proposal. I agree it seems doable. Perhaps, as a minor improvement, one could have an option to map e.g. "theorem" to "Theorem" and "figure caption" to "Figure"?

[clason]

Oh, yes, proper capitalization was assumed :) (As was splitting at the first ., so caption would be removed anyway.)

I was hoping to have a pull request to go with this issue, but tex2tree looks a bit to intricate for me to touch...

[lervag]

Hmm. I've pushed a simple example for testing this. If you go to the test dir and do make, it should output the completion candidates. However, if you open the resulting minimal.aux, you will see it does _not_ contain the added context.

I thus believe this is probably less doable than first thought. That is, I think the content of the \newlabel depends on packages. Probably, cleveref?

[clason]

Don't you need to actually set a label for that (instead of two cref)? And some environment (or at least section) to attach the label to? (Also, there's no makefile.)

And cleveref should not be needed for that unless you want to distinguish different theorem environments sharing the same counter (which I would not do at first).

[lervag]

Don't you need to actually set a label for that (instead of two cref)? And some environment (or at least section) to attach the label to?

Not sure what you mean. But please, if you can help me to fix the minimal example so that it properly represents your proposal, then that would be helpful!

And cleveref should not be needed for that unless you want to distinguish different theorem environments sharing the same counter (which I would not do at first).

Ok, and agreed.

[clason]

Hm, you're right, you need to include hyperref to get the extra information in the aux file. Here's a minimal example (article is needed to get section commands):

\documentclass{article}
\usepackage{amsthm}
\usepackage{hyperref}
\newtheorem{theorem}{Theorem}

\begin{document}

\section{Intro}\label{intro}

\begin{theorem}\label{theorem}
    This is a theorem.
\end{theorem}

\begin{figure}
    \caption{My figure}
    \label{figure}
\end{figure}

\end{document}

\relax 
\providecommand\hyper@newdestlabel[2]{}
\providecommand\HyperFirstAtBeginDocument{\AtBeginDocument}
\HyperFirstAtBeginDocument{\ifx\hyper@anchor\@undefined
\global\let\oldcontentsline\contentsline
\gdef\contentsline#1#2#3#4{\oldcontentsline{#1}{#2}{#3}}
\global\let\oldnewlabel\newlabel
\gdef\newlabel#1#2{\newlabelxx{#1}#2}
\gdef\newlabelxx#1#2#3#4#5#6{\oldnewlabel{#1}{{#2}{#3}}}
\AtEndDocument{\ifx\hyper@anchor\@undefined
\let\contentsline\oldcontentsline
\let\newlabel\oldnewlabel
\fi}
\fi}
\global\let\hyper@last\relax 
\gdef\HyperFirstAtBeginDocument#1{#1}
\providecommand\HyField@AuxAddToFields[1]{}
\providecommand\HyField@AuxAddToCoFields[2]{}
\@writefile{lof}{\contentsline {figure}{\numberline {1}{\ignorespaces My figure}}{1}{figure.1}\protected@file@percent }
\newlabel{figure}{{1}{1}{My figure}{figure.1}{}}
\@writefile{toc}{\contentsline {section}{\numberline {1}Intro}{1}{section.1}\protected@file@percent }
\newlabel{intro}{{1}{1}{Intro}{section.1}{}}
\newlabel{theorem}{{1}{1}{}{theorem.1}{}}

(You didn't actually include any \label{xxx} command in your example, so of course nothing got written to the aux file. Without hyperref -- which is such a default package for me that I didn't even realize this -- labels indeed don't contain the theorem.1 field, though.)

[lervag]

Ok. I think I've fixed this. Please test and give some feedback.

[clason]

Oh, that was quick! A brief test showed some weird labels, mostly from equations in borderline cases (one was \begin{equation}\tag{1}... in a preface, which gets labelled Equation AMS 1, another \begin{equation*}\label{eq:...} which, predictably, picks up the name of the surrounding environment), but this is how they appear in the aux file and thus not vimtex's problem. Otherwise it works well, even in a large project, and it also reverts gracefully if hyperref is not used.
I like that I can just do \ref{Theorem<c-x c-o>} and get _all_ theorem-like environments!

I have to admit, I do prefer (4.1) over Equation 4.1 for equation(-like) environments to more easily distinguish them from theorems and such, but I'm not sure the special casing would be worth it.

What do you think? An improvement or too noisy? Also, left- or right-alignment (as before?) of these labels? (I think left is better here.)

[lervag]

A brief test showed some weird labels, mostly from equations in borderline cases ...

I could look into this, but it would be helpful with a concrete example. If you created a minimal LaTeX file with some of these weird labels, then I could look into how to improve for these edge cases.

I like that I can just do \ref{Theorem} and get all theorem-like environments!

Agreed, so thank you for suggesting this enhancement!

I have to admit, I do prefer (4.1) over Equation 4.1 for equation(-like) environments to more easily distinguish them from theorems and such, but I'm not sure the special casing would be worth it.

I'm not quite sure about this. I could partly agree, but it would make the completions somewhat inconsistent. Also, it would look strange with (4.1) (p. 3), or? It is easy to implement it, so the question is just if we really prefer it. Implementation would only require a simple substitute.

Also, note: based on this issue, it seems you might not be using the convention of systematic labels, e.g. \label{eq:...}, \label{fig:...}, label{thm:...}. I would strongly suggest you pick this up, because it would give some of the same benefits in that you can do \ref{eq:<c-x><c-o> and it also works as expected.

Also, left- or right-alignment (as before?) of these labels? (I think left is better here.)

I was thinking about it, and I settled for left aligned instead of right aligned, because I think it looked better. Right-aligning would align the page numbers, but it would make the actual labels more noisy. But I'm open for discussion. Another idea could be to try and left-align the label part and right-align the page part. But it would require some more work, as the alignment has to be done after collecting all the candidates.

Personally, I'm quite happy with the current version.

[clason]

I could look into this, but it would be helpful with a concrete example. If you created a minimal LaTeX file with some of these weird labels, then I could look into how to improve for these edge cases.

I'm not sure it's worth looking into, but here's an example (cleveref is needed here to get the wrong as opposed to no fields):

\documentclass{article}
\usepackage{amsmath}
\usepackage{hyperref}
\usepackage{cleveref}

\begin{document}

\begin{equation}\label{eq1}
    \tag{1}
    1+1=2
\end{equation}

\section{Intro}\label{intro}

\begin{equation*}\label{eq2}
    1+1=2
\end{equation*}

\end{document}

If I notice anything else (that is more serious), I'll add it.

Agreed, so thank you for suggesting this enhancement!

I stole that from texlab :) (Thought it was only fair after peppering them with feature requests based on vimtex :wink: The project has come a really long way in the last month or two; definitely worth a look if you haven't!)

I'm not quite sure about this. I could partly agree, but it would make the completions somewhat inconsistent. Also, it would look strange with (4.1) (p. 3), or? It is easy to implement it, so the question is just if we really prefer it. Implementation would only require a simple substitute.

Oh, yes, much of this issue is about taste. If it's easy to implement, maybe just check out how it actually looks in practice? I don't have a clear idea either. (But in this case, I'd probably go with (4.1) [p. 3], that should help.)

Also, note: based on this issue, it seems you might not be using the convention of systematic labels, e.g. \label{eq:...}, \label{fig:...}, label{thm:...}. I would strongly suggest you pick this up, because it would give some of the same benefits in that you can do \ref{eq:<c-x><c-o> and it also works as expected.

Oh, I am, just not every coauthor -- or at least not the same (should it be lem:... or lemma:...? endless discussions could be had on this topic...) ;) (And I admit I was too lazy for it for these short examples.)

I was thinking about it, and I settled for left aligned instead of right aligned, because I think it looked better. Right-aligning would align the page numbers, but it would make the actual labels more noisy. But I'm open for discussion. Another idea could be to try and left-align the label part and right-align the page part. But it would require some more work, as the alignment has to be done after collecting all the candidates.

I agree, this way is better.

Personally, I'm quite happy with the current version.

Me, too!

[clason]

Oh, yes, much of this issue is about taste. If it's easy to implement, maybe just check out how it actually looks in practice? I don't have a clear idea either. (But in this case, I'd probably go with (4.1) [p. 3], that should help.)

Compromise: Equation (4.1) [p. 4]?

(I noticed that with this change, doing something like \eqref{4.1<c-x c-o> no longer works -- I _have_ to prefix it with Equation 4.1. Has it always been the case that menu only matches prefix, not substring, differently from word, and I just didn't notice?)

[lervag]

Compromise: Equation (4.1) [p. 4]?

Just to be sure I understand, you propose this change, right?

Figure 1 (p. 1)                  Figure 1 [p. 1]
Figure 2 (p. 1)                  Figure 2 [p. 1]
Theorem 1 (p. 1)                 Theorem 1 [p. 1]
Equation 1.1 (p. 1)              Equation (1.1) [p. 1]
Equation 1.2 (p. 1)              Equation (1.2) [p. 1]
Equation 1.3 (p. 1)      ==>     Equation (1.3) [p. 1]
Equation 2.1a (p. 1)             Equation (2.1a) [p. 1]
Equation 2.1b (p. 1)             Equation (2.1b) [p. 1]
Theorem 2 (p. 1)                 Theorem 2 [p. 1]
Proposition 1 (p. 1)             Proposition 1 [p. 1]
Proposition 2 (p. 1)             Proposition 2 [p. 1]

... Has it always been the case that menu only matches prefix, not substring, differently from word, and I just didn't notice?

Yes, actually. But now it might make sense to change this to substring match
instead. What do you think?

Perhaps there is a need to update the docs as well...

[clason]

Just to be sure I understand, you propose this change, right?

Yes, exactly. What do you think?

Yes, actually. But now it might make sense to change this to substring match
instead. What do you think?

Good to know I wasn't imagining things :) (With the old menu, I guess I never had a reason to type anything other than the prefix). I think the reason I thought it was working is that you have separate _and combined_ matchers for word and menu; so typing eq 2.1 felt like substring matching even though it wasn't (for 2.1).

Yes, substring match would be nicer here; then I could just type 2.1 without the parentheses.

Perhaps there is a need to update the docs as well...

Yes, a slight rewording to change number to values and mentioning that label completion matches substrings in: would be good; I don't think much more is needed here.

[lervag]

Thanks, I think most things are good now. I'm not 100% sure I agree on using parentheses for equation numbers. Reason is, I don't quite see the difference between an equation number and e.g. a figure number; why should they be styled differently? But then again, I don't mind it much either.

[lervag]

I think I've also fixed the issue with the \tags, but I'm not sure. Feel free to throw more examples at me if you find other edge cases.

[clason]

Thanks, I think most things are good now. I'm not 100% sure I agree on using parentheses for equation numbers. Reason is, I don't quite see the difference between an equation number and e.g. a figure number; why should they be styled differently? But then again, I don't mind it much either.

I guess after twenty years, I'm so used to seeing equation numbers in parentheses that they look incredibly weird to me without 😉 (I have a paper in an MR journal that uses _square_ brackets for equation numbers -- looking at that still puts me off...)

More seriously the point is that equations are styled (x.y) in a paper as well, while figures are still Figure x.y. So it's a question of consistency between label types and consistency between vimtex and PDF -- and my vote would be for the latter.

I think I've also fixed the issue with the \tags, but I'm not sure. Feel free to throw more examples at me if you find other edge cases.

Nice! I'll report issues here if they crop up.

[lervag]

Yes, I agree it is common to use parantheses around equation numbers in a lot (most) journal templates. It's a good point, and so we'll keep it like this.

Thanks for the feature request and very good follow-up discussions!

[clason]

As always, thank _you_ for your patience and the work you put into vimtex! (Typing stuff in a comment box is easy...)