Bug 261104 - new handbook website format, multiple problems
Summary: new handbook website format, multiple problems
Status: In Progress
Alias: None
Product: Documentation
Classification: Unclassified
Component: Website (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Many People
Assignee: Sergio Carlavilla Delgado
URL:
Keywords: accessibility
Depends on:
Blocks:
 
Reported: 2022-01-11 12:46 UTC by Bob Frazier
Modified: 2022-01-29 22:02 UTC (History)
3 users (show)

See Also:


Attachments
appearance with script enabled (130.53 KB, image/jpeg)
2022-01-11 12:47 UTC, Bob Frazier
no flags Details
appearance with script disabled (155.33 KB, image/jpeg)
2022-01-11 12:48 UTC, Bob Frazier
no flags Details
appearance reader mode (99.21 KB, image/jpeg)
2022-01-11 12:49 UTC, Bob Frazier
no flags Details

Note You need to log in before you can comment on or make changes to this bug.
Description Bob Frazier 2022-01-11 12:46:31 UTC
Viewing http://freebsd.org/handbook with Firefox 93.0

uname: FreeBSD 12.2-STABLE r370671 GENERIC  amd64
package:  firefox-93.0_1,2

Multiple problems with new handbook layout

a) styles such as "fa-pencil-square-o" uses non-existent UTF-8 character F044 which renders as a box with hex values rather than an actual font.  Also F015 and F105 used by fa-angle-right and fa-home are similar. If these UTF-8 characters are to be used in the content, an appropriate web font will also need to be selected and loaded in the HEAD section.

b) use of script is most likely a bad idea.  However, without script enabled, the pages still "functions" but is actually easier to read since the fonts are not gray. However, the logo banner is missing.

c) FreeBSD logo is 2-color which is inconsistent with the main page.  It should at least match the main page for consistent appearance.  The flat-look is also inferior to a proper 3d skeuomorphic icon like is seen on the main freebsd.org page.

d) font size in left panel is too small to read, and inconsistent with the main text.  When zooming out to 150%, the left panel becomes readable, but the text is too large (and requires more screen scrolling)

e) the scrollbar in the left panel is inconsistent with the system theme.  Where it always seems to have an (inferior) 'Adwaita' appearance, it is also too thin to use properly.  It should have a scrollbar that matches the system theme.  This might be doable using a scrollable table with 'overflow:auto' and 'display:inline-block' styles and fixed height that would then apply the correct system appearance and width to the scroll bar.

f) the left panel cannot be re-sized.  As a result, you get inconsistent appearance when script is enabled, and the text tends to wrap.

g) the "light" theme uses grey fonts that make them harder to read.  it should use a black font or have an alternative that uses a black font instead of grey.  The dark and high contrast themes both have dark background, meaning that if you want a consistent light background you are stuck with a hard to read font.

h) an option to use the old format should be available (I prefer it, easier to use for me).  To get the same effect I did attempt to use 'reader' mode in Firefox, which appears to be supported by the handbook pages; however, the overall appearance wasted a lot of screen real estate (see attachment)

(attaching screen shots, one with script, one without, one in reader mode)
Comment 1 Bob Frazier 2022-01-11 12:47:59 UTC
Created attachment 230899 [details]
appearance with script enabled
Comment 2 Bob Frazier 2022-01-11 12:48:44 UTC
Created attachment 230900 [details]
appearance with script disabled
Comment 3 Bob Frazier 2022-01-11 12:49:25 UTC
Created attachment 230901 [details]
appearance reader mode
Comment 4 Graham Perrin freebsd_committer freebsd_triage 2022-01-11 18:45:23 UTC
> Component: Website

(In reply to Bob Frazier from comment #0)

a) styles such as "fa-pencil-square-o" uses non-existent UTF-8 character F044 which renders as a box with hex values rather than an actual font.  Also F015 and F105 used by fa-angle-right and fa-home are similar. If these UTF-8 characters are to be used in the content, an appropriate web font will also need to be selected and loaded in the HEAD section.

At a glance, that might be bug 260821. 

> Component: Documentation
Comment 5 Graham Perrin freebsd_committer freebsd_triage 2022-01-11 18:54:35 UTC
(In reply to Bob Frazier from comment #0)

> d) font size in left panel is too small to read, and …

> g) the "light" theme uses grey fonts that make them harder to read. …

