Add comment about routine misnomer

Also implement a warning mechanism, so that someone using this routine
based on its name (without reading the
help text) is less likely to be led astray.

Warning text is on by default, but can be overridden with a new
optional argument.

DHB