cite command syntax highlighting including various variants introduced by biblatex-chicago

[alexandreroberts]

Is your feature request related to a problem? Please describe it.
While simple standard cite commands like \cite[10]{ref} are highlighted correctly, this is not the case for more exotic commands introduced by biblatex and biblatex-chicago (as well as some custom commands that I use).

Describe the solution you'd like
I would like the same standard syntax highlighting to be applied to commands of these form as well:

• \volcite{1}[10]{ref} (with or without the optional input variable)
• \headlesscite[10]{ref} (ditto)
• \edcite[10]{ref} (ditto)
• \transcite[10]{ref} (ditto)

Also, all cite commands should be highlighted the same way if their first letter is capitalized (\Cite, \Volcite, etc.), another biblatex-chicago feature.

Hopefully this is a simple matter of tweaking the regex -- in any case, it would be wonderful to have this feature added!

Describe alternatives you've considered
I've just been using it as is, which is fine, but a bit distracting because all these cite commands have their citekey formatted as an ordinary word and underlined as a spelling error.

Additional context

[lervag]

Describe the solution you'd like I would like the same standard syntax highlighting to be applied to commands of these form as well:

* `\volcite{1}[10]{ref}` (with or without the optional input variable)

* `\headlesscite[10]{ref}` (ditto)

* `\edcite[10]{ref}` (ditto)

* `\transcite[10]{ref}` (ditto)

Also, all cite commands should be highlighted the same way if their first letter is capitalized (\Cite, \Volcite, etc.), another biblatex-chicago feature.

Hopefully this is a simple matter of tweaking the regex -- in any case, it would be wonderful to have this feature added!

I believe it should not be too hard. Could you provide a short example file that uses these commands and their forms? Preferable an example that compiles (just for completeness)?

[lervag]

Also, can you refer me to the documentation of these commands?

[lervag]

Btw., \volcite is alreadty implemented:

vimtex/autoload/vimtex/syntax/p/biblatex.vim

Line 32 in a397999

syntax match texCmdRef nextgroup=texRefOpts,texRefArgs skipwhite skipnl "\\[pPfFsStTaA]\?[Vv]olcites\?\>"

[alexandreroberts]

Ah, sorry, yes, you're right, \volcite is already covered. The main place where I've noticed the lack is when I use that capitalized version of these commands (\Cite, \Volcite, etc.).

\edcite and \transcite (and \Edcite and \Transcite) are my own, which would be nice to have covered, but I understand if you'd rather keep to more general-interest features. As for the biblatex-chicago commands, you can find a complete list in the package documentation, section 4.3.2.

MWE

main.tex:

%!TEX TS-program = xelatex
%!TEX encoding = UTF-8 Unicode

% Normal:
\documentclass[12pt,article,draft]{memoir}

\usepackage[notes, useibid]{biblatex-chicago}
\addbibresource{biblatex-examples.bib}

\begin{document}

Test.\footnote{%
\cite{worman}.
Capitalized if ibid:
\Cite{worman}.
\mancite
Just the title:
\headlesscite{worman}.%
}

\end{document}

test.vim:

set nocompatible 
set mmp=5000

call plug#begin('~/.vim/plugged')
Plug 'lervag/vimtex'
call plug#end()

set spell

Spelling errors are highlighted in red in this MWE, indicating when the cite command highlighting has not been triggered:

[alexandreroberts]

I just realized why I thought that \volcite had not been implemented: it only works without the (mandatory) volume argument! As far as I know, \volcite and its arguments should only be highlighted as a cite command when a volume is cited, as in \volcite{1}[23]{citekey} or simply \volcite{1}{citekey} but not if the volume argument is missing, so as to alert the user to the missing volume number.

MWE 2

%!TEX TS-program = xelatex
%!TEX encoding = UTF-8 Unicode

% Normal:
\documentclass[12pt,article,draft]{memoir}

\usepackage[notes, useibid]{biblatex-chicago}
\addbibresource{biblatex-examples.bib}

\begin{document}

Ordinary cite command:
\cite[23]{worman}

Capitalized if using ibidem.
\Cite{worman}.

\mancite
Just the title:
\headlesscite{worman}.

Volcite with volume number:
\volcite{1}[23]{worman}

Volcite without volume number:
\volcite[23]{worman}.

\end{document}

test.vim: same as before

Screenshot:

[alexandreroberts]

I've also noticed that the page number is correctly highlighted in the case of \Cite and \headlesscite (but not in the case of \volcite with volume number), suggesting that you already implemented these commands too but omitted to implement the correct highlighting of their citekey.

%!TEX TS-program = xelatex
%!TEX encoding = UTF-8 Unicode

% Normal:
\documentclass[12pt,article,draft]{memoir}

\usepackage[notes, useibid]{biblatex-chicago}
\addbibresource{biblatex-examples.bib}

\begin{document}

Ordinary cite command:
\cite[23]{worman}

