Add better documentation for upt, maybe single command

[mojca]

First of all (as an independent task) it would make sense if at the end we end up with upt as a standalone command, not just upt-3.7, but independent of that ...

I never know how to call upt. So I'm always confused by how little information I get by typing upt -h. This is semi-useless unless you already know what you are supposed to do:

usage: upt [-h] {list-backends,list-frontends,package} ...

I pause a bit and start thinking what to do. Then I figure out I should probably be using package, and then I need a couple of more commands to get the help for package. But then I mix the frontends and the backends, so another two calls just to confirm what is a frontend and what is a backend.

I would like to have either a complete man page, or the above command could at least automatically already list the available frontends and backends and immediately show

usage:
upt package [-h] -f FRONTEND -b BACKEND [--debug] [-o OUTPUT] [-q] package

plus some extra info.

On a somewhat unrelated matter, using cpan2port and pypi2port is somewhat more intuitive. Just a single command with autocompletion that replaces all of the

upt package -f pypi -b macports -o <something>

I wish we had some shortcuts to call when we want to create a package for macports. Something that would already be available as a command. Maybe upt-cpan2port or upt-pypi-macports, or something along the lines. I know this is somewhat incompatible when you need M x N frontends and backends, and then you install or uninstall just one, so handling the symlinks automatically by the upt package itself becomes a bit nontrivial.

[Steap]

Lots of things to discuss, I love it! Note that there is a upt mailing list (https://framalistes.org/sympa/info/upt), though it's not used that much :(

1. Regarding the manpage, one has been submitted to me by an OpenBSD developer, and I need to find the cleanest way to distribute it with setuptools

2. Regarding the "usage" message, I wrote a patch that makes it a bit more useful by showing the available frontends/backends:

$ upt package
usage: upt package [-h] -f {cpan,rubygems,pypi} -b
                   {fedora,freebsd,guix,nix,openbsd,debian,macports} [--debug]
                   [-o OUTPUT] [-q]
                   package
upt package: error: the following arguments are required: -f/--frontend, -b/--backend, package

3. Regarding the amount of arguments required, I'm writing a patch that allows users to skip "--frontend/--backend" if there is only one frontend/backend installed. So, if you only care about one backend (which is the case of the majority of users), this:

$ upt package -f pypi -b macports requests

will become:

$ upt package -f pypi requests

If you only work with packages from PyPI and don't care about the other frontends, it may even become:

$ upt package requests

4. Frontends could provide an alias. For instance, upt-pypi could provide the "upt-pypi" command, which would allow you to type:

$ upt-pypi package -b macports requests

and turn it into:

$ upt package -f pypi -b macports requests

5. Maybe we could remove subcommands. I originally wanted to have a few different subcommands: list-backends, list-frontends, package and update. I also thought it would be convenient to have room for more subcommands, but in retrospect, it may have been a bad idea. We could probably switch to:

$ upt --list-backends
$ upt --list-frontends
$ upt -f pypi -b macports requests
$ upt -f pypi -b macports --upgrade/-u requests

What do you think? The changes I've mentionned currenlty only exist in my local git repo.

[Steap]

The complete man page is available in the git repo, and will be part of the tarball in the next release.