rust-lang / docs.rs

crates.io documentation generator
https://docs.rs
MIT License
969 stars 193 forks source link

Box drawing characters in comments are tilted, making diagrams look bad #1443

Closed lilyball closed 3 years ago

lilyball commented 3 years ago

It looks like the Source Code Pro font used on docs.rs for code contains italicized versions of box drawing characters (including the ASCII Vertical Line character "|"), which is rather surprising since none of the other fonts I've tested on my computer that have these characters show any difference between the regular and italic variants. (EDIT: The browser is probably synthesizing italic by slanting all characters, including box drawing characters, as no italic variant was declared for Source Code Pro) This means ASCII diagrams in comments in the source listings do not look right, or tables, or anything else relying on straight lines. Here's an example taken from https://docs.rs/crate/tokio-util/0.6.7/source/src/codec/framed_impl.rs:

Screenshot of source code showing an ASCII art diagram. The font is Source Code Pro, and all of the characters, including the box drawing characters, are italicized. This means the box drawing characters do not form straight lines.

If I edit the style to be 'monospace' (which on this computer is Menlo) it looks much better:

Screenshot of the same source code as above. The font is Menlo, and only the letters are italicized. The box drawing characters, including the ASCII vertical line character, are not italicized and therefore they form nice straight lines.

This should probably be filed upstream as a bug with your provider for the Source Code Pro font, but in the meantime, if you can't easily get a version of Source Code Pro that doesn't do this, it seems you can hack it by redeclaring an italic version of the font with the unicode-range property.

Proof of concept

Add the following CSS:

@font-face {
    font-family: 'Source Code Pro';
    font-style: italic;
    font-weight: 400;
    src: url("SourceCodePro-Regular.woff") format("woff");
    unicode-range: U+25??, U+7C;
}

You may want to add a font-weight: 600 variant as well just in case. I'm also not sure if this covers all the unicode characters necessary, but it does cover the ones in this diagram. This produces the following result on Safari 14 (also tested on Firefox 89):

Screenshot of the same source code as above. The font is Source Code Pro, but the vertical line and box drawing characters are straight instead of italic, and therefore they form nice straight lines.
lilyball commented 3 years ago

Now that I think about it, perhaps the issue is that the browser is synthesizing italic characters by adding oblique rendering because of the lack of an italic font. I'm not particularly familiar with @font-face, but it does declare the font style to be "normal". I was assuming that perhaps the referenced WOFF contained both regular and italic versions, but I suspect now that the italic variant would have to be specific explicitly in order to exist at all.

Which is to say, the proper fix is to add an italic variant of Source Code Pro. It looks like an italic variant exists (and does not tilt the box drawing characters, according to my quick test on the Google Fonts page), it's just not being declared here. So either add an italic variant, or use the unicode-range hack described above (after making sure there are no other characters that need to be excluded).