Support optional arguments in math macros

[alcrene]

Which area is this feature request for?

MyST Markdown Syntax

Describe the feature you'd like to request

A commonly used feature of math macros is the ability to define default values for their arguments. So for example, in LaTeX one can write (example adapted from Wikibooks)

\newcommand{\request}[2][me]{A feature request by {#1} and {#2}}

This defines the first argument to macro \wbalTwo as a optional, and sets its default value to Wikimedia. The macro can then be used with or without specifying this argument:

• \request{you} -> A feature request by me and you
• \request[Mary]{Susan} -> A feature request by Mary and Susan

MathJax supports this as well; the macro above, if added to a MathJax config block, would look like the following:

window.MathJax = {
  tex: {
    macros: {
      request: ['A feature request by #1 and #2', 2, 'me']
    }

At present defining optional arguments in mystjs is not supported; I believe this should be added. Even given the idiosyncratic way LaTeX deals with optional parameters, this is quite a useful feature, and one most users (at least those who use macros) will likely expect. Not supporting it also makes it much more work to port existing documents or preamble files to mystjs.

(For reference: the semi-official LaTeX docs on the topic.)

Describe the solution you'd like

In terms of syntax, one option could be to follow MathJax's lead, and allow an additional argument to the list. Then the example from the MyST documentation would become

---
# Math frontmatter:
math:
  # Note the 'single quotes'
  '\dobs': '\mathbf{d}_\text{obs}'
  '\dpred': ['\mathbf{d}_\text{pred}\left( #1 \right)', '\mathbf{m}_\text{ref}']
---

[…] reference model $\dpred$, or more generally to model $m$, $\dpred{m}$.

Some points:

• LaTeX inherits idiosyncracies from TeX, among them the fact that only the first argument may be optional. (Short of packages like twoopt or LaTeX3)
  • MathJax inherits this limitation, which is mostly fine because most people still want their macros to work in LaTeX (or they copy them from some LaTeX source).
• MathJax does not allow nested macro definitions. So the following will work in LaTeX but not MathJax:

  \newcommand{\size}{(L)}
  \newcommand{\data}{D^{\size}}

Describe alternatives you've considered

Possible workarounds could be:

• Embed the macro in within a math block in the document itself, using MathJax's support for \newcommand.
  • Con: Would not work with LaTeX export (which only accepts \newcommand within its preamble)
• Parse a preamble file as a .tex document.
  • Con: Would not work with HTML export
  • Con: Relies on multi-document support, which is still WIP

[welcome[bot]]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:
If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.
If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).
Welcome to the EBP community! :tada:

[rowanc1]

Thanks @alcrene for the detailed write up, this is super helpful.

As a note to others following along, we also talked a bit about other ways we want to open up the macro math frontmatter to support interactivity, color, and linking things together with other roles/directives in myst.

Some ideas that we have thought about are ways to include color, hover, and alt-text for macro definitions:

I think some of these are a step towards a more complete understanding of the math environments and parsing them fully, we helped make a demo made for @andrewhead last year who is researching this (see their video), screenshot:

@thesamovar probably also has ideas here! We will probably keep this issue contained to adding the defaults feature that you asked for @alcrene, but very excited to explore this area more in the coming months!

[thesamovar]

That looks cool @rowanc1. My only suggestion would be automatically showing definitions in a side column when an equation that uses a term is used (similar to other ideas we talked about).

[rowanc1]

Yes! I have started introducing some base theme components that are hopefully going to support some of this work. We now have a grid-system at the base of the myst-theme, which is going to be useful in all of the advanced layouts that we want to get to!