Fonts and CSS for Unicode Art

[samoconnor]

Here is a patch that improves rendering of ASCII Unicode Art:

--- a/assets/html/documenter.css
+++ b/assets/html/documenter.css
@@ -21,7 +21,8 @@ body, input {
 }

 pre, code, kbd {
-  font-family: 'Roboto Mono', Monaco, courier, monospace;
+  font-family: 'Menlo', 'Roboto Mono', Monaco, courier, monospace;
+  line-height: 1.3em;
   font-size: 0.90em;
 }

Maybe 'Roboto Mono' does not have glyphs for the arrow heads and is using a fallback font?

Before:

After:

[mortenpi]

Good catch, although I am not sure what to do with it. I believe you are right about this being a problem with fallback for some glyphs. Could you check what fonts get rendered on your system in the <code> tag?

If you have Chrome, you can check rendered fonts with DevTools (note that it lives under the "Computed" tab and not "Styles" on recent Chrome versions). I get

Roboto Mono—Network resource(737 glyphs)
Liberation Mono—Local file(459 glyphs)
DejaVu Sans Mono—Local file(1 glyph)

and on my system (Ubuntu Linux) the diagram renders fine.

Menlo does not appear to be available on any CDNs and is macOS-specific as far as I can tell (although the font appears to be an open font?). We could have Menlo as one of the fallback fonts (but not primary) to fix this for macs, but ideally we'd have a solution that ensures that it works across all platforms.

Edit: Windows seems to experience the issue too. The fonts I see there are:

Roboto Mono—Network resource(737 glyphs)
Courier New—Local file(459 glyphs)
Segoe UI Symbol—Local file(1 glyph)

[samoconnor]

When I load this page in Chrome and target the inspector on the <code> element it tells me:

Menlo—Local file(1215 glyphs)

It says the style isfont-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, Courier, monospace;

Fontbook tells me that Menlo has 3,157 glyphs while Roboto Mono has 1,042.

I don't understand quite how GitHub's CSS has figured out that Menlo is the superior choice, but it seems to work. Perhaps Documenter.jl can emulate what GitHub is doing?

Either way, given that Menlo has 3x more glyps than Roboto, why not just put Menlo ahead of Roboto in the precedence list?

[samoconnor]

After installing SFMono from /Applications/Utilities/Terminal.app/Contents/Resources/Fonts/, I get this:

SF Mono—Local file(1213 glyphs)
Menlo—Local file(2 glyphs)

Font book says that SF Mono has only 1,437 glyphs.

So, it seems that Menlo has better coverage than SF Mono.

[mortenpi]

GitHub has chosen to use the platform's default monospace font for every platform. SF Mono, Consolas and Liberation Mono are the default monospace fonts for macOS, Windows and Linux, respectively. Documenter tries to have the same look on every platform, hence why we CDN in Roboto Mono etc.

With Menlo being mac-specific, we can't really switch the docs to that. We could have it as one of the fallbacks though, as I said. Maybe even together with SF Mono.

On Linux, DejaVu Sans Mono provides a good Unicode coverage as well without the width issues. But your diagrams would still be broken on Windows (and possibly on other more obscure platforms). Hence the ideal solution would be to CDN in a fallback font with good Unicode coverage, but I haven't found one yet.

[samoconnor]

I'm not sure that I think its a good thing to attempt to use the same font on every platform (the platform vendors often put considerable effort into tuning screen fonts for their platforms). When I write a "```" block in a markdown text, I expect it to be rendered the best way on whatever platform or device or medium the reader is using. It would be disappointing to see a screen font used in a printed book; it would be disappointing to see a high-res font made blury by a low-res screen (when a low-res pixel font would look fine). It is disappointing to have unicode-coverage issues on a platform where built in fonts have excellent coverage.

However, I accept that the goal of Documenter.jl is to use a single font and only fall back when needed.
Perhaps Documenter.jl should check that the glyphs required to render a specific <code> block are present in Roboto and generate use a different tag (<unicodemono>?) with different CSS for blocks that cannot be rendered correctly by Roboto.

Maybe it's possible to do what you are attempting with the right CSS-fu, but it could be that GitHub have tried this and not been successful.

[mortenpi]

I'm not sure that I think its a good thing to attempt to use the same font on every platform (the platform vendors often put considerable effort into tuning screen fonts for their platforms).

That is true to some extent, especially of Apple I think. So in an ideal world you could have font-family: monospace and let the OS decide. Theoretically, the users could also then switch the font themselves if they prefer to use another one.

However, my feeling is that in practice the average user will end up with a sub-par experience, since it is quite opaque how the fallback fonts are decided etc. E.g. this particular example is broken on Windows 10 with default fonts (with the GitHub CSS). And I believe the general consensus is that the default fonts often don't look that great (Apple, as usual, would probably be an exception here).

I would also prefer not to hardcode platform specific stuff into Documenter -- the platform default fonts change relatively often. GitHub can easily keep their CSS up to date as things change, but that is not really possible with Documenter. The docs rendered today should look decent in a few years time as well.

Perhaps Documenter.jl should check that the glyphs required to render a specific <code> block are present in Roboto and generate use a different tag (<unicodemono>?) with different CSS for blocks that cannot be rendered correctly by Roboto.

This feels like a lot of work for relatively little gain. The fallback fonts should be doing that already anyway. Also, what should that different CSS be?

