pgsql: Code review for regexp_replace patch.

Log Message:
-----------
Code review for regexp_replace patch. Improve documentation and comments,
fix problems with replacement-string backslashes that aren't followed by
one of the expected characters, avoid giving the impression that
replace_text_regexp() is meant to be called directly as a SQL function,
etc.

Modified Files:
--------------
pgsql/doc/src/sgml:
func.sgml (r1.287 -> r1.288)
(http://developer.postgresql.org/cvsweb.cgi/pgsql/doc/src/sgml/func.sgml.diff?r1=1.287&r2=1.288)
pgsql/src/backend/utils/adt:
regexp.c (r1.59 -> r1.60)
(http://developer.postgresql.org/cvsweb.cgi/pgsql/src/backend/utils/adt/regexp.c.diff?r1=1.59&r2=1.60)
varlena.c (r1.137 -> r1.138)
(http://developer.postgresql.org/cvsweb.cgi/pgsql/src/backend/utils/adt/varlena.c.diff?r1=1.137&r2=1.138)
pgsql/src/include/utils:
builtins.h (r1.266 -> r1.267)
(http://developer.postgresql.org/cvsweb.cgi/pgsql/src/include/utils/builtins.h.diff?r1=1.266&r2=1.267)