Message-ID: <20231102120053.30630-1-bagasdotme@gmail.com>
Date:   Thu,  2 Nov 2023 19:00:42 +0700
From:   Bagas Sanjaya <bagasdotme@...il.com>
To:     Linux Kernel Mailing List <linux-kernel@...r.kernel.org>,
        Linux Documentation <linux-doc@....kernel.org>
Cc:     Jonathan Corbet <corbet@....net>,
        Thomas Gleixner <tglx@...utronix.de>,
        Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
        Akira Yokosawa <akiyks@...il.com>,
        Stanislav Fomichev <sdf@...gle.com>,
        David Vernet <void@...ifault.com>,
        Miguel Ojeda <ojeda@...nel.org>, James Seo <james@...iv.tech>,
        Daniel Vetter <daniel.vetter@...ll.ch>,
        Federico Vaga <federico.vaga@...a.pv.it>,
        Carlos Bilbao <carlos.bilbao@....com>,
        Bagas Sanjaya <bagasdotme@...il.com>
Subject: [PATCH RFC 0/4] Documentation: Web fonts for kernel documentation

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
`@...t-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

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
-- 
An old man doll... just what I always wanted! - Clara

Powered by blists - more mailing lists