All that said, modifying the fallback fonts would be OK, including having platform-specific fallbacks. The current Monaco, courier is a bit arbitrary anyway.

[samoconnor]

Given that the vendor agrees that Roboto is defective it seems backwards to have Menlo as a "fallback" for Roboto. If Menlo is correct for a larger set of inputs, then Roboto should be the fallback for Menlo (and Consolas ?).
I would argue that Documenter.jl should order the font fallback list:

• First in order of character coverage and correctness of rendering,
• Second in order of the aesthetic preference of the Documenter.jl team.

I would also prefer not to hardcode platform specific stuff into Documenter

That is reasonable, but Menlo is not really "platform specific stuff", Menlo is based upon the Open Source font Bitstream Vera and the public domain font Deja Vu. Putting "platforms" aside, if Menlo more fit for purpose it should come before Roboto in the font list.

[mortenpi]

It's not a matter of aesthetics but cross-platform consistency. If we could CDN in a font with better Unicode coverage, that would be great.

By the way, considering that your case is a bit of an edge case (you're using symbols that you usually would not have in code), you can fix it in your own repo by overriding the font settings using a custom CSS file and the assets keyword to makedocs (see end of HTMLWriter). It already works on Linux (or at least Ubuntu) and putting Menlo first would fix it for macOS. Windows would remain broken since Consolas/Courier/Lucida do not cover those symbols as far as I can tell.

[clarkevans]

Can this be configurable then? I also have unicode text, produced from UnicodePlots.jl that does not present well.

[mortenpi]

You should be able to pass a custom.css via the assets keyword to makedocs where you can override the font hierarchy we define in documenter.css. There's a bit of documentation here.

[samoconnor]

GitHub has chosen to use the platform's default monospace font for every platform.

Why can't Documenter.jl just do this?

What purpose is served by a design predicated on having a good cross platform font when such a font does not seem to exist?

[mortenpi]

Well, the current font system works well for most use cases as far as I can tell. Having complex unicode output is pretty much an edge case. On the other hand, trying to figure out good font combinations for all the platforms times the fact that the platform default fonts seem to change like yearly means quite a bit of extra continous maintanance work.

We could try making configuring this easier to help with these edge cases, so suggestions in that direction would definitely be welcome.

[samoconnor]

... trying to figure out good font combinations for all the platforms

Copy/paste the font-family from github?

... the platform default fonts seem to change like yearly means quite a bit of extra continous maintanance work

But last-year's default does not, like, disappear, so there is no need to make continuous changes. e.g. macOS has all the old default fixed width terminal fonts installed going back to 1983 (Monaco)

[ssfrr]

There are some more issues with Roboto Mono (at least on my Ubuntu machine with Firefox). Bold characters seem to be rendered slightly wider than non-bold. As an example, the code block here looks like this on my machine:

Notice that the lines with bold text cause the comments after to be mis-aligned.

Some unicode characters also seem to be too wide, which affects the plots made with UnicodePlots that are part of the DSP.jl window documentation, which look like this:

On my machine DejaVu Sans Mono doesn't seem to have this issue, though I recognize that there are lot of other factors to font selection, so this is just one data point. On Chrome I don't see the issue with bold text, but the unicode plot is still messed up.

[ssfrr]

More bad Roboto Mono, from Query.jl docs:

[mortenpi]

Here is a small page to test various font declaration options: http://mortenpi.eu/gsoc2019-mockups/fonts/

@samoconnor Could you by any chance see if any of those setups fix the issue for you? I am mainly curious to see if having Roboto Mono before the Apple fonts breaks anything.

Just something I observed -- not only is this OS-dependent, but also Chrome seems to be worse at rendering monospace correctly sometimes. Even though they pick the same fonts, Chome fails to render it correctly, while Firefox does. Unless it's due to Google Fonts serving slightly different Roboto Mono fonts to the different browsers.

[ssfrr]

Awesome test page. Here's what I get (on my Ubuntu machine):

Firefox:

• monospace - ✔️
• Roboto Mono, monospace - lines
• Roboto Mono, system fallbacks, monospace - lines, blocks
• system fallbacks, monospace - lines, blocks
• Roboto/Monaco/Courier/monospace - asciilines

Chrome:

• monospace - lines
• Roboto Mono, monospace - unaligned, lines
• Roboto Mono, system fallbacks, monospace - lines, blocks
• system fallbacks, monospace - lines, blocks
• Roboto/Monaco/Courier/monospace - aciilines

key:

• ✔️ - everything looks good
• blocks - blocks in the graph have some slight variation in their vertical level
• lines - some slight unevenness in the unicode line weight, not a big deal
• asciilines - unicode lines look like ASCII lines (they show up dashed instead of continuous, not a big deal)
• unaligned - characters are unaligned

[KristofferC]

On safari, the only one that looks perfect is system fallbacks, monospace.

[clarkevans]

On the iPhone, which is useful for reading on-line documentation, none of the permutations work well. It seems to be that the space character is significantly shorter than the others.

[mortenpi]

@KristofferC What issues do you see with Roboto Mono, system fallbacks, monospace;?

Another data point: on Android 8.1 / Chrome all options are broken.

[KristofferC]

@KristofferC What issues do you see with Roboto Mono, system fallbacks, monospace;?

It is pretty ok but not perfect, see the lines to the right:

[bkamins]

In 0.25 release under Win10 there is a similar problem when displaying DataFrames:

(on Linux it is OK)