aXSL Font: Font Configuration


Future changes to the font configuration are expected, so that more features can be added.


Some applications are able to obtain all of the information that they need about available fonts from some universal system registry, usually maintained by the operating system. In such cases, a font-configuration is not needed. However, in any case where such information is not available, may not be available, or not adequate for the application, some standard method of communicating information about available fonts is needed. The aXSL font-configuration DTD is an attempt to standardize the format of such information, so that users can avoid the need to maintain multiple configurations for multiple applications. A sample configuration file is also provided, which may be useful either for cut-and-paste or consultation as font-configuration files are created.

The configuration contemplates two general types of fonts. First are those for which at least some information is available from some other registry. In this document, these are referred to as System Fonts (SF). Second are those for which no external information is available at all. These are referred to as Free-standing Fonts (FSF).

The aXSL font-configuration is optimized for flexibility, which makes it somewhat more verbose and complex than it could be. It draws a sharp distinction between configuration of the font itself, which is generally done in the <font> element, and configuration of the way it is used and selected by an application, which is generally done in the <font-description> element. This distincion allows a font to be used in more than one way. Here are some examples where this may possibly be useful:

  • The same font to be used with more than one encoding.
  • The same font can be used in the same or different ways in more than one font family.

<axsl-font-config> element

All attributes of axsl-font-config set global defaults that can be overridden by subsidiary elements.

  • xml:base sets the global base URL from which all relative subsidiary URLs will be located.
  • embed sets the global default value for the embed attribute used by the font element.

<server> element

Important: Most users do not need to configure server elements and can safely skip this section.

  • setup-free-standing-fonts should be set to either "true" or "false" depending on whether free-standing fonts should be configured.
  • setup-system-fonts should be set to either "true" or "false" depending on whether system fonts should be configured.

<parameter> element


A parameter contains two attributes, "key" and either "value" or "from-environment". These are used within the configuration file as a simple substitution. Wherever the text of "key", enclosed in curly braces, occurs in attributes, it will be substituted with the text of "value" or with the value of the environment variable named in "from-environment". This is useful especially for making the paths to files more flexible.

Note that support for environment variables may vary from one programming language to another, from one environment to another, and from one implementation to another. For example, some java platforms only support environment variables set using the java "-D" switch. Others can get environment variables from the operating system. Consult the documentation for your implementation to determine the exact level of support for this feature.

<glyph-list> element

Important: Most users do not need to configure custom glyph-list elements and can safely skip this section. If you do need to specify or create a glyph-list see the Encoding documentation.

<encoding> element

Important: Most users do not need to configure custom encoding elements and can safely skip this section. If you do need to specify or create an encoding see the Encoding documentation.

<font-group> element

The only purpose of the font-group element is as a wrapper for font elements that have similar attributes, or that should be grouped together for some other reason. An attribute set on font-group will be inherited by contained font elements, unless those elements override the attibute.

  • label is for identification purposes only, and is not used by the system.
  • xml:base sets the base URL from which all relative subsidiary URLs will be located.
  • embed sets the default value for the embed attribute used by the font element.

<font> element

Here is a sample <font> element in the font configuration file:

  • id is an XML ID type attribute, and must be unique within the font-configuration file. It is used to identify the font, specifically as the target of "font" attributes in <font-description> elements.
  • embed may be set to all, subset, or none, and defaults to none. If the font is not embedded in the output, the document will be created correctly, but the user may not be able to view it correctly, depending on their local viewer environment.
  • metrics-file provides a URL that contains font metric information for this font. TrueType and OpenType fonts do not need to specifiy a metrics file, because the font-file contains all metric information. However, Type 1 fonts and device-embedded fonts must provide a metrics file.

    Both PFM and AFM font metrics files are supported. However, it is highly recommended that AFM files be used where possible for the following reasons:

    • As far as we can tell, PFM files are only usable for fonts that are encoded using WinAnsiEncoding. We do not know how to map Unicode characters to symbolic fonts or other non-ANSI character sets.
    • Since only WinAnsiEncoding is supported, only characters available in that encoding can be used. Many fonts have additional characters that can be accessed using other encodings, but that encoding data is not stored in a PFM file.
    • PFM files are limited to 512 kerning pairs. Many fonts have more than 512 pairs, so some pairs that would be kerned using an AFM file will not be kerned using a PFM file.
    • The PFM format is a Microsoft format that appears to be no longer supported by them.
    • PFM files are binary files, not readily edited. AFM files on the other hand are text files, which can be edited. This of course is both useful and dangerous.
  • font-file provides a file path or URL to the font file itself. Required for fonts that will be embedded and for fonts that do not have a separate metrics file.

For both metrics-file and font-file, relative paths and URLs are resolved relative to any parent xml:base attribute. Relative xml:base attributes are themselves resolved relative to any parent xml:base attribute. If no xml:base attribute is set on the root element, applications my set the base either to some configured value known to them, or to the current working directory.

