json_format: Add html_safe option

FU/Util.pm

@@ -212,13 +212,6 @@ roughly similar to:
 
   JSON::PP->new->allow_nonref->core_bools->convert_blessed->encode($scalar);
 
-Some modules escape the slash character in encoded strings to prevent a
-potential XSS vulnerability when embedding JSON inside C<< <script> ..
-</script> >> tags.  This function does I<not> do that because it might not even
-be sufficient. The following is probably an improvement:
-
-  json_format($data) =~ s{</}{<\\/}rg =~ s/<!--/<\\u0021--/rg;
-
 This function generates invalid JSON if you pass it a string with invalid
 Unicode characters; I don't see how you'd ever accidentally end up with such a
 string, anyway.
@@ -244,6 +237,26 @@ versions.
 
 Boolean, returns a UTF-8 encoded byte string instead of a Perl Unicode string.
 
+=item html_safe
+
+Boolean. When set, the encoded JSON is safe for (unescaped) inclusion into HTML
+or XML content. This encodes C<< < >>, C<< > >> and C<< & >> as Unicode escapes.
+Commonly used to embed data inside a HTML page:
+
+  $html = '<script id="site_data" type="application/json">'
+        . json_format($data, html_safe => 1)
+        . '</script>';
+
+This option does NOT make it safe to include the encoded JSON as an attribute
+value. There is no way to do that without violating JSON specs, so you should
+use entity escaping instead.
+
+Some JSON modules escape the forward slash (C</>) character instead, but that
+is, at best, B<only> sufficient for embedding inside a C<< <script> >> tag (I'm
+not sure how C<< <!-- >> and C<< <![CDATA[ >> are treated in that context). In
+any other context, you'll need the more thourough escaping provided by this
+C<html_safe> option.
+
 =item max_size
 
 Maximum permitted size, in bytes, of the generated JSON string. Defaults to 1 GiB.