Treat IEEEeqnarray as a math environment

[Jetfrog28]

Issue
IEEEtrantools.sty provides a multiline aligned equation environment, IEEEeqnarray. Both IEEEeqnarray and its starred variant, IEEEeqnarray* should be treated as math environments by vimtex.

Could you please make vimtex properly handle these environments?

IEEEeqnarraybox
This was brought up before in #1637, but dropped due to lack of response. In there, IEEEeqnarraybox was also brought up --- I haven't used it before, but may begin to.

It appears there are 6 forms of this environment:
IEEEeqnarraybox, IEEEeqnarrayboxm, and IEEEeqnarrayboxt, as well as their starred variants, IEEEeqnarraybox*, IEEEeqnarrayboxm*, and IEEEeqnarrayboxt*

From IEEEtrantools.sty, line 2129 (on my system):

% \IEEEeqnarraybox is like \IEEEeqnarray except the box form puts everything
% inside a vtop, vbox, or vcenter box depending on the letter in the second
% optional argument (t,b,c). Vbox is the default. Unlike \IEEEeqnarray,
% equation numbers are not displayed and \IEEEeqnarraybox can be nested.
% \IEEEeqnarrayboxm is for math mode (like \array) and does not put the vbox
% within an hbox.
% \IEEEeqnarrayboxt is for text mode (like \tabular) and puts the vbox within
% a \hbox{$ $} construct.
% \IEEEeqnarraybox will auto detect whether to use \IEEEeqnarrayboxm or 
% \IEEEeqnarrayboxt depending on the math mode.
% The third optional argument specifies the width this box is to be set to -
% natural width is the default.
% The * forms do not add \jot line spacing
% usage: \IEEEeqnarraybox[decl][pos][width]{cols}

Suggested behavior
Now, in reading I've realized that all of the environments mentioned actually use text mode or math mode on a per-column basis, dependent on the column specifier. The modes for each column are described in Table IV of this document, on page 19. It would be wonderful if vimtex could handle this properly, but I imagine it would be difficult or impossible to implement.

If properly handling the mode of each column is infeasible, I suggest the following behavior:

• IEEEeqnarray: math mode
• IEEEeqnarraybox: take mode of surrounding environment
• IEEEeqnarrayboxt: text mode
• IEEEeqnarrayboxm: math mode
  and the same for the starred variant of each of these, for a total of 8 environments.

minimal.tex

\documentclass{minimal}
\usepackage{IEEEtrantools}
\begin{document}
%%% standard usage
\begin{IEEEeqnarray}{rCl}
	1\cdot1 &=& 1 \\
	1       &=& 1\cdot1
\end{IEEEeqnarray}
\begin{IEEEeqnarray*}{rCl}
	1\cdot1 &=& 1 \\
	1       &=& 1\cdot1
\end{IEEEeqnarray*}

%%% column-specific modes
\begin{IEEEeqnarray}{sl}
	text & math
\end{IEEEeqnarray}
\end{document}

Thank you for all the work that goes into this plugin, I very much appreciate it. If there's anything else I can provide, please let me know, I'd like to help as much as I'm able.

P.S. I seem to remember reading an issue a while back asking about users being able to define custom environments as math mode. I don't remember seeing a resolution though; does vimtex have this feature in userland?

Edit: This is probably more of a feature request than a bug, but I can no longer change the label. Apologies.
Edit 2: To clarify, all 8 environments change mode depending on the column specifier, including the basic IEEEeqnarray.

[lervag]

Could you please make vimtex properly handle these environments?

I'll try! :)

IEEEeqnarraybox
This was brought up before in #1637, but dropped due to lack of response. In there, IEEEeqnarraybox was also brought up --- I haven't used it before, but may begin to.

Thanks for noticing and following this up with useful information. I'll be glad to work with it.

Suggested behavior
Now, in reading I've realized that all of the environments mentioned actually use text mode or math mode on a per-column basis, dependent on the column specifier. The modes for each column are described in Table IV of this document, on page 19. It would be wonderful if vimtex could handle this properly, but I imagine it would be difficult or impossible to implement.

