document canonical name and move vars down to usage

Reject (by closing) if this seems silly