docs: improve documentation of rev sytnax

Created by: stefanhengl

Fixes #13275 (closed)

Our revision syntax is partly undocumented and hard to understand. This PR clarifies the syntax and provides more examples.