Rewrite json.md

[abrudz]

No description provided.

[DyalogRichard]

I have not been asked to review this, but as it's ⎕JSON I think I should. Whilst I was surprised that the page appears to have been rewritten so extensively to address #788, it is definitely the case that this page needed a revamp.

I had a very quick scan of the (GitHub-rendered) new page whilst travelling yesterday and there were a couple of technical things that I thought should be discussed before we publish - these may well have been inherited from the original page. However, it will take me a while before I can look at it more carefully and comment. I also had some much more general observations about tone and content which I think the docs team as a whole should review, particularly wrt the amount of specific detail it gives - for example, it now tries to be very precise about the effect of the Dialect variant option which Pete did not and would not do - he always seemed to give "just enough information" to make it clear what was happening, without getting bogged down, and in that context, saying it switches between JSON and JSON5 dialect support is all that is needed. JSON and JSON5 are well documented elsewhere and our documentation does not describe either; we describe just the system function itself. Given that we don't describe either JSON or JSON5, it seems to me that describing (just) the small subset of things that are different between the two is an odd thing to do. Similarly, the documentation for the Null variant option needs only say that it specifies whether the JSON null is represented by ⎕NULL or ⊂'null' - the table showing the four combinations of variant setting and import/exports is not strictly necessary - and I reckon it confuses rather than clarifies anyway: the cell for '⎕NULL' and export says "Both ⎕NULL and ⊂null (sic) are exported as JSON null", and whilst this is true, it is also misleading: ⎕NULL is exported as null because that APL type is represented that way, but ⊂'null' is exported as null because it now falls into the domain of Raw Text.

[abrudz]

I was surprised that the page appears to have been rewritten so extensively to address #788

I found multiple other issues, including inconsistent notes, examples disconnected from their subject matter description, inconsistent and misleading header structures, typos, bad phrasings, inconsistent usage of tables to describe variant behaviour, inconsistent adherence to best practices, unnecessarily complex APL constructs, and more.

it now tries to be very precise about the effect of the Dialect variant (…) saying it switches between JSON and JSON5 dialect support is all that is needed

For import, yes (and only 10 words are spent on this), but that doesn't say anything about export, since JSON is valid JSON5.

Given that we don't describe either JSON or JSON5, it seems to me that describing (just) the small subset of things that are different between the two is an odd thing to do.

It doesn't. It only specifies which features of JSON5 we apply on export: For example, when exporting compact JSON5, we could conceivably use hexadecimal representation of integers ≥10¹² and omit leading zeros for numbers in the range (−1,1) to obtain the most compact JSON5, but we don't. We could also prefer single quotes (many JS programmers do), but we don't.

the documentation for the Null variant option (…) confuses rather than clarifies (…) and whilst this is true, it is also misleading

I agree, and have edited to remove confusing and misleading parts, instead adding a note with reference to the Raw Text section.