Embedded documentation updated.

Changes according to comments in #1584 have been included. Please review.