Add more explanation of what happens in polynomial substitution and also of
its use in casting between types. Clean up some rst glitches.

The Sphinx markup was incorrect the documentation to the polynomial
convenience classes wasn't being generated.

This is the first step in cleaning up the polynomial documentation
and writing an instructional section on the convenience classes.

Also:
1. Note that the polynomial package is preferred over poly1d.

2. Remove deprecation of mapparms in __init__.py as it interferes with the
   documention of the method of the same name. This is probably safe as it
   is unlikely to be used yet.

3. Make some improvements to the documentation in polytemplate.

(backport of feed705)