Add nospell option to vimtex_syntax_custom_cmds

[krissen]

Consider the commands \citeyear[n]{foo} and \parencite[n]{bar}.

Without any extra options, the commands are not folded and the content foo and bar is spellchecked. I'd like them folded and not spellchecked.

The following removes spellchecking of them correctly:

let g:vimtex_syntax_nospell_commands=[ "citeyear", "parencite" ]

And the following makes them fold correctly:

let g:vimtex_syntax_custom_cmds = [
      \ {'name': 'citeyear', 'opt': 1, 'conceal': 1},
      \ {'name': 'parencite', 'opt': 1, 'conceal': 1},
      \]

However, including both nospell_commands and custom_cmds, the commands are still folded but also spellchecked. The latter is the problem. It seems that having both commands, custom_cmds takes precedence and the nospell_commands is ignored.

Suggestion: add a variable spell, nospell or some such, to disable spelling in created custom_cmds.

An alternative option would be if nospell_commands and custom_cmds would not clash.

A third option to add the various citation commands* to be identified in the same way as \cite. Although that would be great, the initial suggestion would also be good, I think, as it covers a wider use-case.

* \footcite, \parencite, \parencites, \fullcite, \citeyear, \citeauthor, \textcite, \citet, \citep, \citealp ... well, the list does go on I guess.

PS. Shouldn't the variables be named in a similar fashion; that is either the _commands part of g:vimtex_syntax_nospell_commands should be abbreviated to _cmds or that the _cmds part of g:vimtex_syntax_custom_cmds shouldn't be abbreviated but spelt out as _commands?

EDIT: Clarified a paragraph and added the PS.

[krissen]

The following diff would be a solution along the lines of option three, mentioned above:

diff --git a/autoload/vimtex/syntax/core.vim b/autoload/vimtex/syntax/core.vim
index cefb795..0809f5d 100644
--- a/autoload/vimtex/syntax/core.vim
+++ b/autoload/vimtex/syntax/core.vim
@@ -257,6 +257,8 @@ function! vimtex#syntax#core#init() abort " {{{1
   syntax match texCmdRef nextgroup=texRefArg           skipwhite skipnl "\\\(page\|eq\)ref\>"
   syntax match texCmdRef nextgroup=texRefArg           skipwhite skipnl "\\v\?ref\>"
   syntax match texCmdRef nextgroup=texRefOpt,texRefArg skipwhite skipnl "\\cite\>"
+  syntax match texCmdRef nextgroup=texRefOpt,texRefArg skipwhite skipnl "\\\(full\|paren\|text\|foot\)cite[s]\>\*\?"
+  syntax match texCmdRef nextgroup=texRefOpt,texRefArg skipwhite skipnl "\\cite\(year\|author\)\>\*\?"
   syntax match texCmdRef nextgroup=texRefOpt,texRefArg skipwhite skipnl "\\cite[tp]\>\*\?"
   call vimtex#syntax#core#new_opt('texRefOpt', {'next': 'texRefOpt,texRefArg'})
   call vimtex#syntax#core#new_arg('texRefArg', {'contains': 'texComment,@NoSpell'})
@@ -1926,6 +1928,12 @@ endfunction
 
 " }}}1
 function! s:match_conceal_cites_brackets() abort " {{{1
+  syntax match texCmdRefConcealed
+        \ "\\\(full\|paren\|text\|foot\)cite[s]\?\>\*\?"
+        \ conceal skipwhite nextgroup=texRefConcealedOpt1,texRefConcealedArg
+  syntax match texCmdRefConcealed
+        \ "\\cite\(year\|author\)\>\*\?"
+        \ conceal skipwhite nextgroup=texRefConcealedOpt1,texRefConcealedArg
   syntax match texCmdRefConcealed
         \ "\\cite[tp]\?\>\*\?"
         \ conceal skipwhite nextgroup=texRefConcealedOpt1,texRefConcealedArg
@@ -1953,6 +1961,12 @@ function! s:match_conceal_cites_icon() abort " {{{1
   execute 'syntax match texCmdRefConcealed'
         \ '"\\cite[tp]\?\*\?\%(\[[^]]*\]\)\{,2}{[^}]*}"'
         \ 'conceal cchar=' . g:vimtex_syntax_conceal_cites.icon
+  execute 'syntax match texCmdRefConcealed'
+        \ '"\\cite\(year\|author\)\?\*\?\%(\[[^]]*\]\)\{,2}{[^}]*}"'
+        \ 'conceal cchar=' . g:vimtex_syntax_conceal_cites.icon
+  execute 'syntax match texCmdRefConcealed'
+        \ '"\\\(full\|paren\|text\|foot\)cite[s]\?\*\?\%(\[[^]]*\]\)\{,2}{[^}]*}"'
+        \ 'conceal cchar=' . g:vimtex_syntax_conceal_cites.icon
 endfunction
 
 " }}}1

Not sure if all the changes are needed, but it seems to work.

