"the callback event will arrive after the next output refresh" is wrong,
if you interpret "output refresh" as framebuffer flip or the moment when
the new pixels turn into light the first time. Weston has probably never
worked this way.

Weston triggers the frame callbacks when it submits repainting commands
to the GPU, which is before the framebuffer flip.

Strike the incorrect claim, and the rest of the paragraph which no
longer offers useful information.

As a replacement, expand on the "throttling and driving animations"
characteristic. The main purpose is to let clients animate at the
display refresh rate, while avoiding drawing frames that will never be
presented.

The new claim is that the server should give some time between
triggering frame callbacks and repainting itself, for clients to draw
and commit. This is somewhat intimate with the repaint scheduling
algorithm a compositor uses, but hopefully the right intention.

Another point of this update is to imply, that frame callbacks should
not be used to count compositor repaint cycles nor monitor refresh
cycles. It has never been guaranteed to work. Removing the mention of
frame callback without an attach hopefully discourages such use.

v2: Don't just remove a paragraph, but add useful information about the
request's intent.

v3: Specify the order of posting frame callbacks.

Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
Cc: Axel Davy <axel.davy@ens.fr>
Cc: Jason Ekstrand <jason@jlekstrand.net>