CSS for generated HTML uses Unicode Private Use Area characters, makes ugly boxes

[erlehmann]

I.e. I have ugly boxes for warning messages, see screenshot: https://mister-muffin.de/p/ShP2.png

Solution: Use appropriate Unicode characters here. Which ones would that be?

[benrob0329]

AsciiDoctor uses Fontawesome for font-based Admonition icons. The alternative is to dip into the emoji glyphs, but that would look worse IMO. I'm willing to explore options, though terminal browsers aren't our intended target. You should be able to install Fontawesome and have those glyphs show up though, BTW.

[erlehmann]

The alternative is to dip into the emoji glyphs, but that would look worse IMO.

Why would using standard unicode codepoints instead of private use area codepoints “look worse”?

I'm willing to explore options, though terminal browsers aren't our intended target.

My screenshot is not from a terminal browser, but from Firefox.

Making plain text web sites not work in specific browsers because it “looks works” would be bad web design.

[benrob0329]

So you disabled fonts and changed a lot of CSS but expect it to look right, and it's the fault of our system if it doesn't? The website "works" fine, but we use fonts for certain icons. Expecting basic font support is not a high bar whatsoever.

And yeah, if all you see are glyph boxes then yes, emoji would look better, but for the rest of us it's generally a subpar option. This isn't a "plain text" website, it's a rich text website. We're going to be using graphs and visual aids too in the future if it helps make the documentation clearer, and I don't expect those to work with the default HTML output either given your extremely stripped down config.

[erlehmann]

So you disabled fonts and changed a lot of CSS but expect it to look right, and it's the fault of our system if it doesn't?

I did not disable anything. In fact, my default font is GNU Unifont, which should be enough for any but the most recent Unicode characters. I do not know why the font does not load on my system, but obviously it does not and depending on a single font to load instead of making it work with a bunch of fonts seems to be easily fixable.

The website "works" fine, but we use fonts for certain icons. Expecting basic font support is not a high bar whatsoever.

I have done my share of web development over the years and know how icon fonts work. I have drawn emoji myself. Relying on a specific font to have an icon in the PUA is a common rookie mistake; the reason is almost always an inability or unwillingness to use something else than the initially chosen icon font that has the glyphs at the wrong codepoint. I will try to figure out how to fix it, to make the output more robust and accessible.

We're going to be using graphs and visual aids too in the future if it helps make the documentation clearer, and I don't expect those to work with the default HTML output either given your extremely stripped down config.

The following web page I have made contains graphs, interactive elements, and animations – all made with basic HTML and SVG (no JS). It works fine on my “extremely stripped down config”: http://dating.dieweltistgarnichtso.net/

[benrob0329]

I'm sorry, I got a bit frustrated there. You have tweaked the CSS, no? I suppose that I can dig around the standard Unicode glyph space and find some standard font icons. Although Fontawesome isn't uncommon nowadays, you are correct that it increases the accessibility of our documentation if we use something more standard.

EDIT: Looks like we have a couple options:

We can either set something like this:

:tip-caption: ⓘ
:note-caption: 📋
:important-caption: ❗
:caution-caption: ⚠
:warning-caption: ⛔

Which doesn't look all that great IMO, or we can change the CSS when we get around to making our own output theme so that the Admonitions have their own CSS class, which is better IMO. Image-based icons are an option too, but I'd prefer not to use those if we don't have to.

[appgurueu]

I say out of scope and won't fix since this is not an issue with what we currently have in this repo - the adoc sources - but rather the tooling surrounding them and a default configuration apparently not suiting you. We'll have to figure this out once we set up a website, but it's still a long way to go until there - see the Lua API coverage mega tracker - and as such this issue is currently a non-issue regarding this repo.