Cross-reference <https://forums.freebsd.org/posts/550750>
Comment 6 Graham Perrin freebsd_committer freebsd_triage 2022-01-11 19:01:44 UTC
(In reply to Bob Frazier from comment #0)

> f) the left panel cannot be re-sized. …

<https://forums.freebsd.org/posts/548999> and subsequent posts may be of interest. The screenshot at <https://forums.freebsd.org/posts/550332> is a relatively extreme example.
Comment 7 Bob Frazier 2022-01-11 19:18:03 UTC
(In reply to Graham Perrin from comment #4)

thanks, I made a reference to that bug.  also those discussion pages that others have posted are interesting too (I am having a look at those as well)

If the use of specialty UTF-8 characters is the best way to go, the solution very well might be the use of various font parameters in the style sheet.

example style stuff:

@charset "UTF-8";

/* default font */
@font-face
{
 font-family: TheHandbookFont;
 src: url(the-handbook-font.woff);
}
fa-pencil-square-o
{
  font-family: 'TheHandbookFont';
}

(or similar)

people more knowledgeable about style sheets might have better ways, but this would probably work (changing font family name and URL as needed)
Comment 8 Pau Amma 2022-01-12 19:11:26 UTC
(In reply to Bob Frazier from comment #7)
I don't understand CSS very well, and overriding webpage font choices in the browser not at all, but someone overriding them usually does that for accessibility reasons (eg, I think users with dyslexia find some fonts work better for them than the webpage choices, so my first question is: would changing the font in CSS break those overrides?
Comment 9 Bob Frazier 2022-01-12 19:33:30 UTC
(In reply to PauAmma from comment #8)

yeah in my example I was assigning the default font for the page.  But if you only assign the font-family for the elements in question, I would expect the behavior for everything else to remain the same.  Good point, though.
Comment 10 commit-hook freebsd_committer freebsd_triage 2022-01-14 22:25:56 UTC
A commit in branch main references this bug:

URL: https://cgit.FreeBSD.org/doc/commit/?id=a45595f3504b17f13a39b4aefebdcc805ad7c0c4

commit a45595f3504b17f13a39b4aefebdcc805ad7c0c4
Author:     Sergio Carlavilla Delgado <carlavilla@FreeBSD.org>
AuthorDate: 2022-01-14 22:20:14 +0000
Commit:     Sergio Carlavilla Delgado <carlavilla@FreeBSD.org>
CommitDate: 2022-01-14 22:20:14 +0000

    Add 'fa' class to fix Font Awesome icons problem

    PR:             261104, 260821
    Submitted by:   Bob Frazier <bobf (AT) mrp3.com>, Graham Perrin <grahamperrin (AT) gmail.com>

 documentation/themes/beastie/assets/styles/global.scss | 5 +++++
 1 file changed, 5 insertions(+)
Comment 11 Sergio Carlavilla Delgado freebsd_committer freebsd_triage 2022-01-14 23:05:55 UTC
Fixed the problem with the icons.
I'll improve the page to users without Javascript enabled.
Comment 12 commit-hook freebsd_committer freebsd_triage 2022-01-29 22:02:57 UTC
A commit in branch main references this bug:

URL: https://cgit.FreeBSD.org/doc/commit/?id=d62340217c0187f57b600a14e35254c0fcac2ee2

commit d62340217c0187f57b600a14e35254c0fcac2ee2
Author:     Sergio Carlavilla Delgado <carlavilla@FreeBSD.org>
AuthorDate: 2022-01-29 21:58:18 +0000
Commit:     Sergio Carlavilla Delgado <carlavilla@FreeBSD.org>
CommitDate: 2022-01-29 21:58:18 +0000

    Improve the website for browsers without Javascript enabled

    Apply the light theme by default and then change it to the
    theme selected by the user. This will allow users with a browser
    with Javascript disabled use the Documentation Portal.

    Also hide the theme chooser since it uses Javascript to change
    the theme. In the future the property prefers-color-scheme
    will be used to change the theme automatically to use the
    browser theme.

    PR:             261104
    Submitted by:   Bob Frazier <bobf (AT) mrp3.com>

 documentation/themes/beastie/assets/js/theme-chooser.js   | 6 ++++--
 documentation/themes/beastie/assets/styles/footer.scss    | 1 +
 documentation/themes/beastie/layouts/_default/baseof.html | 2 +-
 3 files changed, 6 insertions(+), 3 deletions(-)