Capitalized if using ibidem.
\Cite[23]{worman}.

\mancite
Just the title:
\headlesscite[23]{worman}.

Volcite with volume number:
\volcite{1}[23]{worman}

Volcite without volume number:
\volcite[23]{worman}.

\end{document}

[lervag]

Thanks for the detailed follow-up!

\edcite and \transcite (and \Edcite and \Transcite) are my own, which would be nice to have covered, but I understand if you'd rather keep to more general-interest features.

Yes, I don't want to add things that are personal here. Sorry!

As for the biblatex-chicago commands, you can find a complete list in the package documentation, section 4.3.2.

To be honest, it's tricky to see which commands are special to biblatex-chicago. It seems most of the listed commands are already in biblatex and that they only have slighty ajdustments?

I just realized why I thought that \volcite had not been implemented: it only works without the (mandatory) volume argument! As far as I know, \volcite and its arguments should only be highlighted as a cite command when a volume is cited, as in \volcite{1}[23]{citekey} or simply \volcite{1}{citekey} but not if the volume argument is missing, so as to alert the user to the missing volume number.

Is this true for biblatex or biblatex-chicago or both?

---

As you probably see, I'm confused as to what here is related to biblatex and what is related to biblatex-chicago. Could I ask that we first fix things that may be wrong with biblatex, then add biblatex-chicago afterwards?

Thus, could you first comment on if any of the things you are raising here are relevant as "bugs" for the current biblatex implementation?

[alexandreroberts]

Thank you, yes, that makes sense. I just checked the biblatex documentation and realized that you're absolutely right: almost all the commands that I had noticed are not being highlighted properly are biblatex commands (not biblatex-chicago). The only exception to this is \headlesscite and related commands, which belong to biblatex-chicago (see p. 67 of the biblatex-chicago documentation, in section 4.3.2). So you're right, what I am describing turns out to be two parts: 1. a bug report: that \Cite, \volcite, \Volcite are not being highlighted properly 2. a feature request: it would be nice to have certain biblatex-chicago commands covered as well, in particular \headlesscite et sim. About \volcite in particular: the syntax I describe is already there in biblatex (see p. 115 of the biblatex documentation, within section 3.9.6). I think this is the only cite command (or rather the only family of commands, including \pvolcite, \fvolcite, etc.) that has the peculiar feature of having a required argument other than the citekey. (What I neglected to mention is of course the first optional argument, "prenote," which can be there in \volcite too, before the mandatory volume argument.)

[alexandreroberts]

For reference, here are the lines of the biblatex documentation about \volcite et sim.:

[lervag]

Let's focus on the bug report first:

• As far as I can see, \volcite is properly highlighted. But you do need to load the biblatex package for this to work. FYI, the support for these commands is not very thorough; it works by allowing any number of groups of argument groups. But it should work more or less as expected, I think.
• It seems \Cite does not work. I'll fix that now fixed.

Can you please verify that I'm not mistaken somehow? I.e., modify your MWE to use only biblatex and verify that it does work as expected.

[alexandreroberts]

Thank you for fixing \Cite. I haven't tested that yet (I'm still working with the previous commit of vimtex).

As for \volcite, it does not appear to be correctly highlighted on my computer. Here is the updated MWE using plain biblatex:

MWE

main.tex:

%!TEX TS-program = xelatex
%!TEX encoding = UTF-8 Unicode

% Normal:
\documentclass[12pt,article,draft]{memoir}

\usepackage{biblatex}
\addbibresource{biblatex-examples.bib}

\begin{document}

\cite[23]{worman}

\Cite[23]{worman}.

This is good biblatex syntax, so the citekey SHOULD be highlighted as such and should not be spell-checked:
\volcite{1}[23]{worman}

This is bad biblatex syntax, so the citekey would ideally NOT be highlighted as such and SHOULD be spell-checked:
\volcite[23]{worman}

\parencite[23]{worman}

\pvolcite[23]{worman}

\end{document}

test.vim:

set nocompatible 
set mmp=5000

call plug#begin('~/.vim/plugged')
Plug 'lervag/vimtex'
call plug#end()

set spell

And this is what I get with nvim -u test.vim main.tex:

As you can see, the citekey is highlighted as a spelling error only when the \volcite syntax is right, not when it is wrong. The situation should be reversed.

[alexandreroberts]

In other words, the situation with \volcite (and all related commands like \pvolcite) is exceptional, in that it needs to be allowed (indeed required) to have that mandatory volume argument.

[lervag]

Ony my end, both of the \volcite commands prevent spell checking.

[lervag]

I've pushed a minimal version of biblatex-chicago now, FYI; it is probably not good enough yet, but at least it ensures to load the biblatex syntax rules and adds some form of support for \headlesscite.

[alexandreroberts]

That is curious. I will now update the vimtex plugin on my computer and try again.

[lervag]

