[docs] Document feaLib
* Rearrange docs by user intention, highlighting the things you can do with each component.
* Remove reference to lexer and error modules from documentation tree, since they’re not user-facing.
* I’ve added docstrings to the parser even though we only provide access to the user-facing part of the API in the main documentation, just to clarify what some of the more obscure methods do and provide links to the spec.
* AST *is* user-facing if you’re building your own feature files in code, so all classes are documented with the user in mind.
This allows for more than one "lookup ..." chaining statements at each glyph position in a chaining contextual substitution or positioning rule: e.g.
sub a b c' lookup lookup1 lookup lookup2 d;
The corresponding change in the Adobe OpenType Feature File Specification (and implementation in makeotf) happened in adobe-type-tools/afdko#1132.
This checks that glyph names that appear in a feature file are actually
in the glyph set provided in glyphNames. If the set is empty, no check
is done. This preempts a KeyError later during saving of a TTFont object
and makes this case much more easily catchable.
Closes#1723.
If the single substitution involved a glyph class, we were incorrectly
using only the first glyph in the class.
Broken since ec6ff821f0e72022d7aec8794b6bb589d8f81808, apparently no one
else uses this feature!
This would make it easier to construct feaLib AST from code,
where the location is not defined and thus should be None.
Also, we can make other arguments as kwargs with a default
value, now that the first parameter is no longer 'location'.
Currently, the feature file parser always resolves included files,
parses their content and inserts it in the resulting AST. The original
`include` statement is lost.
This commit introduces an option to not follow inclusions. Instead, the
output AST will contain an `include` statement. This allows to process a
feature file on its own, and allows to round-trip it.
For example in glyphsLib, when going from a UFO to a .glyphs file, a
UFO feature file will be sliced up into Glyphs.app classes (e.g. a
GSFeaturePrefix with code `include(../family.fea);`) and when going back
from .glyphs to UFO, the feature file will be patched back together.
A multiple substitution may have a single destination, in which case
it will look just like a single substitution. So if there are both
multiple and single substitutions, upgrade all the single ones to
multiple substitutions. Previously we would just give an error message
in the builder and abort, which means certain valid OpenType lookups
can’t be represented by feature files.
This is the same logic implemented by FontForge (actually the
explanation above is almost copied verbatim from its source), makeotf
does not do this AFAIK but I consider it a bug not a feature.
Fixes https://github.com/fonttools/fonttools/issues/612
As Martin Hosken reported in https://github.com/fonttools/fonttools/pull/1096,
feaLib currently incorrectly handles the case where a marked input
glyph sequence in a contextual chaining sub/pos rule is split into
multiple runs, rather than being a single continuous run of ' marked
glyphs.
The consensus there was to raise a syntax error like makeotf instead of
second-guessing and silently fixing it like fontforge does.
... instead of a glyphMap dict.
The parser does not actually need a reverse glyph order mapping as
it is not interested in knowing the glyphID from the glyph name,
but only whether a glyph is in the font or not.
This makes it easier for client code (e.g. ufo2ft feature compiler)
to use the feaLib Parser, without having to first construct and pass
it a glyphMap argument.
Before this change, the following glyph class:
@Vowels = [@Vowels.lc @Vowels.uc y Y];
Would be written back as:
@Vowels = [@Vowels.lc = [a e i o u]; @Vowels.uc = [A E I O U]; y Y];
Which is clearly invalid. It seems for GlyphClass.asFea() to work
correctly here we should be using GlyphClassName not GlyphClass
for the nested classes (similar to the code at the beginning of
parse_glyphclass_()).
The syntax tree representation now reflects the syntax of feature files.
Before this change, FeatureNames did not have their own `ast.Block`,
which had made the code quite messy.
Before this change, some table statements would allow empty statements
(just a semicolon) while others would not allow them. After this change,
we're more consistent.
