Inconsistent font in example generation

[sclu1034]

The font used in the theme for examples is not properly fixed to a specific value, which can lead to inconsistent text dimensions:

Current API doc for master:

My local version:

Currently, the font is set to sans 8, which will vary between developer systems based on what their preferred font is (e.g. Noto Sans in my example above). It may even change in CI if something there decides to switch default fonts.

So the question is: Which font do we want to fix this to?

[Aire-One]

This raise a fair point. The documentation NEEDS to be 100% "reproducible" regardless of the system used to build it.

I guess we don't need to force the font used for text in the HTML pages (this is insane). We should focus only on the font used by generated images.
As you suggested, to force the generated images to use the same font, we need to choose one, and make the images' generators to always use it. It means we need to add a new (optional (as build the doc is optional)) dependency for this specific font, and force the use of this font in examples template images' generators.

I'm favorable to use Noto. The screenshot you provided looks good, and it's popular on the web (and it's what I use as my default font, me too 🙃 ). Also, according to Wikipedia:

Some projects provide a package for installing Noto fonts, e.g. Debian,[23] Arch Linux,[24] Gentoo Linux,[25] CTAN.[26] Since version 6.0, LibreOffice bundles Noto.[27]

https://en.wikipedia.org/wiki/Noto_fonts#Usage

[actionless]

I guess we don't need to force the font used for text in the HTML pages (this is insane). We should focus only on the font used by generated images.

this will make locally generated documentation not consistent in font for text and images

the only way is to force both, mb optionally and enable that option only for generating website, but not in local build

[sclu1034]

Truly forcing a font for a web page is impossible. Firefox has a built-in option to prevent that, and userstyles can override font-family in any browser.

And I haven't seen a place in the doc's text where typesetting and font width matter. It's only the generated example images that break with different fonts.

I think it would be enough to use the common font-family: <preferred_font>[, <optional_fallbacks>], sans-serif;, without serving <preferred_font> via @font-face, and adding <preferred_font> to the list of optional build dependencies.
That way, everyone who has <preferred_font> installed sees the docs with that font, but we're not forcing users away from their favourite browsing font.

[actionless]

that just make zero sense:

for example, userstyles are quite a hack to be a concern for any of front end developers

and more you go, less logical it is - uninstalling the whole font from the system not the most convenient way to opt out from some style options for a user

[Aire-One]

I guess we don't need to force the font used for text in the HTML pages (this is insane). We should focus only on the font used by generated images.

this will make locally generated documentation not consistent in font for text and images

the only way is to force both, mb optionally and enable that option only for generating website, but not in local build

I don't see the text font as an issue. We can't control what font will be used by the browser to display text. That's why I dismissed it. Do we really need it to be the same as the one used in generated images?
What about code blocks? They should use a monospaced font. It will be different from the rest. (And titles/links/buttons probably also have different font/properties?)

Hmm.... You actually may be right 🤷. All the font used should "look alike"... Even for code blocks, we have to use a monospaced variant of the same font.

It shouldn't cost too much to revisit the CSS rules for fonts.

I think it would be enough to use the common font-family: <preferred_font>[, <optional_fallbacks>], sans-serif;, without serving <preferred_font> via @font-face, and adding <preferred_font> to the list of optional build dependencies.

I mostly agree with this.

I don't see why we should add the preferred font as an optional dependency, tho. Even for local use, the doc is served as a website, so we have to stick to "serving a website rules". It doesn't make sense to force the server to have the font, only the client matter here, and we can't control it with our dependencies.
(However, we agree that the font used to generate images should be an optional build dependency)

I also don't see what's wrong with @font-face. Can you elaborate? If it's about minimalism or user customization, I think we don't care, people doing that already have their rules disabled, so they are out of the scope anyway.

[actionless]

We can't control what font will be used by the browser to display text.

we can control it in site style, but if user purposely chosen to override some of the styles - we should respect that choice and not thinking of possible ways to force it

my main point what introducing hardcoded font instead of 'sans' will make image preview in local awesome build to use some boring font instead of godsent Fantasque Sans Mono, which is not acceptable to me (and as you can see on preview, in case of local build both fonts in preview and text are the same:

thats why hardcoding font for docs (which should happen for both generated images and text styles) should be optional and enabled by default only for generating pages under https://awesomewm.org/doc/

[sclu1034]

I guess this issue got sidetracked on "consistency between HTML content and SVG images", which is not what it is about. The problem described in the initial message is the fact that the font used to generate example images is inconsistent between different machines (e.g. CI vs. developer machine).

Whoever wrote that example for awful.tag.new likely used a font with similar geometry to Noto. They adjusted the example to look nice and proper in their local builds, then pushed the changes.
However, because the CI uses a different font, users now see a broken version of that example, where text is cut off due to a higher cell width and characters are partially covered by widget borders. And you can see the same issue in actionless' screenshot. That illustration was designed with a variable-width font, but is now built with a monospaced font, so text ends up being cut off.

Hardcoding the font in the examples theme does take away some customization options for a person working with a local build, but that same customization can be achieved by applying a simple, short patch before installation.
But as long as the font is not hardcoded and every contributor creates examples based on their own font geometries, broken images like the ones shown here would continue to happen and would require more effort to find and prevent.

[actionless]

still non convinced what adding new font as a dep for awesome is better than learning cmake options

as you've got into offtopic regarding those boxes in the docs - i think it would be better to reuse awful.tooltip or textbox.compute_text_width + margin size instead of hardcoding the sizes at first place

[sclu1034]

still non convinced what adding new font as a dep for awesome is better than learning cmake options

The point of the issue is that everyone working on an example for the documentation should build it with the same, pre-defined font to ensure consistency and prevent the issues presented.
And this "everyone working on [it]" makes it a development-only dependency, just like asciidoctor, ldoc or busted, that are already listed on the "Building and testing" page. Pre-built packages would not need to list this dependency.

And there is no "either font or cmake option". Those two things are independent of each other.
The reason why I think it should not be easily configurable is the fact that the possibility of someone building an example while using a custom font puts additional burden on the reviewers, who, in the worst case, would need to build every example themselves to make sure it looks fine with the desired font. And that would defeat the whole purpose of making it a fixed font.

as you've got into offtopic regarding those boxes in the docs

On the contrary, that was quite on-topic, given that those tooltips exhibit the exact same issue that I illustrated in the opening message.