Configuring Fonts

How to configure fonts in Wordize for .NET: load custom fonts, set fallback options, and perform font substitution for unavailable fonts.

Font handling plays a key role in rendering documents. In Wordize, font configuration offers the ability to load custom fonts, set fallback options, and control how font substitution is performed when certain fonts are unavailable.

Regardless of the purpose for which you are rendering your document, understanding how Wordize manages fonts can help you avoid unexpected results.

Make Fonts Available to Wordize

By default, Wordize relies on system-installed fonts:

%WINDIR%\Fonts on Windows
/Library/Fonts on Mac
/usr/share/fonts, /usr/local/share/fonts, or /usr/X11R6/lib/X11/fonts on Linux systems

If your documents use fonts that are not available, Wordize won’t find them, so you need to install the required fonts or provide them by specifying additional font sources. The following code example shows how to set the folder, where Wordize will search for fonts globally:

// Set the folder, where Wordize will look for fonts globally.
Wordize.Settings.DefaultFontSettings.SetFontsFolder(@"C:\Temp\fonts", true);

Alternatively, you can configure font sources for a specific document processing operation using ProcessorContext:

// Specify fonts folder location for concrete document processing operation.
ConverterContext context = new ConverterContext();
context.FontSettings = new Fonts.FontSettings();
context.FontSettings.SetFontsFolder(@"C:\Temp\fonts", true);

Converter.Create(context)
    .From("C:\\Temp\\DocumentIn.docx")
    .To("C:\\Temp\\DocumentOut.pdf")
    .Execute();

You can also specify multiple font folders at once, and also scan fonts across all folders recursively. The following code example shows how to set up a recursive search for fonts in multiple folders:

Wordize.Settings.DefaultFontSettings.SetFontsFolders(new string[] { @"C:\Temp\fonts", @"C:\Temp\another_fonts" }, true);

Except folders, you can use FileFontSource, FolderFontSource, MemoryFontSource, StreamFontSource, or SystemFontSource. The following code example shows how to use SystemFontSource and custom FolderFontSource:

Wordize.Settings.DefaultFontSettings.SetFontsSources(new FontSourceBase[] { new SystemFontSource(), new FolderFontSource("C:\\Temp\\fonts", true) });

Important to note:

Setting a font folder overrides any font sources set in the FontSettings instance.

By default, FontSettings has a SystemFontSource, but after using the SetFontsFolder, SetFontsFolders, or SetFontsSources method, Wordize will only look for fonts in the specified folders.

Font Substitution Settings

When a document references a font that isn’t available among the specified font sources, Wordize performs font substitution to preserve the text’s readability and formatting. This process replaces missing fonts with available alternatives.

Where Does Wordize Search for a Font?

To begin, Wordize checks for the required fonts in the following order:

Search for a font among available font sources with the exact font name
Search for the required font among the fonts embedded in the source document, if the document format provides for embedded ones (for example, DOCX)

Order for Applying Substitution Rules

If the required font is not found among the available font sources with an exact font name or among the fonts embedded in the original document, then Wordize will apply the font substitution rules one-by-one until a suitable replacement is found:

Cleanup font name: remove suffixes with “-”, “,”, and “(” separators. Enabled by default, but you can disable it as follows:
```
FontSubstitutionSettings.FontNameSubstitution.Enabled = false;
```
Apply OS-level substitution if available (FontConfig on Linux/macOS). Disabled by default, but you can enable it as follows:
```
FontSubstitutionSettings.FontConfigSubstitution.Enabled = true;
```
Use a font substitution table – a special XML table that contains a list of the main substitute font names for different OS. Enabled by default, but you can disable it as follows:
```
FontSubstitutionSettings.TableSubstitution.Enabled = false;
```
Search for the most suitable font according to the font information contained in a specific document. Enabled by default, but you can disable it as follows:
```
FontSubstitutionSettings.FontInfoSubstitution.Enabled = false;
```
Use the default font specified in the DefaultFontName property (default is Times New Roman). Enabled by default, but you can disable it as follows:
```
FontSubstitutionSettings.DefaultFontSubstitution.Enabled = false;
```
By default, Wordize uses the Times New Roman font, but you can change it:
```
Wordize.Settings.DefaultFontSettings.SubstitutionSettings.DefaultFontSubstitution.DefaultFontName = "Arial";
```
If Wordize is unable to perform a font substitution, it tries to get the first available font from the available font sources.
Finally, if Wordize cannot find any fonts among the available font sources, it renders the document using the free Fanwood font that is embedded into the Wordize assembly.

Important to note:

The font info substitution rule will always resolve the font if the font information is available and will override the default font rule. If you want to use the default font rule, you should disable the font info substitution rule.
The font configuration substitution rule will resolve the font in most cases and thus override all other rules.

How to Recognize That the Font Was Substituted

Sometimes it may be unclear why the document layout has changed or why some font does not look as expected. In such cases, font substitution warning messages implemented by the IWarningCallback interface come to rescue:

ConverterContext context = new ConverterContext();
context.WarningCallback = new FontSubstitutionWarningCallback();

Converter.Create(context)
    .From("C:\\Temp\\in.docx")
    .To("C:\\Temp\\out.pdf")
    .Execute();

private class FontSubstitutionWarningCallback : IWarningCallback
{
    public void Warning(WarningInfo info)
    {
        if (info.WarningType == WarningType.FontSubstitution)
            Console.WriteLine(info.Description);
    }
}

Font FallBack Settings

There are two different mechanisms used in Wordize – Font substitution and Font fallback:

Font substitution is used when the font specified in the document cannot be found among the font sources, as described in the section above.
The Font fallback mechanism is used when the font is resolved but it does not contain a specific character. In this case, Wordize tries to use one of the fallback fonts for the character.

There is a BuildAutomatic method that automatically builds fallback settings by scanning available fonts:

Wordize.Settings.DefaultFontSettings.FallbackSettings.BuildAutomatic();

Similar to Table substitution, the Font fallback mechanism uses XML tables for configuration. Wordize includes two predefined tables: MsOfficeFallbackSetting.xml and NotoFallbackSetting.xml:

The MsOfficeFallbackSetting table defines a replacement strategy for a range of characters, which is similar to the strategy used by Microsoft Word. Thus, the strategy requires the installation of Microsoft Office fonts. MsOfficeFallbackSetting can be activated using the following method:
```
Wordize.Settings.DefaultFontSettings.FallbackSettings.LoadMsOfficeFallbackSettings();
```
The NotoFallbackSetting table is created especially for use with Google Noto fonts and can be enabled as follows:
```
Wordize.Settings.DefaultFontSettings.FallbackSettings.LoadNotoFallbackSettings();
```

Alternatively, you can load your own custom fallback settings from XML. You can first save the current fallback setting to XML, then modify them and load them back:

Wordize.Settings.DefaultFontSettings.FallbackSettings.Save("C:\\Temp\\FallbackSettings.xml");

Wordize.Settings.DefaultFontSettings.FallbackSettings.Load("C:\\Temp\\FallbackSettings.xml");