Table of Contents

Fonts and complex scripts

DocWright lays text out with the real font files, just as Word does, so line breaks and page breaks match. It needs the fonts your documents use. This page covers where it looks for them, what happens when one is missing, and how complex scripts are shaped.

Where fonts come from

DocWright searches, in order:

  1. the folders in ConvertOptions.FontDirectories;

  2. the operating system's font folders, recursively:

    Platform Folders
    Windows %WINDIR%\Fonts, %LOCALAPPDATA%\Microsoft\Windows\Fonts
    macOS /System/Library/Fonts, /Library/Fonts, ~/Library/Fonts
    Linux /usr/share/fonts, /usr/local/share/fonts, ~/.fonts
  3. its bundled open-licensed faces: Carlito (metric-compatible with Calibri), Caladea (Cambria) and Liberation (Arial, Times New Roman, Courier New), plus Noto Naskh Arabic for Arabic text and stand-ins for Symbol and Wingdings. A machine with no fonts at all still produces well-laid-out output.

Fonts the document embeds come before all three. They belong to the document, so they are always used.

The same output on every machine

A server, a container or a golden-file test often needs output that doesn't change with what a machine has installed. Turn off the operating-system folders and ship the fonts you depend on:

using DocWright;
using DocWright.Core.Rendering;
using DocWright.Dom;

var confined = new ConvertOptions
{
    IncludeSystemFontDirectories = false,   // ignore whatever this machine has installed
};
confined.FontDirectories.Add("fonts");      // the fonts you ship with your application

using (FileStream input = File.OpenRead("missing-font.docx"))
using (WordDocument document = converter.Load(input))
{
    LaidOutConversion laidOut = converter.Layout(document, confined);
    IEnumerable<IGrouping<string, GlyphRun>> byFace = laidOut.Document.Pages[0].Primitives
        .OfType<GlyphRun>()
        .GroupBy(run => laidOut.Fonts.ResolveRun(run).FamilyName);   // the face each run is drawn with
    foreach (IGrouping<string, GlyphRun> face in byFace)
    {
        Console.WriteLine($"{face.Key,-18} {string.Concat(face.Select(run => run.Text))}");
    }
}

Output. This machine has Calibri installed, but the second paragraph still gets the bundled Carlito, and the missing family is substituted from inside the set:

Liberation Serif   Set in a font that is not installed.
Carlito            And a paragraph in Calibri, which is.
Setting Default Effect
IncludeSystemFontDirectories true false skips the operating-system folders.
IncludeBundledMetricFonts true false skips the bundled Carlito, Caladea, Liberation and Noto Naskh Arabic faces and the Symbol and Wingdings stand-ins.

Convert, ConvertAsync, ConvertToImages and Layout all honour both settings. ConvertPdfToImages ignores them, as it ignores FontDirectories. A family missing from your set is substituted and reported as usual. A bundled face counts as a substitution too, so FailOnFontSubstitution refuses Carlito standing in for Calibri. With both settings off, no FontDirectories and no embedded fonts, the conversion throws FontResolutionException.

When a font is missing

using DocWright;
using DocWright.Core.Diagnostics;
using DocWright.Core.Text;
using DocWright.Fonts;

var diagnostics = new CollectingConversionDiagnostics();
var options = new ConvertOptions
{
    Diagnostics = diagnostics,
    WarnOnFontSubstitution = true,          // report DXP3004 for each substitution
};

options.FontDirectories.Add("fonts");      // your own fonts, searched before the system's
options.FontFallbackChain.Add("Arial");    // tried, in order, for a family that is missing
options.ScriptFallbackFonts[UnicodeScript.Arabic] = [new FontKey("Arial")];

using (FileStream input = File.OpenRead("missing-font.docx"))
using (FileStream output = File.Create("missing-font.pdf"))
{
    converter.Convert(input, output, options);
}

foreach (ConversionDiagnostic d in diagnostics.Snapshot())
{
    Console.WriteLine($"{d.Code}: {d.Message}");
}

Output

DXP3001: Preflight substitution: 'Fontastic Grotesk' -> 'Arial' (outcome UltimateFallback, distance 0).
DXP3004: Font substitution summary: 1 run(s) affected across 1 family/families; worst-case PANOSE distance 0; includes ultimate-fallback substitutions.
DXP3001: Font fallback: 'Fontastic Grotesk' -> 'Arial' (outcome UltimateFallback, distance 0).
missing-font.pdf
Two paragraphs: the first in the fallback font Arial, the second in Calibri

Substitution is silent unless you ask to hear about it:

Setting Effect
WarnOnFontSubstitution = true Reports DXP3004, a summary of every substitution, to your diagnostics sink.
FailOnFontSubstitution = true Throws FontResolutionException instead of substituting.
FontFallbackChain Families to try, in order, for any missing family.
ScriptFallbackFonts[script] Families to try for one script, such as Arabic or Han, ahead of the general chain.
Important

