More examples / --help messages?

[hlein]

I've just started using gpyutils to help move my overlay and p-m'd packages to python3_12, and they're helping a lot but I definitely had some learning curve issues.

The main README.md is a great overview of each tool but only provides examples for a few of them. These strike me as tools written for and by an expert in their use, which, fair enough, but it would be really useful to have more thorough examples or a wiki walking through using them for some maintenance work, or something.

I started running each with -h / --help but the behavior is inconsistent; here's a rundown of ones that don't provide a usage message and/or aren't mentioned in README.md:

$ for A in $(equery f gpyutils | egrep /usr/bin/) ; do echo $A ; $A --help ; done >gpyutils_help 2>&1
/usr/bin/gpy-list-pkg-impls
app-accessibility/accerciser:0           EAPI: 8           STABLE: 3.10 3.11
app-accessibility/brltty:0               EAPI: 8           STABLE: 3.10 3.11 3.12
# ...
# what? Also this is not mentioned in README.md
/usr/bin/gpy-pkgs-with-newest-stable
acct-group/_cron-failure
acct-group/adm
# ...
# same same
/usr/bin/gpy-release-feed-opml
usage: /usr/lib/python-exec/python3.11/gpy-release-feed-opml
# ... yay! Although, not mentioned in README.md
/usr/bin/gpy-showimpls
Traceback (most recent call last):
  File "/usr/lib/python3.11/site-packages/pkgcore/ebuild/atom.py", line 298, in __init__
    sf(self, "_cpv", cpv.CPV(self.cpvstr, versioned=bool(self.op)))
                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
# oof!
/usr/bin/gpy-to-pypi-eclass
usage: /usr/lib/python-exec/python3.11/gpy-to-pypi-eclass [-h] [-a] [data]
# ... yay! But not mentioned in README.md
/usr/bin/gpy-verify-deps
^[[36mPopulating package cache...^[[0m
^[[2K^[[32m...
# ... ouch. No -h and also color seems unconditional even when not a TTY, and no -C support.