Ah, that seems very challenging. If I understand correctly, both the number of columns and the "mode" of the columns may differ. Vim relies heavily on regular expressions for syntax highlighting, although it is possible to parse previous lines to gather a "state". In this case, though, I think the complexity is too high and I would prefer to go the simple route and spend my time on other issues and features.

If properly handling the mode of each column is infeasible, I suggest the following behavior:

* `IEEEeqnarray`: math mode
* `IEEEeqnarraybox`: take mode of surrounding environment
* `IEEEeqnarrayboxt`: text mode
* `IEEEeqnarrayboxm`: math mode
  and the same for the starred variant of each of these, for a total of 8 environments.

This sounds doable. Do I understand correctly then, that IEEEeqnarray can be treated almost identical to environments like \begin{align} ... \end{align}? I'll start with this one, then add the *box* versions after.

Thank you for all the work that goes into this plugin, I very much appreciate it. If there's anything else I can provide, please let me know, I'd like to help as much as I'm able.

Thanks for the kind words and offer! I'll probably ask for some more examples of the *box* variants, but for now, I think I have what I need to implement the basics.

P.S. I seem to remember reading an issue a while back asking about users being able to define custom environments as math mode. I don't remember seeing a resolution though; does vimtex have this feature in userland?

There is a function vimtex#syntax#misc#new_math_zone, but it is more of a dev API than a user API. So I guess the answer is no.

Edit: This is probably more of a feature request than a bug, but I can no longer change the label. Apologies.

No worries!

[lervag]

I've pushed a first version of this. It probably needs some polish, but it should provide support for the pure math mode versions.

[Jetfrog28]

If I understand correctly, both the number of columns and the "mode" of the columns may differ.

Yes, that's correct. You can specify an arbitrary number of columns, each of which includes a "mode" in its specification, and then the environment expects exactly the specified number of columns with the specified modes. In that regard it acts like a tabular environment.

Do I understand correctly then, that IEEEeqnarray can be treated almost identical to environments like \begin{align} ... \end{align}?

I believe so (aside from the additional column specifier argument). Semantically, it's perhaps closer to the standard eqnarray environment, but I imagine those are both treated the same for highlighting purposes.

Vim relies heavily on regular expressions for syntax highlighting, although it is possible to parse previous lines to gather a "state". In this case, though, I think the complexity is too high and I would prefer to go the simple route and spend my time on other issues and features.

That's entirely fair. I imagine the simple route will cover the majority of use cases anyway --- it certainly covers mine, as I didn't even know you could use text-mode columns until I filed this report.

There is a function vimtex#syntax#misc#new_math_zone, but it is more of a dev API than a user API. So I guess the answer is no.

Alright, thank you. I'll look into it further if I ever find I need it.

I've pushed a first version of this. It probably needs some polish, but it should provide support for the pure math mode versions.

Thanks for the quick update! It seems to be working as expected in all of my files. It's really nice to have that working now!

In testing I've noticed two things (neither really directly related to this). In LaTeX, things enclosed in a \noalign{...things...} seem to be typeset in text mode, but vimtex still highlights the contents as math mode inside math environments (see new minimal.tex). I don't have any documentation on hand to support this, but the behavior I see when testing is that the \noaligned text always goes to text mode, even in a math environment. I hope that that will be an easy fix, as I know vimtex can already highlight things in that form, e.g. with \emph{}.

Also, does vimtex's syntax highlighting depend on what text is being displayed? I don't have a minimal example here, but in a large document I have, when I scroll to the bottom, it seems to get math mode and text mode switched, and highlight math areas as text and text areas as math. Is that a known issue? If not, I could try to get a MWE and file a separate report.

New minimal.tex

\documentclass{minimal}
\usepackage{IEEEtrantools}
\begin{document}
%%% standard usage
\begin{IEEEeqnarray}{rCl}
	1\cdot1 &=& 1 \\
	1       &=& 1\cdot1
\end{IEEEeqnarray}
\begin{IEEEeqnarray*}{rCl}
	1\cdot1 &=& 1 \\
	1       &=& 1\cdot1
