[booth] potentially misleading or mistaken formulations in pcs booth help texts (ticket revoke in particular)

[jnpkrn]

It's rather unsettling to see this:

Usage: pcs booth <command>

[...]

    ticket revoke <ticket> [<site address>]
        Revoke the ticket for the site specified by address.  Site address
        which has been specified with 'pcs booth create' command is
        used if 'site address' is omitted.  Specifying site address is
        mandatory when running this command on an arbitrator.

Beside a slight grammatical violation in using "which" instead of
"that" (non-essential clause), semantics of that command is explained
in a straight (or easily deducible) contradiction to the real state
of affairs.

The true semantics is:

1. if the revoking command is run with a site address explicitly
   entered, the ticket is revoked within the whole booth formation
   ("cluster of clusters") as derived from the cluster representative
   under "site address", i.e., not just "for the site specified by
   address"

2. if the revoking command is run without a site address explicitly
   entered (hence, presumably on a cluster/site representative)
   the ticket is, again, revoked within the whole booth formation
   as derived from this local cluster representative, i.e., again,
   not just "for the site [assumed]"

That is, there's a proper asymmetry, whereby granting a ticket
is a function of a specific site (particulat booth formation is
a derived information ... that you grant a ticket at specific
site implies you make that ticket available within the pertaining
formation), revoking a ticket is a function of the whole booth
formation (that you revoke the ticket from the formation implies
that you revoke the ticket from its particular site in possession
of the ticket at that time, if any), and the site is required because
particular booth formation is not addressable on its own.

---

Why this is important: anyone reasonably versed with pacemaker and
its "fluid" approach to configuration might expect that "revoke"
might work also as a function of a specific site, akin to setting
a -INFINITY location constraint for a ticket at given site.
That'd be very mistaken, indeed.

---

Therefore, it shall rather be specified as follows:

    ticket revoke <ticket> [<site address>]
        Revoke the ticket in the booth formation as identified with
        one of its member sites specified by the address.  When this
        specification is omitted, site address that has been specified
        with a prior 'pcs booth create' command is used.  Specifying
        site address is therefore mandatory when running this command
        at a host in an arbitrator role.

Going backwards, to unify this new and more reality reflecting
explanation with ticket grant, fixing dubious preposition in the
process and adding rather a vital piece of information:

    ticket grant <ticket> [<site address>]
        Grant the ticket to the site specified by the address, hence to
        the booth formation this site is a member of.  When this
        specification is omitted, site address that has been specified
        with 'pcs booth create' command is used.  Specifying site address
        is therefore mandatory when running this command at a host in an
        arbitrator role.
        Note that the ticket must not be already granted in given
        booth formation; for an ad-hoc (and, in the worst case, abrupt,
        for a lack of a direct atomicity) change of this preference
        baring direct interventions at the sites, the ticket needs to
        be revoked first, only then it can be granted at another site
        again.

[tomjelinek]

Thanks, fixed in dfaa499.