update docs to match current behavior

diff --git a/doc/antora/modules/installation/pages/upgrade.adoc b/doc/antora/modules/installation/pages/upgrade.adoc
index 300c0d81e75d90bbefb9c25621c350e8d4a652a4..f1da760d579d045946fb6c3f351e0108c79ddb8e 100644 (file)
--- a/doc/antora/modules/installation/pages/upgrade.adoc
+++ b/doc/antora/modules/installation/pages/upgrade.adoc
@@ -591,22 +591,55 @@ keywords, such as `subrequest`.
 
 == Update sections
 
-The filtering operators `<`, `>`, `\<=`, `>=`, etc. have been moved to
-the `filter` keyword.  These operators will still be accepted in an
-`update` section, but using them will generate a warning.
+The `update` sections are deprecated.  See new the attribute
+xref:reference:unlang/edit.adoc[editing] documentation.
 
-== Filter Sections
+The server has limited support for "auto-conversion" of `update`
+sections to the new syntax.
 
-The `filter` section is now used to filter attributes.
+=== Recommendations
 
-The filtering operators have been modified. They no longer _set_ the
-attribute to a value. Instead, they only _filter_ the attribute list,
-and delete any attributes which do not match. The filtering operators
-do not _create_ any attribute.
+We recommend manually converting the `update` sections to the new
+method.  The biggest change that confuses people is the old `+=`
+operator does not work the same way as before.
 
-In order to achieve the same functionality as v3, you will need to set
-the value of the attribute via `=` in an `update` statement, and then
-filter it.
+Instead of doing:
+
+```
+&Reply-Message += "foo"
+```
+
+you should edit the `reply` list, using the `+=` operator:
+
+```
+&reply += {
+    &Reply-Message = "foo"
+}
+```
+
+We also recommend removing double-quotes from xlat expansions where
+possible.  The temptation in v3 is to just add double quotes to
+everything, and hope it all works out.  This is no longer necessary in
+v4.
+
+For example, in v3 you would do:
+
+```
+update reply {
+       &Framed-IP-Address := "%{sql:SELECT ...}"
+}
+```
+
+In v4, you can remove the `update`, and also remove the double quotes:
+
+```
+&reply.Framed-IP-Address := %{sql:SELECT ...}
+```
+
+Using double quotes everywhere means that every bit of data gets
+converted to printable strings, and then back to it's real data type
+(`ipaddr` in the above example).  Removing the double quotes means
+that there is less work going on, which means higher performance.
 
 == load-balance and redundant-load-balance sections
 
@@ -637,7 +670,7 @@ modules, similar to the v3 proxy `keyed-balance` configuration.
 
 == Connection timeouts
 
-In v3 and earlier, the config items for configuring connection timeouts
+In v3 and earlier, the configuration items for configuring connection timeouts
 were either confusingly named, or completely absent in the case of many
 contributed modules.