[RFC,RESEND,0/4] Documentation: Web fonts for kernel documentation

  [resend from previous RFC [4] with correct linux-doc address]

Intro
=====

The Linux kernel documentation is primarily composed of text (both
prose and code snippets) and a few images. Hence, making the text
easy to read by proper typography choices is crucial.

The problem
===========

Currently, the kernel docs uses system-default serif fonts, as in
Documentation/conf.py:

```
...
if  html_theme == 'alabaster':
    html_theme_options = {
        'description': get_cline_version(),
        'page_width': '65em',
        'sidebar_width': '15em',
        'fixed_sidebar': 'true',
        'font_size': 'inherit',
        'font_family': 'serif',
    }
...
```

The problem is depending on the serif font selected by system, the docs
text (especially long passages) can be hard and uncomfortable to read.
For developers reading the docs on multiple devices, the apparence may
look inconsistent.

The solution
============

Uniform the font choices by leveraging web fonts. Most of people reading
the kernel docs should already have modern browser that supports this
feature (e.g. Chrome/Chromium and Firefox). The fonts are downloaded
automatically when loading the page, but only if the reader don't
already have ones installed locally. Subsequent docs page loading will
use the browser cache to retrieve the fonts. If for some reasons the
fonts fail to load, the browser will fall back to fallback fonts
commonly seen on other sites.

For the font choices, we settle down on IBM Plex Sans (sans-serif), IBM
Plex Mono (monospace), and Newsreader (serif). All these fonts are
licensed under OFL 1.1 and can be distributed alongside the kernel docs.
We have also considered to use Söhne [1] instead, but because it is paid
font, it is concluded that such font is non-free [2] (and by
implication, distributions must patch the kernel to not use it).

The fonts selected are downloaded from Google Fonts directory [3]. As
the font files are in .ttf format, these are compressed first into
.woff2 format (just like other sites that use web fonts do) using
`woff2_compress` program from `woff2` Debian package. These converted
files are then referenced in Documentation/sphinx-static/fonts.css via
`@font-face` directive and the appropriate `font-family` rule selects
that font.

Note that only necessary styles (regular, bold, italic, and bold-italic)
are included and used. For Newsreader, use the classic 14 pt static font
instead of variable variant for compatibility with older browsers.

Scope
=====

Only the main documentation and translations in languages using Latin
script (Italian and Spanish) are covered.

[1]: https://klim.co.nz/retail-fonts/soehne/
[2]: https://lists.debian.org/debian-legal/2023/06/msg00005.html
[3]: https://fonts.google.com
[4]: https://lore.kernel.org/all/20231102120053.30630-1-bagasdotme@gmail.com/

