update and clarify a few usage details