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)