adding some documentation; assorted other revisiosn