Document lib keys modifying ufo2ft's behavior

[madig]

Tackle #240.

Stub stub.

• Write explanation, example and when (not) to use blurb for every filter.
• Include explanation of feature writer modification in Extra lookup in 'kern' feature introduced in ufo2ft v2.0.0 #280 (comment).
• Maybe turn this into Sphinx documentation if it grows too unwieldy?

PS: You can copy-paste it into e.g. https://livesphinx.herokuapp.com/ to get a rendered preview.

[madig]

Oops, missed conversionError and reverseDirection. I think I was looking for conversionError actually (googlefonts/cu2qu#158). The setup of the filter chain is... convoluted. compileTTF shadows TTFPreProcessor shadows CubicToQuadraticFilter...

[madig]

Oops once more, pre and post mean:

    Custom filters can be applied before or after the default filters.
    These are specified in the UFO lib.plist under the private key
    "com.github.googlei18n.ufo2ft.filters".

[arrowtype]

This is really helpful; thanks for starting it!

I have a question that I’m unsure about, even after looking at your docs and the UFO spec:

How would I add multiple ufo2ft filters?

For example, I’d like to add both the flattenComponents filter to nested components and the decomposeComponents filter to a specific list of glyphs.

This seems to work, mostly (but has a partially unexpected result for the flattenComponents filter, whether or not I use the decomposeComponents filter):

<key>com.github.googlei18n.ufo2ft.filters</key>
<array>
    <dict>
        <key>name</key>
        <string>flattenComponents</string>
        <key>pre</key>
        <integer>1</integer>
    </dict>
    <dict>
        <key>name</key>
        <string>decomposeComponents</string>
        <key>include</key>
        <array>
          <string>quotesingle</string>
          <string>quotedbl</string>
          <string>quoteleft</string>
          <string>quoteright</string>
          <string>quotedblleft</string>
          <string>quotedblright</string>
          <string>quotesinglbase</string>
          <string>quotedblbase</string>
        </array>
    </dict>
</array>

In Python:

    font.lib["com.github.googlei18n.ufo2ft.filters"] = [
            {
            'name': 'flattenComponents', 
            'pre': 1
            },
            {
            'name': 'decomposeComponents', 
            'include': "quotesingle quotedbl quoteleft quoteright quotedblleft quotedblright quotesinglbase quotedblbase".split()
            },
    ]

[madig]

Right on the money, except 'include' should be a ["list", "of", "str"]. I don't know how filters interact with each other. I think they are run in order?

[anthrotype]

I think they are run in order?

yep

[chrissimpkins]

Does it matter that pre key is defined with:

Stephen's approach

<key>pre</key>
<integer>1</integer>

instead of:

documentation approach

<key>pre</key>
<true />

?

[madig]

Don't think so. Both evaluate to True

[arrowtype]

'include' should be a ["list", "of", "str"].

I ended my string with .split() and ran this in a RoboFont script, so it seems to work, though I am surprised by two things:

1. include gets sorted before the name. Should it?
2. The order I place things in my Python doesn’t get preserved in the lib.

		<key>com.github.googlei18n.ufo2ft.filters</key>
		<array>
			<dict>
				<key>include</key>
				<array>
					<string>quotesingle</string>
					<string>quotedbl</string>
					<string>quoteleft</string>
					<string>quoteright</string>
					<string>quotedblleft</string>
					<string>quotedblright</string>
					<string>quotesinglbase</string>
					<string>quotedblbase</string>
				</array>
				<key>name</key>
				<string>decomposeComponents</string>
			</dict>
			<dict>
				<key>name</key>
				<string>decomposeTransformedComponents</string>
				<key>pre</key>
				<integer>1</integer>
			</dict>
			<dict>
				<key>name</key>
				<string>flattenComponents</string>
				<key>pre</key>
				<integer>1</integer>
			</dict>
		</array>

My RoboFont script, in case it’s relevant (Click to expand)

from vanilla.dialogs import *

inputFonts = getFile("select UFOs", allowsMultipleSelection=True, fileTypes=["ufo"])

for fontPath in inputFonts:
    font = OpenFont(fontPath, showInterface=False)

    # for other font info attributes, see
    # http://unifiedfontobject.org/versions/ufo3/fontinfo.plist/

    font.info.openTypeOS2VendorID = "ARRW"

    font.info.copyright = "Copyright 2017-2020 Arrow Type"

    # un-nest nested components # https://github.com/googlefonts/fontbakery/issues/296
    font.lib["com.github.googlei18n.ufo2ft.filters"] = [
            {
            'name': 'decomposeComponents', 
            'include': "u b q d p arrowleft arrowup arrowright arrowdown arrowrighttail arrowlefttailfeather arrowlefttriangle \
                        nine Adieresis.titl Odieresis.titl Udieresis.titl Odieresis.RECT_titl Udieresis.RECT_titl \
                        quotesingle quotedbl quoteleft quoteright quotedblleft quotedblright quotesinglbase quotedblbase".split()
            },
            {
            'name': 'decomposeTransformedComponents', 
            'pre': 1
            },
            {
            'name': 'flattenComponents', 
            'pre': 1
            },
    ]

    print("Updated info for:")
    print("family: ", font.info.familyName, "\n ", "style: ", font.info.styleName)

    font.save()
    font.close()

[madig]

Plists keys are sorted alphabetically.

[anthrotype]

Plists keys are sorted alphabetically.

right, but an array (of dicts, or whatever) should keep the order.And the filter order matters

[madig]

But looking at the script the filters are in order?