Font Management in ksTFL

Overview

ksTFL renders DOCX documents using a C++ engine that requires TrueType/OpenType font files for text measurement and pagination. Starting with version 0.7.0, the package automatically discovers fonts installed on the operating system at load time. If a required font is not available on the system, a metrically compatible open-source fallback is used.

This guide explains how font discovery works, which fallback fonts are bundled, and how to configure custom font directories.

How Font Discovery Works

When ksTFL is loaded, it performs four steps:

1. Scan system directories. The C++ font scanner inspects platform-specific directories and reads family names and style flags from .ttf, .otf, and .ttc files.

2. Scan user directories. If the R option ksTFL.font_dirs is set, those directories are scanned as well.

3. Scan bundled fallbacks. The package’s own inst/fonts/ directory is scanned last.

4. Resolve target fonts. For each target family (Arial, Times New Roman, Courier New, Georgia, Verdana, Trebuchet MS), ksTFL keeps the discovered font when available or assigns a designated fallback.

Key rule: system-installed fonts always take priority. The bundled fallbacks are only used when a target font is not found anywhere on the system.

Target Fonts and Fallbacks

The rendering engine targets six font families commonly used in clinical documents. Each has a metrically compatible open-source fallback bundled with the package:

All bundled fonts are licensed under the SIL Open Font License 1.1.

If a font family requested in a spec (via s_font(font_name = "...")) is not a target font and is not found on the system, the engine falls back to Liberation Sans as the last resort.

For convenience, ksTFL also ships built-in style atoms for the target font families: font_arial, font_courier_new, font_times_new_roman, font_georgia, font_verdana, and font_trebuchet_ms. These atoms set only font_name, so they can be safely combined with size, colour, alignment, and other style atoms via f_combine().

Checking Font Status

After loading the package, call tfl_font_status() to see the current font resolution:

library(ksTFL)
tfl_font_status()
#> ksTFL font scan: 3 target(s) resolved, 3 using fallback
#>   [ok]       Arial                -> Arial
#>   [ok]       Times New Roman      -> Times New Roman
#>   [ok]       Courier New          -> Courier New
#>   [fallback] Georgia              -> Liberation Serif
#>   [fallback] Verdana              -> Liberation Sans
#>   [fallback] Trebuchet MS         -> Liberation Sans
#>   Scanned 5 directories

Reading the output:

• [ok] — The target font was found on the system and will be used directly.
• [fallback] — The target font was not found; the bundled fallback is used instead.

Adding Custom Font Directories

If proprietary fonts are installed in a non-standard location (e.g., a network share or a project-local folder), point the ksTFL.font_dirs option to those directories before loading the package, or rescan afterwards:

options(ksTFL.font_dirs = c("/opt/company-fonts", "/mnt/shared/fonts"))
library(ksTFL)

library(ksTFL)
options(ksTFL.font_dirs = "/opt/company-fonts")
tfl_rescan_fonts()

Rescanning Fonts

Call tfl_rescan_fonts() after:

• Installing new system fonts
• Changing the ksTFL.font_dirs option
• Mounting a new network font directory

# Install Georgia to /usr/local/share/fonts/georgia/ ... then:
tfl_rescan_fonts()
#> ksTFL font scan: 6 target(s) resolved, 0 using fallback
#>   [ok]       Arial                -> Arial
#>   [ok]       Times New Roman      -> Times New Roman
#>   [ok]       Courier New          -> Courier New
#>   [ok]       Georgia              -> Georgia
#>   [ok]       Verdana              -> Verdana
#>   [ok]       Trebuchet MS         -> Trebuchet MS
#>   Scanned 5 directories

Startup Messages

When the package is attached, it prints a concise summary if any target fonts are using fallbacks:

ksTFL v0.7.0 - Clinical TFL Framework
For help, type: ??ksTFL
Note: 3 font(s) using fallback: Georgia, Verdana, Trebuchet MS
Run tfl_font_status() for details.

If all target fonts are found on the system, no font-related message is shown.

Interaction with write_doc()

The write_doc() function (and replay_report()) automatically uses the font directories from the scanner cache. You can still pass additional per-call directories via the font_dirs argument:

write_doc(report, name = "output",
          outDir = "results",
          metaPath = tempdir(),
          font_dirs = "/path/to/extra-fonts")

Per-call directories are appended to the scanner’s cached list for that render only — they do not modify the global font registry.

FAQ

options(ksTFL.font_dirs = "/path/to/font/directory")
tfl_rescan_fonts()

suppressPackageStartupMessages(library(ksTFL))