pagination improvements

+ documentation improvements