major doc fixes thanks to #perl