diff --git a/doc/content-for-file-formats.html b/doc/content-for-file-formats.html
index d56e4ca4a..e8f488686 100644
--- a/doc/content-for-file-formats.html
+++ b/doc/content-for-file-formats.html
@@ -191,18 +191,31 @@ POKI_RUN_COMMAND{{mlr --json --jvstack head -n 1 then put '${values:uv} = ${valu
Arrays
-Arrays aren’t supported in Miller. The put/filter
-DSL does support hashmaps, and an array could be read in as an integer-keyed
-map: e.g. JSON ["a","b","c"] could be read in as Miller hashmap
-{1:"a",2:"b",3:"c"}. But then arrays and maps both become maps, with
-the result that, once written back as output, they would differ from input.
+Arrays aren’t supported in Miller’s
+put/filter DSL. By default, JSON arrays are read in as
+integer-keyed maps.
-As a result, Miller by default fatals when it encounters arrays, which are
-“unmillerable”. You can use mlr
---json-skip-arrays-on-input, if you like, which ignores arrays. To truly
-handle JSON, please use a JSON-processing tool such as
-jq.
+ Suppose you have arrays like this in our input data:
+POKI_RUN_COMMAND{{cat data/json-example-3.json}}HERE
+
+ Then integer indices (starting from 0 and counting up) are used as map keys:
+
+POKI_RUN_COMMAND{{mlr --ijson --oxtab cat data/json-example-3.json}}HERE
+
+ When the data are written back out as JSON, field names are re-expanded as above,
+but what were arrays on input are now maps on output:
+
+POKI_RUN_COMMAND{{mlr --json --jvstack cat data/json-example-3.json}}HERE
+
+ This is non-ideal, but it allows Miller (5.x release being latest as of
+this writing) to handle JSON arrays at all.
+
+You might also use mlr --json-skip-arrays-on-input or mlr
+--json-fatal-arrays-on-input.
+
+To truly handle JSON, please use a JSON-processing tool such as jq.
Formatting JSON options
diff --git a/doc/file-formats.html b/doc/file-formats.html
index 87c31028b..45b986dd1 100644
--- a/doc/file-formats.html
+++ b/doc/file-formats.html
@@ -655,18 +655,80 @@ $ mlr --json --jvstack head -n 1 then put '${values:uv} = ${values:u} * ${values
Arrays
-Arrays aren’t supported in Miller. The put/filter
-DSL does support hashmaps, and an array could be read in as an integer-keyed
-map: e.g. JSON ["a","b","c"] could be read in as Miller hashmap
-{1:"a",2:"b",3:"c"}. But then arrays and maps both become maps, with
-the result that, once written back as output, they would differ from input.
+Arrays aren’t supported in Miller’s
+put/filter DSL. By default, JSON arrays are read in as
+integer-keyed maps.
-As a result, Miller by default fatals when it encounters arrays, which are
-“unmillerable”. You can use mlr
---json-skip-arrays-on-input, if you like, which ignores arrays. To truly
-handle JSON, please use a JSON-processing tool such as
-jq.
+ Suppose you have arrays like this in our input data:
+
+
+
+$ cat data/json-example-3.json
+{
+ "label": "orange",
+ "values": [12.2, 13.8, 17.2]
+}
+{
+ "label": "purple",
+ "values": [27.0, 32.4]
+}
+
+
+
+$ mlr --ijson --oxtab cat data/json-example-3.json
+label orange
+values:0 12.2
+values:1 13.8
+values:2 17.2
+
+label purple
+values:0 27.0
+values:1 32.4
+
+
+
+$ mlr --json --jvstack cat data/json-example-3.json
+{
+ "label": "orange",
+ "values": {
+ "0": 12.2,
+ "1": 13.8,
+ "2": 17.2
+ }
+}
+{
+ "label": "purple",
+ "values": {
+ "0": 27.0,
+ "1": 32.4
+ }
+}
+
+
Formatting JSON options