new improvements, clearifications and cleanup