Adobe - OpenType Feature File Specification Accessibility

OpenType Feature File Specification

Copyright

Copyright (c) 1997,1998,2002,2003,2007 Adobe Systems Incorporated

Permission is hereby granted, free of charge, to any person obtaining a copy of this documentation file to use, copy, publish, distribute, sublicense, and/or sell copies of the documentation, and to permit others to do the same, provided that:

Permission is hereby granted, free of charge, to any person obtaining a copy of this documentation file, to create their own derivative works from the content of this document to use, copy, publish, distribute, sublicense, and/or sell the derivative works, and to permit others to do the same, provided that the derived work is not represented as being a copy or version of this document.

Adobe shall not be liable to any party for any loss of revenue or profit or for indirect, incidental, special, consequential, or other similar damages, whether based on tort (including without limitation negligence or strict liability), contract or other legal or equitable grounds even if Adobe has been advised or had reason to know of the possibility of such damages. The Adobe materials are provided on an "AS IS" basis. Adobe specifically disclaims all express, statutory, or implied warranties relating to the Adobe materials, including but not limited to those concerning merchantability or fitness for a particular purpose or non-infringement of any third party rights regarding the Adobe materials.

Version

[ Document version 1.7. Last updated 25 Oct 2006 ]

Caution:

Portions of the syntax unimplemented by Adobe are subject to change.

  1. Introduction
  2. Syntax
    1. Comments
    2. White space
    3. Keywords
    4. Special characters
    5. Numbers and other metrics
      1. Number
      2. Metric
      3. Device table
      4. Value record
      5. Contour point
      6. Anchor
      7. Caret value
    6. Glyphs
      1. Glyph name
      2. CID
    7. Glyph classes
      1. Ranges
      2. Named glyph classes
    8. Tags
    9. Lookup block labels
  3. Including files
  4. Specifying features
    1. feature
    2. Language system
      1. languagesystem
      2. script and language
    3. parameters
    4. lookupflag
    5. lookup
    6. subtable
    7. Examples
  5. Glyph substitution (GSUB) rules
    1. [GSUB LookupType 1] Single substitution
    2. [GSUB LookupType 2] Multiple substitution
    3. [GSUB LookupType 3] Alternate substitution
    4. [GSUB LookupType 4] Ligature substitution
    5. [GSUB LookupType 5] Contextual substitution
    6. [GSUB LookupType 6] Chaining contextual substitution
      1. Specifying a Chain Sub rule and marking sub-runs
      2. Specifying exceptions to the Chain Sub rule
    7. [GSUB LookupType 7] Extension substitution
  6. Glyph positioning (GPOS) rules
    1. [GPOS LookupType 1] Single adjustment positioning
    2. [GPOS LookupType 2] Pair adjustment positioning
      1. Specific and class pair kerning
      2. Enumerating pairs
      3. Subtable breaks
    3. [GPOS LookupType 3] Cursive attachment positioning
    4. [GPOS LookupType 4] Mark-to-Base attachment positioning
    5. [GPOS LookupType 5] Mark-to-Ligature attachment positioning
    6. [GPOS LookupType 6] Mark-to-Mark attachment positioning
    7. [GPOS LookupType 7] Contextual positioning
    8. [GPOS LookupType 8] Chaining contextual positioning
      1. Specifying a Chain Pos rule and marking sub-runs
      2. Specifying exceptions to the Chain Pos rule
    9. [GPOS LookupType 9] Extension positioning
  7. Ordering of lookups and rules in the feature file
    1. An OpenType Layout engine's layout algorithm
    2. Ordering of lookups and subtables
    3. Ordering of rules within a lookup
  8. Specially handled features
    1. The all alternates ('aalt') feature
    2. The optical size ('size') feature
  9. Specifying or overriding table values
    1. BASE table
    2. GDEF table
    3. head table
    4. hhea table
    5. name table
    6. OS/2 table
    7. vhea table
    8. vmtx table
  10. Specifying anonymous data blocks
  11. Document revisions

1. Introduction

An OpenType feature file is a text file that contains the typographic layout feature specifications for an OpenType font in an easy-to-read format. It may also contain override values for certain fields in the font tables. It is read in during the creation or editing of an OpenType font. This document specifies the feature file grammar.

