`pyftsubset` gives missing glyphs exception when using single hyphens for CLI args

[otherjoel]

The docs seem to indicate that some arguments (such as the unicodes argument, as well as glyphs) should be given with one hyphen, and others with two hyphens.

I spent a couple of days trying to figure out why I was getting exceptions for missing glyphs, such as below:

❯ pyftsubset Courier\ Prime.ttf -glyphs='*' --verbose -layout-features='*' --flavor="woff2" --output-file="reg.woff2" 
Text: ''
Unicodes: []
Glyphs: ['-glyphs=*', '-layout-features=*']
Gids: []
maxp pruned
cmap pruned
post pruned
name pruned
glyf pruned
Missing requested glyphs: {'-layout-features=*', '-glyphs=*'}
Traceback (most recent call last):
  File "/opt/homebrew/bin/pyftsubset", line 8, in <module>
    sys.exit(main())
  File "/opt/homebrew/lib/python3.10/site-packages/fontTools/misc/loggingTools.py", line 372, in wrapper
    return func(*args, **kwds)
  File "/opt/homebrew/lib/python3.10/site-packages/fontTools/subset/__init__.py", line 3241, in main
    subsetter.subset(font)
  File "/opt/homebrew/lib/python3.10/site-packages/fontTools/subset/__init__.py", line 3047, in subset
    self._closure_glyphs(font)
  File "/opt/homebrew/lib/python3.10/site-packages/fontTools/subset/__init__.py", line 2855, in _closure_glyphs
    raise self.MissingGlyphsSubsettingError(self.glyphs_missing)
fontTools.subset.Subsetter.MissingGlyphsSubsettingError: {'-layout-features=*', '-glyphs=*'}

I finally stumbled on the fix, which was to use two hyphens for all arguments (so, --glyphs instead of -glyphs), contra the docs.

Can/should the documentation be updated to reflect this? I’ve been out of Python for a while, so I don’t know if there is some historical reason why some options were documented this way.

I’m using Python 3.10 under ZSH on Mac OS 12.6 (Monterey) on ARM64.

[behdad]

The docs seem to indicate that some arguments (such as the unicodes argument, as well as glyphs) should be given with one hyphen, and others with two hyphens.

That's a bug in the docs.

[behdad]

I don't know why the rendered docs come out that way. The sources are correct:

fonttools/Lib/fontTools/subset/__init__.py

Line 59 in 5a0dc4b

--gids=<NNN>[,<NNN>...]

[khaledhosny]

For some reason, some of the -- got turned into U+2013 (en dash). Looks like some of these “helpful” formatters. What is odd is that some, but not all of them got converted.

[khaledhosny]

looks like options that has square brackets get treated as general text and use proportional font not monospaced one like the others.

[otherjoel]

Yes, it feels like the square brackets are breaking a regex somewhere.

Quickest fix, then, would be to make some simple edits to the docstring:

1. Remove square brackets around optional values, e.g. change --gids=<NNN>[,<NNN>...] to --gids=<NNN>,<NNN>.... While the former is more correct, I think people would intuitively understand that multiple NNN is not required.
2. Move any case of [default] that occurs directly after the option to the end of its description instead (example: --ignore-missing-unicodes). Other options already use this convention, so this would make everything more consistent anyway.

I squinted at the RST syntax for option lists but am still not sure if there is a more idiomatic method for showing optional values in RST.

Another approach would be to disable “smart” processing for dashes altogether by setting the smartquotes_action option to qe instead of the default qDe.

[pjg11]

Yes, it feels like the square brackets are breaking a regex somewhere.

It's not just brackets, even ellipses and commas seem to break it, based on the documentation for option lists:

Option arguments may take one of two forms:

• Begins with a letter ([a-zA-Z]) and subsequently consists of letters, numbers, underscores and hyphens ([a-zA-Z0-9_-]).
• Begins with an open-angle-bracket (<) and ends with a close-angle-bracket (>); any characters except angle brackets are allowed internally.

In the first form (which applies to the --unicodes flag), the regex doesn't include commas, ellipses or brackets.

For the flag to display correctly, it could be re-written as --unicodes=<XXXX[,XXXX...]>, which matches the second form. The rewritten form seems to render correctly in a local build, though I'm not sure if this is an idiomatic way of writing this.