[lervag]

A third option to add the various citation commands* to be identified in the same way as \cite.

• \footcite, \parencite, \parencites, \fullcite, \citeyear, \citeauthor, \textcite, \citet, \citep, \citealp ... well, the list does go on I guess.

All of these are available in natbib (\cite[pt], \citeauthor, \citeyear), and/or biblatex. And VimTeX already has quite a lot of support for these commands, see:

https://github.com/lervag/vimtex/blob/e658338a000e41cdb14f60467568f45f9ed6ae3d/autoload/vimtex/syntax/p/natbib.vim

https://github.com/lervag/vimtex/blob/e658338a000e41cdb14f60467568f45f9ed6ae3d/autoload/vimtex/syntax/p/biblatex.vim

All of the listed commands above should be supported in this package level. There may be bugs or some missing commands, though, if so, feel free to point it out.

PS. Shouldn't the variables be named in a similar fashion; that is either the _commands part of g:vimtex_syntax_nospell_commands should be abbreviated to _cmds or that the _cmds part of g:vimtex_syntax_custom_cmds shouldn't be abbreviated but spelt out as _commands?

Yes, probably. I like to be consistent, but sometimes I fail. I could do this change, but I need to remember to mark the commit as breaking (note to self).

I think I prefer the terse variant, i.e.

let g:vimtex_syntax_custom_cmds = ...
let g:vimtex_syntax_nospell_cmds = ...

Suggestion: add a variable spell, nospell or some such, to disable spelling in created custom_cmds.

This is a good idea, actually. I think it may also render the nospell_commands option useless as it will be covered by the custom_cmds option. Thus it would also render the commands vs cmds issue irrelevant.

" Instead of
let g:vimtex_syntax_nospell_commands = ["citeyear", "parencite"]

" Use
let g:vimtex_syntax_custom_cmds = [
      \ {'name': 'citeyear', 'spell': 0},
      \ {'name': 'parencite', 'spell': 0},
      \]

[krissen]

All of these are available in natbib (\cite[pt], \citeauthor, \citeyear), and/or biblatex. And VimTeX already has quite a lot of support for these commands [...] All of the listed commands above should be supported in this package level. There may be bugs or some missing commands, though, if so, feel free to point it out.

I keep getting surprised by the intricacies of vimtex, and the level of support it has for various packages etc. Amazing.

I though the problem might have been that the biblatex package isn't getting loaded.

I tried with the following init.lua:

require('packerbootstrap')

return vim.cmd([[
  let g:vimtex_fold_enabled=1
  set conceallevel=2
  let g:vimtex_syntax_nospell_comments=1
  let g:vimtex_syntax_packages = {'biblatex': {'load': 2}}
]])

(packerbootstrap installs packer and vimtex; nothing else.)

And the following minimal test.tex file:

\documentclass{article}

\usepackage{biblatex}
\addbibresource{../../../../lektionsplanering/kallor.bib}

\begin{document}

X	\parencite{Niemi}

X	\citeyear{Niemi}

OK	\cite{Niemi}

OK	\footcite{Niemi}

X	\citeyear{Niemi}


\end{document}

% vim: sw=4:ts=4:spell:spelllang=sv

Lines starting with OK have citation commands that are folded; lines starting with X are not folded.

echo g:vimtex_syntax_packages returns

