Rustdoc does not correctly ignore input inside HTML tags.

[497e0bdf29873]

I am trying to use the KaTeX html-in-header autorender workaround to include mathematics in documentation (see, for example, https://docs.rs/rustdoc-katex-demo/latest/rustdoc_katex_demo/). However, KaTeX auto-render postprocessing is severely incompatible with markdown due to markdown processing almost any underscores it encounters as italics.

For example, the documentation

/// For an operator $A$ this is an operator $A_*$ such that its adjoint $(A_*)^*=A$. 

gets converted into the HTML

For an operator $A$ this is an operator $A_<em>$ such that its adjoint $(A_</em>)^*=A$.

The standard workaround (unreadable-as-text, and will also stop README.md sharing with a modern markdown processor that directly supports KaTeX) would be to to write instead

/// For an operator $A$ this is an operator <span>$A_*$</span> such that its adjoint <span>$(A_*)^*=A$</span> 

because markdown should not process things between HTML tags. This does not work with rustdoc:

For an operator $A$ this is an operator <span>$A_<em>$</span> such that its adjoint <span>$(A_</em>)^*=A$</span>. 

So it seems rustdoc is incorrectly processing input between HTML tags, that standard markdown would ignore.

This is on nightly.

Issue related to : #17390, #16300, and several others begging some form of LaTeX math support.

[ehuss]

The markdown standard does not call for markdown to be disabled inside inline HTML tags. It is only disabled in very specific circumstances described in HTML Blocks. This can be seen on dingus or here on GitHub:

For an operator $A$ this is an operator $A_$ such that its adjoint $(A_)^*=A$

I don't have a particular suggestion other than escaping with backslashes.

[497e0bdf29873]

Neither backslash escapes work

/// For an operator $A$ this is an operator $A\_*$ such that its adjoint $(A\_*)^*=A$

becomes the same old

For an operator $A$ this is an operator $A_<em>$ such that its adjoint $(A_</em>)^*=A$.

Edit: Oh, wait, you need like 10 million escapes there.

[aDotInTheVoid]

For an operator $A$ this is an operator $A_\*$ such that its adjoint $(A_\*)^\*=A$. 

becomes

<p>For an operator $A$ this is an operator $A_*$ such that its adjoint $(A_*)^*=A$.</p>

Which I think is what you want

(At least in dingus)

[GuillaumeGomez]

Should we close it then?