CLOUDFLARE: Correct redirect function documentation (#696)

* expand on how Page Rules are handled

* Correct Cloudflare redirect function documentation

* add warning per discussion on #696

docs/_functions/domain/CF_REDIRECT.md

@@ -5,12 +5,30 @@ parameters:
   - modifiers...
 ---
 
-`CF_REDIRECT` is the same as `CF_TEMP_REDIRECT` but generates a
-http 301 redirect (permanent redirect) instead of a temporary
-redirect.
+`CF_REDIRECT` uses Cloudflare-specific features ("Forwarding URL" Page Rules) to
+generate a HTTP 301 permanent redirect.
 
-These redirects are cached by browsers forever, usually ignoring
-any TTLs or other cache invalidation techniques.   It should be
-used with great care.  We suggest using a `CF_TEMP_REDIRECT`
-initially, then changing to a `CF_REDIRECT` only after sufficient
-time has elapsed to prove this is what you really want.
+If _any_ `CF_REDIRECT` or `CF_TEMP_REDIRECT` functions are used then
+`dnscontrol` will manage _all_ "Forwarding URL" type Page Rules for the domain.
+Page Rule types other than "Forwarding URL” will be left alone.
+
+WARNING: Cloudflare does not currently fully document the Page Rules API and
+this interface is not extensively tested. Take precautions such as making
+backups and manually verifying `dnscontrol preview` output before running
+`dnscontrol push`. This is especially true when mixing Page Rules that are
+managed by DNSControl and those that aren't.
+
+HTTP 301 redirects are cached by browsers forever, usually ignoring any TTLs or
+other cache invalidation techniques. It should be used with great care. We
+suggest using a `CF_TEMP_REDIRECT` initially, then changing to a `CF_REDIRECT`
+only after sufficient time has elapsed to prove this is what you really want.
+
+This example redirects the bare (aka apex, or naked) domain to www:
+
+{% include startExample.html %}
+{% highlight js %}
+D("foo.com", .... ,
+  CF_REDIRECT("mydomain.com/*", "https://www.mydomain.com/$1"),
+);
+{%endhighlight%}
+{% include endExample.html %}

docs/_functions/domain/CF_TEMP_REDIRECT.md

@@ -5,13 +5,18 @@ parameters:
   - modifiers...
 ---
 
-`CF_REDIRECT` uses Cloudflare-specific features ("page rules") to
-generate an HTTP 301 redirect.
+`CF_TEMP_REDIRECT` uses Cloudflare-specific features ("Forwarding URL" Page
+Rules) to generate a HTTP 302 temporary redirect.
 
-WARNING: If the domain has other pagerules in place, they may be
-deleted. At this time this feature is best used on bare domains
-that need to redirect to another domain, perhaps with wildcard
-substitutions.
+If _any_ `CF_REDIRECT` or `CF_TEMP_REDIRECT` functions are used then
+`dnscontrol` will manage _all_ "Forwarding URL" type Page Rules for the domain.
+Page Rule types other than "Forwarding URL” will be left alone.
+
+WARNING: Cloudflare does not currently fully document the Page Rules API and
+this interface is not extensively tested. Take precautions such as making
+backups and manually verifying `dnscontrol preview` output before running
+`dnscontrol push`. This is especially true when mixing Page Rules that are
+managed by DNSControl and those that aren't.
 
 {% include startExample.html %}
 {% highlight js %}