update the copy from documentation

this commit already documents options which are not yet
available but will be added shortly.