manual.yml: clarify and expand section on identity

[pkoppstein]

Mostly clarifications w.r.t. numbers.

The anomalous behavior of leading minus signs is documented, with an explicit notice that this will probably change.

[nicowilliams]

We must not commit to number representations. RFC 8259 blessed -or cursed, depending on your viewpoint- JSON implementors with a great deal of latitude on internal (no limits here, as the RFC does not even envision tools like jq) and external JSON number representation. There is nothing like a canonical number representation. Any representation we choose, even a -in some cases- literal-preserving scheme like our current one could be obnoxious to some users. There is no right answer here, therefore we may not commit to even our current scheme.

We must remain free to replace decNumber or even go back to just IEEE 754 doubles if we want. I'm not saying that we will, but that we should retain that freedom.

Moreover, we should not impose our number representation schemes on other implementations of the jq language. The implementors of those ought to at least get a say, and the easiest thing to do in that regard is to not even raise the issue.

Any documentation regarding how jq supports numbers at this time must be explicit on this point.

[nicowilliams]

s/will/may/

[nicowilliams]

s/will/may/

[nicowilliams]

Make this:

Currently, though this may change in the future, negative literals in jq programs may be converted to IEEE 754 doubles, with consequent loss in precision.

[nicowilliams]

s/are/may be/

[nicowilliams]

BTW, thank you for this @pkoppstein -- clearly we slipped up a bit in the docs when we accepted the decNumber contribution. We really should be very careful about what we say about number representations!

[pkoppstein]

@nicowilliams @emanuele6 - Thanks for all the corrections and suggestions.

Please note that I've restructured the text with the intent of clearly identifying that which is subject to change,
in a way which should also make it easy to keep the documentation up-to-date.

Please also note that with the revised version, "All checks have passed".

As regards other implementations of jq: I agree it would be great to have a mutually agreed-upon definition of "standard jq", and clearly langjq serves as a kind of reference for other implementations. But manual.yml has not been written with buy-in from the authors of other implementations, and indeed both gojq and especially jaq deliberately depart from several key aspects of jq.

Until there is some kind of agreement amongst the jq, gojq, and jaq authors/maintainers/communities
about what "standard jq" or "core jq" is, I think manual.yml for jq 1.7 should continue to focus on jqlang, being clear about
what is intended to be stable, what is currently undefined, and, in some instances, what is likely to change.

That would also be helpful to the authors of other implementations, not least in the writing of their own documentation.

[nicowilliams]

Thank you! LGTM.

I think on rebase-and-merge the merge commit will go away, but I strongly recommend doing git pull --rebase instead of git merge.

[pkoppstein]

@nicowilliams wrote:

I strongly recommend ...

Is this for future reference, or would you like me to do something regarding this particular PR?

(If you want me to do something for this particular PR, I'd be inclined to delete it, and this branch, and start afresh. My git skills outside of GitHub Desktop are at best negligible.)

[nicowilliams]

@pkoppstein in the list of commits for this PR there's a merge commit. I don't know whether clicking the "Rebase and merge" button would make that merge commit go away, but I want it to. We should very much try to have "linear history" in jq, which means no merge commits. This gist might be useful to you.