Bug 8180 - Incorrect fonts in TAG
Summary: Incorrect fonts in TAG
Alias: None
Product: ThinLinc
Classification: Unclassified
Component: Documentation (show other bugs)
Version: trunk
Hardware: Other Other
: P2 Normal
Target Milestone: 4.15.0
Assignee: Tobias
Keywords: relnotes, samuel_tester
Depends on:
Blocks: 7910
  Show dependency treegraph
Reported: 2023-07-04 12:48 CEST by Tobias
Modified: 2023-07-13 16:48 CEST (History)
1 user (show)

See Also:
Acceptance Criteria:
The following should apply to both HTML and PDF versions MUST: * Font families consistent with other ThinLinc web services * Good readability in terms of font sizes and general separation of text


Description Tobias cendio 2023-07-04 12:48:41 CEST
We'd like to use the font families Mulish, Poppins, and Space Mono, in certain fashions.

Generally, Mulish is designated for body text, Poppins for headers, and Space Mono where monospace is appropriate such as code.
Comment 1 Tobias cendio 2023-07-05 14:12:54 CEST
In order to make use of our own fonts of choice in the Sphinx framework, we must identify the relevant CSS selectors with associated font-family attributes, and override them in our cendio.css. These turn out to be

(1)  body
(2)  div.body h1-6
(3)  div.sphinxsidebar h1-6
(4)  div.sphinxsidebar input
(5)  div.admonition p.admonition-title
(6)  p.caption
(7)  .guilabel
(8)  .menuselection
(9) .sig
(10) .sig-inline.c-texpr
(11) .sig-inline.cpp-texpr
(12) .viewcode-back
(13) tt

where (1) sets the overall default Mulish, and (2)-(8) and (9)-(13) are Poppins and monospace contexts, respectively. Note that selectors (10)-(13) are currently not in use in the TAG, but should still be included so that they're not missed in the future.
Comment 4 Tobias cendio 2023-07-05 15:37:31 CEST
The vast majority of the text should have its proper font now. However, there are certain instances of imprecise selectors that essentially function as headers that should be Poppins, but currently exhibit Mulish; see e.g. the page on Client Touch Gestures. 

Perhaps these selectors can stem from the unique section ids, since ultimately there shouldn't be too many.
Comment 5 Tobias cendio 2023-07-06 11:52:50 CEST
Touching upon comment 4, a separate bug (bug 8182) has been broken out to encompass the greater problem of how to consistently present and emphasize a set of features. That being said, the current state of how fonts are applied is fine, in that mentioning of general features retains Mulish while GUI-features exhibit Poppins.

However, the PDF version hasn't been treated at all with the new fonts so the claim that most fonts are fine by now only applies to the HTML version.
Comment 6 Pierre Ossman cendio 2023-07-10 13:46:48 CEST
Font handling in rst2pdf seems to be a bit hacky, but I think I've got something that seems to work.

There are a few options on how to provide the font files for it. You can explicitly list where the files are, or you can put it in a specific directory, or it can find them via fontconfig.

We'll like need the fonts to generate other things at some point, so we might as well put everything in the build environment.

rst2pdf seems to assume that every variant of a font (Bold, Italic, etc.) is its own file, so it gets confused by the variable weight version we have of Mulish. It seems like we'll need to package classical files for that as well.

rst2pdf also doesn't seem to have much flexibility when it comes to font weight. It just seems to cater to "Regular" and "Bold". Still, if I specify "Poppins-Semibold" it seems to find the correct font just fine.

I also tested the broken ligatures with Space Mono, and they do not show up. Maybe rst2pdf doesn't support ligatures at all?
Comment 7 Pierre Ossman cendio 2023-07-10 14:15:39 CEST
Some of our images also use text, and the font they get is a bit random.

These images need to be redone in the new style anyway, so I'm ignoring the font issue for those for now. They look decent enough next to everything else.
Comment 8 Pierre Ossman cendio 2023-07-10 15:37:38 CEST
It doesn't seem to be possible to easily style headers or footers. rst2pdf generates a sole "Paragraph" object for these with the style "bodytext". There are "header" and "footer" classes defined in the default rst2pdf style sheet, but it seems these aren't used. :/

I've reported this issue upstream:

Comment 13 Pierre Ossman cendio 2023-07-11 10:50:44 CEST
With the PDF updated, things should now be done:

> * Font families consistent with other ThinLinc web services

Both PDF and HTML versions use our three fonts in a way that looks consistent with Web Access, Web Admin and our homepage.

There are a few minor things mentioned in earlier comments that we weren't able to fix right now, though.

> * Good readability in terms of font sizes and general separation of text

The HTML version already had a good font size and line height, so nothing to fix there. The PDF text is a bit small, but it's a lot of work to fix so it has been moved to bug 8186.
Comment 14 Pierre Ossman cendio 2023-07-11 14:49:20 CEST
Found a bug. In the chapter dealing with make-dummy-cert (page 70), the arrow symbol doesn't render correctly in the PDF.
Comment 17 Pierre Ossman cendio 2023-07-11 15:42:48 CEST
New replacement character in place that should hopefully be more robust.
Comment 18 Samuel Mannehed cendio 2023-07-13 16:48:54 CEST
Nice! In general, I think this brings a big improvement to how the TAG looks and feels. 

I tested both the HTML and PDF versions from build 3320 hosted on cendio.com/resources/docs/tag-devel. I only tested in Google Chrome on Fedora 38 since I don't believe there are many differences between platforms and browsers in this area.

Using the web inspector in Chrome, I verified our fonts were used correctly on the HTML version:

 ✓ Poppins:
   ✓ Headers and sub headers (*)
   ✓ Figure text labels (**)
   ✓ GUI element labels
 ✓ Space Mono
   ✓ Commands
   ✓ Configuration examples
   ✓ Lists of ciphers
   ✓ Code examples
 ✓ Mulish
   ✓ Text body

(*) Minor inconsistencies regarding some sub headers, but this was addressed in comment 5.
(**) Fits us since we use these figure texts like headers/labels.

For the PDF version, I know of no way to inspect what font is being used, so the test was more visual and less precise. I attempted to check the same things, however.

Acceptance criteria look sane and fulfilled when the aforementioned caveats are considered.

I looked through the discussion here in bugzilla, and the commits made on the topic. No further issues were found aside from those mentioned in previous comments. Decisions and exceptions are well documented.

Looks good. Closing.

Note You need to log in before you can comment on or make changes to this bug.