\end{IEEEeqnarray*}

%%% column-specific modes
\begin{IEEEeqnarray}{sl}
	text & math
\end{IEEEeqnarray}

\begin{eqnarray}
	5+5 &=& 10 \\
	\noalign{explanatory text:}
	10 &=& 5+5
\end{eqnarray}

\begin{IEEEeqnarray}{rCl}
	5+5 &=& 10 \\
	\noalign{explanatory text:}
	10 &=& 5+5
\end{IEEEeqnarray}

\end{document}

Thanks again for all your help here.

Edit: Accidentally left document class as article from testing.

[lervag]

Thanks for the quick update! It seems to be working as expected in all of my files. It's really nice to have that working now!

Great. Do I understand correctly that you consider this sufficient for the issue to be resolved? Or did I miss anything?

In testing I've noticed two things (neither really directly related to this). In LaTeX, things enclosed in a \noalign{...things...} seem to be typeset in text mode, but vimtex still highlights the contents as math mode inside math environments (see new minimal.tex). I don't have any documentation on hand to support this, but the behavior I see when testing is that the \noaligned text always goes to text mode, even in a math environment. I hope that that will be an easy fix, as I know vimtex can already highlight things in that form, e.g. with \emph{}.

It seems \noalign{...} is meant to add things between table rows, see here. As far as I can tell, it does not really seem to be a command that you should want to use like that. Thus, I would appreciate some more reference/documentation before I add something like this.

Also, does vimtex's syntax highlighting depend on what text is being displayed? I don't have a minimal example here, but in a large document I have, when I scroll to the bottom, it seems to get math mode and text mode switched, and highlight math areas as text and text areas as math. Is that a known issue? If not, I could try to get a MWE and file a separate report.

Yes, sorry about that. This is a known problem and something I hope I might be able to fix as a consequence of solving #1781. But for now, you could try to do :syntax sync fromstart (which might also increase the lag due to syntax calculations).

Thanks again for all your help here.

No problem :)

[Jetfrog28]

Great. Do I understand correctly that you consider this sufficient for the issue to be resolved? Or did I miss anything?

Yup! All seems well, thanks for your efforts! I'll close the issue.

It seems \noalign{...} is meant to add things between table rows, see here. As far as I can tell, it does not really seem to be a command that you should want to use like that. Thus, I would appreciate some more reference/documentation before I add something like this.

Fair enough. It was something I picked up from this document (section 6.1, page 20), and it seems to mostly work for me, but I don't know enough to say whether that really fits its intended usage.

Yes, sorry about that. This is a known problem and something I hope I might be able to fix as a consequence of solving #1781. But for now, you could try to do :syntax sync fromstart (which might also increase the lag due to syntax calculations).

Thanks for the tip, that does fix it (and doesn't seem to add much lag). It looks like adopting syntax support will be a big undertaking --- good luck; I hope it goes smoothly.

Thanks again for the quick change.

[lervag]

Yup! All seems well, thanks for your efforts! I'll close the issue.

Great! :)

Fair enough. It was something I picked up from this document (section 6.1, page 20), and it seems to mostly work for me, but I don't know enough to say whether that really fits its intended usage.

I think you forgot the link...

Thanks for the tip, that does fix it (and doesn't seem to add much lag). It looks like adopting syntax support will be a big undertaking --- good luck; I hope it goes smoothly.

Thanks!

Thanks again for the quick change.

My pleasure!

[Jetfrog28]

Sorry about that. Here's the link. It's the same document referenced in the previous on these environments.

[lervag]

Thanks. It seems like a very nice document for finding good ways to typeset advanced equation requirements. I still think it seems somewhat random to specify that the command argument should be text without being more "sure" about it.

[Jetfrog28]

That's fair enough. Thanks!

[lervag]

No problem.

[krishnakumarg1984]

IEEEeqnarray is awesome! But pandoc does not support this at all, thereby not making it feasible for my future documents. It was frustrating to get the equations neatly fitted exactly as how I wanted them to be, but then pandoc copping out!