Improve documentation

[etam]

alts -h says:

           alts [-u] [-s] -n <program> [-p <alt_priority>]
              sets an override with a given priority as default
              if priority is not set, then resets to default by removing override
              -u -- user override, default for non-root users
              -s -- system overrude, default for root users
              -n -- program to override with a given priority alternative

alts -l iptables says:

Binary: iptables
Alternatives: 2
  Priority: 1   Target: /usr/sbin/xtables-legacy-multi
                 Group: ip6tables, ip6tables-restore, ip6tables-save, iptables, iptables-restore, iptables-save
  Priority: 2*  Target: /usr/sbin/xtables-nft-multi
                 Group: ip6tables, ip6tables-restore, ip6tables-save, iptables, iptables-restore, iptables-save

1. It's not clear which priority value makes which choice the more important one. I guess higher value means higher priority. For contrast there are systems, where lower value is higher priority (for example zypper repos).
2. It's not clear how to change the alternative. I would assume I should provide the target value, but help only mentions -p alt_priority. Does that mean that targets must have a distinct priority values and are identified by it?

[sebastianha]

I second this request. I just took me a while to understand how it works. Perhaps provide an example:

Show available versions: alts -lnode
Switch to version 14: alts -u -n node -p 14

[lnussel]

I think the confusion is caused by the word "priority". The mental model my head came up with actually assumed that something called "priority" may not be unique. In alts however priority is basically also a unique key. So selecting a default based on id aka priority makes sense.

[AdamMajer]

We could call this "id" instead of "priority". Priority is mostly used to mirror the update-alternatives definition. Maybe we have too many priorities everywhere 😆