Bagas Sanjaya (4):
  LICENSES: Add SIL Open Font License 1.1
  Docmentation: Use IBM Plex Sans for page body
  Documentation: Use Newsreader font for document headings
  Documentation: Use IBM Plex Mono as monospace font

 Documentation/conf.py                         |   4 +
 .../sphinx-static/IBMPlexMono-Bold.woff2      | Bin 0 -> 39984 bytes
 .../IBMPlexMono-BoldItalic.woff2              | Bin 0 -> 43816 bytes
 .../sphinx-static/IBMPlexMono-Italic.woff2    | Bin 0 -> 43236 bytes
 .../sphinx-static/IBMPlexMono-Regular.woff2   | Bin 0 -> 38740 bytes
 .../sphinx-static/IBMPlexSans-Bold.woff2      | Bin 0 -> 55412 bytes
 .../IBMPlexSans-BoldItalic.woff2              | Bin 0 -> 59112 bytes
 .../sphinx-static/IBMPlexSans-Italic.woff2    | Bin 0 -> 59468 bytes
 .../sphinx-static/IBMPlexSans-Regular.woff2   | Bin 0 -> 55380 bytes
 .../sphinx-static/Newsreader_14pt-Bold.woff2  | Bin 0 -> 44512 bytes
 .../Newsreader_14pt-BoldItalic.woff2          | Bin 0 -> 48152 bytes
 .../Newsreader_14pt-Italic.woff2              | Bin 0 -> 44864 bytes
 .../Newsreader_14pt-Regular.woff2             | Bin 0 -> 41212 bytes
 Documentation/sphinx-static/fonts.css         | 157 ++++++++++++++++++
 LICENSES/dual/OFL-1.1                         | 107 ++++++++++++
 15 files changed, 268 insertions(+)
 create mode 100644 Documentation/sphinx-static/IBMPlexMono-Bold.woff2
 create mode 100644 Documentation/sphinx-static/IBMPlexMono-BoldItalic.woff2
 create mode 100644 Documentation/sphinx-static/IBMPlexMono-Italic.woff2
 create mode 100644 Documentation/sphinx-static/IBMPlexMono-Regular.woff2
 create mode 100644 Documentation/sphinx-static/IBMPlexSans-Bold.woff2
 create mode 100644 Documentation/sphinx-static/IBMPlexSans-BoldItalic.woff2
 create mode 100644 Documentation/sphinx-static/IBMPlexSans-Italic.woff2
 create mode 100644 Documentation/sphinx-static/IBMPlexSans-Regular.woff2
 create mode 100644 Documentation/sphinx-static/Newsreader_14pt-Bold.woff2
 create mode 100644 Documentation/sphinx-static/Newsreader_14pt-BoldItalic.woff2
 create mode 100644 Documentation/sphinx-static/Newsreader_14pt-Italic.woff2
 create mode 100644 Documentation/sphinx-static/Newsreader_14pt-Regular.woff2
 create mode 100644 Documentation/sphinx-static/fonts.css
 create mode 100644 LICENSES/dual/OFL-1.1


base-commit: babe393974de0351c0e6cca50f5f84edaf8d7fa1
  

Bagas Sanjaya <bagasdotme@gmail.com> writes:

> The problem
> ===========
>
> Currently, the kernel docs uses system-default serif fonts, as in
> Documentation/conf.py:
>
> ```
> ...
> if  html_theme == 'alabaster':
>     html_theme_options = {
>         'description': get_cline_version(),
>         'page_width': '65em',
>         'sidebar_width': '15em',
>         'fixed_sidebar': 'true',
>         'font_size': 'inherit',
>         'font_family': 'serif',
>     }
> ...
> ```
>
> The problem is depending on the serif font selected by system, the docs
> text (especially long passages) can be hard and uncomfortable to read.
> For developers reading the docs on multiple devices, the apparence may
> look inconsistent.
>
> The solution
> ============
>
> Uniform the font choices by leveraging web fonts. Most of people reading
> the kernel docs should already have modern browser that supports this
> feature (e.g. Chrome/Chromium and Firefox). The fonts are downloaded
> automatically when loading the page, but only if the reader don't
> already have ones installed locally. Subsequent docs page loading will
> use the browser cache to retrieve the fonts. If for some reasons the
> fonts fail to load, the browser will fall back to fallback fonts
> commonly seen on other sites.

So my immediate response to this is pretty uniformly negative.

- If you don't like serif, tweaking conf.py is easy enough without
  pushing it on everybody else.

- I'm not thrilled about adding a bunch of binary font data to the
  kernel, and suspect a lot of people would not feel that the bloat is
  worth it.

- The licensing of the fonts is not fully free.

There's so much we can do to improve our documentation and access to it;
messing around with web fonts seems - to me, at least - pretty low on
the list.

I suppose I can ask people at the kernel summit session in a couple
weeks to see if others feel differently.

Thanks,

jon
  

On Thu, Nov 02, 2023 at 10:35:47AM -0600, Jonathan Corbet wrote:
> Bagas Sanjaya <bagasdotme@gmail.com> writes:

Hello Bagas,

[...]

> > The solution
> > ============
> >
> > Uniform the font choices by leveraging web fonts. Most of people reading
> > the kernel docs should already have modern browser that supports this
> > feature (e.g. Chrome/Chromium and Firefox). The fonts are downloaded
> > automatically when loading the page, but only if the reader don't
> > already have ones installed locally. Subsequent docs page loading will
> > use the browser cache to retrieve the fonts. If for some reasons the
> > fonts fail to load, the browser will fall back to fallback fonts
> > commonly seen on other sites.
> 
> So my immediate response to this is pretty uniformly negative.
> 
> - If you don't like serif, tweaking conf.py is easy enough without
>   pushing it on everybody else.
> 
> - I'm not thrilled about adding a bunch of binary font data to the
>   kernel, and suspect a lot of people would not feel that the bloat is
>   worth it.
> 
> - The licensing of the fonts is not fully free.