This is an example of a complete feature file (keywords are shown boldface):

	 # Script and language coverage
	 languagesystem DFLT dflt;
	 languagesystem latn dflt;
	 {
	 
	 # Ligature formation
	 feature liga {
		substitute f i by fi;
		substitute f l by fl;
	 } liga;
   
	 # Kerning
	 feature kern {
		position A Y -100;
		position a y -80;
		position s f' <0 0 10 0> t;
	 } kern;

This file specifies the formation of the "fi" and "fl" ligatures, and the kern values of the glyph pairs "A" "Y" and "a" "y", and a contextual positioning pair ft when preceded by s. It also specifies that all features will be applied under all languages in the latn script, and for all scripts not named in the feature file.

Note: all "Implementation Notes" and "Currently not implemented" comments in the rest of the specification below refer to the Adobe implementation of the feature file grammar in teh makeotf program, unless otherwise indicated.

2. Syntax

2.a. Comments

The "#" character indicates the start of a comment; the comment extends until the end of the line. Text on a line after the comment is discarded before processing.

2.b. White space

White space is not significant except for delimiting tokens. You can have multiple line endings, spaces, and tabs between tokens. Macintosh, UNIX and PC line endings are all supported.

2.c. Keywords

This is a complete list of keywords in the feature file language, shown in boldface in examples:

 *anchor
  anonymous (or anon)
  by

 *caret
 *cursive
 *device
  enumerate (or enum)
  excludeDFLT (deprecated)

  exclude_dflt
  feature block; feature statement
  from
  ignore substitute; ignore position
  IgnoreBaseGlyphs

  IgnoreLigatures
  IgnoreMarks
  include
  includeDFLT (deprecated)
  include_dflt
  language

  languagesystem
  lookup block and statement
  lookupflag
 *mark
  nameid
 *NULL device; NULL value record; NULL anchor
  parameters

  position (or pos)
 *required
  RightToLeft
  script
  substitute (or sub)
  subtable

  table
  useExtension

The following are keywords only in their corresponding table/feature blocks, and are shown in boldface in examples:

  HorizAxis.BaseTagList      # BASE table
  HorizAxis.BaseScriptList   "
 *HorizAxis.MinMax           "
  VertAxis.BaseTagList       "
  VertAxis.BaseScriptList    "
 *VertAxis.MinMax            "
 *GlyphClassDef              # GDEF table
 *Attach                     "
 *LigatureCaret              "
  FontRevision               # head table
  CaretOffset                # hhea table
  Ascender                   # hhea table
  Descender                  # hhea table
  LineGap                    # hhea table
  Panose                     # OS/2 table
  TypoAscender               "
  TypoDescender              "
  TypoLineGap                "
  winAscent                  "
  winDescent                 "
  UnicodeRange               "
  CodePageRange              "
  XHeight                    "
  CapHeight                  "
  Vendor                     "
  sizemenuname               # size feature
  VertTypoAscender           # vhea table
  VertTypoDescender          "
  VertTypoLineGap            "
  VertOriginY                # vmtx table
  VertAdvanceY               # vmtx table

[* Currently not implemented. ]

The following are keywords only where a tag is expected:

  DFLT  # can be used only with the script keyword and as the script value with the languagesystem keyword. 
  dflt  # can be used only with the language keyword and as the language value with the languagesystem keyword.

The only permitted language tag for the 'DFLT script is 'dflt'.

2.d. Special characters

  #    pound sign      Denotes start of comment
  ;    semicolon       Terminates a statement
  ,    comma           Separator in various lists
  @    at sign         Identifies glyph class names
  \    backslash       Identifies CIDs. Distinguishes glyph names from
                       an identical keyword
  -    hyphen          Denotes glyph ranges in a glyph class
  =    equal sign      Glyph class assignment operator
  '    single quote    Marks a glyph or glyph class for contextual substitution
                       or positioning
  "    double quote    Marks a glyph or glyph class for contextual substitution
                       or positioning
  " "  double quotes   Enclose a name table string
  { }  braces          Enclose a feature, lookup, table, or anonymous block
  [ ]  square brackets Enclose components of a glyph class
  < >  angle brackets  Enclose a device, value record, contour point, anchor, or caret
  ( )  parentheses     Enclose the file name to be included

2.e. Numbers and other metrics

2.e.i. Number

A <number> is a signed decimal integer (without leading zeroes). For example:

  -150
  1000

It is used in device tables [§2.e.iii] and contour points [§2.e.v], as well as the values of various table fields [§9].

2.e.ii. Metric

A <metric> value is simply a <number> in font design units. It is used in value records [§2.e.iv] for positioning rules, as well as to express the values of various table fields [§9].

[ Note: Multiple master support has been withdrawn as of OpenType specification 1.3. ]

2.e.iii. Device table

[ Currently not implemented. ]

A <device> represents a single device table or a null offset to it. It is used in value records [§2.e.iv], anchors [§2.e.vi], and caret values [§2.e.vii].

2.e.iv. Value record

A <valuerecord> is used in some positioning rules [§6].

It must be enclosed by angle brackets, except for format A, in which the angle brackets are optional. Note that the <metric> adjustments indicate values (in design units) to add to (positive values) or subtract from (negative values) the placement and advance values provided in the font (in the 'hmtx' and 'vmtx' tables).

2.e.v. Contour point

[ Currently not implemented. ]

A <contour point> is used in anchors [§2.e.vi] and caret values [§2.e.vii]. It takes the format:

  < contourpoint <number> >

where <number> specifies a contour point index. For example:

  <contourpoint 2>

Note: Since CFF OpenType fonts do not specify contour point indexes, a <contour point> may be used only with TrueType OpenType fonts.

2.e.vi. Anchor

[ Currently not implemented. ]

An <anchor> is used in some positioning rules [§6]. It takes 4 formats:

2.e.vii. Caret value

[ Currently not implemented. ]

<caret value> is used in the GDEF table [§9.b]. It takes 3 formats:

2.f. Glyphs

These are represented by one of:

2.f.i. Glyph name

A glyph name may be up to 31 characters in length, must be entirely comprised of characters from the following set:

A-Z
a-z
0-9
. (period)
_ (underscore)

and must not start with a digit or period. The only exception is the special character ".notdef".

"twocents", "a1", and "_" are valid glyph names. "2cents" and ".twocents" are not.

An initial backslash serves to differentiate a glyph name from an identical keyword in the feature file language. (See §2.c for a list of keywords.) For example, a glyph named "table" must be specified in the feature file as:

   \table

A glyph name alias database may be used by the implementation of the feature file grammar. If it is used, then it is the responsibility of the implementation to correlate the glyph name aliases used in the feature file with the actual glyph names in the font.

2.f.ii. CID

CIDs are represented by a non-negative <number> [§2.e.i] preceded by a backslash. For example:

  \101
  \0

2.g. Glyph classes

Note: The feature file glyph classes described in this section are not to be confused with glyph classes of OpenType Layout ClassDefs. The latter are described in the chapter "Common Table Formats" in the OpenType Font File Specification.

A feature file glyph class, <glyphclass>, represents a single glyph position in a sequence and is denoted by a list of glyphs enclosed in square brackets. For example:

  [endash emdash figuredash]

An example of a sequence which contains a glyph class is:

  space [endash emdash figuredash] space

This would match any of the 3 sequences "space endash space", "space emdash space", or "space figuredash space" during OpenType layout.

A feature file glyph class that contains only one single glyph is known as a singleton glyph class.

A feature file glyph class is also used to represent the set of alternate glyphs in an alternate substitution lookup type rule.

2.g.i. Ranges

A range of glyphs is denoted by a hyphen:

  [<firstGlyph> - <lastGlyph>]

Spaces around the hyphen are not required since hyphens are not permitted in feature file glyph names. For example:

  [\0-\31]
  [A-Z]

For CID fonts, the ordering is the CID ordering.

For non-CID fonts, the ordering is independent of the ordering of glyphs in the font. <firstGlyph> and <lastGlyph> must be the same length and can differ:

  1. By a single letter from A-Z, either uppercase or lowercase. For example:

      [A.swash - Z.swash]
      [a - z]
    

    The range is expanded by incrementing the letter that differs, while keeping the rest of the glyph name the same.

  2. By upto 3 decimal digits in a contiguous run. For example:

      [ampersand.01 - ampersand.58]
    

    The range is expanded by incrementing the number values, while keeping the rest of the glyph name the same.

      [ampersand.1 - ampersand.58]         # invalid
    

    is not a valid glyph class since the length of the glyph names differ.

Note that

  [zero - nine]

is not a valid glyph range, as the intended range is not in alphabetic order. It must be enumerated explicitly:

  @digits = [zero one two three four five six seven eight nine];
2.g.ii. Named glyph classes

A glyph class can be named by assigning it to a glyph class name, which begins with the "@" character, and then referred to later on by the glyph class name. For example:

  @dash = [endash emdash figuredash];     # Assignment
  space @dash space                       # Usage

The part of the glyph class name after the "@" is subject to the same name restrictions that apply to a glyph name, except that its maximum length is 30.

Glyph class assignments can appear anywhere in the feature file. A glyph class name may be used in the feature file only after its definition.

When a glyph class name occurs within square brackets, its elements are simply added onto the other elements in the glyph class being defined. For example:

  @Vowels.lc = [a e i o u];
  @Vowels.uc = [A E I O U];
  @Vowels = [@Vowels.lc @Vowels.uc y Y];

Here the last statement is equivalent to:

  @Vowels = [a e i o u A E I O U y Y];

No square brackets are needed if a glyph class name is assigned to another single glyph class name. For example:

  @Figures_lining_tabular = @FIGSDEFAULT;

Ranges, glyphs, and glyph class names can be combined in a glyph class. For example:

  [A.oldstyle - Z.oldstyle  ampersand.oldstyle  @smallCaps]

Implementation Note: When feature file glyph sequences (including glyph classes) are converted into OpenType Layout ClassDefs or Coverages in the font, the Adobe implementation ensures that ClassDefs or Coverages that are identical are shared, even if they are in different features. This happens regardless of whether ranges, glyphs or glyph class names were used to express the feature file glyph classes. (The only exception to this is for lookups that use the Extension lookup types: such lookups will not share their ClassDefs and Coverages with non-extension lookups.)

2.h. Tags

Tags are four-letter identifiers. These are denoted simply by tag name, without any final spaces, and are distinguished from glyph names by context. For example:

  DEU

Note that the final space in the example is implicit.

The special language tag 'dflt' denotes the default language system of the corresponding script.

2.i. Lookup block labels

The same length and name restrictions that apply to a glyph name apply to a lookup block label.

3. Including files

Including files is indicated by the directive:

  include(<filename>)

The implementation software is responsible for handling the search paths for the location of the included files.

In a typical implementation, if the file name were absolute then that path would be used. If the file name were relative, then it would be appended to the directory of the including feature file.

A maximum include depth of 5 ensures against infinite include loops (files that include each other).

4. Specifying features

4.a. feature

Each feature is specified in a feature block:

  feature <feature tag> {
     # specifications go here
  } <feature tag>;

For example:

  feature liga {
     # ...
  } liga;

The 'aalt' feature is treated specially; see §8.a. For example, the "useExtension" keyword may optionally precede "{" in its feature block syntax, and other features can be referred to with a "feature" statement within its feature block. The 'size' feature is also treated specially; see §8.b.

A feature file "rule" is a statement that specifies glyph substitution or glyph positioning. A feature block may contain glyph substitution rules [§5], glyph positioning rules [§6], or both.

A lookup is a group of rules of the same type. See §4.e.

4.b. Language system

An OpenType language system is any combination of a script and language tag. (In the text of this document, the notation <script tag>/<language tag> is used to refer to a language system; for example, 'script latn;'/'language dflt' denotes the default language of the Latin script.)

The lookups in every OpenType feature must be registered under one or more language systems. The lookups of a particular feature may vary across the language systems that feature is registered under.

There are two ways to specify language system in the feature file: with the languagesystem keyword outside of feature definition blocks, and by the script and language keywords within feature definition blocks.

4.b.i. languagesystem

In practice, most or all of the features in a font will be registered under the same set of language systems, and a particular feature's lookups will be identical across the language systems that feature is registered under.

The "languagesystem" statement takes advantage of this fact. It is the simplest way to specify language system in the feature file. (For the 'aalt' and 'size' features, it is the only way to specify language system.) One or more such statements may be present in the feature file at global scope (i.e. outside of the feature blocks or any other blocks) and before any of the feature blocks:

  languagesystem <script tag> <language tag>;

When these statements are present, then all the lookups in each feature that does not contain an explicit "script" or "language" statement (see 4.b.ii below) will be registered under every language system specified by the "languagesystem" statement(s). If a feature block does contain 'script' or 'language' tags, then all lookups that occur before the first 'script' or 'language' tag will also be applied under all the specified languagesystems.

If no "languagesystem" statement is present, then the implementation must behave exactly as though the following statement were present at the beginning of the feature file:

  languagesystem DFLT dflt;

If any languagesystem statement is used, then the statement specifying:

  languagesystem DFLT dflt;

must be specified explicitly; if not, this languagesystem will not be included in the font. This script/language pair is special: it is used if a program cannot find a match in the font to the current writing script and language. If it is not in your font, then all the rules may be invisible to the program if your font does not have a match for the current script and language.It is strongly recommended to use the statement 'languagesystem DFLT dflt;'.

If the statement 'languagesystem DFLT dflt;' is present, it must be the first of the languagesystem statements. Note that the only permitted language tag for the 'DFLT' script is 'dflt'.

Please see example 1 in §4.g below.

4.b.ii. script and language

Occasionally a feature may need to be specified whose lookups vary across the language systems of the feature, or whose language systems vary from the set of language systems of the rest of the features in the file, as specified by the "languagesystem" statements). In these cases, "script" and "language" statements will need to be used within the feature block itself. Such statements affect only that feature.

