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

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.

[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.