Servers and containers: install the fonts your documents use. Substitutes are metric-compatible where possible, but only the real font guarantees the same line breaks as Word. Copy the font files into your image and add the folder to FontDirectories.

The font cache

Indexing the installed fonts takes about a second, so each DocWrightConverter caches its font engine, one per combination of font settings, up to eight. That is why an application should keep one converter. A host that changes fonts per tenant can call converter.ClearFontCache() to release the memory. It is safe while conversions are running, and it never changes the output.

Complex scripts

Arabic always has a face. Arabic text whose font has no Arabic glyphs is set in the bundled Noto Naskh Arabic (Regular and Bold) and shaped there, so a container with no fonts draws joined Arabic instead of empty boxes. This happens, for example, where Arial resolves to Liberation Sans, which has no Arabic. A font that has Arabic keeps its text. A family you name in ScriptFallbackFonts[UnicodeScript.Arabic] comes first. The substitution is reported once as DXP3001. Noto Naskh Arabic is not metric-compatible with Microsoft's Arabic faces: its letters are wider and its lines taller, so ship the document's own Arabic fonts where line breaks must match Word.

arabic.pdf with IncludeSystemFontDirectories = false
The same Arabic text set in the bundled Noto Naskh Arabic, joined and right to left

Arabic and Hebrew are shaped by the built-in engine: joining forms, ligatures such as lam-alef, and mark positioning. No setup is needed.

arabic.pdf (built-in shaping)
Arabic text with correctly joined letters, rendered right to left

Indic scripts (Devanagari, Bengali, Tamil…), Thai, Khmer and other complex scripts need a shaper. Without one, each character is drawn on its own: vowel signs land in the wrong place and conjuncts don't form. Install DocWright.ComplexText and set the HarfBuzz shaper:

dotnet add package DocWright.ComplexText
using DocWright;
using DocWright.ComplexText;

var shaped = new ConvertOptions { TextShaper = new HarfBuzzTextShaper() };

using (FileStream input = File.OpenRead("hindi.docx"))
using (FileStream output = File.Create("hindi-harfbuzz.pdf"))
{
    converter.Convert(input, output, shaped);
}
Hindi: without and with HarfBuzz
Hindi text with vowel signs in the wrong positionBuilt-in: the vowel sign in हिन्दी is misplaced
Hindi text shaped correctlyHarfBuzzTextShaper: correct

When the built-in engine can't shape a script it reports DXP2002, so you can detect documents that need the shaper.

Note

DocWright.ComplexText is the only DocWright package with a native dependency (HarfBuzzSharp). Windows and macOS binaries are included. On Linux, also add HarfBuzzSharp.NativeAssets.Linux to your application.

Symbol fonts

Symbol and Wingdings characters are stored as private-use code points: Word's default bullet is U+F0B7 in Symbol, its third-level bullet U+F0A7 in Wingdings. Those codes mean something only in that one font.

On a machine without Symbol or Wingdings (a Linux container, or IncludeSystemFontDirectories = false), the bundled stand-ins draw them: DocWright Symbol Fallback and DocWright Dingbat Fallback. Each has the original's code points, advance widths and line metrics, so the layout matches, and each code draws the character it means. The text itself is not changed. An installed Symbol or Wingdings always wins, and the substitution is reported as DXP3001.

using DocWright;
using DocWright.Core.Diagnostics;
using DocWright.Core.Rendering;
using DocWright.Dom;

var diagnostics = new CollectingConversionDiagnostics();
var noSystemFonts = new ConvertOptions { IncludeSystemFontDirectories = false, Diagnostics = diagnostics };

using (FileStream input = File.OpenRead("bullets.docx"))
using (WordDocument document = converter.Load(input))
{
    LaidOutConversion laidOut = converter.Layout(document, noSystemFonts);
    foreach (GlyphRun run in laidOut.Document.Pages[0].Primitives.OfType<GlyphRun>()
        .Where(run => run.Text.Length > 0 && run.Text[0] >= ''))
    {
        Console.WriteLine($"U+{(int)run.Text[0]:X4} drawn in {run.FontFamily}");
    }

    using FileStream pdf = File.Create("bullets.pdf");
    converter.Convert(document, pdf, noSystemFonts);
}

Output:

U+F0B7 drawn in DocWright Symbol Fallback
U+F0A7 drawn in DocWright Dingbat Fallback
bullets.pdf with IncludeSystemFontDirectories = false
Word's three bullet levels, a disc, a circle and a small square, drawn with no system fonts

Symbol's U+F0C3 (℘) and Wingdings' U+F0FF (the Windows logo) have no glyph in the stand-ins. Wingdings 2, Wingdings 3 and Webdings have no stand-in.

In the PDF's text layer, DocWright maps the Symbol and Dingbat sets to real Unicode, so a Symbol bullet copies as "•" and a Greek alpha as "α". Text drawn with the Wingdings stand-in copies as what it means too ("▪", "✓"). An installed Wingdings, Webdings and private symbol fonts have no published mapping. Their characters render correctly but extract as private-use code points, reported once per font as DXP3006.