Use italics for O notation

[pierwill]

In documentation, I think it makes sense to italicize O notation (O(n)) as opposed to using back-ticks (O(n)). Visually, back-ticks focus the reader on the literal characters being used, making them ideal for representing code. Using italics, as far I can tell, more closely follows typographic conventions in mathematics and computer science.

Just a suggestion, of course! 😇

[rust-highfive]

r? @Mark-Simulacrum

(rust_highfive has picked a reviewer for you, use r? to override)

[Mark-Simulacrum]

I'm going to tentatively cc @rust-lang/rustdoc and r? @GuillaumeGomez here, I guess this is more in "docs" territory but that doesn't currently exist.

[CAD97]

As I understand it, it would be Most Correct to use actual math markup for big-O notation, whether with MathML directly, faux-LaTeX (pre)processors like MathJax or KaTeX, or even some ad-hoc markup.

Here's an example set with KaTeX:

Or with the alt stylization:

And the different variants easily usable in markdown:

`O(n)`
`O(n log n)`

*O(n)*
*O(n log n)*

*O*(*n*)
*O*(*n* log *n*)

O(n)
O(n log n)

O(n)
O(n log n)

O(n)
O(n log n)

Correct notation italicizes the big O itself and the variable name n, but not mathematical functions such as log, constants such as 1, or the parenthesis.

It's probably worth looking at what other projects writing documentation in markdown and talking about big-O do. Honestly, I expect most to just not offset the math at all, just writing e.g. O(n log n). Italicizing is probably "correct enough" to be both more correct than <code> (at least, if it lowered to (the retconned) <i>, anyway; <em> is a harder sell) and less needless notation effort than properly italicizing only the mathematical symbols of big-O notation.

[ratijas]

On a side note, I'd love to see some advanced markup possibilities (like MathML) in rustdoc system. There's beautiful simplicity (rust) on one end, and complex alien syntax (reST) on the other end, — it feels like there should be something reasonably usable in between.

[GuillaumeGomez]

You put the whole O notation in italic, but I have to admit that just having O and n in italic looks better (like @CAD97 suggested).

[pierwill]

You put the whole O notation in italic, but I have to admit that just having O and n in italic looks better (like @CAD97 suggested).

I agree. I'll update this PR when I get a chance and ping for a re-review—

[steveklabnik]

I'm going to tentatively cc @rust-lang/rustdoc and r? @GuillaumeGomez here, I guess this is more in "docs" territory but that doesn't currently exist.

Ultimately, stdlib doc contents are now the responsibility of the libs team, though obviously folks involved in docs tooling would want to be involved :)

Yes, Mathjax would be nice, but historically it has been seen as too heavy a dependency.

[kinnison]

What's the situation with MathML - you used to hear quite a bit about it, but not recently.

[CAD97]

https://caniuse.com/#feat=mathml

Chrome doesn't have native support for MathML, so using it without MathJax is basically a nonstarter. You can use MathML, but you have to include the KaTeX or MathJax stylesheets to do the actual work of transforming the markup into actual math notation.

I don't have the source for it, but I remember seeing that work on MathML was basically stopped because MathJax got the same effect. (MathJax can take MathML as an input, KaTeX only takes faux-TeX.)

[GuillaumeGomez]

If you want specific parsers for your format, you can have it in your own documentation, rustdoc allows to add your own scripts. However, adding an extra dependency will impact everyone and will only benefit a few. So to be clear: no additional dependency will be allowed for doing this automatically in rustdoc itself.

[pierwill]

You put the whole O notation in italic, but I have to admit that just having O and n in italic looks better (like @CAD97 suggested).

I've updated this PR along these lines.

[pierwill]

Pushed those changes!

[GuillaumeGomez]

Thanks!

@bors: r+ rollup

[bors]

📌 Commit 76b8420 has been approved by GuillaumeGomez

[bors]

⌛ Testing commit 76b8420 with merge 7138410...

[bors]

☀️ Test successful - checks-actions, checks-azure
Approved by: GuillaumeGomez
Pushing 7138410 to master...