[rustdoc] Convert double-hyphen to dash in docs

[alexreg]

It would be nice to get rustdoc to convert double-hyphen (--) (probably just when surrounded by spaces?) to a dash character (–) in doc-comments. People tend to use double-hyphen in code instead of the actual actual character, since it's easier to type on most keyboards. I reckon this could be done perfectly reliably.

[GuillaumeGomez]

Do you have an example of where it'd be useful? In such cases, I'm afraid of side-effects of unwanted replacements or maybe users' misunderstanding.

[alexreg]

Well, it's just about nicer typography. See the rustc guide for example. What side effects do you imagine? The main one I can envisage is --command-line-options, but they should always be in backticks, I'd think... and you use a Markdown parser anyway, so I think it's okay.

[GuillaumeGomez]

So still doesn't sell much of a dream: ;)

[alexreg]

Oh I know, the benefit is incremental... but the implementation cost is so low, and I don't see the downside. ;-)

[alexreg]

I mean... don't we all like nice, propr typography?

[GuillaumeGomez]

Install a better font maybe? 😛

[alexreg]

This is nothing to do with fonts... it's to do with – vs. --!

[ollie27]

I'm assuming you mean converting a pair of hyphen-minus characters into an en dash like in TeX?

rustdoc uses CommonMark and unless this was added to that spec I don't think it's worth adding this feature. It's already possible to insert en dashes using – for example.

[alexreg]

@ollie27 Yes, I wrote it correctly in my title and the wrong way round in the comment oops. I think this is really orthogonal to Markdown to be honest... Sure, it's already possible, but no one is going to write %ndash; in doc-comments, that's the problem. We might as well accept the convention and just aim for better typographical display.

[Ixrec]

People tend to use double-dash in code instead of the actual hyphen character, since it's easier to type on most keyboards.

I think this is simply incorrect: it's the em dash [—] that I'm trying to emulate when I use a double hyphen [--], not a single hyphen [-] (or an en dash [–] for that matter). Obviously "the actual hyphen character" is easy to type, since a double hyphen is literally just typing it twice.

But assuming that was just terminology confusion, auto-converting a double hyphen to an em dash makes a lot of sense to me, and I feel like I've encountered this behavior in other tools before without complaint. Though it also seems reasonable to move this question to the CommonMark spec, since it probably ought to be done in all markdown-processing tools.

[alexreg]

@Ixrec

1. That was was just me accidentally writing them the wrong way round (I had written it correctly earlier, oops!).
2. The en/em-dash is definitely not easier to type on most keyboards (which don't have it) and OSs. On Windows you need an Alt+code combination, and on macOS you need Alt + Shift + - for the em-dash! Double-tapping the same key twice is a lot easier, I'm sure.
3. Glad you think the behaviour itself is useful. I agree it would probably make sense to become a part of CommonMark, but I don't think it needs to for us to implement it here. But I'll file an issue there anyway; good idea.

[alexreg]

Ah, seems there's already an "optional extension" to the spec, but it has -- meaning en-dash and --- meaning em-dash, which is slightly awkward I think. (In practice, en-dash is encountered much less often, I find, since it used primarily for ranges, and the typographic difference from hyphen is less noticeable.)

commonmark/commonmark-spec#593

[steveklabnik]

rustdoc uses CommonMark and unless this was added to that spec I don't think it's worth adding this feature. It's already possible to insert en dashes using – for example.

This is my opinion as well.

[alexreg]

@steveklabnik See my above comment. It's an optional extension already part of the spec, according to that thread. :-)

[pacak]

Unless I'm mistaken rustdoc now uses pulldown-cmark which performs this transformation. Transformation is performed inconsistently - only in blocks it considers to be markdown. This makes generating documentation in markdown with extra html styling complicated enough to the point it's easier to generate just html.

Either way this ticket seems to be completed.