This is more or less what the existing hacks are doing. I agree it would be cool to make it first-class in some manner.
i had an idea after reviewing this thread and i have to say i like it a lot:
/// Computes the value of
#[doc = emmle::typst!($ x * x = x^2 $)]
/// .
pub fn square(x: f32) -> f32 {
x * x
}
this renders to svg, like so
but could easily be extended to MathML with some other backend.
the AOT-via-proc-macro solution is nice because
- no javascript
- small bundle size
- endlessly extensible
- no need for rust to commit to any 1 solution.
actual crate to come when i can be bothered to make this usable.
9 Likes
Rustdoc uses Markdown because most people are already familiar with it. So we shouldn't ignore what conventions for displaying math already exist.
GitHub supports LaTeX math delimited by $ (inline) or $$ (block), and this has become a de-facto standard used also by GitLab, Obsidian, StackOverflow, HackMD, Discord, Jupyter Notebooks, and probably many more.
Although it's tempting to use our favourite markup language (Typst, AsciiMath, etc.) it may be more important to be compatible with existing tools. For example, people may quote documentation comments on GitHub, and would prefer if GitHub rendered it correctly. Or they may write documentation in a .md file with Markdown All in One (which supports LaTeX math) and include it with #[doc = include_str!("...")].
I know there is no official spec for math in Markdown. Many Markdown implementations don't even conform to CommonMark. But it's still worthwhile to pursue compatibility with the wider ecosystem, where possible. Note that documentation comments aren't just consumed by rustdoc and rust-analyzer, but also by 3rd party tools (e.g. cargo-readme, rusty-man, UniFFI). Using the same syntax for math as everyone else (LaTeX math) will make their life much easier.
7 Likes
One issue is that there is no One True Version of "LaTeX math". LaTeX is a full language, with a wide variety of loadable extensions.
2 Likes
Re Stack Overflow, the software powering it (Stack Exchange) allows the choice of either $ or \$ as the marker for math markup, and many sites using it use the latter because $ has too many false positives. (This is a bit unfortunate because in the case where $ is the marker, \$ would be how you escape it in order to prevent it counting as a marker.)
I would be potentially worried about false postives for a single $. Rust's use of it would mostly be in code blocks (I don't expect many people to talk about a $macro_var in their documetnation without putting it in code formatting), but some amount of natural-language use of $ might also exist in existing documentation, that we would prefer to not break.
1 Like
Agreed. That's the kind of thing we could change in an edition, though, and have an opt-in for otherwise.
We’re trying to be compatible with GitHub, VSCode, Pandoc, and other extended Markdown renderers. They don’t implement the full TeX macro language, and neither should we.
There are corner cases where they disagree with each other, but that’s true of a lot of markdown extensions that rustdoc already implements.
2 Likes