events.markdown document improvements

Improvements to events.markdown documentation per #8853 (same fix as before but rebased on joyent/v0.10