{'biblatex': {'load': 2}, 'babel': {'conceal': 1}, 'hyperref': {'conceal': 1}', 'amsmath': {'load': 2}}

So the biblatex syntax package is getting loaded. Nevertheless, parencite and citeyear, which as you showed are supported in the biblatex syntax package, are not folded.

However, this is a separate issue than this ticket. Should I open a separate issue? (If it indeed is an issue, that is. Perhaps there's something wrong with my config?)

[krissen]

This is a good idea, actually. I think it may also render the nospell_commands option useless as it will be covered by the custom_cmds option. Thus it would also render the commands vs cmds issue irrelevant.

" Instead of
let g:vimtex_syntax_nospell_commands = ["citeyear", "parencite"]

" Use
let g:vimtex_syntax_custom_cmds = [
      \ {'name': 'citeyear', 'spell': 0},
      \ {'name': 'parencite', 'spell': 0},
      \]

Exactly! Sounds good. This would close the issue at hand. (Possible biblatex syntax package bug/incompetency on my part is a separate matter.)

[krissen]

So the biblatex syntax package is getting loaded. Nevertheless, parencite and citeyear, which as you showed are supported in the biblatex syntax package, are not folded.

On further investigation, although the aforementioned citation commands are indeed recognized as citation commands through the biblatex syntax file you referred to, they are not checked for concealment.

The following diff adds support for concealment of citeyear and parencite:

diff --git a/autoload/vimtex/syntax/p/biblatex.vim b/autoload/vimtex/syntax/p/biblatex.vim
index e6e475a..36b4b1e 100644
--- a/autoload/vimtex/syntax/p/biblatex.vim
+++ b/autoload/vimtex/syntax/p/biblatex.vim
@@ -39,6 +39,8 @@ function! vimtex#syntax#p#biblatex#load(cfg) abort " {{{1

   if g:vimtex_syntax_conceal.cites
     let s:re_concealed_cites = '\v\\%(' . join([
+          \ '[Pp]arencite[s]?',
+          \ 'citeyear?',
           \ '(foot)?cite[tp]?',
           \ '%([Tt]ext|[Ss]mart|[Aa]uto)cite',
           \ ], '|') . ')>\*?'

If I've identified the problem correctly, and it indeed is a bug/feature that can be supported, I can add the rest of the biblatex citation commands in a similar fashion and submit a PR?

[lervag]

I keep getting surprised by the intricacies of vimtex, and the level of support it has for various packages etc. Amazing.

Thanks! :)

Lines starting with OK have citation commands that are folded; lines starting with X are not folded.

So the biblatex syntax package is getting loaded. Nevertheless, parencite and citeyear, which as you showed are supported in the biblatex syntax package, are not folded.

Folded? Do you mean concealed?

However, this is a separate issue than this ticket. Should I open a separate issue? (If it indeed is an issue, that is. Perhaps there's something wrong with my config?)

I believe a new issue is useful, if only to make things more concrete and focussed. If I don't resolve it immediately, then a long thread often leads to longer delays because of the workload of simply reading everything again.

This is a good idea, actually. I think it may also render the nospell_commands option useless as it will be covered by the custom_cmds option. Thus it would also render the commands vs cmds issue irrelevant.

Exactly! Sounds good. This would close the issue at hand. (Possible biblatex syntax package bug/incompetency on my part is a separate matter.)

Then I'll give this a go, and we'll consider the lack of conceals (I believe this is what you mean) a new issue.

On further investigation, although the aforementioned citation commands are indeed recognized as citation commands through the biblatex syntax file you referred to, they are not checked for concealment.

...

If I've identified the problem correctly, and it indeed is a bug/feature that can be supported, I can add the rest of the biblatex citation commands in a similar fashion and submit a PR?

Yes, a PR would be even better than a new issue :)

[krissen]

Folded? Do you mean concealed?

I did, yes. Concealed.

Then I'll give this a go, and we'll consider the lack of conceals (I believe this is what you mean) a new issue.

Perfect.

Yes, a PR would be even better than a new issue :)

If the changes I made in the diff above look reasonable, I will add the additional commands in a similar fashion!

[lervag]

I've pushed the mentioned change now, I think it worked out nicely. Please test!

Yes, a PR would be even better than a new issue :)

If the changes I made in the diff above look reasonable, I will add the additional commands in a similar fashion!

Yes, the changes look reasonable. If you go for a PR, please also consider to update the test/test-syntax/test-biblatex.{tex,vim} files as well (if necessary). Notice that these tests are not really CI tests, they are manual in the sense that they make it very easy to do nvim -u test-biblatex.vim to open a split version of the test-biblatex.tex file where I can see the effect of the syntax and highlight rules, including the conceals.

[lervag]

And I believe my commit resolves the current thread, as discussed.

[krissen]

And I believe my commit resolves the current thread, as discussed.

Indeed it does! Many thanks for the swift implementation! 🙏

Minor thing. Consider the following line in a preamble:

\DeclareLanguageMapping{swedish}{swedish-apa}

And the following in ViM init files:

let g:vimtex_syntax_custom_cmds = [
      \ {'name': 'DeclareLanguageMapping', 'argspell': 0},
      \]

Here, the first argument is indeed not spellchecked. The latter one is. Would it be possible to make argspell a blanket statement; neither options [] nor additional arguments {}{} would be spellchecked?

(Concealment works the same way, by the by. The first argument is concealed if 'conceal': 1, the latter argument not. Individual preamble lines doesn't really make sense to conceal, so that's not worth looking into. Just mentioning as I happened to notice.)

[lervag]

And I believe my commit resolves the current thread, as discussed.

Indeed it does! Many thanks for the swift implementation! pray

Glad to hear it!

Minor thing. ...

Here, the first argument is indeed not spellchecked. The latter one is. Would it be possible to make argspell a blanket statement; neither options [] nor additional arguments {}{} would be spellchecked?

This is actually more tricky, because there is no simple way to know how many arguments a LaTeX command should accept. I believe one easy fix is to allow one more option: arggready, which, if true, would allow any number of arguments - all matched with the same argument group.

But it is too hard to make custom_cmds work for every single case, so I don't think we can go any further than that here.

So, we could do

let g:vimtex_syntax_custom_cmds = [
      \ {'name': 'DeclareLanguageMapping', 'argspell': 0, 'arggready': 1},
      \]

and this would would as "expected". If you wrote \DeclareLanguageMapping{swedish}{swedish-apa} {something else here}, then the {something else here} part would also be capture with the same argument group, but I think this would be a rare exception.