How to make LaTeX macros conditional

[benkeks]

Description

I'm trying to provide different versions of macros for PDF and HTML output of my document. (This is necessary to handle some inconsistencies between browser math rendering and PDF rendering.)

But I don't seem to find out how to achieve this. Other discussions mentioned to use .content-visible / .content-hidden blocks. But these do not affect the macro unfolding.

---
title: "Conditional Macros"
format: pdf
pdf-engine: xelatex
keep-tex: true
---

::: {.content-visible when-format="html"}
\providecommand{\mymacro}{\texttt{HTML version of macro}}

(This is HTML output.)
:::

::: {.content-visible when-format="pdf"}
\providecommand{\mymacro}{\texttt{PDF version of macro}}

(This is PDF output.)
:::

$$\textrm{Test: }\mymacro$$

My hope would have been that this renders as (This is HTML output.) Test: HTML version of macro for HTML and as (This is PDF output.) Test: PDF version of macro for PDF.

But the PDF output is:

The reason seems to be that macros are detected regardless of content visibility policy and then unfolded in a preprocessing step (likely by Pandoc's latex_macros?).
The intermediary TeX reads:

[...]
\providecommand{\mymacro}{\texttt{PDF version of macro}}

(This is PDF output.)

\[\textrm{Test: }\texttt{HTML version of macro}\]
[...]

How can one properly control the macro set for the preprocessing?

[mcanouil]

You could start avoiding raw language without specifying its raw languages which could explain the issue you are having.

https://quarto.org/docs/authoring/markdown-basics.html#raw-content

And regarding Math macros: https://quarto.org/docs/authoring/markdown-basics.html#equations

(likely by Pandoc's latex_macros?)

Yes, this macro thing is a Pandoc feature, not a Quarto one.

[mcanouil]

To be clear using raw code blocks like that is mostly used for its side effect that is to ask Pandoc to exclude the content that does not match the output format language, so it's not really conditional content.

For me, that's a little unsatisfactory, as I would prefer using KaTeX, where I'm dependent on Pandoc processing the macros. Is there any way to make the content-hidden filter happen before Pandoc collects and applies macros?

Choose KaTeX and look at the tool documentation about how to define macros.

[mcanouil]

To be clear, what Quarto documents for MathJax macro is coming directly from MathJax documentation.
That's not a Quarto or Pandoc feature.

https://docs.mathjax.org/en/latest/input/tex/macros.html

[mcanouil]

KaTeX does support macros, but you need to define them as it expects them.

https://katex.org/docs/supported.html#macros

Note that this is unrelated to Quarto or Pandoc.

[benkeks]

KaTeX does support macros, but you need to define them as it expects them.

According to the issue discussion over at #7518 (comment), KaTeX macros do not work in the Pandoc/Quarto setup. (That's also my experience.)

[mcanouil]

Thanks, I forgot about that issue.
Note that it works but not inside the double dollars contrary to MathJax syntax.

This is where Pandoc automatic guessing gets weird.
The only way to get macro expansion for kaTeX is to use bare LaTeX code that Pandoc will see as "macros", it will then do the macro expansion before the rest, and write the proper HTML if needed.
The issue here is that Pandoc is used as the Markdown parser for the document at the first step.

Maybe there is a way using a Lua filter.

---
title: "Conditional Macros"
format:
  native: default
---

\newcommand{\mymacro}{\texttt{HTML version of macro}}

$$
\textrm{Test: }\mymacro
$$

is

Pandoc
  Meta
    { unMeta =
        fromList
          [ ( "title"
            , MetaInlines [ Str "Conditional" , Space , Str "Macros" ]
            )
          ]
    }
  [ RawBlock
      (Format "tex")
      "\\newcommand{\\mymacro}{\\texttt{HTML version of macro}}"
  , Para
      [ Math
          DisplayMath
          "\n\\textrm{Test: }\\texttt{HTML version of macro}\n"
      ]
  ]

[benkeks]

The following workaround leads to Pandoc unfolding latex_macros for HTML output (which is necessary for macros to affect KaTeX math), and to Pandoc leaving the macro processing to LaTeX for PDF.

---
title: "Conditional Macros"
format:
  html:
    html-math-method: katex
  pdf:
    from: markdown-latex_macros
---

::: {.content-visible when-format="html"}
\providecommand{\mymacro}{\texttt{HTML version of macro}}
<!-- this version of the macro will be unfolded by Pandoc's latex_macros filter, which we deactivate for PDF  -->

(This is HTML output.)
:::

::: {.content-visible when-format="pdf"}
\providecommand{\mymacro}{\texttt{PDF version of macro}}
<!-- this version of the macro will be unfolded by LaTeX -->

(This is PDF output.)
:::

$$\textrm{Test: }\mymacro$$

(Note that the order of the providecommand statements matters for the trick to work! The order makes the HTML version dominate the PDF version in Pandocs macro processing.)

[mcanouil]

I think that's the best workaround as Lua filters won't do the trick or I am missing a piece.

As you can see with this simple example, "Hello" is removed, but the macro still works.

---
title: "Conditional Macros"
format:
  html:
    filters:
      - at: pre-ast
        path: macro-html.lua
---

::: {#macro-html}
\providecommand{\mymacro}{\texttt{HTML version of macro}}

Hello
:::

$$
\textrm{Test: }\mymacro
$$

function Div(el)
  if el.identifier == "macro-html" then
    return pandoc.Null()
  end
end

[cderv]

@mcanouil LaTeX Macros are a Pandoc Reader options. So it happens at parsing time within Markdown reader when the latex_macros extensions is activated. This is why macros are still applied even if you remove in Lua.

[cderv]

For reference,

• Conditional content does not work with latex macros #2580

[mcanouil]

FYI, following KaTeX documentation:

• https://katex.org/docs/supported.html#macros
• https://katex.org/docs/api#persistent-macros

---
title: "Conditional Macros"
format:
  html:
    html-math-method: katex
    include-after-body:
      - text: |
          <script>
            const macros = {};
            for (let element of mathElements) {
                katex.render(element.textContent, element, {
                    throwOnError: false,
                    macros
                };
            }
          </script>
---

$$
\gdef\mymacro{\texttt{HTML version of macro}}
$$

$$
\textrm{Test: }\mymacro
$$

Which lead to:

---
title: "Conditional Macros"
format:
  pdf: default
  html:
    html-math-method: katex
    include-after-body:
      - text: |
          <script>
            const macros = {};
            for (let element of mathElements) {
                katex.render(element.textContent, element, {
                    throwOnError: false,
                    macros
                };
            }
          </script>
---

::: {.content-visible when-format="html"}
$$
\gdef\mymacro{\texttt{HTML version of macro}}
$$

(This is HTML output.)
:::

::: {.content-visible when-format="pdf"}
```{=latex}
\newcommand{\mymacro}{\texttt{PDF version of macro}}
```

(This is PDF output.)
:::

$$
\textrm{Test: }\mymacro
$$