first cut of reference (#9): port content from 1.1 manual