Fonts¶
kolinsky draws text with the fonts it can find in three places, looked at in this order:
- the
@font-facerules of the document; - the font files and folders you add to the engine, in the order you add them (the files of a folder sorted by path, the faces of a collection in file order);
- the fonts installed on the system, unless you turn them off.
System fonts¶
System fonts are on by default: fontconfig's directories on Linux and other Unix systems, the system and user
font folders on macOS and Windows. kolinsky fonts lists every face the engine would use, in matching order,
with its family, style, weight and file; --json prints the same list as JSON.
Font folders and files¶
Add your own fonts with --font-dir (repeatable) on the command line. A folder is searched with its
sub-folders for .ttf, .otf, .ttc, .otc, .woff and .woff2 files (the extension in any letter
case); other files are skipped.
In Rust a FontSet holds the added fonts: add_dir for a folder, add_file for one file and add_bytes
for font data in memory. A folder that does not exist, a missing file and a file that is not a font are
errors; add_bytes fails with Error::Parse on data that is not a font.
use kolinsky::{Engine, FontSet, Input, PdfOptions, RenderOptions};
fn main() -> Result<(), Box<dyn std::error::Error>> {
// Every font file in the folder and its sub-folders; single files and font bytes can be added too
let mut fonts = FontSet::new();
fonts.add_dir("fonts")?;
// The added faces come first, then the system fonts
let engine = Engine::builder().fonts(fonts).system_fonts(true).build();
let rendered = engine.render(Input::Path("scripts.html".into()), &RenderOptions::default(), &PdfOptions::default())?;
for d in rendered.diagnostics.iter().filter(|d| d.code == "glyph.missing") {
eprintln!("{}", d.message);
}
std::fs::write("scripts.pdf", rendered.output)?;
Ok(())
}
In Python, Engine(fonts=...) takes paths of font files and folders; a path that does not exist raises
FileNotFoundError.
from pathlib import Path
import kolinsky
# Font folders and files, then the system fonts
engine = kolinsky.Engine(fonts=["fonts"], system_fonts=True)
result = engine.render(Path("scripts.html"))
Path("scripts.pdf").write_bytes(result.pdf)
The fonts are fixed when the engine is built. Build the engine once and reuse it: the fonts are read and indexed once for all the documents it renders (see Performance).
Web fonts with @font-face¶
@font-face rules load fonts through the same resource loading as images and stylesheets, so they follow the
access policy: local files are allowed, network URLs only when you allow the network.
TrueType, OpenType with CFF outlines, WOFF and WOFF 2 files are supported.
@font-face {
font-family: "Brand";
src: url(fonts/brand-regular.woff2) format("woff2");
}
@font-face {
font-family: "Brand";
font-weight: bold;
src: url(fonts/brand-bold.woff2) format("woff2");
}
body { font-family: "Brand", sans-serif }
A font that cannot be loaded gives a resource.* diagnostic, and one that loads but does not decode gives
resource.invalid; the text then falls back to the next family of the list.
Choosing a face¶
For each run of text, kolinsky takes the families of font-family in order and picks the face that best matches
font-weight, font-style and font-stretch. Family names are compared ignoring case and blanks, and the
generic families (serif, sans-serif, monospace and the others) resolve to installed families. A family
without a bold or italic face is used as it is.
Fallback works per character: a character that the chosen face does not have is drawn by the next family that
has it, and the text after it returns to the first family. A paragraph mixing Latin, Arabic and Chinese is
drawn by the first family that has each script. A character that no available face has is kept as text, drawn
with the font's missing glyph, and reported once per call with the diagnostic glyph.missing, which names the
code point (U+XXXX). With strict set to missing-glyphs it fails the render instead (see
Diagnostics).
The language of the text takes part in the choice: the lang attribute (or font-language-override) selects,
for example, the Chinese or Japanese forms of Han characters when both are installed.
Complex scripts and right-to-left text¶
Text is shaped with the OpenType tables of its font, so Arabic joins, Devanagari and Thai clusters and Latin ligatures come out as the font designs them. Kerning and standard ligatures are on by default.
The base direction of a paragraph comes from direction or the dir attribute (ltr or rtl), never from the
text itself. Inside a line the Unicode bidirectional algorithm orders the runs: right-to-left words, numbers,
brackets (drawn mirrored) and embedded left-to-right words are placed in visual order. In a right-to-left block
the lines are flush right, text-align: start and end follow the direction, and inline boxes are placed from
the right.
Not everything of the bidirectional and writing-mode features is applied:
dir="auto"does not detect the direction from the text; the inherited direction stays.unicode-bidihas no effect, andbdoandbdielements do not override or isolate.writing-modedoes not make text vertical; vertical boxes are laid out horizontally.
Font features¶
The font properties select OpenType features: font-variant-ligatures, font-variant-caps (including
small capitals), font-variant-numeric, font-variant-position, font-variant-east-asian and
font-variant-alternates, the font-variant shorthand, font-kerning, and font-feature-settings for any
feature tag:
font-variation-settings has no effect, and font-synthesis and font-size-adjust are ignored.
The same fonts everywhere¶
Two machines with different installed fonts can lay out the same document differently. For output that is the
same on every machine, turn off the system fonts and give the engine its fonts explicitly:
Engine::builder().fonts(fonts).system_fonts(false) in Rust, Engine(fonts=[...], system_fonts=False) in
Python, --font-dir DIR --no-system-fonts on the command line. Together with
reproducible output this gives byte-identical PDFs.