Oh; the problem is with the concealed variants. I'll look into that now.

[alexandreroberts]

Ah, OK. Just to confirm the results of my update: I still am getting the spell-check highlighting on the correct \volcite command (i.e., the problem is not solved for me).

[lervag]

I've pushed a fix for the volcites now. Notice that it is not ideal: The bad form will still "look" right. I hope that's OK.

[alexandreroberts]

That did the trick, thank you!

[alexandreroberts]

And yes, it's fine for the bad form to still look correct. It's the kind of syntax error one rarely makes, since the whole point of using \volcite is to enter a volume number!

[lervag]

Great; glad to hear it! So, over to biblatex-chicago. The docs were not very specific on the arguments for \headlesscite - could you check if the updates are sufficient?

[alexandreroberts]

Yes, I can confirm that \headlesscite (and variants, at least the capitalized and pluralized variants) work too. Thank you!

Now I think that everything related to this feature request/bug report that I had noticed was missing (other than my custom commands, of course) has been implemented. Thanks for doing it so quickly!

[lervag]

Great! Glad to hear it works as expected! And thanks for making it easy by providing all the necessary details!

[alexandreroberts]

Sorry to trouble you about this closed issue, but I have been trying to make my own "personal" biblatex cite commands highlight by mimicking your code, but clearly I don't understand how vim works.

You wrote:

\edcite and \transcite (and \Edcite and \Transcite) are my own, which would be nice to have covered, but I understand if you'd rather keep to more general-interest features.

Yes, I don't want to add things that are personal here. Sorry!

I tried to make \[Ee]dcite and \[Tt]ranscite work by copying your the whole function in autoload/vimtex/syntax/p/biblatex.vim, pasting it into ftplugin/tex.vim, and then adding these two to the list of functions, i.e., adding:

syntax match texCmdRef nextgroup=texRefOpt,texRefArg skipwhite skipnl "\\[Ee]dcite[pt]\?\>\*\?"
syntax match texCmdRef nextgroup=texRefOpt,texRefArg skipwhite skipnl "\\[Tt]ranscite[pt]\?\>\*\?"

But this gives me an error message and makes the highlighting not work at all.

Is there a recommended way to do what I am trying to do?

[lervag]

Sorry to trouble you about this closed issue,

No problem!

I tried to make \[Ee]dcite and \[Tt]ranscite work … and then adding these two to the list of functions, i.e., adding: …

Is there a recommended way to do what I am trying to do?

Yes: I would add the additional syntax rules that you want to your CONFIG/after/syntax/tex.vim file, where CONFIG is typicall ~/.vim for Vim and ~/.config/nvim for Neovim.

The contents of that file should be the same as the lines you already tried:

syntax match texCmdRef nextgroup=texRefOpt,texRefArg skipwhite skipnl "\\[Ee]dcite[pt]\?\>\*\?"
syntax match texCmdRef nextgroup=texRefOpt,texRefArg skipwhite skipnl "\\[Tt]ranscite[pt]\?\>\*\?"

This is, by the way, a very good use case of the after/ concept; see :help after-directory.

[alexandreroberts]

That did it, thank you! I thought I vaguely understood the after/ directory; I will study that documentation.

[lervag]

Glad to hear it works!

[engeir]

I wanted to ask here first before possibly opening a new issue, as I think it is a very similar question.

I write a paper now where they expect apacite (specifically apaciteclassic) to be used. Apacite implements

• \cite<prenote>[postnote}{ref}
• \citeA<>[]{}

for parenthesis and in-text citation, respectively. With a custom syntax rule specified in CONFIG/after/syntax/tex.vim like you mention above I got the highlighting for citeA to work.

However, the <> style for prenotes breaks the highlighting. Is there an easy fix for that case I could add to the syntax file?

EDIT: I realize now that this affects the ability to get the list of references as well, not only the highlighting. Can open an issue on this when I get some more time!

[lervag]

With a custom syntax rule specified in CONFIG/after/syntax/tex.vim like you mention above I got the highlighting for citeA to work.

However, the <> style for prenotes breaks the highlighting. Is there an easy fix for that case I could add to the syntax file?

I think this is an OK approach here. To allow the <...> syntax, you could also add something like this:

syntax match texRefADelim '<\|>' contained
syntax match texRefAOpt '<[^>]*>'
      \ contained contains=texRefADelim
      \ nextgroup=texRefOpt,texRefArg

syntax match texCmdRef '\\citeA\?' contains=texRefAOpt,texRefOpt,texRefArg

highlight link texRefAOpt texOpt
highlight link texRefADelim texDelim

EDIT: I realize now that this affects the ability to get the list of references as well, not only the highlighting. Can open an issue on this when I get some more time!

I believe you are referring to completion, here? If so, please open an issue for that. But let's keep these things separated. I don't have a good way to allow easy customization of the completion "triggers", thus I'll have to accept changing the regex to allow this angled bracket variant as well.