Put ERRORS and DIAGNOSTICS information in the sections where they belong.

Put ERRORS and DIAGNOSTICS information in the sections where they belong.
More details on RETURN VALUES and ERRORS.
Document all DIAGNOSTICS messages except the various malloc(3)-related
ones and except those that cannot actually occur but would merely report
violations of internal invariants.  Shorten some wordings in this section.

Using feedback from jmc@ and Ted Bullock.
OK jmc@ and nicm@ on an earlier version.