update documentation on string escaping, etc.

diff --git a/doc/antora/modules/reference/pages/type/cast.adoc b/doc/antora/modules/reference/pages/type/cast.adoc
index 0a58066d0c66be1ce79be418addc47e7f2418553..7349feedec2ddb7810daf5d432cb292d34c2612e 100644 (file)
--- a/doc/antora/modules/reference/pages/type/cast.adoc
+++ b/doc/antora/modules/reference/pages/type/cast.adoc
@@ -117,6 +117,15 @@ string, and assigning the resulting value to the `string`.  For
 Casting a `string` value to another data type means _parsing_ the
 string as that data type.
 
+See xref:types/string/double.adoc[double-quoted strings] for examples
+of how double-quoted strings are used.
+
+==== Other Data Types
+
+Other data types such as `ethernet`, etc. can generally be cast
+to/from `octet`, and printed to/from `string`.  Most other casts do
+not make sense, and will not work.
+
 === Expressions
 
 Unlang xref:unlang/expression.adoc[expressions] can use casts, too, as

diff --git a/doc/antora/modules/reference/pages/type/string/double.adoc b/doc/antora/modules/reference/pages/type/string/double.adoc
index fb8ba479bb7502c0e1e804949449821a7c6201f5..9c4e7d41ee9879f571904129d9941aae0d5bee1d 100644 (file)
--- a/doc/antora/modules/reference/pages/type/string/double.adoc
+++ b/doc/antora/modules/reference/pages/type/string/double.adoc
@@ -100,6 +100,30 @@ because it is already a string.
 The output strings here are completely different than for the previous
 examples.  The output data type is `octets`, and not `string`.
 
+If the goal is to have the _raw_ `octets` data inserted into a
+`string`, you must use the `%{string:...}` expansion.  This expansion
+will copy the input `octets` value to a the output, changing the data
+type to `string`.  The value is left alone.
+
+.Example of casting to raw 'octets'
+[source,unlang]
+----
+"User-Name is %{Tmp-Octets-0}"
+"User-Name is %{string:%{Tmp-Octets-0}}"
+----
+
+if the `&Tmp-Octets-0` attribute has value `0x666f6f` (`foo`)
+
+In the first expansion, the resulting output is `User-Name is
+0x666f6f`.  In the second expansion, the resulting output is
+`User-name is foo`.
+
+Note that placing raw `octets` data into a string may allow for binary
+data to be inserted into what should be a printable string.  Any uses
+of the string will result in the non-printable data being escaped as
+`\000` or other methods such a `\n`, depending on how and wheere the
+string is being used.
+
 .Examples
 
 `"word"` +

diff --git a/doc/antora/modules/reference/pages/xlat/builtin.adoc b/doc/antora/modules/reference/pages/xlat/builtin.adoc
index 28677d368cb1ae9eafbed0dcc5c7e74c6efe9f99..0c7c6593d6281e54eb701ae928caadab3ba34db0 100644 (file)
--- a/doc/antora/modules/reference/pages/xlat/builtin.adoc
+++ b/doc/antora/modules/reference/pages/xlat/builtin.adoc
@@ -135,26 +135,27 @@ The tag value of the second instance of Tunnel-Server-Enpoint is 192.0.5.2
 
 === %{string:<data>}
 
-Convert input to a string if (possible).  For _octets_ type attributes, this
-means interpreting the data as a UTF8 string, and inserting octal escape
-sequences where appropriate.
+Convert input to a string if (possible).  For _octets_ type
+attributes, this means interpreting the data as a UTF8 string.  Any
+non-printable characters are left in place.
 
 For other types, this means printing the value in its _presentation_ format,
 i.e. dotted quads for IPv4 addresses, link:https://en.wikipedia.org/wiki/ISO_8601[ISO 8601]
 time for date types, enumeration values for attributes such as `radius.Service-Type` etc.
 
-.Return: _string_
+In practice, the only real use of this expansion is to insert `octets`
+data types into a `string`.  For other data types, using
+`%{string:...}` is not necessary.  For example, for any data type
+other than `octets`, the following equivalency holds true.
+
+See xref:types/string/double.adoc[double-quoted strings] and
+xref:type/cast.adoc[casting] for examples of how strings are used.
 
-.String interpolation using the raw octets value of Tmp-Octets-0, and the stringified version
+.String expansion equivalents
 ====
 [source,unlang]
 ----
-update control {
-    &Tmp-Octets-0 := 0x7465737431
-}
-update reply {
-    &Reply-Message := "The string value of %{control.Tmp-Octets-0} is %{string:%{control.Tmp-Octets-0}}"
-}
+"foo" + (string)&Bar == "foo%{Bar}"
 ----
 ====