manual.yml: revise section on identity, clarifying what is subject to change

Mostly clarifications w.r.t. numbers.

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

1 files changed, 50 insertions, 20 deletions

diff --git a/docs/content/manual/manual.yml b/docs/content/manual/manual.yml
index f031c927..2f4bd3c0 100644
--- a/docs/content/manual/manual.yml
+++ b/docs/content/manual/manual.yml
@@ -312,36 +312,66 @@ sections:
       - title: "Identity: `.`"
         body: |
 
-          The absolute simplest filter is `.` .  This is a filter that
-          takes its input and produces it unchanged as output.  That is,
-          this is the identity operator.
-
-          Since jq by default pretty-prints all output, this trivial
-          program can be a useful way of formatting JSON output from,
-          say, `curl`.
-
-          An important point about the identity filter is that it
-          guarantees to preserve the literal decimal representation
-          of values. This is particularly important when dealing with numbers
-          which can't be losslessly converted to an IEEE754 double precision
+          The absolute simplest filter is `.` .  This filter takes its
+          input and produces the same value as output.  That is, this
+          is the identity operator.
+
+          Since jq by default pretty-prints all output, a trivial
+          program consisting of nothing but `.` can be used to format
+          JSON output from, say, `curl`.
+
+          Although the identity filter never modifies the value of its
+          input, jq processing can sometimes make it appear as though
+          it does.  For example, using the current implementation of
+          jq, we would see that the expression:
+          
+              `1E1234567890 | .`
+
+          produces `1.7976931348623157e+308` on at least one platform.
+          This is because, in the process of parsing the number, this
+          particular version of jq has converted it to an IEEE754
+          double-precision representation, losing precision.
+
+          The way in which jq handles numbers has changed over time
+          and further changes are likely within the parameters set by
+          the relevant JSON standards.  The following remarks are
+          therefore offered with the understanding that they are
+          intended to be descriptive of the current version of jq and
+          should not be interpreted as being prescriptive:
+
+          (1) Any arithmetic operation on a number that has not
+          already been converted to an IEEE754 double precision
+          representation will trigger a conversion to the IEEE754
           representation.
 
-          jq doesn't truncate the literal numbers to double unless there
-          is a need to make arithmetic operations with the number.
-          Comparisons are carried out over the untruncated big decimal
-          representation of the number.
+          (2) jq will attempt to maintain the original decimal
+          precision of number literals, but in expressions such
+          `1E1234567890`, precision will be lost if the exponent is
+          too large.
 
-          jq will also try to maintain the original decimal precision of the provided
-          number literal. See below for examples.
+          (3) In jq programs, a leading minus sign will trigger the
+          conversion of the number to an IEEE754 representation.
+
+          (4) Comparisons are carried out using the untruncated
+          big decimal representation of numbers if available, as
+          illustrated in one of the following examples.
 
         examples:
           - program: '.'
             input: '"Hello, world!"'
             output: ['"Hello, world!"']
 
-          - program: '. | tojson'
+          - program: '.'
+            input:  '0.12345678901234567890123456789'
+            output: ['0.12345678901234567890123456789']
+
+          - program: '[., tojson]'
             input: '12345678909876543212345'
-            output: ['"12345678909876543212345"']
+            output: ['[12345678909876543212345,"12345678909876543212345"]']
+
+          - program: '. < 0.12345678901234567890123456788'
+            input: '0.12345678901234567890123456789'
+            output: ['false']
 
           - program: 'map([., . == 1]) | tojson'
             input: '[1, 1.000, 1.0, 100e-2]'