+1 to all of Jon's points. We already have to deal with folks arguing
against .rst and pushing for us to just use plaintext for everything. I
suspect their reaction to this would be, to put it politely, even less
restrained.

Thanks,
David
  

On Thu, Nov 02, 2023 at 10:35:47AM -0600, Jonathan Corbet wrote:

Jon, some slight nit-picking below, after comments on the stated
problem.

> Bagas Sanjaya <bagasdotme@gmail.com> writes:
> 
[...]
> >
> > The solution
> > ============
> >
> > Uniform the font choices by leveraging web fonts. Most of people reading
> > the kernel docs should already have modern browser that supports this
> > feature (e.g. Chrome/Chromium and Firefox). The fonts are downloaded
> > automatically when loading the page, but only if the reader don't
> > already have ones installed locally. Subsequent docs page loading will
> > use the browser cache to retrieve the fonts. If for some reasons the
> > fonts fail to load, the browser will fall back to fallback fonts
> > commonly seen on other sites.
> 
Bagas,

If loading the web font fails, you will get whichever fallback
fonts are enabled by fontconfig and whichever fonts you, or your
distro, have installed.  If those fonts are not generally adequate
you should complain to your distro, or install different fonts in
~/.local/share/fotns and perhaps change your fonts.conf entries.

> So my immediate response to this is pretty uniformly negative.
> 
> - If you don't like serif, tweaking conf.py is easy enough without
>   pushing it on everybody else.
> 
> - I'm not thrilled about adding a bunch of binary font data to the
>   kernel, and suspect a lot of people would not feel that the bloat is
>   worth it.
> 

Jon,

As I understand it the (woff) fonts would be downloaded on request
by the browser if this went in.  So not a bunch of binary font data
in the kernel, but a download from google (adding to the popularity
of the font) and yet more font data in the browser cache.  I don't
have any desire to see woff fonts referenced in the docs, just
nit-picking about the details.

However -

> - The licensing of the fonts is not fully free.
> 

AFAICS, the SIL OFL allows everything except changing the font name.
If you have the right tools you can apparently fix things like "that
specific glyph looks ugly" or "you put a latin breve on a cyrillic
letter" (apparently they should differ) or "You mismapped this
codepoint to the wrong glyph". What you cannot do, if those changes
are not accepted by the font designer/maintainer, or if the font is
no-longer maintained, is fork it and provide it under the same name.

You can fork, but the font name has to be changed (e.g. LinLibertine
-> Libertinus and then the serif forked to CommonSerif).

Oh, and you cannot sell the fonts by themselves, but you can bundle
them with a distro or embed them.
https://www.tldrlegal.com/license/open-font-license-ofl-explained

Question: is that not free enough, or is that site wrong ?  If not
free enough, is there a better licence for fonts ?

ĸen
  

On Thu, Nov 02, 2023 at 10:35:47AM -0600, Jonathan Corbet wrote:
> So my immediate response to this is pretty uniformly negative.
> 
> - If you don't like serif, tweaking conf.py is easy enough without
>   pushing it on everybody else.

As local commit of course.

> 
> - I'm not thrilled about adding a bunch of binary font data to the
>   kernel, and suspect a lot of people would not feel that the bloat is
>   worth it.

MediaWiki project takes the same stance regarding web fonts:

> What about using webfonts?
>
> Webfonts is a system to deliver a font to users who do not have it installed.
> This involves having a user's browser download a font we provide, which causes
> additional resources to load and would have a negative impact on site
> performance (i.e. how fast pages load). This is particularly true for older
> browsers. In the future we may explore using webfonts, but for now this update
> provides greater readability and consistency while not degrading page load
> times.

Indeed, it's possible to achieve the same effect without resorting to web
fonts (as MediaWiki did), see [1].

> 
> - The licensing of the fonts is not fully free.