The description above is for the typical configuration of a free-standing font. Some applications need to be able to concurrently support and configure system fonts along with free-standing fonts. These can be obtained in one of two ways:

  • If the applications supports it, SFs can be obtained by simply asking for them by name. To specify this, exclude the "embed", "metrics-file", and "font-file" attributes.
  • If the application supports it, SFs can be manufactured from a font file in much the same manner as a free-standing font. The advantage to this method is that the font can be embedded in an output document. To use this approach, you must include the "embed" and "font-file" attributes in the same way that you would for a free-standing font.

In either of these cases, the following attribute must be included for the <font> element.

  • system-name (optional) is the name which should be supplied to the external registry when requesting the System Font. Note that this is the name of the font, not the font-family.

The <font> is intended to represent exactly one logical font. This font can be a simple SF, a simple FSF, or a font that can manifest itself as both an SF and an FSF. In some cases it is possible to abuse the <font> element to represent one SF and a different FSF. This practice is discouraged. A better solution is to use the <font-family-alias> and related <alias-configuration> elements to alias different fonts in different circumstances.

<font-family> element

The font-family element contains one or more font-description elements. When the font-family is selected in a document, the font-description elements are searched for a match on the remaining descriptive items (weight, style, etc.)

  • name (required) is the value that should be matched against the font-family provided in the document.
  • embed (optional) is the default embed value for all contained font-description elements.
  • simulate-small-caps (optional) is the default simulate-small-caps value for all contained font-description elements.

<font-description> element

  • font (required) is an XML IDREF type attribute, and must match the "id" attribute of some <font> element.
  • style (optional, default "normal") = normal | italic | oblique | backslant. Corresponds to the XSL-FO font-style property.
  • weight (optional, default "normal") = 100 | 200 | 300 | (normal | 400) | 500 | 600 | (bold | 700) | 800 | 900. Corresponds to the XSL-FO font-weight property. Following is an unofficial guide to the weight values:
    Description Weight
    Ultralight 100
    Light 200
    SemiLight 300
    Normal, Regular, Roman, Book 400
    Medium 500
    SemiBold 600
    Bold 700
    Black 800
    UltraBlack 900
  • simulate-small-caps takes a percentage, and the "%" character should be included. It performs two functions for applications that can simulate small-caps. First, in the font-selection process, the existence of this attribute indicates that this font-description can be selected when small-caps are needed (it can also be selected when small-caps are not needed). Second, if selected, it tells the application what percentage of the font-size that is used for regular caps should be used for the simulated small-cap glyphs. For example, a value of "80%", when applied to a font-size of 12 points, will result in small-caps at 9.6 points.
  • encoding (optional, default "InternalEncoding") corresponds to a defined encoding scheme. This attribute is generally useful only for Type 1 fonts. It should typically be set to "WinAnsiEncoding" for fonts using a standard Roman character set, and to "InternalEncoding" (the default) for most other fonts. However, other standard encodings are available, and custom encodings can be created if needed. See Encoding for details.

Note that the purpose of separating a font-description from its underlying font is to allow the same font to be used multiple ways. The same font can be used within different font-family entries, and can be defined with different characteristics.

The result of defining two font-description elements with identical characteristics in the same font family is undefined. With 9 font-stretch possibilities, 4 for font-style, 2 for font-variant, and 9 for font-weight, there are 648 possible fonts in a font-family.

<font-family-alias> element

<font-family-alias alias="sans-serif"
  <alias-configuration name="pdf"          font-family="Base14-Helvetica"/>
  <alias-configuration name="awt"          font-family="AWT-sans-serif"/>

The <font-family-alias> and child <alias-configuration> elements are designed to allow a font-configuration to be used for different purposes. The combination of the two allows a font-family to be accessed using more than one name, and allows more than one font-family to be accessed using the same name. In the example above, the font-family "Base14-Helvetica" can be accessed using either the font-family name "Base14-Helvetica" or its alias "sans-serif". On the other hand, the alias "sans-serif" can point to either "Base14-Helvetica" or "AWT-sans-serif", depending on the context or active configuration.

  • alias (required) defines the alias name that should be matched to the font-family requested.
  • default-family (required) indicates the name of the font-family that should be substituted for the alias if no matching child <alias-configuration> element is found.

<alias-configuration> element

The <alias-configuration> element is an optional child to the <font-family-alias> element, and allows an alias name to point to different font-family elements depending upon some configuration name. The configuration name is application-dependent. Some applications may choose not to use them at all, and others may have a complex scheme for determining which configuration to use in a given circumstance. A typical use is to distinguish between fonts available for print applications, like PDF and PostScript, from those available for viewing documents on the screen, such as AWT applications.