Rules that are specified after the start of a feature and before the first "script" and/or "language" statement will be included in all the the language systems specified by the "languagesystem" statements. If you do not want any of the rules in the feature to be registered under the language systems specified by the "languagesystem" statements, then a "script" and/or "language" statement for a script other than 'DFLT' must be present before the first rule in the feature.

Once the first script (other than 'DFLT') or language statement occurs within a feature block, subsequent lookups and rules are registered only within the currently specified script and language. To register a rule or lookup under more than one script and language, you must explicitly include it following each script and language specification.

The one exception to this rule are the default lookups. There are two levels of default lookups. Rules specified between the start of a feature definition and the first 'script' keyword for a script other than 'DFLT' are added to all language-systems, unless a language statement specifies the 'exclude_dflt' keyword. Rules specified between the occurrence of the 'language dflt;' statement and the next language statement are added to all languages for the current script, but not to other scripts.

The current script and language attributes may be changed as follows:

Since the 'aalt' and 'size' features are treated specially, "script" and "language" statements are not allowed within these features.

Special notes:

4.c. parameters

The "parameters" statement specifies the feature parameters for the currently defined language system. It is currently supported only for the 'size' feature; see §8.b.

4.d. lookupflag

The chapter "Common Table Formats" in the OpenType Font File Specification describes the LookupFlag field in the Lookup table.

The lookupflag attribute defaults to 0 at the start of a feature block.

The lookupflag attribute stays the same until explicitly changed, until a lookup reference statement is encountered that changes it, until the script is changed, or until the end of the feature.

To change the lookupflag attribute explicitly, use the lookupflag statement, which takes two formats:

The base glyphs, ligatures, and marks are defined in the GDEF table block [§9.b].

4.e. lookup

A lookup is a group of rules of the same type. The font editor can label a run of rules and refer to it explicitly later on, in order to have different parts of the font tables refer to the same lookup. This decreases the size of the font in addition to freeing the editor from maintaining duplicate sets of rules.

A lookup in the OpenType font will be created from each named lookup block or each run of rules with the same feature, script, language, lookupflag and lookup type attribute.

To define and label a lookup, use a named lookup block:

  lookup <label> [useExtension] {
     # rules to be grouped
  } <label>;

The lookup will be created with a GSUB or GPOS Extension lookup type if and only if the optional "useExtension" keyword is used.

t has two effects: all the records of all types that are referenced by a lookup are placed in one contiguous block of data, and the offset to the lookup may be 32 bits rather limited to 16 bits.

When you font cannot be built because of an offset overflow error (meaning that the offset from one record to another record exceeds the 64 Kbyte limit imposed by the maximum size possible for a 16-bit offset field), then add this quailifer to the largest lookup. Keep adding it to more lookups until your font will build.

Note that since the Extension lookup types were added in OpenType specification v1.3, they will not be recognized by all OpenType layout parsers.

(See also §8.a for how to specify the entire 'aalt' feature be made with the Extension lookup type.)

To refer to the lookup later on, use a lookup reference statement:

  lookup <label>;

For example:

  lookup SHARED {       # lookup definition
     # ...
  } SHARED;
  # ...
  lookup SHARED;        # lookup reference

An example of a lookup that uses the Extension lookup type:

  lookup EXTENDED_KERNING useExtension {       # lookup definition
     # ...
  } EXTENDED_KERNING;
  # ...
  lookup EXTENDED_KERNING;    # lookup reference. "useExtension" not needed

Since the labeled block literally defines a single lookup in the font, the rules within the lookup block must be of the same lookup type and have the same lookupflag attribute. A lookup block may not contain any other kind of block. The order of lookups within a font is defined by the order of the lookup definitions in the feature file.

4.f. subtable

The feature file implementation must insert subtable breaks among the rules for a particular lookup if needed. For example, if a set of alternate substitution rules specified in the feature file exceeds the subtable size limit, several subtables must be automatically created.

The "subtable" statement may be used as follows:

  subtable;

to explicitly force a subtable break after the previous rule.

[ This is currently supported only for Pair Adjustment Positioning Format 2 (i.e. pair class kerning) in order to reduce subtable size. See §6.b.iii for details. ]

4.g. Examples

Example 1. The following is an example of an entire feature file and demonstrates the two ways to register features under language systems (see §4.b above):

  languagesystem DFLT dflt;
  languagesystem latn dflt;
  languagesystem latn DEU;
  languagesystem cyrl dflt;

  feature smcp {
     sub [a-z] by [A.sc-Z.sc];
     # All the rules in this feature will be grouped in a single lookup
     # that is is registered under all the language-systems.
  } smcp;

  feature liga {
           sub f f by ff;
           sub f i by fi;
           sub f l by fl;
            # Since no script or language keyword has been specified yet, the rules above will
            # be placed in a single lookup, which will be registered for this feature under all the
            # language systems.
            
     script latn;
        language dflt;
           # lookupflag 0;      (implicit)
           sub c t by c_t;
           sub c s by c_s;
           # The rules above will be placed in a lookup that is registered for all the
           # languages for the script latn, but not any other scripts.
           
       language DEU;
           # script latn;       (stays the same)
           # lookupflag 0;      (stays the same)
           sub c h by c_h;
           sub c k by c_k;
           # The rules above will be placed in a lookup that is registered only under the
           # script latn, language DEU.
  } liga;

  feature kern {
     pos a y -150; 
     # [more pos statements]
     # All the rules in this feature will be grouped in a single lookup
     # that is is registered under all the language-systems.
  } kern;

In the above example, the 'smcp' and 'kern' features will be registered under the 'DFLT'/'dflt', latn'/'dflt', 'latn'/'DEU ' and 'cyrl'/'dflt' language systems since no explicit "script" or "language" statements are present in those features.

In the 'liga' feature, the ff, fi and fl ligature substitutions will be applied under all all language systems. The c_t and c_s ligature substitutions will be applied under all languages of the script latn, but not under any other scripts. The c_h and c_k ligature substitutions will be applied when the language is German (i.e. they are registered only under 'latn'/'DEU ').

Example 2. The following example illustrates labeled lookup blocks and the use of the exclude_dflt keyword:

  languagesystem DFLT dflt;
  languagesystem latn dflt;
  languagesystem latn DEU;
  languagesystem cyrl dflt;
  languagesystem cyrl SRB;
  languagesystem grek dflt;
  
  feature liga {
            # start of default rules that are applied under all language systems.
           lookup HAS_I {
              sub f f i by ffi;
              sub f i by fi;
           } HAS_I;

           lookup NO_I {
             sub f f l by ffl;
             sub f f by ff;
           } NO_I;
            # end of default rules that are applied under all language systems.

     script latn;
         language dflt;               # default lookup fotr latn included under all languages for the latn script
            sub f l by fl;

        language DEU;               # default lookups included under the DEU language..

           sub s s by germandbls;   # This is also included.

        language TRK exclude_dflt;   # default lookups are excluded.
           lookup NO_I;             # Only this lookup is included under the TRK language

     script cyrl;
        language SRB;
             sub c t by c_t; # this rule will apply only under script cyrl language SRB.
  } liga;

The 'DFLT'/'dflt', 'cyrl'/'dflt', and 'grek'/'dflt' language systems will all contain the default rules for 'liga' functionality, the rules in the lookups HAS_I and NO_I.

Under the 'latn' script, all languages but TRK will contain the default lookups, and the fl ligature rule.

The germandbls ligature will apply only for the 'latn'/'DEU ' language system.

The 'latn'/'TRK ' languagesystem will contain only the NO_I lookup.

The 'cyrl'/'SRB ' languagesystem will contain all the default rules, and the c_t ligature rule.

Note that if you specify no explicit rules or lookup references after a script and language statement, that the effect is to include all the default rules for all scripts for the feature. Note also that lookup HAS_I must be placed before lookup NO_I since the ffi substitution must precede the ff substitution when both are applied. (See §7, "Ordering of lookups and rules in the feature file," below).

