SignDoc SDK (C++): Font Configuration

For creating the appearance of DigSig signatures in PDF documents, for filling in PDF text fields, and for inserting text into PDF documents, extended fonts are required if characters outside the character set supported by the standard fonts (or fonts already embedded in the document) are used.

Additional fonts may also be required rendering PDF documents.

A font configuration file is an XML document specifying the pathnames of TrueType font files and font substitution rules. The "FontFiles" element contains the pathname of a TrueType font file. The last component of the pathname may contain ? and * wildcards to refer to multiple files. Relative pathnames are relative to the directory containing the font configuration file. (If font configuration is read from a stream, relative pathnames will be relative to a specified directory. If no directory is specified, "FontFiles" elements with relative pathnames will be ignored.)

See Using SignDoc SDK in Windows Store apps for restrictions on pathnames in Windows Store apps.

The "Substitution" element defines a font substitution rule specifies the font name to be replaced and the name to be used as replacement (both in "FontName" elements).

When a font is needed, the substitution rules whose "type" attribute is "forced" are tried in the sequence specified in the font configuration file until a match is found. If a match is found, the font name will be replaced by the substitute font name and the "embed" attribute of the substitution rule will take effect. If no match is found, the original font name will be used.

Then, SignDocSDK tries to locate the font by trying these methods sequentially until a suitable font (ie, one having a matching name and supporting all required characters) is found:

match against the fonts declared in the document's interactive form dictionary (AcroForm)
match against the names of the 14 standard fonts
match against the fonts used by the document's pages
match against the font files loaded by the "FontFiles" elements in the order they occur in the font configuration file

If a suitable font is found, it will be used. Otherwise, the substitution rules whose "type" attribute is "fallback" (or missing) are tried in the sequence specified in the font configuration file until a match is found. The substitution rules are applied to the original font name (ie, without taking the substitutions of type "forced" into account). If no match is found or the substutition doesn't change the font name, SignDocSDK will report an error. Otherwise, the font name will be replaced by the substitute font name and the "embed" attribute of the substitution rule will take effect. SignDocSDK then tries again to locate the font by using the methods listed above.

Font substitution rules are always applied to the original, requested font name, that is, the output of a rule is not used as input for another rule.

For embedded fonts and font files, the font name will be matched against the PostScript names and font family names. The italic and bold attributes of the font are also compared (in case the match is on the font family name).

Note that SignDoc SDK ignores the fsType entry in the OS/2 table of OpenType fonts. In consequence, fonts can be embedded and subsetted even if the font copyright owner prohibits embedding and/or subsetting.

Here is the Document Type Definition for font configuration files:

<?xml version="1.0" encoding="UTF-8"?>
<!-- A font configuration file specifies font files, font replacements,
     and and font substitutions. -->
<!ELEMENT SPFontConfig (FontFiles*, Substitution*)>

<!-- Contents: either the pathname of a single font or a pathname
     containing wildcard characters * and ? in the last component
     such as c:\fonts\*.ttf. Relative pathnames are relative to the
     directory containing the font configuration file.

     The "embed" attribute controls whether the fonts will be
     embedded into the document or not.  If a font is already
     embedded and contains all required glyphs, it won't be
     embedded again. These values are available:
       no       The fonts won't be embedded; this is not allowed unless
                explicitely overriden with setShootInFoot()
       yes      The fonts will be embedded completely
       subset   Only the required glyphs will be embedded
     The "Substitution" element can override this attribute.
     Note that documents compliant with PDF/A must embed all fonts.
     Due to implementation restrictions, embedding a Type1 font currently
     removes PDF/A compliance. -->
<!ELEMENT FontFiles (#PCDATA)>
<!ATTLIST FontFiles
    embed (no|yes|subset) "subset"
>

<!-- Defines one font substitution. Font substitutions are tried one by
     one until a match is found or the end is reached.  Substitute the
     first font with the second one.  Letter case and space characters
     are ignored.  There is only one level of font substitutions, that
     is, substituted names are not subject to substitution.

     There are two types of font substitutions: If the "type"
     attribute is "forced", the substitution will be applied before
     trying to locate the font. That way, font can be substituted by
     another one even if it covers all required characters.

     If the "type" attribute is "fallback", the substitution will be
     applied only if no suitable font has been found.  The substitution
     will be applied to the original font name, ie, without taking
     a substitution of type "forced" into account.

     In other words, these steps are performed when looking for a
     font:

     - apply font substitutions of type "forced"
     - search for the font
     - If a suitable font has been found, use it
     - apply font substitutions of type "fallback" to the original font name
     - search for the font
     - If a suitable font has been found, use it

     The "embed" attribute controls whether the font will be
     embedded into the document or not.  If a font is already
     embedded and contains all required glyphs, it won't be
     embedded again. These values are available:
       default  Use the "embed" attribute of the FontFile element for the
                substituted font
       no       The font won't be embedded; this is not allowed unless
                explicitely overriden with setShootInFoot()
       yes      The font will be embedded completely
       subset   Only the required glyphs will be embedded
     The "no", "yes", and "subset" values override the "embed" attribute
     of the FontFile element for the substituted font.
     Note that documents compliant with PDF/A must embed all fonts.
     Due to implementation restrictions, embedding a Type1 font currently
     removes PDF/A compliance. -->
<!ELEMENT Substitution (FontName,FontName)>
<!ATTLIST Substitution
    type (forced|fallback) "fallback"
    embed (default|no|yes|subset) "default"
>

<!-- Contents: the font family name or PostScript name of the font to be
     substituted or of the font used as substitute. -->
<!ELEMENT FontName (#PCDATA)>

Example:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE SPFontConfig SYSTEM "SPFontConfig.dtd">
<SPFontConfig>
  <FontFiles embed="yes">c:\fonts\LinLibertine_*.ttf</FontFiles>
  <FontFiles embed="yes">c:\fonts\DejaVu*.ttf</FontFiles>
  <Substitution type="forced">
    <FontName>Times Roman</FontName>
    <FontName>Linux Libertine</FontName>
  </Substitution>
  <Substitution>
    <FontName>Helv</FontName>
    <FontName>DejaVu Sans</FontName>
  </Substitution>
  <Substitution>
    <FontName>Helvetica</FontName>
    <FontName>DejaVu Sans</FontName>
  </Substitution>
  <Substitution>
    <FontName>Arial</FontName>
    <FontName>DejaVu Sans</FontName>
  </Substitution>
</SPFontConfig>

The fonts referenced by this font configuration files can be obtained from http://dejavu-fonts.org and http://linuxlibertine.sourceforge.net .