informative adjunct to the docs.  Forward-port of Raymond's r86225 and
r86245 using the new source reST role added in #10334.