The ordering of ligature rules within a particular lookup does not matter, however, as the implementation will sort them in order to avoid conflict. For example, in lookup HAS_I, the fi substitution may be placed before the ffi substitution. (See §5.d, "Ligature substitution," below).

5. Glyph substitution (GSUB) rules

Glyph substitution rules begin with the keyword "substitute"; this keyword may be abbreviated as "sub". (The "ignore" keyword may precede the "substitute" keyword in some cases.) The GSUB lookup type is auto-detected from the format of the rest of the rule.

5.a. [GSUB LookupType 1] Single substitution

A Single Sub rule is specified in one of the following formats:

  substitute <glyph> by <glyph>;             # format A
  substitute <glyphclass> by <glyph>;        # format B
  substitute <glyphclass> by <glyphclass>;   # format C

Format B specifies that any glyph in the target glyph class must be replaced by the same replacement glyph.

Format C specifies that any of the glyphs in the target glyph class must be replaced by its corresponding glyph (in the order of glyphs in the glyph classes) in the replacement glyph class. If the replacement is a singleton glyph class, then the rule will be treated identically to a format B rule. If the replacement class has more than one glyph, then the number of elements in the target and replacement glyph classes must be the same.

For example:

  sub a by A.sc;                                            # format A
  substitute [one.fitted one.oldstyle one.tab.oldstyle] by one; # format B
  substitute [a - z] by [A.sc - Z.sc];                    # format C
  substitute @Capitals by @CapSwashes;                        # format C

The third line in the above example produces an identical representation in the font as:

  substitute a by A.sc;
  substitute b by B.sc;
  substitute c by C.sc;
  # ...
  substitute z by Z.sc;

5.b. [GSUB LookupType 2] Multiple substitution

[ This LookupType is currently not implemented. ]

A Multiple Sub rule is specified as:

  substitute <glyph> by <glyph sequence>;

<glyph sequence> contains two or more glyphs. It may not contain glyph classes. (If it did, the rule would be ambiguous as to which replacement sequence were required.) For example:

  substitute ffi by f f i;            # Ligature decomposition

5.c. [GSUB LookupType 3] Alternate substitution

An Alternate Sub rule is specified as:

  substitute <glyph> from <glyphclass>;

For example:

  substitute ampersand from [ampersand.1 ampersand.2 ampersand.3];

5.d. [GSUB LookupType 4] Ligature substitution

A Ligature Sub rule is specified as:

  substitute <glyph sequence> by <glyph>;

<glyph sequence> must contain two or more <glyph|glyphclass>es. For example:

  substitute [one one.oldstyle] [slash fraction] [two two.oldstyle] by onehalf;

Since the OpenType specification does not allow ligature substitutions to be specified on target sequences that contain glyph classes, the implementation software will enumerate all specific glyph sequences if glyph classes are detected in <glyph sequence>. Thus, the above example produces an identical representation in the font as if all the sequences were manually enumerated by the font editor:

  substitute one         slash    two         by onehalf;
  substitute one.oldstyle slash    two         by onehalf;
  substitute one         fraction two         by onehalf;
  substitute one.oldstyle fraction two         by onehalf;
  substitute one         slash    two.oldstyle by onehalf;
  substitute one.oldstyle slash    two.oldstyle by onehalf;
  substitute one         fraction two.oldstyle by onehalf;
  substitute one.oldstyle fraction two.oldstyle by onehalf;

A contiguous set of ligature rules does not need to be ordered in any particular way by the font editor; the implementation software must do the appropriate sorting. So:

  sub f f by ff;
  sub f i by fi;
  sub f f i by ffi;
  sub o f f i by offi;

will produce an identical representation in the font as:

  sub o f f i by offi;
  sub f f i by ffi;
  sub f f by ff;
  sub f i by fi;

5.e. [GSUB LookupType 5] Contextual substitution

This LookupType is a functional subset of GSUB LookupType 6, chaining contextual substitution. Thus, all desired rules of this LookupType can be expressed in terms of chaining contextual substitution rules.

5.f. [GSUB LookupType 6] Chaining contextual substitution

5.f.i. Specifying a Chain Sub rule and marking sub-runs

A Chain Sub rule describes a target glyph sequence and one or more lookups of any non-contextual lookup type that will be applied to specified sub-runs if the target glyph sequence is matched. The rule is specified as follows:

  substitute <marked glyph sequence>   # Target sequence with marked sub-run
  by <glyph sequence> (, <glyph sequence>)*;  # Sub-run replacement sequences

A <glyph sequence> comprises one or more glyphs or glyph classes.

