Font management

Command-line options

Metanorma CLI, starting from version 1.3.9, supports the following additional font-related arguments:

--agree-to-terms
--no-install-fonts
--continue-without-fonts

Background

There are some fonts that we expect to be on every single platform, but it is simply not the case.

For example, the Arial font is installed by default on both Windows and macOS, yet it is not as such on Linux.

Despite Arial being an openly-licensed font for common usage, an additional package or a manual install is still necessary to make this font available on your favorite Linux distribution

A number of flavors, such as Metanorma for OGC, require fonts like “Arial” — and platform-specific availability of fonts limits what platforms document builds can occur. Unlike HTML/CSS which allows font compatibility, a PDF cannot be generated without given the correct font files.

Automatic font installs with Fontist

To make openly-licensed fonts available, Metanorma is integrated with Fontist.

Fontist is a cross-platform font installer that helps you install publicly available fonts.

If Metanorma detects that a necessary font is missing on your setup, it would automatically invoke Fontist to install the font.

Note	For those who are interested, the full list of fonts supported by Fontist can be seen in the Fontist Formulas repository. Since some fonts are only available from larger pieces of software, installing those fonts can take time.

Publicly available fonts and licensing needs

Some fonts are openly-licensed under the SIL Open Font License (OFL) and can be installed automatically by Fontist, such as the SIL fonts and Google’s font collection.

However, fonts like “Arial” from Microsoft, which we are all so familiar with, require user acceptance of a font license.

This is clearly not something that that Metanorma or Fontist can decide for the user.

Manual intervention needed for font installation

If you run a Metanorma flavor, such as OGC, which requires a font like Arial — that can be installed but requires acceptance of a font license — you will be presented with the following daunting message.

$ metanorma compile -t ogc -x xml,html,doc,pdf document.adoc
...

FONT LICENSE END ("Arial")
.../fontist-1.8.4/lib/fontist/font.rb:120:in `check_and_confirm_required_license':
  Fontist will not download these fonts unless you accept the terms.
  (Fontist::Errors::LicensingError)
...

At this point you are prompted to enter “YES” or “NO” to indicate acceptance or rejection of the font license.

Which is fine and dandy for a local machine, because you only need to install it once. Once the font is installed, you will never be asked again since Fontist is clever enough to find the font on your machine.

Automated font license acceptance as CLI options

In an automated pipeline such as for continuous integration, there is a clear need to enable non-attended installation for such fonts.

Enter the new CLI options: allowing you to indicate acceptance of the font licenses.

Metanorma CLI starting from version 1.3.9, supports the following additional font-related arguments under all document processing subcommands (compile, collection and site):

--agree-to-terms: agree to all font license agreements of necessary fonts
--no-install-fonts: do not install any fonts
--continue-without-fonts: continue with compilation even if necessary fonts are not installed

You can always run the command metanorma help compile to get reminded of these options:

$ metanorma help compile
Usage:
  metanorma compile FILENAME

Options:
    ...
    [--agree-to-terms], [--no-agree-to-terms]
      # Agree / Disagree with all third-party licensing terms
      # presented (WARNING: do know what you are agreeing with!)
    [--no-install-fonts], [--no-no-install-fonts]
      # Skip the font installation process
    [--continue-without-fonts], [--no-continue-without-fonts]
      # Continue processing even when fonts are missing

We STRONGLY ENCOURAGE YOU to manually run the font installs locally first to know what font licenses you are accepting (on every automated run)!

Have a look at the Metanorma sample document repositories on how to use these options in your continuous integration flow, e.g. mn-samples-itu.

Fonts caching for Docker

Given that Docker containers are transient, non-default fonts installed on the container will disappear on the next run.

The official Metanorma Docker images (the release image metanorma/metanorma and development image metanorma/mn) provide a mechanism for font caching to avoid fonts being re-downloaded on each Docker run.

Note	The `metanorma/mn` image is intended for development only, and is not guaranteed to work. Please use the `metanorma/metanorma` image unless you absolutely need unreleased features of Metanorma.

The Metanorma Docker images expose a separate volume /config/fonts to store non-default fonts.

This is how to use font caching for Metanorma Docker containers. The following commands assume that locally the font cache directory is located at ${HOME}/.fontist/fonts.

For Linux/macOS:

docker run \
  -v "$(pwd)":/metanorma \
  -v "${HOME}/.fontist/fonts":/config/fonts \
  -w /metanorma \
  metanorma/metanorma \
  metanorma site generate --agree-to-terms

For Windows:

cmd.exe:

docker run ^
  -v %cd%:/metanorma ^
  -v %USERPROFILE%\.fontist\fonts:/config/fonts ^
  -w /metanorma ^
  -it ^
  metanorma/metanorma ^
  metanorma site generate --agree-to-terms

PowerShell:

docker run `
  -v ${pwd.Path}:/metanorma `
  -v ${env:USERPROFILE}/.fontist/fonts:/config/fonts `
  -w /metanorma `
  -it `
  metanorma/metanorma `
  metanorma site generate --agree-to-terms

Warning

The Metanorma containers are currently only published using the x86-64 architecture. If you are on an ARM-based platform such as Apple Silicon, you will have to add the --platform linux/amd64 argument for these commands to work.

Questions and feedback

If you need help with font issues, feel free to raise it at our GitHub Discussions page!

References

Metanorma CLI