doc and fixes to block-shift detection