From a988cd9005b0ddd6e88cb93ac05db05e99a310eb Mon Sep 17 00:00:00 2001
From: Mike Farah <mikefarah@gmail.com>
Date: Fri, 1 Dec 2023 11:39:02 +1100
Subject: [PATCH] Updating JSON doc: NDJSON spec deprecated, prefer JSON Lines

---
 pkg/yqlib/doc/usage/convert.md |  8 +++-----
 pkg/yqlib/json_test.go         | 15 +++++++--------
 2 files changed, 10 insertions(+), 13 deletions(-)

diff --git a/pkg/yqlib/doc/usage/convert.md b/pkg/yqlib/doc/usage/convert.md
index 5060f8da..83357dba 100644
--- a/pkg/yqlib/doc/usage/convert.md
+++ b/pkg/yqlib/doc/usage/convert.md
@@ -125,9 +125,7 @@ will output
 {"whatever":"cat"}
 ```
 
-## Roundtrip NDJSON
-Unfortunately the json encoder strips leading spaces of values.
-
+## Roundtrip JSON Lines / NDJSON
 Given a sample.json file of:
 ```json
 {"this": "is a multidoc json file"}
@@ -147,7 +145,7 @@ will output
 ```
 
 ## Roundtrip multi-document JSON
-The NDJSON parser can also handle multiple multi-line json documents in a single file!
+The parser can also handle multiple multi-line json documents in a single file (despite this not being in the JSON Lines / NDJSON spec). Typically you would have one entire JSON document per line, but the parser also supports multiple multi-line json documents
 
 Given a sample.json file of:
 ```json
@@ -229,7 +227,7 @@ will output
 {"a number":4}
 ```
 
-## Decode NDJSON
+## Decode JSON Lines / NDJSON
 Given a sample.json file of:
 ```json
 {"this": "is a multidoc json file"}
diff --git a/pkg/yqlib/json_test.go b/pkg/yqlib/json_test.go
index b36d1e19..ff81618c 100644
--- a/pkg/yqlib/json_test.go
+++ b/pkg/yqlib/json_test.go
@@ -216,15 +216,14 @@ var jsonScenarios = []formatScenario{
 		scenarioType:   "encode",
 	},
 	{
-		description:    "Roundtrip NDJSON",
-		subdescription: "Unfortunately the json encoder strips leading spaces of values.",
-		input:          sampleNdJson,
-		expected:       expectedRoundTripSampleNdJson,
-		scenarioType:   "roundtrip-ndjson",
+		description:  "Roundtrip JSON Lines / NDJSON",
+		input:        sampleNdJson,
+		expected:     expectedRoundTripSampleNdJson,
+		scenarioType: "roundtrip-ndjson",
 	},
 	{
 		description:    "Roundtrip multi-document JSON",
-		subdescription: "The NDJSON parser can also handle multiple multi-line json documents in a single file!",
+		subdescription: "The parser can also handle multiple multi-line json documents in a single file (despite this not being in the JSON Lines / NDJSON spec). Typically you would have one entire JSON document per line, but the parser also supports multiple multi-line json documents",
 		input:          sampleMultiLineJson,
 		expected:       roundTripMultiLineJson,
 		scenarioType:   "roundtrip-multi",
@@ -246,13 +245,13 @@ var jsonScenarios = []formatScenario{
 		scenarioType:   "roundtrip-ndjson",
 	},
 	{
-		description:  "Decode NDJSON",
+		description:  "Decode JSON Lines / NDJSON",
 		input:        sampleNdJson,
 		expected:     expectedNdJsonYaml,
 		scenarioType: "decode-ndjson",
 	},
 	{
-		description:  "Decode NDJSON, maintain key order",
+		description:  "Decode JSON Lines / NDJSON, maintain key order",
 		skipDoc:      true,
 		input:        sampleNdJsonKey,
 		expected:     expectedJsonKeysInOrder,