reformatting doc with latest changes from upstream/master