remove serious bug in shell() and clean up docs