Improvements to the visual appearance of the tutorial

[MateuszKowalewski]

In addition to changing the theme colors to some more pleasing defaults, this fixes some layout issues such as the displaced anchor icons and especially the non-scrollable sidebar.

Also, the typography should now be consistent across systems - although this comes at the cost of heavy use of currently unoptimized web fonts.

The main motivation to look into this was the completely broken box drawing of the diagrams on my machine.

Now the rendering depends only on the fonts that are also included as static resources. Having all resources bundled so the tutorial site doesn't make any external request will also help with making the documentation usable in an offline context, which is imho important. (Also this stops the privacy hostile and unnecessary user tracking by Google through their fonts API.)

The next step would be to optimize the font loading with a custom made font which would include only the necessary glyphs. But getting rid of the layout bugs has imho priority so I'm submitting this in this state. Making the site more lightweight should be independent of making it usable in the first place.

[TomasMikula]

Oh wow, I haven't realized the diagrams could appear that garbled on someone else's computer.

Thanks!

[MateuszKowalewski]

Oh wow, I haven't realized the diagrams could appear that garbled on someone else's computer.

You've identified the issue already once: The missing fallback to a monospace font for the --code-font in the theme will make the browser use it's default font, which isn't usually monospace. But the previous "fix" doesn't work really (besides maybe on Macs). It still didn't specify a fallback. (And Menlo is anyway only available on Macs, and can't be redistributed).

Now all fonts are fixed to the ones delivered as web fonts. (But won't load if they're installed already locally.)

This isn't ideal either still because almost no glyphs form the big font files are used. The 5MB emoji font is there only to provide one (!) glyph… (At least it will look now everywhere the same, and this font is at least installed on quite some machines; I guess not Macs, but elsewhere). The 1MB font is there only to have a reasonably looking "lollipop"… (This was actually quite adventurous: There are almost no monospace fonts that include the "lollipop tip". On my machine it fell back to GNU Freefont, which I've never head of before, as not even my std. monospace font DejaVu has this glyph—even it's one of the most complete Unicode fonts out there). I've decided than to us JuliaMono, the only other monospace font with this glyph for the "lollipop tip" I could find. It aligns better with the other monospace font used, and is actually substantially smaller than the (even more complete) Freefont.

In case I find motivation to fiddle even more with that I maybe minimize the fonts, and extract the two (+ 1 bold) glyphs from DejaVu Sans, the one glyph from JuliaMono, and the one emoij. This would reduced the font size to some reasonable dimension. But this should be a build step as it could be otherwise quite confusing in case new Unicode signs are used but not included in manually minimized font files.

So for now the big font files will stay I guess. Not a big deal I think. And for off-line use it makes no difference anyway.

In the long run I think it would make sense to switch to some more sophisticated and complete documentation solution. But I think there are currently still much more pressing issues open. Thank you once more for creating Libretto! :smiley:

[TomasMikula]

The updated version is now up: https://continuously.dev/libretto/docs/latest/tutorial/basics.html

I think it's time I put some effort into generating the diagrams directly from Libretto code. It would be one less thing to take care of in fonts. Plus it would save me a lot of time whenever I am preparing slides on Libretto.

Anyway, thanks again for putting effort into this!

[MateuszKowalewski]

Anyway, thanks again for putting effort into this!

It's imho important that the docs look reasonable. This is the first impression people get form a project. If the docs look broken many won't even look closer. Sad but true.

I had this fixes already for some time as a local style and thought I should contribute them.

As I'm looking more into Libretto I really wish that it succeeds and gets great! This is the first time since long that FP makes again sens to me. Functional programming, and even actually computers as such, was always in my head conceptually "little machines with ports which you can wire up". Libretto seems to model exactly this. But finally in a sane looking way.

I want to connect components ("pure functions") into bigger systems, and not fight monads constantly.

I want to process streams of event-data, and not wrap and unwrap just single elements the whole time.

I want my wired up system to be checked by the compiler for sanity.

Libretto looks like the only reasonable solution at the moment. I think you're in the process of inventing the future of functional programming! I see some massive potential!

Would be actually cool if you could create some tickets that could be picked up even by early adopters prior to having all the documentation available. I can do the usual stuff. Only with the design of Libretto I could likely not help at the moment. But I like to try it out from the perspective of an end-user; please see the GitHub Discussions I've opened.

[TomasMikula]

Thanks for the encouraging words! And thanks for opening the discussions! It's great that you came up with a potential use case (safe Netty alternative). We can iterate on that and you will get a better idea about Libretto, while for me it can generate some feedback and pain points to focus on.