That was being discussed on the original RFC thread.

> 
> There's so much we can do to improve our documentation and access to it;
> messing around with web fonts seems - to me, at least - pretty low on
> the list.
> 
> I suppose I can ask people at the kernel summit session in a couple
> weeks to see if others feel differently.

OK, I want to hear about their opinion.

Thanks.

[1]: https://www.mediawiki.org/wiki/Typography_refresh
  

On Fri, Nov 03, 2023 at 12:26:19AM +0000, Ken Moffat wrote:
> On Thu, Nov 02, 2023 at 10:35:47AM -0600, Jonathan Corbet wrote:
> 
> Jon, some slight nit-picking below, after comments on the stated
> problem.
> 
> > Bagas Sanjaya <bagasdotme@gmail.com> writes:
> > 
> [...]
> > >
> > > The solution
> > > ============
> > >
> > > Uniform the font choices by leveraging web fonts. Most of people reading
> > > the kernel docs should already have modern browser that supports this
> > > feature (e.g. Chrome/Chromium and Firefox). The fonts are downloaded
> > > automatically when loading the page, but only if the reader don't
> > > already have ones installed locally. Subsequent docs page loading will
> > > use the browser cache to retrieve the fonts. If for some reasons the
> > > fonts fail to load, the browser will fall back to fallback fonts
> > > commonly seen on other sites.
> > 
> Bagas,
> 
> If loading the web font fails, you will get whichever fallback
> fonts are enabled by fontconfig and whichever fonts you, or your
> distro, have installed.  If those fonts are not generally adequate
> you should complain to your distro, or install different fonts in
> ~/.local/share/fotns and perhaps change your fonts.conf entries.

I beg to differ.

That's depending on font-family rule. For example, if I write it as:

```
body {
	font-family: "Liberation Sans", Helvetica, Arial, sans-serif;
}
```

browsers will try loading the first three fonts, in order. If a font
isn't available, they will try the next one until they can. Only then
when all other options are exhausted, generic fallback font will kick
in.

And yes, I do copying all fonts from my Windows installation (since
I dual-boot both it and Debian), then configure GNOME to use Segoe UI
as UI font (as it looks nicer to me). I also drop in font substitution
rules in `~/.config/fontconfig/conf.d` since I'm not the fan of
(obviously non-free) Söhne and substitute it with Inter and Source
Code Pro.

> 
> > So my immediate response to this is pretty uniformly negative.
> > 
> > - If you don't like serif, tweaking conf.py is easy enough without
> >   pushing it on everybody else.
> > 
> > - I'm not thrilled about adding a bunch of binary font data to the
> >   kernel, and suspect a lot of people would not feel that the bloat is
> >   worth it.
> > 
> 
> Jon,
> 
> As I understand it the (woff) fonts would be downloaded on request
> by the browser if this went in.  So not a bunch of binary font data
> in the kernel, but a download from google (adding to the popularity
> of the font) and yet more font data in the browser cache.  I don't
> have any desire to see woff fonts referenced in the docs, just
> nit-picking about the details.

But I wasn't considering people using terminal-only browsers (like
Lynx).

> 
> However -
> 
> > - The licensing of the fonts is not fully free.
> > 
> 
> AFAICS, the SIL OFL allows everything except changing the font name.
> If you have the right tools you can apparently fix things like "that
> specific glyph looks ugly" or "you put a latin breve on a cyrillic
> letter" (apparently they should differ) or "You mismapped this
> codepoint to the wrong glyph". What you cannot do, if those changes
> are not accepted by the font designer/maintainer, or if the font is
> no-longer maintained, is fork it and provide it under the same name.
> 
> You can fork, but the font name has to be changed (e.g. LinLibertine
> -> Libertinus and then the serif forked to CommonSerif).
> 
> Oh, and you cannot sell the fonts by themselves, but you can bundle
> them with a distro or embed them.
> https://www.tldrlegal.com/license/open-font-license-ofl-explained
> 
> Question: is that not free enough, or is that site wrong ?  If not
> free enough, is there a better licence for fonts ?

Yet Debian distributes OFL fonts in its main archive...

For me, for the fonts, I'd like CC-BY-SA instead.

Thanks.