<marked glyph sequence> is a <glyph sequence> in which one or more sub-runs of glyphs or glyph classes are identified, i.e. "marked". A sub-run is marked by inserting a single quote (') after each of its member elements. Two or more contiguous sub-runs may be distinguished by marking the elements of the first sub-run with the single quote, the elements of the second sub-run with the double-quote ("), the elements of the third sub-run with the single-quote, and so on, alternating between single- and double-quotes as needed.

These sub-runs represent the target sequences of the lookups called by this rule. Each such sub-run of marked glyphs must correspond to, in order, a replacement glyph sequence in the comma-separated list of replacement <glyph sequence>s. The lookup types of the lookups called by this rule are autodetected from their target and replacement sequences in the same way as in their corresponding stand-alone (i.e. non-contextual) statements.

[ Currently a limited form of chaining contextual substitution is implemented: one single or one ligature substitution (either of which may include glyph classes) within a glyph sequence. ]

Example 1. This calls a Single Sub lookup. The rule below means: in sequences "a d" or "e d" or "n d", substitute "d" by "d.alt".

  substitute [a e n] d' by d.alt;

Example 2. This also calls a Single Sub lookup. The rule below means: if a capital letter is followed by a small capital, then replace the small capital by its corresponding lowercase letter.

  substitute [A-Z] [A.sc-Z.sc]' by [a-z];

Example 3. This calls a Ligature Sub lookup. The rule below means: in sequences "e t c" or "e.begin t c", substitute the first two glyphs by the ampersand.

  substitute [e e.begin]' t' c by ampersand;
5.f.ii. Specifying exceptions to the Chain Sub rule

Exceptions to a chaining contextual substitution rule are expressed by inserting a statement of the following form anywhere before the chaining contextual rule and in the same lookup as it:

  ignore substitute <marked glyph sequence> (, <marked glyph sequence>)*;

The keywords "ignore substitute" are followed by a comma-separated list of <marked glyph sequence>s. At most one sub-run of glyphs or glyph classes may be marked in each <marked glyph sequence>, by a single-quote (') following each glyph or glyph class. This marked sub-run, when present, is taken to correspond to the "input sequence" of that rule. This generally means that it should correspond to the place where substitution would have occurred had the sequence not been an exception (see examples below). This is necessary for the OpenType layout engine to correctly handle skipping this sequence. When no glyphs are marked, then only the first glyph or glyph class is taken to be marked.

The "ignore substitute" statement works by creating subtables in the GSUB that tell the OT layout engine simply to match the specified sequences, and not to perform any substitutions on them. As a result of the match, remaining rules (i.e. subtables) in the lookup will be skipped. (See the OT layout algorithm in §7.a.)

Example 1. Ignoring specific sequences:
The "ignore substitute" rule below specifies that the substitution in the "substitute" rule should not occur for the sequences "f a d", "f e d", or "a d d". Note that the marked glyphs in the exception sequences indicate where a substitution would have occurred; this is necessary for the OpenType layout engine to correctly handle skipping this sequence.

  ignore substitute f [a e] d', a d' d;
  substitute [a e n] d' by d.alt;

Example 2. Matching a beginning-of-word boundary:

  ignore substitute @LETTER f' i';
  substitute f' i' by f_i.begin;

The example above shows how a ligature may be substituted at a word boundary. @LETTER must be defined to include all glyphs considered to be part of a word. The substitute statement will get applied only if the sequence doesn't match "@LETTER f i"; i.e. only at the beginning of a word.

Example 3. Matching a whole word boundary:

  ignore substitute @LETTER a' n' d', a' n' d' @LETTER;
  substitute a' n' d' by a_n_d;

In this example, the a_n_d ligature will apply only if the sequence "a n d" is neither preceded nor succeeded by a @LETTER.

Example 4. This shows a specification for the contextual swashes feature:

  feature cswh {

     # --- Glyph classes used in this feature:
     @BEGINNINGS = [A-N P-Z Th m];
     @BEGINNINGS_SWASH = [A.swash-N.swash P.swash-Z.swash T_h.swash m.begin];
     @ENDINGS = [a e z];
     @ENDINGS_SWASH = [a.end e.end z.end];

     # --- Beginning-of-word swashes:
     ignore substitute @LETTER @BEGINNINGS';
     substitute @BEGINNINGS' by @BEGINNINGS_SWASH;

     # --- End-of-word swashes:
     ignore substitute @ENDINGS' @LETTER;
     substitute @ENDINGS' by @ENDINGS_SWASH;

  } cswh;

If a feature only targets glyphs at the beginning or ending of a word, such as the 'init' and 'fina' features, then the application could be made responsible for detecting the word boundary; the feature itself would be simply defined as the appropriate substitutions without regard for word boundary. Such application responsibilities must be described in the feature tag registry.

5.g. [GSUB LookupType 7] Extension substitution

The "useExtension" keyword specifies creating lookups of this lookup type. See §4.e and §8.a.

6. Glyph positioning (GPOS) rules

Glyph positioning rules begin with the keyword "position"; this keyword may be abbreviated as "pos". (The "enumerate" or "ignore" keywords may precede the "position" keyword in some cases.) The GPOS lookup type is auto-detected from the format of the rest of the rule.

Glyph positioning is specified in terms of metrics [§2.e.ii], device tables [§2.e.iii], value records [§2.e.iv], and anchors [§2.e.vi]. In all positioning rules, these are inserted immediately after the glyph(s) they apply to, with the exception of Pair Pos format B.

6.a. [GPOS LookupType 1] Single adjustment positioning

A Single Pos rule is specified as:

  position <glyph|glyphclass> <valuerecord>;

Here, the <glyph|glyphclass> is adjusted by the <valuerecord> [§2.e.iv]. For example, to reduce the left and right side-bearings of a glyph each by 80 design units:

  position one <-80 0 -160 0>;

[ Currently only <valuerecord> format B is implemented for this LookupType. ]

6.b. [GPOS LookupType 2] Pair adjustment positioning

6.b.i. Specific and class pair kerning

Rules for this LookupType are usually used for kerning, and may be in either of 2 formats:

Note that in both formats A and B, if at least one glyph class is present (even if it is a singleton glyph class), then the rule is interpreted as a class pair; otherwise, the rule is interpreted as a specific pair.

In the 'kern' feature, the specific glyph pairs will typically precede the glyph class pairs in the feature file, mirroring the way that they will be stored in the font. (See §7, "Ordering of lookups and rules in the feature file," below.)

  feature kern {
     # specific pairs for all scripts
     # class pairs for all scripts
  } kern;
6.b.ii. Enumerating pairs

If some specific pairs are more conveniently represented as a class pair, but the editor does not want the pairs to be in a class kerning subtable, then the class pair must be preceded by the keyword "enumerate" (which can be abbreviated as "enum"). The implementation software will enumerate such pairs as specific pairs. Thus, these pairs can be thought of as "class exceptions" to class pairs. For example:

  @Y_LC = [y yacute ydieresis];
  @SMALL_PUNC = [comma semicolon period];

  enum pos @Y_LC semicolon  -80;    # specific pairs
  pos      f quoteright 30;         # specific pair
  pos      @Y_LC @SMALL_PUNC -100;  # class pair

The enum rule above can be replaced by:

  pos y semicolon -80;
  pos yacute semicolon -80;
  pos ydieresis semicolon -80;

without changing the representation in the font.

6.b.iii. Subtable breaks

The implementation software will insert a subtable break within a run of class pair rules if a single subtable cannot be created due to class overlap. A warning will be emitted. For example:

  pos [Ygrave] [colon semicolon] -55;   # [line 99]   In first subtable
  pos [Y Yacute] period -50;            # [line 100]  In first subtable
  pos [Y Yacute Ygrave] period -60;     # [line 101]  In second subtable

will produce a warning that a new subtable has been started at line 101, and that some kern pairs within this subtable may never be accessed. Note that this allows the font to be built, but the result will not match the developer's intention. The kerning feature will not work as expected until the causes for all such errors are removed. The pair (Ygrave, period) will have a value of 0 if the above example comprised the entire lookup, since Ygrave is in the coverage (i.e. union of the first glyphs) of the first subtable. One way to understand this is to imagine a lookup table of kern class pairs as a spreadsheet of all possible pairs of kern left-side classes that are used in the lookup table with all the kern right-side classes that are used in the lookup table. Imagine each left side class is the title of a row in the spreadsheet, and each right side class is the title of a column. A glyph can be put in only one row title, and in only one column title. All glyphs not named in a row title get put together in a special row title. All glyphs not named in a column title get put together in a special column title. When you specify the value of a class pair, you are specifying the value in only one cell of the spreadsheet. When you specify a series of kern pair rules between a particular left side class and a series of right side classes, you are filling in a series of cells in the row for the specific left side class. All cells for which no values are specified are set to 0. When programs look for a kern value between "Ygrave" and something else, they look through the list of left side class definitions to find the first occurrence of 'Ygrave'. By definition, the first spreadsheet row which includes "Ygrave" will define the kern pair value of "Ygrave" with all other right-side classes, e.g spreadsheet columns. Since a pair value with a right-side period has not been explicitly defined at this point, the default value is 0. Since the programs will not look further than this row, the kernclass pair:

pos [Y Yacute Ygrave] period -60; will never be used.

Sometimes the class kerning subtable may get too large. The editor can make it smaller by forcing subtable breaks at any point by inserting the statement:

  subtable;

between two class kerning rules. The new subtable created will still be in the same lookup, so the editor must ensure that the coverages of the subtables thus created do not overlap, since the processing rules will not find and report a conflict.

When seeking to decrease the class table size, it is best to place subtable breaks between blocks of rules where there is no cross linking, such that no left side class in one block is used with any right side class in the other block. However, in most large Western fonts, such groups are so small that breaking them into separate subtables does not yield much decrease in the the overall lookup size. In this common case, an adequate strategy is to first divide the entire list of kern class rules in two roughly equal blocks with a subtable break. If this does not make the class kern tables small enough, then continue to subdivide each block of rules in two with a subtable break. Because the class definitions must be repeated for each subtable, a point of diminishing returns usually comes with around 6 subtable breaks.

6.c. [GPOS LookupType 3] Cursive attachment positioning

[ This LookupType is currently not implemented. ]

A Cursive Pos rule is specified as:

  position cursive <glyph|glyphclass> <anchor>   # Entry anchor
                                      <anchor>;  # Exit anchor

The first <anchor> [§2.e.vi] indicates the entry anchor point for <glyph|glyphclass>; the second, the exit anchor point.

For example, to define the entry point of glyph meem.medial to be at x=500, y=20, and the exit point to be at x=0, y=-20:

  position meem.medial <anchor 500 20> <anchor 0 -20>;

A glyph may have a defined entry point, exit point, or both. <anchor> format D, the null anchor, must be used to indicate that an <anchor> is not defined.

6.d. [GPOS LookupType 4] Mark-to-Base attachment positioning

[ This LookupType is currently not implemented. ]

A Mark-to-Base Pos rule is specified as:

  position <glyph|glyphclass> <anchor>  # base glyph(s) and anchor
           mark <glyph|glyphclass>;     # mark glyph(s)

The keyword "mark" always precedes a <glyph|glyphclass> that is a mark in the rules for GPOS LookupTypes 4-6.

The <anchor> [§2.e.vi] indicates the point on the base glyph(s) to which the mark glyph(s)' anchor point should be attached.

The anchor points of all the mark glyphs must have been previously defined in the feature file by a "mark" statement. The base glyphs must not have been previously defined in "mark" statements.

A mark statement is specified as:

  mark <glyph|glyphclass> <anchor>;

For example, to specify that the anchor of mark glyphs acute and grave is at x=30, y=600, and to position the anchor point of acute and grave at anchor point x=250, y=450 of glyphs a, e, o and u:

  mark [acute grave] <anchor 30 600>;
  position [a e o u] <anchor 250 450>

           mark [acute grave];

6.e. [GPOS LookupType 5] Mark-to-Ligature attachment positioning

[ This LookupType is currently not implemented. ]

A Mark-to-Ligature Pos rule is specified as:

  position <glyph|glyphclass> <anchor> <anchor>+;  # ligature(s) and anchors
           mark <glyph|glyphclass>                 # mark glyph(s)

It is assumed that all ligature glyphs (if there are more than one) in the rule have the same number of components. There must be as many <anchor>s [§2.e.vi] as there are components in a ligature glyph; each <anchor> corresponds, in logical order, to a ligature glyph component. If a particular component does not define an anchor point, then its corresponding <anchor> must be set to the null anchor (<anchor> format D).

There must be at least two <anchor>s since this is the only way this rule is distinguished from a mark-to-base attachment positioning rule [§6.d].

The anchor points of all the mark glyphs must have been previously defined in the feature file by "mark" statements [§6.d].

The example in the OpenType specification for this LookupType could be expressed as:

  # 1. Define mark anchors:
  mark sukun    <anchor 261 488>;
  mark kasratan <anchor 346 -98>;

  # 2. Define mark-to-ligature rules:
  position lam_meem_jeem
           <anchor 625 1800>    # mark above lam
           <anchor NULL>

           <anchor NULL>
           mark sukun;

  position lam_meem_jeem
           <anchor NULL>
           <anchor 376 -368>    # mark below meem
           <anchor NULL>

           mark kasratan;

6.f. [GPOS LookupType 6] Mark-to-Mark attachment positioning

[ This LookupType is currently not implemented. ]

A Mark-to-Mark Pos rule is specified as:

  position mark <glyph|glyphclass> <anchor>  # base mark(s) and + anchor
           mark <glyph|glyphclass>;          # attaching mark(s)

The anchor points [§2.e.vi] of all the attaching marks must have been previously defined in the feature file by "mark" statements [§6.d].

This rule is distinguished from a Mark-to-Base Pos rule [§6.d] by the first "mark" keyword.

The example in the OpenType specification for this LookupType could be expressed as:

  # 1. Define mark anchors:
  mark damma <anchor 189 -103>;

  # 2. Define mark-to-mark rule:
  position mark hanza <anchor 221 301>

           mark damma;

6.g. [GPOS LookupType 7] Contextual positioning

This LookupType is a functional subset of GPOS LookupType 8, chaining contextual positioning. Thus, all desired rules of this LookupType can be expressed in terms of chaining contextual positioning rules.

6.h. [GPOS LookupType 8] Chaining contextual positioning

Positioning rules in this lookup type are supported as of FDK 2.0 [ mark and anchor rules in this lookup type is currently not implemented. ]

6.h.i. Specifying a Chain Pos rule and marking sub-run

A Chain Pos rule describes a target glyph sequence and one or more lookups of any non-contextual lookup type that will be applied to specified sub-runs if the target glyph sequence is matched. The rule is specified as follows:

  position <marked glyph pos sequence>;

<marked glyph pos sequence> is a <glyph sequence> with a marked sub-run that contains <valuerecord>s or <anchor>s (as well as the "cursive" or "mark" keywords, if needed) such that each sub-run and its metrics corresponds in format to any of the non-contextual positioning rules (except for Pair Pos format B).

Only the <glyph|glyphclass>s in a sub-run may be marked. They are marked in the same way as for Chain Sub rules [§5.f]: by single-quotes. The <valuerecord>s, <anchor>s, and "cursive" and "mark" keywords themselves must not be marked.

Example 1:

  position [quoterleft quotedblleft ][Y T]' <0 0 20 0 >  [quoteright quotedblright];
  position [quoterleft quotedblleft ][Y T]' 20  [quoteright quotedblright];

These both increase the advance width of Y or T by 10, when preceded by either quoterleft or quotedblleft, and followed by quoteright quotedblright. Note that not all marked glyph|glyphclass must be followed by a value record; if this is omitted, then the item's positioning info will not be affected. Note that contextual lookups used in a kern feature will be in a different lookup than the pair positioning rules, and hence the two sets of rules will be additive whenever they match the same glyph pair in the text stream. Also, note that you should mark only the glyphs which are positioned in the marked sequence. Example 2:

  position s f' 10 t;
  position s f'10 t' -5 period

The first example specifies a kern pair "ft" when preceded by "s", and increases the x-advance of f by 10. The second species a kern triplet "ft.", when preceded by "s". The x-advance of f is increased by 10, and the xadvance of t is decreased by 5. The entire run of marked glyphs will be consumed by a rule; in the first case, after matching this rule, the set of rules in current lookup will next be applied starting at the glyph "t". In the second case, the rules will next be applied starting at the glyph "period". Example 3:

  position lam_meem_jeem'                       # First sub-run..
           <anchor 625 1800> <anchor NULL> <anchor NULL>

           mark sukun'                          # 
           alef' <5>;                            # 

The first sub-run and its anchors will be identified by the feature file parser as describing a Mark-to-Ligature Pos lookup. The second sub-run and its corresponding value record will be identified as describing a Single Pos lookup. These two lookups will be applied during OpenType layout only when the target context of the entire rule is matched.

6.h.ii. Specifying exceptions to the Chain Pos rule

Exceptions to a chaining contextual positioning rule are expressed by inserting a statement of the following form anywhere before the chaining contextual rule and in the same lookup:

  ignore position <marked glyph sequence> (, <marked glyph sequence>)*;

This rule works in exactly the same was as specifying exceptions to a chaining contextual substitution rule [§5.f.ii].

6.i. [GPOS LookupType 9] Extension positioning

The "useExtension" keyword specifies creating lookups of this lookup type. See §4.e.

7. Ordering of lookups and rules in the feature file

7.a. An OpenType Layout engine's layout algorithm

The following is a reference summary of the algorithm used by an OpenType layout (OTL) engine to perform substitutions and positionings. The important aspect of this for a feature file editor is that each lookup corresponds to one "pass" over the glyph run (see step 4 below). Thus, each lookup has as input the accumulated result of all previous lookups in the LookupList (whether in the same feature or in other features).

  1. All glyphs in the client's glyph run must belong to the same language
     system. (Glyph sequence matching may not occur across language
     systems.)

  --- Do the following first for the GSUB and then for the GPOS: ---

  2.  Assemble all features (including any required feature) for the glyph
      run's language system.

  3.  Assemble all lookups in these features, in LookupList order, removing
      any duplicates. (All features and thus all lookups needn't be applied to
      every glyph in the run.)

  4.  For each lookup:

  5.     For each glyph in the glyph run:

  6.        If the lookup is applied to that glyph and the lookupflag
            doesn't indicate that that glyph is to be ignored:

  7.           For each subtable in the lookup:

  8.              If the subtable's target context is matched:

  9.                 Do the glyph substitution or positioning,
                     --- OR: ---
                     If this is a (chain) contextual lookup do the
                     following [(10)-(11)] in the subtable's
                     Subst/PosLookupRecord order:

  10.                For each (sequenceIndex, lookupListIndex) pair:

  11.                  Apply lookup[lookupListIndex] at input
                       sequence[sequenceIndex] [steps (7)-(11)]

  12.                Goto the glyph after the input sequence matched in (8)
                     (i.e. skip any remaining subtables in the lookup).

The "target context" in step 8 above comprises the input sequence and any backtrack and lookahead sequences.

The input sequence must be matched entirely within the lookup's "application range" at that glyph (that contiguous subrun of glyphs including and around the current glyph on which the lookup is applied). There is no such restriction on the backtrack and lookahead sequences.

"Matching" includes matching any glyphs designated to be skipped in the lookup's LookupFlag.

7.b. Ordering of lookups and subtables

A lookup in the OpenType font will be created from each named lookup block [§4.e] or each run of rules with the same feature, script, language, lookupflag and lookup type attribute.

Lookups will be created in the GSUB/GPOS table's LookupList in the same order as the corresponding named lookup blocks or runs of rules in the feature file, except for the lookups that comprise the 'aalt' feature. These will always be created before all other features [§8.a].

A lookup may contain one or more subtables. Subtable breaks may have been inserted by the implementation software due to format restrictions, or they may have been explicitly requested by the editor [§4.f]. In either case, subtables will be created in the same order as the corresponding subtables in the feature file, if the order is relevant to OT layout. If the order is irrelevant, the implementation may choose to order subtables within a lookup in any manner.

Note that the lookup sharing mechanism (i.e. a "lookup" reference statement that refers to a named lookup block) is implemented simply by referring to the LookupList index of the lookup as many times as needed in the Feature tables.

7.c. Ordering of rules within a lookup

In the feature file, the ordering of rules within a lookup is important only for chaining contextual substitution and chaining contextual positioning rules. This is because in all other cases of LookupTypes (including ligature substitutions; see section 5.d), the appropriate ordering can be automatically deduced.

8. Specially handled features

8.a. The all alternates ('aalt') feature

The allt feature consists of a feature definition block which contains a series of statements in the form:

     feature <feature tag>;

followed by one or more single and alternates substitution rules.

The feature file parser should create the 'aalt' feature from the feature file definition as follows:

  1. Considering only features indicated by:

      feature <feature tag>;
    

    in the 'aalt' specification feature block (see example below), combine all single and alternate substitutions in those features (including single substitutions that appear within a chaining contextual rule) into groups with the first glyph in the group being the target glyph of the substitution. Subsequent elements of the group will be ordered by the order of the relevant rule in the feature file. Duplicate glyphs will be removed.

    The 'aalt' feature block must appear before the feature block of any <feature tag> it references in the above manner. It will also always be created as the first feature in the font (i.e. its lookups will be at the beginning of the GSUB LookupList).

  2. Add any additional single and alternate substitutions in the 'aalt' specification to the groups that were created algorithmically, by step (i). This facility is provided to fine-tune the semantic groups, for instance, if certain glyphs weren't referenced in any of the features indicated in (i) above. This can also be used to override substitutions specified by including other features: for any target glyph, the alternate glyphs specified by this mechanism precede in order any other alternate glyphs.
  3. If there are only two glyphs in a group, create a single substitution in the 'aalt' feature, with the first glyph being the target glyph and the second glyph being the replacement glyph. If there are more than two glyphs in a group, create an alternate substitution in the 'aalt' feature, with the first glyph being the target glyph and the remaining glyphs being the alternate set. These alternate glyphs will be sorted in the order that the source features are named in the 'aalt' definition, not the order of the feature definitions in the file. Alternates defined explicitly, as in step (ii) above, will precede all others.

The "useExtension" keyword:

The "useExtension" keyword may optionally precede "{" in the feature block syntax. The 'aalt' lookups will be created with the GSUB Extension lookup type if and only if the "useExtension" keyword is used. Note that since the Extension lookup types were added in OpenType specification v1.3, they will not be recognized by all OpenType layout parsers.

Specifying language system:

This feature will be registered under all language systems specified by "languagesystem" statements; see §4.b.i above.

The following are not allowed in the 'aalt' feature definition: "script", "language", "lookupflag", and "subtable" statements; named lookup blocks and lookup reference statements. The 'aalt' lookups will be created with LookupFlag 0.

Examples:

  languagesystem DFLT dflt;
  languagesystem latn dflt;
  languagesystem latn TRK;
  languagesystem cyrl dflt;

  feature aalt {
     feature SALT;
     feature smcp;
     substitute d by d.alt;
  } aalt;

  feature smcp {
     sub [a-c] by [A.sc-C.sc];
     sub f i by fi;     # not considered for aalt
  } smcp;

  feature SALT {
     sub a from [a.alt1 a.alt2 a.alt2];
     sub e [c d e] f by [c.mid d.mid e.mid];
     sub b by b.alt;
  } SALT;

The 'aalt' lookups from the above example will be registered under the default language systems of the 'DFLT', 'latn' and 'cyrl' scripts, and also under the 'latn'/'TRK ' language systems. The 'aalt' created would be the same as if the font editor had specified:

  feature aalt {
     sub a from [a.alt1 a.alt2 a.alt3 A.sc];
     sub b from [b.alt B.sc];
     sub c from [c.mid C.sc];
     sub d from [d.alt d.mid];
     sub e by e.mid;
  } aalt;

The following example will result in the 'aalt' lookups being created with the GSUB Extension lookup type:

  feature aalt useExtension {
     feature SALT;
     feature smcp;
     substitute d by d.alt;
     # ... other rules
  } aalt;

8.b. The optical size ('size') feature

This feature is unique in that it contains no substitution or positioning rules (the LookupCount field in its Feature table will always be 0).

The feature's data is accessed instead through the FeatureParams value of its Feature table.

Thus, the syntax for this feature is different from all other features. The feature block must contain:

No other feature file statements, blocks or keywords are permitted. (Comments are allowed.)

This feature will be created in the GPOS table and will be registered under all language systems specified by "languagesystem" statements (see §4.b.i above).

For example:

  feature size {
     parameters 100  # design size (decipoints)
                  3  # subfamily identifier
                 80  # range start (exclusive, decipoints)
                139; # range end (inclusive, decipoints)
     sizemenuname "Win MinionPro Size Name";
     sizemenuname 1 "Mac MinionPro Size Name";
     sizemenuname 1 21 0 "Mac MinionPro Size Name";
  } size;

See the OpenType feature tag registry for a description of the "parameters" statement fields. " decipoints" is a unit of 1/10 of a point.

These values may also be specified more directly as decimal point values, but a decimal point and following value is then required. For example, "8.0" and "80" will both result in the same value being stored in the font.

The parameter "sizemenuname" provides the menu name to be used for a group of fonts with the same subfamily identifier.

If the font is part of such a group, then the "sizemenuname" statement must be provided in order for the members of the group to be grouped together in a sub-menu under the specified menu name.

In the this case, we strongly recommend providing at least the two entries for Windows and Macintosh platform Roman script name strings. You may also include as any another localized name strings that may be useful.

If the font is not part of such a group, then the "sizemenuname" statement must be omitted, and all fields but the first (design size) for the parameter statement must be set to 0.

This can be used to indicate the intended design size for a font, even when it is not part of an optical size group.

The syntax of the "sizemenuname" statement follows that of the name table name strings, as described in §9.e.

The names specified by the "sizemenuname" statement are actually stored in the name table, with name ID's starting at the first unused name ID at or after 256.

9. Specifying or overriding table values

In addition to GSUB and GPOS OpenType layout features, the feature file provides for specifying or overriding values in certain other tables. These are specified within the corresponding table block:

  table <table tag> {
     # ...
  } <table tag>;

The following table values are currently supported:

9.a. BASE table

If no BASE table entry is specified in the feature file, no BASE table is created in the OpenType font.

  table BASE {
     HorizAxis.BaseTagList    <baseline tag>+;
     HorizAxis.BaseScriptList <script record> (, <script record>)*;
     HorizAxis.MinMax         <minmax>;

     VertAxis.BaseTagList     <baseline tag>+;
     VertAxis.BaseScriptList  <script record> (, <script record>)*;
     VertAxis.MinMax          <minmax>;
  } BASE;

A <script record> is of the form:

  <script tag> <default baseline tag> <base coord>+

<base coord> can take several formats: [ Currently only format A is implemented ]

  <number>                               # format A
  <number> <glyph> <number>              # format B
  <number> <device>                      # format C

The baseline tags for each BaseTagList must be sorted in increasing ASCII order.

The number of baseline values for a particular script should be the same as the same as the number of baseline tags in the corresponding BaseTagList.

A <minmax> [ currently not implemented ] is of the form:

  <script tag> <language tag>   # Defines the language system
       <base coord>,            # Min value for this language system
       <base coord>             # Max value for this language system
       [, <feature tag>         # (Optional) feature tag
          <base coord>,         # Min value for this feature tag
          <base coord>]         # Max value for this feature tag
       ;

For example:

  table BASE {
     HorizAxis.BaseTagList                   ideo romn;
     HorizAxis.BaseScriptList  latn   romn   -120    0,
                               cyrl   romn   -120    0,
                               grek   romn   -120    0,
                               hani   ideo   -120    0,
                               kana   ideo   -120    0,
                               hang   ideo   -120    0;
  } BASE;

9.b. GDEF table

[ Currently not implemented. ]

  table GDEF {
     GlyphClassDef <glyphclass>    # simple glyphs
                   <glyphclass>    # ligature glyphs
                   <glyphclass>    # mark glyphs
                   <glyphclass>;   # component glyphs

     Attach        <glyph|glyphclass> <number>+;
                                   # <number> is a contour point index

     LigatureCaret <glyph|glyphclass> <caret value>+;
  } GDEF:

The number of <caret value>s specified for a LigatureCaret must be: (number of ligature components) - 1.

Here is an example of a GDEF table block:

  table GDEF {
     GlyphClassDef @SIMPLE @LIGATURES @MARKS @COMPONENT;
     Attach noon.final 5;
     Attach noon.initial 4;
     LigatureCaret ffi <caret 380> <caret 760>;
  } GDEF;

9.c. head table

The head table FontRevision value is used as the overall font version number, and should be incremented whenever any data in the fonts is changed. It is both specified and reported as a decimal number with three significant decimal places. The actual value stored in the font will, however, be a Fixed number (16.16 bit format). Due to the limited precision of this format, the value stored may differ by a small decimal fraction from that specified, but will always round to the same value when rounded to three fractional decimal places.

This value is also used as the source for the font version string in the name table name string ID 5 "Version".

  table head {
     FontRevision <fixed point number with three fractional decimal places>;
  } head;

Example 1:

  table head {
     FontRevision  1.1;
  } head;

This format is supported, but will cause a warning that the specification will be converted to "1.100". It will be stored in the font as 0x0001199A. A more exact decimal representation would be 1.10000610352, but it will be reported as "1.100".

Example 2:

  table head {
     FontRevision  1.001;
  } head;

This value be stored in the font as 0x00010042. A more exact decimal representation is 1.001007, but it will be reported as "1.001".

Example 3:

  table head {
     FontRevision  1.500;
  } head;

This value be stored in the font as 0x00018000, and will be reported as "1.500". The decimal and Fixed values are equal in this case.

9.d. hhea table

  table hhea {
     CaretOffset <metric>;
     Ascender <metric>;
     Descender <metric>;
     LineGap <metric>;
  } hhea;

For example:

  table hhea {
     CaretOffset -50;
     Ascender 800;
     Descender 200;
     LineGap 200;
  } hhea;

9.e. name table

  table name {
     # name records
  } name;

A name record is of the form:

  nameid <id> [<string attribute>] <string>;

An <id> is a number specifying the id of the name string to be added to the name table. This number must be in the registered id range 0, 7-255. Note that ids 1-6 (Family, Subfamily, Unique, Full, Version, and FontName) are reserved by the implementation and cannot be overridden; doing so will elicit a warning message and the record will be ignored.

An optional <string attribute> is one or three space delimited numbers that specify the platform, platform-specific, and language ids to be stored in the name record of the name table. If only one number is specified it represents the platform id. The platform id may be either 1 or 3, corresponding to the Macintosh or Microsoft (hereafter called Windows) platforms, respectively. The other id numbers must be in the range 0-65535 but are not otherwise validated.

Decimal numbers must begin with a non-0 digit, octal numbers with a 0 digit, and hexadecimal numbers with a 0x prefix to numbers and hexadecimal letters a-f or A-F.

If some or all of the string attribute id numbers aren't specified their values are defaulted as follows:

  platform id      3 (Windows)

Windows platform selected:

  platspec id      1 (Unicode)
  language id      0x0409 (Windows default English)

Macintosh platform selected:

  platspec id      0 (Roman)
  language id      0 (English)

Putting this all together gives the following valid nameid formats and the ids that are assigned.

  representation              id  platform id platspec id language id
  --------------------------- --- ----------- ----------- -----------
  nameid I <string>;          I   3           1           0x0409
  nameid I 3 <string>;        I   3           1           0x0409
  nameid I 3 S L <string>;    I   3           S           L

  nameid I 1 <string>;        I   1           0           0
  nameid I 1 S L <string>;    I   1           S           L

A string is composed of 1-byte ASCII characters enclosed by ASCII double quote characters ("). Newlines embedded within the string are removed from the character sequence to be stored.

Strings are converted to Unicode for the Windows platform by adding a high byte of 0. 2-byte Unicode values for the Windows platform may be specified using a special character sequence of a backslash character (\) followed by exactly four hexadecimal numbers (of either case) which may not all be zero, e.g. \4e2d. The ASCII backslash character must be represented as the sequence \005c or \005C and the ASCII double quote character must be represented as the sequence \0022.

There is no corresponding conversion to Unicode for the Macintosh platform but character codes in the range 128-255 may be specified using a special character sequence of a backslash character (\) followed by exactly two hexadecimal numbers (of either case) which may not both be zero, e.g. \83 . The ASCII blackslash character must be represented as the sequence \5c or \5C and the ASCII double quote character must be represented as the sequence \22.

Example (add designer's name that includes non-ASCII characters for Mac and Windows platforms):

  table name {
     nameid 9 "Joachim M\00fcller-Lanc\00e9";    # Windows (Unicode)
     nameid 9 1 "Joachim Mu\9fller-Lanc\8e";     # Macintosh (Mac Roman)
  } name;

9.f. OS/2 table

  table OS/2 {
     FSType        <number>;
     Panose        <panose number>;
     UnicodeRange  <Unicode range list>;
     CodePageRange <code page list>;
     TypoAscender  <metric>;
     TypoDescender <metric>;
     TypoLineGap   <metric>;
     winAscent     <metric>;
     winDescent    <metric>;
     XHeight       <metric>;
     CapHeight     <metric>;
     WeightClass   <number>;
     WidthClass    <number>;
     Vendor        <string>;
  } OS/2;

Vendor should 4 character-long. If a shorter vendor id is given, it is automatically padded with spaces. A longer vendor id causes an error.

<panose number> is ten (decimal) numbers separated by white space. For <Unicode range list> is a whitespace-separated list of Unicode bit numbers from the OpenType specification for the ulUnicodeRange1-4 in the OS/2 table. <code page list> is a whitespace-separated list of Windows code page numbers from the OpenType specification for the ulCodePageRange1-2 in the OS/2 table. Example:

  table OS/2 {
     FSType         4;
     Panose         2 15 0 0 2 2 8 2 9 4;
     TypoAscender   800;
     TypoDescender -200;
     winAscent      832;
     winDescent     321; # Note that winDescent is positive for descent below the baseline.
     TypoDescender -200; # Note that TypoDescender is negative for descent below the baseline.
     UnicodeRange    0   # Basic Latin
	                       1   # Latin-1 Supplement
	                       9   # Cyrillic
	                       55  # CJK Compatibility
	                       59  # CJK Unified Ideographs
	                       60  # Private Use Area
	                       ;
     CodePageRange   1252    # Latin 1
                            1251    # Cyrillic
                            932     # JIS/Japan
                            ;
     XHeight        400;
     CapHeight      600;
     WeightClass    800;
     WidthClass     3;
     Vendor         "ADBE";
  } OS/2;

Note that that for the code page ranges, the list numbers may be separated by any amount of white space. Note that the terminal semi-colon cannot follow a comment character on a line, as all text on a line following the comment character is removed before processing.

9.g. vhea table

  table vhea {
     VertTypoAscender  <number>;
     VertTypoDescender <number>;
     VertTypoLineGap   <number>;
  } vhea;

For example:

  table vhea {
     VertTypoAscender   500;
     VertTypoDescender -500;
     VertTypoLineGap   1000;
  } vhea;

9.h. vmtx table

In OpenType, each glyph may have a unique vertical origin y coordinate and a unique vertical advance width. By default, for each glyph the vertical origin y coordinate is set to the value of the OS/2.TypoAscender field, and the vertical advance width is set to the distance between the values of the of OS/2.TypoAscender and the OS/2.TypoDescender. However, other values may be assigned to a glyph as follows:

  table vmtx {
     VertOriginY <glyph> <number1>;
     VertAdvanceY <glyph> <number2>;
  } vmtx;

This would result in the glyph's vertical origin Y coordinate and the glyph's vertical advance width being set as shown. The value set here for the vertical origin Y coordinate will also set the topSideBearing value in the 'vmtx' table and the vertical origin y value in the 'VORG' table for the named glyph.

For example:

  table vmtx {
     VertOriginY  \711  864;
     VertOriginY  \712  867;
     VertOriginY  \713  866;
  } vmtx;

A special case for the vertical advance width is the set of glyphs referenced by the 'vrt2' feature. The default vertical advance for these glyphs is the horizontal advance of their corresponding target (upright) glyphs. These values will also be overridden by VertAdvanceY values.

10. Specifying anonymous data blocks

The feature file can contain "anonymous" tagged blocks of data that must be passed back to the client of the implementation software. These blocks of data typically contain information needed to specify custom or unsupported tables. The parser will not attempt to parse the data. Each such block is specified as follows:

  anonymous <tag> {
     # ...
  } <tag>;

Note: the keyword "anonymous" can be abbreviated as "anon". For example:

  anon sbit {
     /* sbit table specifications */
     72  % dpi
     sizes {
        10, 12, 14 source {
            all "Generic/JGeneric"
        }
     }
  } sbit;

The closing brace, tag, and semicolon must all be on the same line to indicate the end of the anonymous block to the parser. White space may be used between tokens on this line, and a comment may follow the semicolon. The "include" directive will not be recognized within the block, starting from "anonymous" and ending at the end of the closing line, so the entire block must exist within the same file.

The data that is passed back to the client starts at the beginning of the line after the opening brace and ends at (and includes) the newline before the closing brace. In the example above, the client is passed back the following data:

  /* sbit table specifications */
  72  % dpi
  sizes {
     10, 12, 14 source {
        all "Generic/JGeneric"
     }
  }

along with the tag 'sbit'.

11. Document revisions

The HOT library version numbers below refer to the version of the Adobe implementation (Hatch OpenType) of the feature file grammar.

v1.7 [25 Oct 2006]:

v1.6 [28 March 2006]:

v1.5 [23 November 2005]:

v1.4 [23 January 2003; supported by HOT library v01.00.36]:

v1.3 [23 May 2002]:

v1.2 [7 March 2001; HOT library v01.00.29]:

v1.1 [1 December 2000; HOT library v01.00.28]:

v1.0 [29 September 2000; HOT library v01.00.24]:

v0.9 [25 April 2000; HOT library v01.00.23]:

v0.8 [24 February 2000; HOT library v01.00.23]:

v0.7 [11 October 1999; HOT library v01.00.22]:

v0.6 [22 March 1999; HOT library v119]:

v0.5 [29 January 1999]:

v0.4 [20 January 1999]:

v0.3 [9 October 1998]:

v0.2 [18 March 1998]:

v0.1 [6 February 1998]: First version