@port-labs/jq-node-bindings 0.0.13 → 0.0.15-dev1

package/deps/jq/docs/content/{3.manual/v1.6 → manual/dev}/manual.yml

@@ -1,11 +1,6 @@
 ---
 headline: jq Manual (development version)
 
-history: |
-
-  *For released versions, see [jq 1.5](/jq/manual/v1.5),
-  [jq 1.4](/jq/manual/v1.4) or [jq 1.3](/jq/manual/v1.3).*
-
 body: |
 
   A jq program is a "filter": it takes an input, and produces an
@@ -65,7 +60,7 @@ manpage_epilogue: |
 
   Presumably. Report them or discuss them at:
 
-      https://github.com/stedolan/jq/issues
+      https://github.com/jqlang/jq/issues
 
   ## AUTHOR
 
@@ -78,67 +73,61 @@ sections:
       jq filters run on a stream of JSON data. The input to jq is
       parsed as a sequence of whitespace-separated JSON values which
       are passed through the provided filter one at a time. The
-      output(s) of the filter are written to standard out, again as a
-      sequence of whitespace-separated JSON data.
+      output(s) of the filter are written to standard output, as a
+      sequence of newline-separated JSON data.
+
+      The simplest and most common filter (or jq program) is `.`,
+      which is the identity operator, copying the inputs of the jq
+      processor to the output stream.  Because the default behavior of
+      the jq processor is to read JSON texts from the input stream,
+      and to pretty-print outputs, the `.` program's main use is to
+      validate and pretty-print the inputs.  The jq programming
+      language is quite rich and allows for much more than just
+      validation and pretty-printing.
 
       Note: it is important to mind the shell's quoting rules.  As a
       general rule it's best to always quote (with single-quote
-      characters) the jq program, as too many characters with special
+      characters on Unix shells) the jq program, as too many characters with special
       meaning to jq are also shell meta-characters.  For example, `jq
       "foo"` will fail on most Unix shells because that will be the same
       as `jq foo`, which will generally fail because `foo is not
       defined`.  When using the Windows command shell (cmd.exe) it's
       best to use double quotes around your jq program when given on the
       command-line (instead of the `-f program-file` option), but then
-      double-quotes in the jq program need backslash escaping.
-
-      You can affect how jq reads and writes its input and output
-      using some command-line options:
-
-      * `--version`:
-
-        Output the jq version and exit with zero.
-
-      * `--seq`:
-
-        Use the `application/json-seq` MIME type scheme for separating
-        JSON texts in jq's input and output.  This means that an ASCII
-        RS (record separator) character is printed before each value on
-        output and an ASCII LF (line feed) is printed after every
-        output.  Input JSON texts that fail to parse are ignored (but
-        warned about), discarding all subsequent input until the next
-        RS.  This mode also parses the output of jq without the `--seq`
-        option.
+      double-quotes in the jq program need backslash escaping. When using
+      the Powershell (`powershell.exe`) or the Powershell Core
+      (`pwsh`/`pwsh.exe`), use single-quote characters around the jq
+      program and backslash-escaped double-quotes (`\"`) inside the jq
+      program.
 
-      * `--stream`:
+      * Unix shells: `jq '.["foo"]'`
+      * Powershell: `jq '.[\"foo\"]'`
+      * Windows command shell: `jq ".[\"foo\"]"`
 
-        Parse the input in streaming fashion, outputing arrays of path
-        and leaf values (scalars and empty arrays or empty objects).
-        For example, `"a"` becomes `[[],"a"]`, and `[[],"a",["b"]]`
-        becomes `[[0],[]]`, `[[1],"a"]`, and `[[1,0],"b"]`.
+      Note: jq allows user-defined functions, but every jq program
+      must have a top-level expression.
 
-        This is useful for processing very large inputs.  Use this in
-        conjunction with filtering and the `reduce` and `foreach` syntax
-        to reduce large inputs incrementally.
+      You can affect how jq reads and writes its input and output
+      using some command-line options:
 
-      * `--slurp`/`-s`:
+      * `--null-input` / `-n`:
 
-        Instead of running the filter for each JSON object in the
-        input, read the entire input stream into a large array and run
-        the filter just once.
+        Don't read any input at all. Instead, the filter is run once
+        using `null` as the input. This is useful when using jq as a
+        simple calculator or to construct JSON data from scratch.
 
-      * `--raw-input`/`-R`:
+      * `--raw-input` / `-R`:
 
         Don't parse the input as JSON. Instead, each line of text is
         passed to the filter as a string. If combined with `--slurp`,
         then the entire input is passed to the filter as a single long
         string.
 
-      * `--null-input`/`-n`:
+      * `--slurp` / `-s`:
 
-        Don't read any input at all! Instead, the filter is run once
-        using `null` as the input. This is useful when using jq as a
-        simple calculator or to construct JSON data from scratch.
+        Instead of running the filter for each JSON object in the
+        input, read the entire input stream into a large array and run
+        the filter just once.
 
       * `--compact-output` / `-c`:
 
@@ -146,75 +135,104 @@ sections:
         will result in more compact output by instead putting each
         JSON object on a single line.
 
-      * `--tab`:
+      * `--raw-output` / `-r`:
 
-        Use a tab for each indentation level instead of two spaces.
+        With this option, if the filter's result is a string then it
+        will be written directly to standard output rather than being
+        formatted as a JSON string with quotes. This can be useful for
+        making jq filters talk to non-JSON-based systems.
 
-      * `--indent n`:
+      * `--raw-output0`:
+
+        Like `-r` but jq will print NUL instead of newline after each output.
+        This can be useful when the values being output can contain newlines.
+        When the output value contains NUL, jq exits with non-zero code.
+
+      * `--join-output` / `-j`:
+
+        Like `-r` but jq won't print a newline after each output.
+
+      * `--ascii-output` / `-a`:
+
+        jq usually outputs non-ASCII Unicode codepoints as UTF-8, even
+        if the input specified them as escape sequences (like
+        "\u03bc"). Using this option, you can force jq to produce pure
+        ASCII output with every non-ASCII character replaced with the
+        equivalent escape sequence.
 
-        Use the given number of spaces (no more than 8) for indentation.
+      * `--sort-keys` / `-S`:
+
+        Output the fields of each object with the keys in sorted order.
 
       * `--color-output` / `-C` and `--monochrome-output` / `-M`:
 
         By default, jq outputs colored JSON if writing to a
         terminal. You can force it to produce color even if writing to
         a pipe or a file using `-C`, and disable color with `-M`.
+        When the `NO_COLOR` environment variable is not empty, jq disables
+        colored output by default, but you can enable it by `-C`.
 
         Colors can be configured with the `JQ_COLORS` environment
         variable (see below).
 
-      * `--ascii-output` / `-a`:
+      * `--tab`:
 
-        jq usually outputs non-ASCII Unicode codepoints as UTF-8, even
-        if the input specified them as escape sequences (like
-        "\u03bc"). Using this option, you can force jq to produce pure
-        ASCII output with every non-ASCII character replaced with the
-        equivalent escape sequence.
+        Use a tab for each indentation level instead of two spaces.
+
+      * `--indent n`:
 
-      * `--unbuffered`
+        Use the given number of spaces (no more than 7) for indentation.
+
+      * `--unbuffered`:
 
         Flush the output after each JSON object is printed (useful if
         you're piping a slow data source into jq and piping jq's
         output elsewhere).
 
-      * `--sort-keys` / `-S`:
+      * `--stream`:
 
-        Output the fields of each object with the keys in sorted order.
+        Parse the input in streaming fashion, outputting arrays of path
+        and leaf values (scalars and empty arrays or empty objects).
+        For example, `"a"` becomes `[[],"a"]`, and `[[],"a",["b"]]`
+        becomes `[[0],[]]`, `[[1],"a"]`, and `[[2,0],"b"]`.
 
-      * `--raw-output` / `-r`:
+        This is useful for processing very large inputs.  Use this in
+        conjunction with filtering and the `reduce` and `foreach` syntax
+        to reduce large inputs incrementally.
 
-        With this option, if the filter's result is a string then it
-        will be written directly to standard output rather than being
-        formatted as a JSON string with quotes. This can be useful for
-        making jq filters talk to non-JSON-based systems.
+      * `--stream-errors`:
 
-      * `--join-output` / `-j`:
+        Like `--stream`, but invalid JSON inputs yield array values
+        where the first element is the error and the second is a path.
+        For example, `["a",n]` produces `["Invalid literal at line 1,
+        column 7",[1]]`.
 
-        Like `-r` but jq won't print a newline after each output.
+        Implies `--stream`.  Invalid JSON inputs produce no error values
+        when `--stream` without `--stream-errors`.
+
+      * `--seq`:
+
+        Use the `application/json-seq` MIME type scheme for separating
+        JSON texts in jq's input and output.  This means that an ASCII
+        RS (record separator) character is printed before each value on
+        output and an ASCII LF (line feed) is printed after every
+        output.  Input JSON texts that fail to parse are ignored (but
+        warned about), discarding all subsequent input until the next
+        RS.  This mode also parses the output of jq without the `--seq`
+        option.
 
-      * `-f filename` / `--from-file filename`:
+      * `-f` / `--from-file`:
 
-        Read filter from the file rather than from a command line, like
-        awk's -f option. You can also use '#' to make comments.
+        Read the filter from a file rather than from a command line,
+        like awk's -f option. This changes the filter argument to be
+        interpreted as a filename, instead of the source of a program.
 
-      * `-Ldirectory` / `-L directory`:
+      * `-L directory` / `--library-path directory`:
 
         Prepend `directory` to the search list for modules.  If this
         option is used then no builtin search list is used.  See the
         section on modules below.
 
-      * `-e` / `--exit-status`:
-
-        Sets the exit status of jq to 0 if the last output values was
-        neither `false` nor `null`, 1 if the last output value was
-        either `false` or `null`, or 4 if no valid result was ever
-        produced.  Normally jq exits with 2 if there was any usage
-        problem or system error, 3 if there was a jq program compile
-        error, or 0 if the jq program ran.
-
-        Another way to set the exit status is with the `halt_error`
-        builtin function.
-
       * `--arg name value`:
 
         This option passes a value to the jq program as a predefined
@@ -224,7 +242,8 @@ sections:
         bind `$foo` to `"123"`.
 
         Named arguments are also available to the jq program as
-        `$ARGS.named`.
+        `$ARGS.named`. When the name is not a valid identifier, this is
+        the only way to access it.
 
       * `--argjson name JSON-text`:
 
@@ -244,17 +263,9 @@ sections:
 
         This option reads in the named file and binds its contents to the given
         global variable.  If you run jq with `--rawfile foo bar`, then `$foo` is
-        available in the program and has a string whose contents are to the texs
+        available in the program and has a string whose contents are to the texts
         in the file named `bar`.
 
-      * `--argfile variable-name filename`:
-
-        Do not use.  Use `--slurpfile` instead.
-
-        (This option is like `--slurpfile`, but when the file has just
-        one text, then that is used, else an array of texts is used as
-        in `--slurpfile`.)
-
       * `--args`:
 
         Remaining arguments are positional string arguments.  These are
@@ -265,6 +276,43 @@ sections:
         Remaining arguments are positional JSON text arguments.  These
         are available to the jq program as `$ARGS.positional[]`.
 
+      * `--exit-status` / `-e`:
+
+        Sets the exit status of jq to 0 if the last output value was
+        neither `false` nor `null`, 1 if the last output value was
+        either `false` or `null`, or 4 if no valid result was ever
+        produced.  Normally jq exits with 2 if there was any usage
+        problem or system error, 3 if there was a jq program compile
+        error, or 0 if the jq program ran.
+
+        Another way to set the exit status is with the `halt_error`
+        builtin function.
+
+      * `--binary` / `-b`:
+
+        Windows users using WSL, MSYS2, or Cygwin, should use this option
+        when using a native jq.exe, otherwise jq will turn newlines (LFs)
+        into carriage-return-then-newline (CRLF).
+
+      * `--version` / `-V`:
+
+        Output the jq version and exit with zero.
+
+      * `--build-configuration`:
+
+        Output the build configuration of jq and exit with zero.
+        This output has no supported format or structure and may change
+        without notice in future releases.
+
+      * `--help` / `-h`:
+
+        Output the jq help and exit with zero.
+
+      * `--`:
+
+        Terminates argument processing.  Remaining arguments are not
+        interpreted as options.
+
       * `--run-tests [filename]`:
 
         Runs the tests in the given file or standard input.  This must
@@ -273,7 +321,7 @@ sections:
         program lines followed by one input line, as many lines of
         output as are expected (one per output), and a terminating empty
         line.  Compilation failure tests start with a line containing
-        only "%%FAIL", then a line containing the program to compile,
+        only `%%FAIL`, then a line containing the program to compile,
         then a line containing an error message to compare to the
         actual.
 
@@ -284,80 +332,149 @@ 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.
+          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.  Moreover, build configuration
+          options can alter how jq processes numbers.
+
+          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.
+
+          (2) jq will attempt to maintain the original decimal
+          precision of number literals (if the `--disable-decnum`
+          build configuration option was not used), but in expressions
+          such `1E1234567890`, precision will be lost if the exponent
+          is too large.
 
-          Since jq by default pretty-prints all output, this trivial
-          program can be a useful way of formatting JSON output from,
-          say, `curl`.
+          (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.
+
+          The examples below use the builtin function `have_decnum` in
+          order to demonstrate the expected effects of using / not
+          using the `--disable-decnum` build configuration option, and
+          also to allow automated tests derived from these examples to
+          pass regardless of whether that option is used.
 
         examples:
           - program: '.'
             input: '"Hello, world!"'
             output: ['"Hello, world!"']
 
+          - program: '.'
+            input: '0.12345678901234567890123456789'
+            output: ['0.12345678901234567890123456789']
+
+          - program: '[., tojson] | . == if have_decnum then [12345678909876543212345,"12345678909876543212345"] else [12345678909876543000000,"12345678909876543000000"] end'
+            input: '12345678909876543212345'
+            output: ['true']
+
+          - program: '. < 0.12345678901234567890123456788'
+            input: '0.12345678901234567890123456789'
+            output: ['false']
+
+          - program: 'map([., . == 1]) | tojson | . == if have_decnum then "[[1,true],[1.000,true],[1.0,true],[1.00,true]]" else "[[1,true],[1,true],[1,true],[1,true]]" end'
+            input: '[1, 1.000, 1.0, 100e-2]'
+            output: ['true']
+
+          - program: '. as $big | [$big, $big + 1] | map(. > 10000000000000000000000000000000) | . == if have_decnum then [true, false] else [false, false] end'
+            input: '10000000000000000000000000000001'
+            output: ['true']
+
       - title: "Object Identifier-Index: `.foo`, `.foo.bar`"
         body: |
 
-          The simplest *useful* filter is `.foo`. When given a
-          JSON object (aka dictionary or hash) as input, it produces
-          the value at the key "foo", or null if there's none present.
+          The simplest *useful* filter has the form `.foo`. When given a
+          JSON object (aka dictionary or hash) as input, `.foo` produces
+          the value at the key "foo" if the key is present, or null otherwise.
 
-          A filter of the form `.foo.bar` is equivalent to `.foo|.bar`.
+          A filter of the form `.foo.bar` is equivalent to `.foo | .bar`.
 
-          This syntax only works for simple, identifier-like keys, that
+          The `.foo` syntax only works for simple, identifier-like keys, that
           is, keys that are all made of alphanumeric characters and
           underscore, and which do not start with a digit.
 
-          If the key contains special characters, you need to surround
-          it with double quotes like this: `."foo$"`, or else `.["foo$"]`.
+          If the key contains special characters or starts with a digit,
+          you need to surround it with double quotes like this:
+          `."foo$"`, or else `.["foo$"]`.
 
           For example `.["foo::bar"]` and `.["foo.bar"]` work while
-          `.foo::bar` does not, and `.foo.bar` means `.["foo"].["bar"]`.
+          `.foo::bar` does not.
 
         examples:
           - program: '.foo'
             input: '{"foo": 42, "bar": "less interesting data"}'
-            output: [42]
+            output: ['42']
+
           - program: '.foo'
             input: '{"notfoo": true, "alsonotfoo": false}'
             output: ['null']
+
           - program: '.["foo"]'
             input: '{"foo": 42}'
-            output: [42]
+            output: ['42']
 
       - title: "Optional Object Identifier-Index: `.foo?`"
         body: |
 
-          Just like `.foo`, but does not output even an error when `.`
-          is not an array or an object.
+          Just like `.foo`, but does not output an error when `.` is not an
+          object.
 
         examples:
           - program: '.foo?'
             input: '{"foo": 42, "bar": "less interesting data"}'
-            output: [42]
+            output: ['42']
           - program: '.foo?'
             input: '{"notfoo": true, "alsonotfoo": false}'
             output: ['null']
           - program: '.["foo"]?'
             input: '{"foo": 42}'
-            output: [42]
+            output: ['42']
           - program: '[.foo?]'
             input: '[1,2]'
             output: ['[]']
 
-      - title: "Generic Object Index: `.[<string>]`"
+      - title: "Object Index: `.[<string>]`"
         body: |
 
           You can also look up fields of an object using syntax like
-          `.["foo"]` (.foo above is a shorthand version of this, but
+          `.["foo"]` (`.foo` above is a shorthand version of this, but
           only for identifier-like strings).
 
-      - title: "Array Index: `.[2]`"
+      - title: "Array Index: `.[<number>]`"
         body: |
 
-          When the index value is an integer, `.[<value>]` can index
+          When the index value is an integer, `.[<number>]` can index
           arrays.  Arrays are zero-based, so `.[2]` returns the third
           element.
 
@@ -377,16 +494,17 @@ sections:
             input: '[1,2,3]'
             output: ['2']
 
-      - title: "Array/String Slice: `.[10:15]`"
+      - title: "Array/String Slice: `.[<number>:<number>]`"
         body: |
 
-          The `.[10:15]` syntax can be used to return a subarray of an
-          array or substring of a string. The array returned by
-          `.[10:15]` will be of length 5, containing the elements from
-          index 10 (inclusive) to index 15 (exclusive). Either index may
-          be negative (in which case it counts backwards from the end of
-          the array), or omitted (in which case it refers to the start
-          or end of the array).
+          The `.[<number>:<number>]` syntax can be used to return a
+          subarray of an array or substring of a string. The array
+          returned by `.[10:15]` will be of length 5, containing the
+          elements from index 10 (inclusive) to index 15 (exclusive).
+          Either index may be negative (in which case it counts
+          backwards from the end of the array), or omitted (in which
+          case it refers to the start or end of the array).
+          Indices are zero-based.
 
         examples:
           - program: '.[2:4]'
@@ -412,11 +530,14 @@ sections:
           entirely, it will return *all* of the elements of an
           array. Running `.[]` with the input `[1,2,3]` will produce the
           numbers as three separate results, rather than as a single
-          array.
+          array. A filter of the form `.foo[]` is equivalent to
+          `.foo | .[]`.
 
           You can also use this on an object, and it will return all
           the values of the object.
 
+          Note that the iterator operator is a generator of values.
+
         examples:
           - program: '.[]'
             input: '[{"name":"JSON", "good":true}, {"name":"XML", "good":false}]'
@@ -428,6 +549,10 @@ sections:
             input: '[]'
             output: []
 
+          - program: '.foo[]'
+            input: '{"foo":[1,2,3]}'
+            output: ['1','2','3']
+
           - program: '.[]'
             input: '{"a": 1, "b": 1}'
             output: ['1', '1']
@@ -436,7 +561,8 @@ sections:
         body: |
 
           Like `.[]`, but no errors will be output if . is not an array
-          or object.
+          or object. A filter of the form `.foo[]?` is equivalent to
+          `.foo | .[]?`.
 
       - title: "Comma: `,`"
         body: |
@@ -449,6 +575,8 @@ sections:
           .bar`, produces both the "foo" fields and "bar" fields as
           separate outputs.
 
+          The `,` operator is one way to construct generators.
+
         examples:
           - program: '.foo, .bar'
             input: '{"foo": 42, "bar": "something else", "baz": true}'
@@ -467,13 +595,13 @@ sections:
 
           The | operator combines two filters by feeding the output(s) of
           the one on the left into the input of the one on the right. It's
-          pretty much the same as the Unix shell's pipe, if you're used to
-          that.
+          similar to the Unix shell's pipe, if you're used to that.
 
           If the one on the left produces multiple results, the one on
           the right will be run for each of those results. So, the
           expression `.[] | .foo` retrieves the "foo" field of each
-          element of the input array.
+          element of the input array.  This is a cartesian product,
+          which can be surprising.
 
           Note that `.a.b.c` is the same as `.a | .b | .c`.
 
@@ -496,7 +624,7 @@ sections:
         examples:
           - program: '(. + 2) * 5'
             input: '1'
-            output: [15]
+            output: ['15']
 
   - title: Types and Values
     body: |
@@ -506,11 +634,21 @@ sections:
       hashes with only string keys), and "null".
 
       Booleans, null, strings and numbers are written the same way as
-      in javascript. Just like everything else in jq, these simple
+      in JSON. Just like everything else in jq, these simple
       values take an input and produce an output - `42` is a valid jq
       expression that takes an input, ignores it, and returns 42
       instead.
 
+      Numbers in jq are internally represented by their IEEE754 double
+      precision approximation. Any arithmetic operation with numbers,
+      whether they are literals or results of previous filters, will
+      produce a double precision floating point result.
+
+      However, when parsing a literal jq will store the original literal
+      string. If no mutation is applied to this value then it will make
+      to the output in its original form, even if conversion to double
+      would result in a loss.
+
     entries:
       - title: "Array construction: `[]`"
         body: |
@@ -548,13 +686,16 @@ sections:
           dictionaries or hashes), as in: `{"a": 42, "b": 17}`.
 
           If the keys are "identifier-like", then the quotes can be left
-          off, as in `{a:42, b:17}`.  Keys generated by expressions need
-          to be parenthesized, e.g., `{("a"+"b"):59}`.
+          off, as in `{a:42, b:17}`.  Variable references as key
+          expressions use the value of the variable as the key.  Key
+          expressions other than constant literals, identifiers, or
+          variable references, need to be parenthesized, e.g.,
+          `{("a"+"b"):59}`.
 
-          The value can be any expression (although you may need to
-          wrap it in parentheses if it's a complicated one), which gets
-          applied to the {} expression's input (remember, all filters
-          have an input and an output).
+          The value can be any expression (although you may need to wrap
+          it in parentheses if, for example, it contains colons), which
+          gets applied to the {} expression's input (remember, all
+          filters have an input and an output).
 
               {foo: .bar}
 
@@ -592,6 +733,16 @@ sections:
 
               {"stedolan": ["JQ Primer", "More JQ"]}
 
+          Variable references as keys use the value of the variable as
+          the key.  Without a value then the variable's name becomes the
+          key and its value becomes the value,
+
+              "f o o" as $foo | "b a r" as $bar | {$foo, $bar:$foo}
+
+          produces
+
+              {"foo":"f o o","b a r":"f o o"}
+
         examples:
           - program: '{user, title: .titles[]}'
             input: '{"user":"stedolan","titles":["JQ Primer", "More JQ"]}'
@@ -608,27 +759,39 @@ sections:
           Recursively descends `.`, producing every value.  This is the
           same as the zero-argument `recurse` builtin (see below).  This
           is intended to resemble the XPath `//` operator.  Note that
-          `..a` does not work; use `..|.a` instead.  In the example
-          below we use `..|.a?` to find all the values of object keys
+          `..a` does not work; use `.. | .a` instead.  In the example
+          below we use `.. | .a?` to find all the values of object keys
           "a" in any object found "below" `.`.
 
           This is particularly useful in conjunction with `path(EXP)`
           (also see below) and the `?` operator.
 
         examples:
-          - program: '..|.a?'
+          - program: '.. | .a?'
             input: '[[{"a":1}]]'
             output: ['1']
 
   - title: Builtin operators and functions
     body: |
 
-      Some jq operator (for instance, `+`) do different things
+      Some jq operators (for instance, `+`) do different things
       depending on the type of their arguments (arrays, numbers,
       etc.). However, jq never does implicit type conversions. If you
       try to add a string to an object you'll get an error message and
       no result.
 
+      Please note that all numbers are converted to IEEE754 double precision
+      floating point representation. Arithmetic and logical operators are working
+      with these converted doubles. Results of all such operations are also limited
+      to the double precision.
+
+      The only exception to this behaviour of number is a snapshot of original number
+      literal. When a number which originally was provided as a literal is never
+      mutated until the end of the program then it is printed to the output in its
+      original literal form. This also includes cases when the original literal
+      would be truncated when converted to the IEEE754 double precision floating point
+      number.
+
     entries:
       - title: "Addition: `+`"
         body: |
@@ -644,10 +807,10 @@ sections:
           - **Strings** are added by being joined into a larger string.
 
           - **Objects** are added by merging, that is, inserting all
-              the key-value pairs from both objects into a single
-              combined object. If both objects contain a value for the
-              same key, the object on the right of the `+` wins. (For
-              recursive merge use the `*` operator.)
+            the key-value pairs from both objects into a single
+            combined object. If both objects contain a value for the
+            same key, the object on the right of the `+` wins. (For
+            recursive merge use the `*` operator.)
 
           `null` can be added to any value, and returns the other
           value unchanged.
@@ -684,14 +847,14 @@ sections:
             input: '["xml", "yaml", "json"]'
             output: ['["json"]']
 
-      - title: "Multiplication, division, modulo: `*`, `/`, and `%`"
+      - title: "Multiplication, division, modulo: `*`, `/`, `%`"
         body: |
 
           These infix operators behave as expected when given two numbers.
           Division by zero raises an error. `x % y` computes x modulo y.
 
           Multiplying a string by a number produces the concatenation of
-          that string that many times. `"x" * 0` produces **null**.
+          that string that many times. `"x" * 0` produces `""`.
 
           Dividing a string by another splits the first using the second
           as separators.
@@ -703,8 +866,8 @@ sections:
 
         examples:
           - program: '10 / . * 3'
-            input: 5
-            output: [6]
+            input: '5'
+            output: ['6']
           - program: '. / ", "'
             input: '"a, b,c,d, e"'
             output: ['["a","b,c,d","e"]']
@@ -715,6 +878,21 @@ sections:
             input: '[1,0,-1]'
             output: ['1', '-1']
 
+      - title: "`abs`"
+        body: |
+
+          The builtin function `abs` is defined naively as: `if . < 0 then - . else . end`.
+
+          For numeric input, this is the absolute value.  See the
+          section on the identity filter for the implications of this
+          definition for numeric input.
+
+          To compute the absolute value of a number as a floating point number, you may wish use `fabs`.
+
+        examples:
+          - program: 'map(abs)'
+            input: '[-10, -1.1, -1e-1]'
+            output: ['[10,1.1,1e-1]']
 
       - title: "`length`"
         body: |
@@ -726,16 +904,20 @@ sections:
             codepoints it contains (which will be the same as its
             JSON-encoded length in bytes if it's pure ASCII).
 
+          - The length of a **number** is its absolute value.
+
           - The length of an **array** is the number of elements.
 
           - The length of an **object** is the number of key-value pairs.
 
           - The length of **null** is zero.
 
+          - It is an error to use `length` on a **boolean**.
+
         examples:
           - program: '.[] | length'
-            input: '[[1,2], "string", {"a":2}, null]'
-            output: [2, 6, 1, 0]
+            input: '[[1,2], "string", {"a":2}, null, -5]'
+            output: ['2', '6', '1', '0', '5']
 
 
       - title: "`utf8bytelength`"
@@ -747,7 +929,7 @@ sections:
         examples:
           - program: 'utf8bytelength'
             input: '"\u03bc"'
-            output: [2]
+            output: ['2']
 
       - title: "`keys`, `keys_unsorted`"
         body: |
@@ -811,18 +993,51 @@ sections:
             input: '[2, 0]'
             output: ['[false, true]']
 
-      - title: "`map(x)`, `map_values(x)`"
+      - title: "`map(f)`, `map_values(f)`"
         body: |
 
-          For any filter `x`, `map(x)` will run that filter for each
-          element of the input array, and return the outputs in a new
-          array. `map(.+1)` will increment each element of an array of numbers.
+          For any filter `f`, `map(f)` and `map_values(f)` apply `f`
+          to each of the values in the input array or object, that is,
+          to the values of `.[]`.
+
+          In the absence of errors, `map(f)` always outputs an array
+          whereas `map_values(f)` outputs an array if given an array,
+          or an object if given an object.
+
+          When the input to `map_values(f)` is an object, the output
+          object has the same keys as the input object except for
+          those keys whose values when piped to `f` produce no values
+          at all.
+
+          The key difference between `map(f)` and `map_values(f)` is
+          that the former simply forms an array from all the values of
+          `($x|f)` for each value, $x, in the input array or object,
+          but `map_values(f)` only uses `first($x|f)`.
+
+          Specifically, for object inputs, `map_values(f)` constructs
+          the output object by examining in turn the value of
+          `first(.[$k]|f)` for each key, $k, of the input.  If this
+          expression produces no values, then the corresponding key
+          will be dropped; otherwise, the output object will have that
+          value at the key, $k.
+
+          Here are some examples to clarify the behavior of `map` and
+          `map_values` when applied to arrays. These examples assume the
+          input is `[1]` in all cases:
 
-          Similarly, `map_values(x)` will run that filter for each element,
-          but it will return an object when an object is passed.
+              map(.+1)          #=>  [2]
+              map(., .)         #=>  [1,1]
+              map(empty)        #=>  []
+
+              map_values(.+1)   #=>  [2]
+              map_values(., .)  #=>  [1]
+              map_values(empty) #=>  []
+
+          `map(f)` is equivalent to `[.[] | f]` and
+          `map_values(f)` is equivalent to `.[] |= f`.
+
+          In fact, these are their implementations.
 
-          `map(x)` is equivalent to `[.[] | x]`. In fact, this is how
-          it's defined. Similarly, `map_values(x)` is defined as `.[] |= x`.
 
         examples:
           - program: 'map(.+1)'
@@ -833,6 +1048,34 @@ sections:
             input: '{"a": 1, "b": 2, "c": 3}'
             output: ['{"a": 2, "b": 3, "c": 4}']
 
+          - program: 'map(., .)'
+            input: '[1,2]'
+            output: ['[1,1,2,2]']
+
+          - program: 'map_values(. // empty)'
+            input: '{"a": null, "b": true, "c": false}'
+            output: ['{"b":true}']
+
+
+      - title: "`pick(pathexps)`"
+        body: |
+
+          Emit the projection of the input object or array defined by the
+          specified sequence of path expressions, such that if `p` is any
+          one of these specifications, then `(. | p)` will evaluate to the
+          same value as `(. | pick(pathexps) | p)`. For arrays, negative
+          indices and `.[m:n]` specifications should not be used.
+
+        examples:
+          - program: 'pick(.a, .b.c, .x)'
+            input: '{"a": 1, "b": {"c": 2, "d": 3}, "e": 4}'
+            output: ['{"a":1,"b":{"c":2},"x":null}']
+
+          - program: 'pick(.[2], .[0], .[0])'
+            input: '[1,2,3,4]'
+            output: ['[1,null,3]']
+
+
       - title: "`path(path_expression)`"
         body: |
 
@@ -912,7 +1155,7 @@ sections:
       - title: "`delpaths(PATHS)`"
         body: |
 
-          The builtin function `delpaths` sets the `PATHS` in `.`.
+          The builtin function `delpaths` deletes the `PATHS` in `.`.
           `PATHS` must be an array of paths, where each path is an array
           of strings and numbers.
 
@@ -921,7 +1164,7 @@ sections:
             input: '{"a":{"b":1},"x":{"y":2}}'
             output: ['{"a":{},"x":{"y":2}}']
 
-      - title: "`to_entries`, `from_entries`, `with_entries`"
+      - title: "`to_entries`, `from_entries`, `with_entries(f)`"
         body: |
 
           These functions convert between an object and an array of
@@ -929,11 +1172,11 @@ sections:
           for each `k: v` entry in the input, the output array
           includes `{"key": k, "value": v}`.
 
-          `from_entries` does the opposite conversion, and
-          `with_entries(foo)` is a shorthand for `to_entries |
-          map(foo) | from_entries`, useful for doing some operation to
-          all keys and values of an object. `from_entries` accepts key, Key,
-          name, Name, value and Value as keys.
+          `from_entries` does the opposite conversion, and `with_entries(f)`
+          is a shorthand for `to_entries | map(f) | from_entries`, useful for
+          doing some operation to all keys and values of an object.
+          `from_entries` accepts `"key"`, `"Key"`, `"name"`, `"Name"`,
+          `"value"`, and `"Value"` as keys.
 
         examples:
           - program: 'to_entries'
@@ -950,8 +1193,8 @@ sections:
       - title: "`select(boolean_expression)`"
         body: |
 
-          The function `select(foo)` produces its input unchanged if
-          `foo` returns true for that input, and produces no output
+          The function `select(f)` produces its input unchanged if
+          `f` returns true for that input, and produces no output
           otherwise.
 
           It's useful for filtering lists: `[1,2,3] | map(select(. >= 2))`
@@ -989,17 +1232,26 @@ sections:
         examples:
           - program: '1, empty, 2'
             input: 'null'
-            output: [1, 2]
+            output: ['1', '2']
           - program: '[1,2,empty,3]'
             input: 'null'
             output: ['[1,2,3]']
 
-      - title: "`error(message)`"
+      - title: "`error`, `error(message)`"
         body: |
 
-          Produces an error, just like `.a` applied to values other than
-          null and objects would, but with the given message as the
-          error's value.  Errors can be caught with try/catch; see below.
+          Produces an error with the input value, or with the message
+          given as the argument. Errors can be caught with try/catch;
+          see below.
+
+        examples:
+          - program: 'try error catch .'
+            input: '"error message"'
+            output: ['"error message"']
+
+          - program: 'try error("invalid value: \(.)") catch .'
+            input: '42'
+            output: ['"invalid value: 42"']
 
       - title: "`halt`"
         body: |
@@ -1017,7 +1269,7 @@ sections:
           The given `exit_code` (defaulting to `5`) will be jq's exit
           status.
 
-          For example, `"Error: somthing went wrong\n"|halt_error(1)`.
+          For example, `"Error: something went wrong\n"|halt_error(1)`.
 
       - title: "`$__loc__`"
         body: |
@@ -1031,29 +1283,26 @@ sections:
             input: 'null'
             output: ['"{\"file\":\"<top-level>\",\"line\":1}"']
 
-      - title: "`paths`, `paths(node_filter)`, `leaf_paths`"
+      - title: "`paths`, `paths(node_filter)`"
         body: |
 
           `paths` outputs the paths to all the elements in its input
           (except it does not output the empty list, representing .
           itself).
 
-          `paths(f)` outputs the paths to any values for which `f` is true.
-          That is, `paths(numbers)` outputs the paths to all numeric
+          `paths(f)` outputs the paths to any values for which `f` is `true`.
+          That is, `paths(type == "number")` outputs the paths to all numeric
           values.
 
-          `leaf_paths` is an alias of `paths(scalars)`; `leaf_paths` is
-          *deprecated* and will be removed in the next major release.
-
         examples:
           - program: '[paths]'
             input: '[1,[[],{"a":2}]]'
             output: ['[[0],[1],[1,0],[1,1],[1,1,"a"]]']
-          - program: '[paths(scalars)]'
+          - program: '[paths(type == "number")]'
             input: '[1,[[],{"a":2}]]'
             output: ['[[0],[1,1,"a"]]']
 
-      - title: "`add`"
+      - title: "`add`, `add(generator)`"
         body: |
 
           The filter `add` takes as input an array, and produces as
@@ -1064,16 +1313,22 @@ sections:
 
           If the input is an empty array, `add` returns `null`.
 
+          `add(generator)` operates on the given generator rather than
+          the input.
+
         examples:
           - program: add
             input: '["a","b","c"]'
             output: ['"abc"']
           - program: add
             input: '[1, 2, 3]'
-            output: [6]
+            output: ['6']
           - program: add
             input: '[]'
             output: ["null"]
+          - program: add(.[].a)
+            input: '[{"a":3}, {"a":5}, {"b":6}]'
+            output: ['8']
 
       - title: "`any`, `any(condition)`, `any(generator; condition)`"
         body: |
@@ -1152,12 +1407,12 @@ sections:
             input: '[{"foo": "bar"}, [{"foo": "baz"}]]'
             output: ['[{"foo": "bar"}, {"foo": "baz"}]']
 
-      - title: "`range(upto)`, `range(from;upto)` `range(from;upto;by)`"
+      - title: "`range(upto)`, `range(from; upto)`, `range(from; upto; by)`"
         body: |
 
-          The `range` function produces a range of numbers. `range(4;10)`
+          The `range` function produces a range of numbers. `range(4; 10)`
           produces 6 numbers, from 4 (inclusive) to 10 (exclusive). The numbers
-          are produced as separate outputs. Use `[range(4;10)]` to get a range as
+          are produced as separate outputs. Use `[range(4; 10)]` to get a range as
           an array.
 
           The one argument form generates numbers from 0 to the given
@@ -1170,22 +1425,22 @@ sections:
           with an increment of `by`.
 
         examples:
-          - program: 'range(2;4)'
+          - program: 'range(2; 4)'
             input: 'null'
             output: ['2', '3']
-          - program: '[range(2;4)]'
+          - program: '[range(2; 4)]'
             input: 'null'
             output: ['[2,3]']
           - program: '[range(4)]'
             input: 'null'
             output: ['[0,1,2,3]']
-          - program: '[range(0;10;3)]'
+          - program: '[range(0; 10; 3)]'
             input: 'null'
             output: ['[0,3,6,9]']
-          - program: '[range(0;10;-1)]'
+          - program: '[range(0; 10; -1)]'
             input: 'null'
             output: ['[]']
-          - program: '[range(0;-5;-1)]'
+          - program: '[range(0; -5; -1)]'
             input: 'null'
             output: ['[0,-1,-2,-3,-4]']
 
@@ -1219,7 +1474,7 @@ sections:
         examples:
           - program: '.[] | tonumber'
             input: '[1, "1"]'
-            output: [1, 1]
+            output: ['1', '1']
 
       - title: "`tostring`"
         body: |
@@ -1269,7 +1524,7 @@ sections:
             input: 'null'
             output: ['"number"', '"number"']
 
-      - title: "`sort, sort_by(path_expression)`"
+      - title: "`sort`, `sort_by(path_expression)`"
         body: |
 
           The `sort` functions sorts its input, which must be an
@@ -1288,19 +1543,25 @@ sections:
           sorted order), and if their keys are equal then the values
           are compared key by key.
 
-          `sort` may be used to sort by a particular field of an
-          object, or by applying any jq filter.
-
-          `sort_by(foo)` compares two elements by comparing the result of
-          `foo` on each element.
+          `sort_by` may be used to sort by a particular field of an
+          object, or by applying any jq filter. `sort_by(f)` compares
+          two elements by comparing the result of `f` on each element.
+          When `f` produces multiple values, it firstly compares the
+          first values, and the second values if the first values are
+          equal, and so on.
 
         examples:
           - program: 'sort'
             input: '[8,3,null,6]'
             output: ['[null,3,6,8]']
+
           - program: 'sort_by(.foo)'
-            input: '[{"foo":4, "bar":10}, {"foo":3, "bar":100}, {"foo":2, "bar":1}]'
-            output: ['[{"foo":2, "bar":1}, {"foo":3, "bar":100}, {"foo":4, "bar":10}]']
+            input: '[{"foo":4, "bar":10}, {"foo":3, "bar":10}, {"foo":2, "bar":1}]'
+            output: ['[{"foo":2, "bar":1}, {"foo":3, "bar":10}, {"foo":4, "bar":10}]']
+
+          - program: 'sort_by(.foo, .bar)'
+            input: '[{"foo":4, "bar":10}, {"foo":3, "bar":20}, {"foo":2, "bar":1}, {"foo":3, "bar":10}]'
+            output: ['[{"foo":2, "bar":1}, {"foo":3, "bar":10}, {"foo":3, "bar":20}, {"foo":4, "bar":10}]']
 
       - title: "`group_by(path_expression)`"
         body: |
@@ -1427,9 +1688,21 @@ sections:
           - program: 'index(", ")'
             input: '"a,b, cd, efg, hijk"'
             output: ['3']
+          - program: 'index(1)'
+            input: '[0,1,2,1,3,1,4]'
+            output: ['1']
+          - program: 'index([1,2])'
+            input: '[0,1,2,3,1,4,2,5,1,2,6,7]'
+            output: ['1']
           - program: 'rindex(", ")'
             input: '"a,b, cd, efg, hijk"'
             output: ['12']
+          - program: 'rindex(1)'
+            input: '[0,1,2,1,3,1,4]'
+            output: ['5']
+          - program: 'rindex([1,2])'
+            input: '[0,1,2,3,1,4,2,5,1,2,6,7]'
+            output: ['8']
 
       - title: "`inside`"
         body: |
@@ -1512,6 +1785,25 @@ sections:
             input: '["fo", "foo", "barfoo", "foobar", "foob"]'
             output: ['["fo","","bar","foobar","foob"]']
 
+      - title: "`trim`, `ltrim`, `rtrim`"
+        body: |
+
+          `trim` trims both leading and trailing whitespace.
+
+          `ltrim` trims only leading (left side) whitespace.
+
+          `rtrim` trims only trailing (right side) whitespace.
+
+          Whitespace characters are the usual `" "`, `"\n"` `"\t"`, `"\r"`
+          and also all characters in the Unicode character database with the
+          whitespace property. Note that what considers whitespace might
+          change in the future.
+
+        examples:
+          - program: 'trim, ltrim, rtrim'
+            input: '" abc "'
+            output: ['"abc"', '"abc "', '" abc"']
+
       - title: "`explode`"
         body: |
 
@@ -1538,6 +1830,9 @@ sections:
 
           Splits an input string on the separator argument.
 
+          `split` can also split on regex matches when called with
+          two arguments (see the regular expressions section below).
+
         examples:
           - program: 'split(", ")'
             input: '"a, b,c,d, e, "'
@@ -1569,10 +1864,10 @@ sections:
           Emit a copy of the input string with its alphabetic characters (a-z and A-Z)
           converted to the specified case.
 
-        example:
+        examples:
           - program: 'ascii_upcase'
             input: '"useful but not for é"'
-            output: '"USEFUL BUT NOT FOR é"'
+            output: ['"USEFUL BUT NOT FOR é"']
 
       - title: "`while(cond; update)`"
         body: |
@@ -1590,6 +1885,22 @@ sections:
             input: '1'
             output: ['[1,2,4,8,16,32,64]']
 
+      - title: "`repeat(exp)`"
+        body: |
+
+          The `repeat(exp)` function allows you to repeatedly
+          apply expression `exp` to `.` until an error is raised.
+
+          Note that `repeat(exp)` is internally defined as a
+          recursive jq function.  Recursive calls within `repeat` will
+          not consume additional memory if `exp` produces at most one
+          output for each input.  See advanced topics below.
+
+        examples:
+          - program: '[repeat(.*2, error)?]'
+            input: '1'
+            output: ['[2]']
+
       - title: "`until(cond; next)`"
         body: |
 
@@ -1609,7 +1920,7 @@ sections:
             output: ['24']
 
 
-      - title: "`recurse(f)`, `recurse`, `recurse(f; condition)`, `recurse_down`"
+      - title: "`recurse(f)`, `recurse`, `recurse(f; condition)`"
         body: |
 
           The `recurse(f)` function allows you to search through a
@@ -1634,7 +1945,7 @@ sections:
           When called without an argument, `recurse` is equivalent to
           `recurse(.[]?)`.
 
-          `recurse(f)` is identical to `recurse(f; . != null)` and can be
+          `recurse(f)` is identical to `recurse(f; true)` and can be
           used without concerns about recursion depth.
 
           `recurse(f; condition)` is a generator which begins by
@@ -1643,10 +1954,6 @@ sections:
           to generate all the integers, at least in principle, one
           could write `recurse(.+1; true)`.
 
-          For legacy reasons, `recurse_down` exists as an alias to
-          calling `recurse` without arguments. This alias is considered
-          *deprecated* and will be removed in the next major release.
-
           The recursive calls in `recurse` will not consume additional
           memory whenever `f` produces at most a single output for each
           input.
@@ -1669,11 +1976,8 @@ sections:
               - '1'
 
           - program: 'recurse(. * .; . < 20)'
-            input: 2
-            output:
-                - 2
-                - 4
-                - 16
+            input: '2'
+            output: ['2', '4', '16']
 
       - title: "`walk(f)`"
         body: |
@@ -1701,6 +2005,32 @@ sections:
             output:
               - '[{"a":{"b":2}}]'
 
+      - title: "`have_literal_numbers`"
+        body: |
+
+          This builtin returns true if jq's build configuration
+          includes support for preservation of input number literals.
+
+      - title: "`have_decnum`"
+        body: |
+
+          This builtin returns true if jq was built with "decnum",
+          which is the current literal number preserving numeric
+          backend implementation for jq.
+
+      - title: "`$JQ_BUILD_CONFIGURATION`"
+        body: |
+
+          This builtin binding shows the jq executable's build
+          configuration.  Its value has no particular format, but
+          it can be expected to be at least the `./configure`
+          command-line arguments, and may be enriched in the
+          future to include the version strings for the build
+          tooling used.
+
+          Note that this can be overridden in the command-line
+          with `--arg` and related options.
+
       - title: "`$ENV`, `env`"
         body: |
 
@@ -1735,13 +2065,13 @@ sections:
       - title: "`bsearch(x)`"
         body: |
 
-          bsearch(x) conducts a binary search for x in the input
+          `bsearch(x)` conducts a binary search for x in the input
           array.  If the input is sorted and contains x, then
-          bsearch(x) will return its index in the array; otherwise, if
+          `bsearch(x)` will return its index in the array; otherwise, if
           the array is sorted, it will return (-1 - ix) where ix is an
           insertion point such that the array would still be sorted
           after the insertion of x at ix.  If the array is not sorted,
-          bsearch(x) will return an integer that is probably of no
+          `bsearch(x)` will return an integer that is probably of no
           interest.
 
         examples:
@@ -1755,7 +2085,7 @@ sections:
             input: '[1,2,3]'
             output: ['[1,2,3,4]']
 
-      - title: "String interpolation - `\\(foo)`"
+      - title: "String interpolation: `\\(exp)`"
         body: |
 
           Inside a string, you can put an expression inside parens
@@ -1771,9 +2101,9 @@ sections:
         body: |
 
           The `tojson` and `fromjson` builtins dump values as JSON texts
-          or parse JSON texts into values, respectively.  The tojson
-          builtin differs from tostring in that tostring returns strings
-          unmodified, while tojson encodes strings as JSON strings.
+          or parse JSON texts into values, respectively.  The `tojson`
+          builtin differs from `tostring` in that `tostring` returns strings
+          unmodified, while `tojson` encodes strings as JSON strings.
 
         examples:
           - program: '[.[]|tostring]'
@@ -1813,6 +2143,11 @@ sections:
             Applies percent-encoding, by mapping all reserved URI
             characters to a `%XX` sequence.
 
+          * `@urid`:
+
+            The inverse of `@uri`, applies percent-decoding, by mapping
+            all `%XX` sequences to their corresponding URI characters.
+
           * `@csv`:
 
             The input must be an array, and it is rendered as CSV
@@ -1865,10 +2200,6 @@ sections:
             input: '"This works if x < y"'
             output: ['"This works if x &lt; y"']
 
-#          - program: '@html "<span>Anonymous said: \(.)</span>"'
-#            input: '"<script>alert(\"lol hax\");</script>"'
-#            output: ["<span>Anonymous said: &lt;script&gt;alert(&quot;lol hax&quot;);&lt;/script&gt;</span>"]
-
           - program: '@sh "echo \(.)"'
             input: "\"O'Hara's Ale\""
             output: ["\"echo 'O'\\\\''Hara'\\\\''s Ale'\""]
@@ -1913,7 +2244,7 @@ sections:
 
           The `gmtime` builtin consumes a number of seconds since the
           Unix epoch and outputs a "broken down time" representation of
-          Greenwhich Meridian time as an array of numbers representing
+          Greenwich Mean Time as an array of numbers representing
           (in this order): the year, the month (zero-based), the day of
           the month (one-based), the hour of the day, the minute of the
           hour, the second of the minute, the day of the week, and the
@@ -1929,7 +2260,7 @@ sections:
 
           The `strptime(fmt)` builtin parses input strings matching the
           `fmt` argument.  The output is in the "broken down time"
-          representation consumed by `gmtime` and output by `mktime`.
+          representation consumed by `mktime` and output by `gmtime`.
 
           The `strftime(fmt)` builtin formats a time (GMT) with the
           given format.  The `strflocaltime` does the same, but using
@@ -1961,40 +2292,40 @@ sections:
 
           jq provides a few SQL-style operators.
 
-           * INDEX(stream; index_expression):
+          * INDEX(stream; index_expression):
 
-             This builtin produces an object whose keys are computed by
-             the given index expression applied to each value from the
-             given stream.
+            This builtin produces an object whose keys are computed by
+            the given index expression applied to each value from the
+            given stream.
 
-           * JOIN($idx; stream; idx_expr; join_expr):
+          * JOIN($idx; stream; idx_expr; join_expr):
 
-             This builtin joins the values from the given stream to the
-             given index.  The index's keys are computed by applying the
-             given index expression to each value from the given stream.
-             An array of the value in the stream and the corresponding
-             value from the index is fed to the given join expression to
-             produce each result.
+            This builtin joins the values from the given stream to the
+            given index.  The index's keys are computed by applying the
+            given index expression to each value from the given stream.
+            An array of the value in the stream and the corresponding
+            value from the index is fed to the given join expression to
+            produce each result.
 
-           * JOIN($idx; stream; idx_expr):
+          * JOIN($idx; stream; idx_expr):
 
-             Same as `JOIN($idx; stream; idx_expr; .)`.
+            Same as `JOIN($idx; stream; idx_expr; .)`.
 
-           * JOIN($idx; idx_expr):
+          * JOIN($idx; idx_expr):
 
-             This builtin joins the input `.` to the given index, applying
-             the given index expression to `.` to compute the index key.
-             The join operation is as described above.
+            This builtin joins the input `.` to the given index, applying
+            the given index expression to `.` to compute the index key.
+            The join operation is as described above.
 
-           * IN(s):
+          * IN(s):
 
-             This builtin outputs `true` if `.` appears in the given
-             stream, otherwise it outputs `false`.
+            This builtin outputs `true` if `.` appears in the given
+            stream, otherwise it outputs `false`.
 
-           * IN(source; s):
+          * IN(source; s):
 
-             This builtin outputs `true` if any value in the source stream
-             appears in the second stream, otherwise it outputs `false`.
+            This builtin outputs `true` if any value in the source stream
+            appears in the second stream, otherwise it outputs `false`.
 
       - title: "`builtins`"
         body: |
@@ -2009,34 +2340,45 @@ sections:
       - title: "`==`, `!=`"
         body: |
 
-          The expression 'a == b' will produce 'true' if the result of a and b
-          are equal (that is, if they represent equivalent JSON documents) and
+          The expression 'a == b' will produce 'true' if the results of evaluating
+          a and b are equal (that is, if they represent equivalent JSON values) and
           'false' otherwise. In particular, strings are never considered equal
-          to numbers. If you're coming from Javascript, jq's == is like
-          Javascript's === - considering values equal only when they have the
-          same type as well as the same value.
+          to numbers.  In checking for the equality of JSON objects, the ordering of keys
+          is irrelevant.  If you're coming from JavaScript, please note that jq's `==` is like
+          JavaScript's `===`, the "strict equality" operator.
 
           != is "not equal", and 'a != b' returns the opposite value of 'a == b'
 
         examples:
+          - program: '. == false'
+            input: 'null'
+            output: ['false']
+
+          - program: '. == {"b": {"d": (4 + 1e-20), "c": 3}, "a":1}'
+            input: '{"a":1, "b": {"c": 3, "d": 4}}'
+            output: ['true']
+
           - program: '.[] == 1'
             input: '[1, 1.0, "1", "banana"]'
             output: ['true', 'true', 'false', 'false']
 
-      - title: if-then-else
+      - title: if-then-else-end
         body: |
 
           `if A then B else C end` will act the same as `B` if `A`
           produces a value other than false or null, but act the same
           as `C` otherwise.
 
+          `if A then B end` is the same as `if A then B else .  end`.
+          That is, the `else` branch is optional, and if absent is the
+          same as `.`. This also applies to `elif` with absent ending `else` branch.
+
           Checking for false or null is a simpler notion of
-          "truthiness" than is found in Javascript or Python, but it
+          "truthiness" than is found in JavaScript or Python, but it
           means that you'll sometimes have to be more explicit about
-          the condition you want: you can't test whether, e.g. a
-          string is empty using `if .name then A else B end`, you'll
-          need something more like `if (.name | length) > 0 then A else
-          B end` instead.
+          the condition you want.  You can't test whether, e.g. a
+          string is empty using `if .name then A else B end`; you'll
+          need something like `if .name == "" then A else B end` instead.
 
           If the condition `A` produces multiple results, then `B` is evaluated
           once for each result that is not false or null, and `C` is evaluated
@@ -2053,10 +2395,10 @@ sections:
               else
                 "many"
               end
-            input: 2
+            input: '2'
             output: ['"many"']
 
-      - title: "`>, >=, <=, <`"
+      - title: "`>`, `>=`, `<=`, `<`"
         body: |
 
           The comparison operators `>`, `>=`, `<=`, `<` return whether
@@ -2068,15 +2410,16 @@ sections:
 
         examples:
           - program: '. < 5'
-            input: 2
+            input: '2'
             output: ['true']
 
-      - title: and/or/not
+      - title: "`and`, `or`, `not`"
         body: |
 
-          jq supports the normal Boolean operators and/or/not. They have the
-          same standard of truth as if expressions - false and null are
-          considered "false values", and anything else is a "true value".
+          jq supports the normal Boolean operators `and`, `or`, `not`.
+          They have the same standard of truth as if expressions -
+          `false` and `null` are considered "false values", and
+          anything else is a "true value".
 
           If an operand of one of these operators produces multiple
           results, the operator itself will produce a result for each input.
@@ -2086,12 +2429,12 @@ sections:
           rather than with special syntax, as in `.foo and .bar |
           not`.
 
-          These three only produce the values "true" and "false", and
+          These three only produce the values `true` and `false`, and
           so are only useful for genuine Boolean operations, rather
           than the common Perl/Python/Ruby idiom of
           "value_that_may_be_null or default". If you want to use this
           form of "or", picking between two values rather than
-          evaluating a condition, see the "//" operator below.
+          evaluating a condition, see the `//` operator below.
 
         examples:
           - program: '42 and "a string"'
@@ -2100,9 +2443,6 @@ sections:
           - program: '(true, false) or false'
             input: 'null'
             output: ['true', 'false']
-#          - program: '(true, false) and (true, false)'
-#            input: 'null'
-#            output: ['true', 'false', 'false', 'false']
           - program: '(true, true) and (true, false)'
             input: 'null'
             output: ['true', 'false', 'true', 'false']
@@ -2113,9 +2453,16 @@ sections:
       - title: "Alternative operator: `//`"
         body: |
 
-          A filter of the form `a // b` produces the same
-          results as `a`, if `a` produces results other than `false`
-          and `null`. Otherwise, `a // b` produces the same results as `b`.
+          The `//` operator produces all the values of its left-hand
+          side that are neither `false` nor `null`. If the
+          left-hand side produces no values other than `false` or
+          `null`, then `//` produces all the values of its right-hand
+          side.
+
+          A filter of the form `a // b` produces all the results of
+          `a` that are not `false` or `null`.  If `a` produces no
+          results, or no results other than `false` or `null`, then `a
+          // b` produces the results of `b`.
 
           This is useful for providing defaults: `.foo // 1` will
           evaluate to `1` if there's no `.foo` element in the
@@ -2123,13 +2470,36 @@ sections:
           (jq's `or` operator is reserved for strictly Boolean
           operations).
 
-        examples:
+          Note: `some_generator // defaults_here` is not the same
+          as `some_generator | . // defaults_here`.  The latter will
+          produce default values for all non-`false`, non-`null`
+          values of the left-hand side, while the former will not.
+          Precedence rules can make this confusing.  For example, in
+          `false, 1 // 2` the left-hand side of `//` is `1`, not
+          `false, 1` -- `false, 1 // 2` parses the same way as `false,
+          (1 // 2)`.  In `(false, null, 1) | . // 42` the left-hand
+          side of `//` is `.`, which always produces just one value,
+          while in `(false, null, 1) // 42` the left-hand side is a
+          generator of three values, and since it produces a
+          value other `false` and `null`, the default `42` is not
+          produced.
+
+        examples:
+          - program: 'empty // 42'
+            input: 'null'
+            output: ['42']
           - program: '.foo // 42'
             input: '{"foo": 19}'
-            output: [19]
+            output: ['19']
           - program: '.foo // 42'
             input: '{}'
-            output: [42]
+            output: ['42']
+          - program: '(false, null, 1) // 42'
+            input: 'null'
+            output: ['1']
+          - program: '(false, null, 1) | . // 42'
+            input: 'null'
+            output: ['42', '42', '1']
 
       - title: try-catch
         body: |
@@ -2164,14 +2534,14 @@ sections:
               # Repeat an expression until it raises "break" as an
               # error, then stop repeating without re-raising the error.
               # But if the error caught is not "break" then re-raise it.
-              try repeat(exp) catch .=="break" then empty else error;
+              try repeat(exp) catch if .=="break" then empty else error
 
           jq has a syntax for named lexical labels to "break" or "go (back) to":
 
               label $out | ... break $out ...
 
           The `break $label_name` expression will cause the program to
-          to act as though the nearest (to the left) `label $label_name`
+          act as though the nearest (to the left) `label $label_name`
           produced `empty`.
 
           The relationship between the `break` and corresponding `label`
@@ -2193,51 +2563,62 @@ sections:
           The `?` operator, used as `EXP?`, is shorthand for `try EXP`.
 
         examples:
-          - program: '[.[]|(.a)?]'
+          - program: '[.[] | .a?]'
             input: '[{}, true, {"a":1}]'
             output: ['[null, 1]']
+          - program: '[.[] | tonumber?]'
+            input: '["1", "invalid", "3", 4]'
+            output: ['[1, 3, 4]']
 
-
-  - title: Regular expressions (PCRE)
+  - title: Regular expressions
     body: |
 
-      jq uses the Oniguruma regular expression library, as do php,
-      ruby, TextMate, Sublime Text, etc, so the description here
-      will focus on jq specifics.
+      jq uses the
+      [Oniguruma regular expression library](https://github.com/kkos/oniguruma/blob/master/doc/RE),
+      as do PHP, TextMate, Sublime Text, etc, so the
+      description here will focus on jq specifics.
+
+      Oniguruma supports several flavors of regular expression, so it is important to know
+      that jq uses the ["Perl NG" (Perl with named groups)](https://github.com/kkos/oniguruma/blob/master/doc/SYNTAX.md) flavor.
 
       The jq regex filters are defined so that they can be used using
       one of these patterns:
 
-          STRING | FILTER( REGEX )
-          STRING | FILTER( REGEX; FLAGS )
-          STRING | FILTER( [REGEX] )
-          STRING | FILTER( [REGEX, FLAGS] )
+          STRING | FILTER(REGEX)
+          STRING | FILTER(REGEX; FLAGS)
+          STRING | FILTER([REGEX])
+          STRING | FILTER([REGEX, FLAGS])
 
       where:
-      * STRING, REGEX and FLAGS are jq strings and subject to jq string interpolation;
-      * REGEX, after string interpolation, should be a valid PCRE regex;
+
+      * STRING, REGEX, and FLAGS are jq strings and subject to jq string interpolation;
+      * REGEX, after string interpolation, should be a valid regular expression;
       * FILTER is one of `test`, `match`, or `capture`, as described below.
 
+      Since REGEX must evaluate to a JSON string, some characters that are needed
+      to form a regular expression must be escaped. For example, the regular expression
+      `\s` signifying a whitespace character would be written as `"\\s"`.
+
       FLAGS is a string consisting of one of more of the supported flags:
 
       * `g` - Global search (find all matches, not just the first)
       * `i` - Case insensitive search
-      * `m` - Multi line mode ('.' will match newlines)
+      * `m` - Multi line mode (`.` will match newlines)
       * `n` - Ignore empty matches
       * `p` - Both s and m modes are enabled
-      * `s` - Single line mode ('^' -> '\A', '$' -> '\Z')
+      * `s` - Single line mode (`^` -> `\A`, `$` -> `\Z`)
       * `l` - Find longest possible matches
       * `x` - Extended regex format (ignore whitespace and comments)
 
-      To match whitespace in an x pattern use an escape such as \s, e.g.
+      To match a whitespace with the `x` flag, use `\s`, e.g.
 
-      * test( "a\\sb", "x" ).
+          jq -n '"a b" | test("a\\sb"; "x")'
 
       Note that certain flags may also be specified within REGEX, e.g.
 
-      * jq -n '("test", "TEst", "teST", "TEST") | test( "(?i)te(?-i)st" )'
+          jq -n '("test", "TEst", "teST", "TEST") | test("(?i)te(?-i)st")'
 
-      evaluates to: true, true, false, false.
+      evaluates to: `true`, `true`, `false`, `false`.
 
     entries:
       - title: "`test(val)`, `test(regex; flags)`"
@@ -2296,7 +2677,7 @@ sections:
 
           - program: '[ match("."; "g")] | length'
             input: '"abc"'
-            output: [3]
+            output: ['3']
 
 
       - title: "`capture(val)`, `capture(regex; flags)`"
@@ -2320,24 +2701,23 @@ sections:
           To capture all the matches for each input string, use the idiom
           `[ expr ]`, e.g. `[ scan(regex) ]`.
 
-        example:
+        examples:
           - program: 'scan("c")'
             input: '"abcdefabc"'
             output: ['"c"', '"c"']
 
-          - program: 'scan("b")'
-            input: ("", "")
-            output: ['[]', '[]']
-
       - title: "`split(regex; flags)`"
         body: |
 
-          For backwards compatibility, `split` splits on a string, not a regex.
+          Splits an input string on each regex match.
+
+          For backwards compatibility, when called with a single argument,
+          `split` splits on a string, not a regex.
 
-        example:
+        examples:
           - program: 'split(", *"; null)'
             input: '"ab,cd, ef"'
-            output: ['"ab","cd","ef"']
+            output: ['["ab","cd","ef"]']
 
 
       - title: "`splits(regex)`, `splits(regex; flags)`"
@@ -2346,37 +2726,47 @@ sections:
           These provide the same results as their `split` counterparts,
           but as a stream instead of an array.
 
-        example:
+        examples:
           - program: 'splits(", *")'
-            input: '("ab,cd", "ef, gh")'
-            output: ['"ab"', '"cd"', '"ef"', '"gh"']
+            input: '"ab,cd,   ef, gh"'
+            output: ['"ab"','"cd"','"ef"','"gh"']
 
-      - title: "`sub(regex; tostring)` `sub(regex; string; flags)`"
+      - title: "`sub(regex; tostring)`, `sub(regex; tostring; flags)`"
         body: |
 
-          Emit the string obtained by replacing the first match of regex in the
-          input string with `tostring`, after interpolation.  `tostring` should
-          be a jq string, and may contain references to named captures. The
-          named captures are, in effect, presented as a JSON object (as
-          constructed by `capture`) to `tostring`, so a reference to a captured
-          variable named "x" would take the form: "\(.x)".
+          Emit the string obtained by replacing the first match of
+          regex in the input string with `tostring`, after
+          interpolation.  `tostring` should be a jq string or a stream
+          of such strings, each of which may contain references to
+          named captures. The named captures are, in effect, presented
+          as a JSON object (as constructed by `capture`) to
+          `tostring`, so a reference to a captured variable named "x"
+          would take the form: `"\(.x)"`.
 
-        example:
-          - program: 'sub("^[^a-z]*(?<x>[a-z]*).*")'
-            input: '"123abc456"'
-            output: '"ZabcZabc"'
+        examples:
+          - program: 'sub("[^a-z]*(?<x>[a-z]+)"; "Z\(.x)"; "g")'
+            input: '"123abc456def"'
+            output: ['"ZabcZdef"']
 
+          - program: '[sub("(?<a>.)"; "\(.a|ascii_upcase)", "\(.a|ascii_downcase)")]'
+            input: '"aB"'
+            output: ['["AB","aB"]']
 
-      - title: "`gsub(regex; string)`, `gsub(regex; string; flags)`"
+      - title: "`gsub(regex; tostring)`, `gsub(regex; tostring; flags)`"
         body: |
 
           `gsub` is like `sub` but all the non-overlapping occurrences of the regex are
-          replaced by the string, after interpolation.
+          replaced by `tostring`, after interpolation. If the second argument is a stream
+          of jq strings, then `gsub` will produce a corresponding stream of JSON strings.
 
-        example:
+        examples:
           - program: 'gsub("(?<x>.)[^a]*"; "+\(.x)-")'
             input: '"Abcabc"'
-            output: '"+A-+a-"'
+            output: ['"+A-+a-"']
+
+          - program: '[gsub("p"; "a", "b")]'
+            input: '"p"'
+            output: ['["a","b"]']
 
 
   - title: Advanced features
@@ -2393,7 +2783,7 @@ sections:
 
       It is also possible to define functions in jq, although this is
       is a feature whose biggest use is defining jq's standard library
-      (many jq functions such as `map` and `find` are in fact written
+      (many jq functions such as `map` and `select` are in fact written
       in jq).
 
       jq has reduction operators, which are very powerful but a bit
@@ -2443,7 +2833,7 @@ sections:
           fields, and another object which is used to map author usernames to
           real names. Our input looks like:
 
-              {"posts": [{"title": "Frist psot", "author": "anon"},
+              {"posts": [{"title": "First post", "author": "anon"},
                          {"title": "A well-written article", "author": "person1"}],
                "realnames": {"anon": "Anonymous Coward",
                              "person1": "Person McPherson"}}
@@ -2451,7 +2841,7 @@ sections:
           We want to produce the posts with the author field containing a real
           name, as in:
 
-              {"title": "Frist psot", "author": "Anonymous Coward"}
+              {"title": "First post", "author": "Anonymous Coward"}
               {"title": "A well-written article", "author": "Person McPherson"}
 
           We use a variable, $names, to store the realnames object, so that we
@@ -2465,7 +2855,7 @@ sections:
           foreach loop.
 
           Just as `{foo}` is a handy way of writing `{foo: .foo}`, so
-          `{$foo}` is a handy way of writing `{foo:$foo}`.
+          `{$foo}` is a handy way of writing `{foo: $foo}`.
 
           Multiple variables may be declared using a single `as` expression by
           providing a pattern that matches the structure of the input
@@ -2512,7 +2902,7 @@ sections:
 
       - title: 'Destructuring Alternative Operator: `?//`'
         body: |
-        
+
           The destructuring alternative operator provides a concise mechanism
           for destructuring an input that can take one of several forms.
 
@@ -2521,10 +2911,10 @@ sections:
           the first event for each resource. The API (having been clumsily
           converted from XML) will only wrap the events in an array if the resource
           has multiple events:
-          
+
               {"resources": [{"id": 1, "kind": "widget", "events": {"action": "create", "user_id": 1, "ts": 13}},
                              {"id": 2, "kind": "widget", "events": [{"action": "create", "user_id": 1, "ts": 14}, {"action": "destroy", "user_id": 1, "ts": 15}]}]}
-          
+
           We can use the destructuring alternative operator to handle this structural change simply:
 
               .resources[] as {$id, $kind, events: {$user_id, $ts}} ?// {$id, $kind, events: [{$user_id, $ts}]} | {$user_id, $kind, $id, $ts}
@@ -2626,34 +3016,11 @@ sections:
 
           For example, in the following expression there is a binding
           which is visible "to the right" of it, `... | .*3 as
-          $times_three | [.  + $times_three] | ...`, but not "to the
+          $times_three | [. + $times_three] | ...`, but not "to the
           left".  Consider this expression now, `... | (.*3 as
-          $times_three | [.+ $times_three]) | ...`: here the binding
+          $times_three | [. + $times_three]) | ...`: here the binding
           `$times_three` is _not_ visible past the closing parenthesis.
 
-      - title: Reduce
-        body: |
-
-          The `reduce` syntax in jq allows you to combine all of the
-          results of an expression by accumulating them into a single
-          answer. As an example, we'll pass `[3,2,1]` to this expression:
-
-              reduce .[] as $item (0; . + $item)
-
-          For each result that `.[]` produces, `. + $item` is run to
-          accumulate a running total, starting from 0. In this
-          example, `.[]` produces the results 3, 2, and 1, so the
-          effect is similar to running something like this:
-
-              0 | (3 as $item | . + $item) |
-                  (2 as $item | . + $item) |
-                  (1 as $item | . + $item)
-
-        examples:
-          - program: 'reduce .[] as $item (0; . + $item)'
-            input: '[10,2,5,3]'
-            output: ['20']
-
       - title: "`isempty(exp)`"
         body: |
 
@@ -2664,31 +3031,50 @@ sections:
             input: 'null'
             output: ['true']
 
-      - title: "`limit(n; exp)`"
+          - program: 'isempty(.[])'
+            input: '[]'
+            output: ['true']
+
+          - program: 'isempty(.[])'
+            input: '[1,2,3]'
+            output: ['false']
+
+      - title: "`limit(n; expr)`"
         body: |
 
-          The `limit` function extracts up to `n` outputs from `exp`.
+          The `limit` function extracts up to `n` outputs from `expr`.
 
         examples:
-          - program: '[limit(3;.[])]'
+          - program: '[limit(3; .[])]'
             input: '[0,1,2,3,4,5,6,7,8,9]'
             output: ['[0,1,2]']
 
+      - title: "`skip(n; expr)`"
+        body: |
+
+          The `skip` function skips the first `n` outputs from `expr`.
+
+        examples:
+          - program: '[skip(3; .[])]'
+            input: '[0,1,2,3,4,5,6,7,8,9]'
+            output: ['[3,4,5,6,7,8,9]']
+
       - title: "`first(expr)`, `last(expr)`, `nth(n; expr)`"
         body: |
 
           The `first(expr)` and `last(expr)` functions extract the first
           and last values from `expr`, respectively.
 
-          The `nth(n; expr)` function extracts the nth value output by
-          `expr`.  This can be defined as `def nth(n; expr):
-          last(limit(n + 1; expr));`.  Note that `nth(n; expr)` doesn't
-          support negative values of `n`.
+          The `nth(n; expr)` function extracts the nth value output by `expr`.
+          Note that `nth(n; expr)` doesn't support negative values of `n`.
 
         examples:
-          - program: '[first(range(.)), last(range(.)), nth(./2; range(.))]'
+          - program: '[first(range(.)), last(range(.)), nth(5; range(.))]'
             input: '10'
             output: ['[0,9,5]']
+          - program: '[first(empty), last(empty), nth(5; empty)]'
+            input: 'null'
+            output: ['[]']
 
       - title: "`first`, `last`, `nth(n)`"
         body: |
@@ -2703,32 +3089,79 @@ sections:
             input: '10'
             output: ['[0,9,5]']
 
+      - title: "`reduce`"
+        body: |
+
+          The `reduce` syntax allows you to combine all of the results of
+          an expression by accumulating them into a single answer.
+          The form is `reduce EXP as $var (INIT; UPDATE)`.
+          As an example, we'll pass `[1,2,3]` to this expression:
+
+              reduce .[] as $item (0; . + $item)
+
+          For each result that `.[]` produces, `. + $item` is run to
+          accumulate a running total, starting from 0 as the input value.
+          In this example, `.[]` produces the results `1`, `2`, and `3`,
+          so the effect is similar to running something like this:
+
+              0 | 1 as $item | . + $item |
+                  2 as $item | . + $item |
+                  3 as $item | . + $item
+
+        examples:
+          - program: 'reduce .[] as $item (0; . + $item)'
+            input: '[1,2,3,4,5]'
+            output: ['15']
+
+          - program: 'reduce .[] as [$i,$j] (0; . + $i * $j)'
+            input: '[[1,2],[3,4],[5,6]]'
+            output: ['44']
+
+          - program: 'reduce .[] as {$x,$y} (null; .x += $x | .y += [$y])'
+            input: '[{"x":"a","y":1},{"x":"b","y":2},{"x":"c","y":3}]'
+            output: ['{"x":"abc","y":[1,2,3]}']
+
       - title: "`foreach`"
         body: |
 
           The `foreach` syntax is similar to `reduce`, but intended to
           allow the construction of `limit` and reducers that produce
-          intermediate results (see example).
+          intermediate results.
 
           The form is `foreach EXP as $var (INIT; UPDATE; EXTRACT)`.
-          Like `reduce`, `INIT` is evaluated once to produce a state
-          value, then each output of `EXP` is bound to `$var`, `UPDATE`
-          is evaluated for each output of `EXP` with the current state
-          and with `$var` visible.  Each value output by `UPDATE`
-          replaces the previous state.  Finally, `EXTRACT` is evaluated
-          for each new state to extract an output of `foreach`.
+          As an example, we'll pass `[1,2,3]` to this expression:
 
-          This is mostly useful only for constructing `reduce`- and
-          `limit`-like functions.  But it is much more general, as it
-          allows for partial reductions (see the example below).
+              foreach .[] as $item (0; . + $item; [$item, . * 2])
+
+          Like the `reduce` syntax, `. + $item` is run for each result
+          that `.[]` produces, but `[$item, . * 2]` is run for each
+          intermediate values. In this example, since the intermediate
+          values are `1`, `3`, and `6`, the `foreach` expression produces
+          `[1,2]`, `[2,6]`, and `[3,12]`. So the effect is similar
+          to running something like this:
+
+              0 | 1 as $item | . + $item | [$item, . * 2],
+                  2 as $item | . + $item | [$item, . * 2],
+                  3 as $item | . + $item | [$item, . * 2]
+
+          When `EXTRACT` is omitted, the identity filter is used.
+          That is, it outputs the intermediate values as they are.
 
         examples:
-          - program: '[foreach .[] as $item
-                        ([[],[]];
-                        if $item == null then [[],.[0]] else [(.[0] + [$item]),[]] end;
-                        if $item == null then .[1] else empty end)]'
-            input: '[1,2,3,4,null,"a","b",null]'
-            output: ['[[1,2,3,4],["a","b"]]']
+          - program: 'foreach .[] as $item (0; . + $item)'
+            input: '[1,2,3,4,5]'
+            output: ['1','3','6','10','15']
+
+          - program: 'foreach .[] as $item (0; . + $item; [$item, . * 2])'
+            input: '[1,2,3,4,5]'
+            output: ['[1,2]','[2,6]','[3,12]','[4,20]','[5,30]']
+
+          - program: 'foreach .[] as $item (0; . + 1; {index: ., $item})'
+            input: '["foo", "bar", "baz"]'
+            output:
+              - '{"index":1,"item":"foo"}'
+              - '{"index":2,"item":"bar"}'
+              - '{"index":3,"item":"baz"}'
 
       - title: Recursion
         body: |
@@ -2767,19 +3200,19 @@ sections:
             array or an object), `range(0; 10)` generates the integers
             between 0 and 10, and so on.
 
-            Even the comma operator is a generator, generating first the
-            values generated by the expression to the left of the comma,
-            then for each of those, the values generate by the
-            expression on the right of the comma.
+            Even the comma operator is a generator, generating first
+            the values generated by the expression to the left of the
+            comma, then the values generated by the expression on the
+            right of the comma.
 
             The `empty` builtin is the generator that produces zero
             outputs.  The `empty` builtin backtracks to the preceding
             generator expression.
 
             All jq functions can be generators just by using builtin
-            generators.  It is also possible to define new generators
-            using only recursion and the comma operator.  If the
-            recursive call(s) is(are) "in tail position" then the
+            generators.  It is also possible to construct new generators
+            using only recursion and the comma operator.  If
+            recursive calls are "in tail position" then the
             generator will be efficient.  In the example below the
             recursive call by `_range` to itself is in tail position.
             The example shows off three advanced topics: tail recursion,
@@ -2827,7 +3260,7 @@ sections:
       One-input C math functions: `acos` `acosh` `asin` `asinh` `atan`
       `atanh` `cbrt` `ceil` `cos` `cosh` `erf` `erfc` `exp` `exp10`
       `exp2` `expm1` `fabs` `floor` `gamma` `j0` `j1` `lgamma` `log`
-      `log10` `log1p` `log2` `logb` `nearbyint` `pow10` `rint` `round`
+      `log10` `log1p` `log2` `logb` `nearbyint` `rint` `round`
       `significand` `sin` `sinh` `sqrt` `tan` `tanh` `tgamma` `trunc`
       `y0` `y1`.
 
@@ -2847,11 +3280,13 @@ sections:
       are provided for this, `input` and `inputs`, that read from the
       same sources (e.g., `stdin`, files named on the command-line) as
       jq itself.  These two builtins, and jq's own reading actions, can
-      be interleaved with each other.
+      be interleaved with each other.  They are commonly used in combination
+      with the null input option `-n` to prevent one input from being read
+      implicitly.
 
       Two builtins provide minimal output capabilities, `debug`, and
       `stderr`.  (Recall that a jq program's output values are always
-      output as JSON texts on `stdout`.)  The `debug` builtin can have
+      output as JSON texts on `stdout`.) The `debug` builtin can have
       application-specific behavior, such as for executables that use
       the libjq C API but aren't the jq executable itself.  The `stderr`
       builtin outputs its input in raw mode to stder with no additional
@@ -2867,21 +3302,50 @@ sections:
 
           Outputs one new input.
 
+          Note that when using `input` it is generally be necessary to
+          invoke jq with the `-n` command-line option, otherwise
+          the first entity will be lost.
+
+              echo 1 2 3 4 | jq '[., input]' # [1,2] [3,4]
+
       - title: "`inputs`"
         body: |
 
           Outputs all remaining inputs, one by one.
 
           This is primarily useful for reductions over a program's
-          inputs.
+          inputs.  Note that when using `inputs` it is generally necessary
+          to invoke jq with the `-n` command-line option, otherwise
+          the first entity will be lost.
+
+              echo 1 2 3 | jq -n 'reduce inputs as $i (0; . + $i)' # 6
 
-      - title: "`debug`"
+      - title: "`debug`, `debug(msgs)`"
         body: |
 
-          Causes a debug message based on the input value to be
-          produced.  The jq executable wraps the input value with
-          `["DEBUG:", <input-value>]` and prints that and a newline on
-          stderr, compactly.  This may change in the future.
+          These two filters are like `.` but have as a side-effect the
+          production of one or more messages on stderr.
+
+          The message produced by the `debug` filter has the form
+
+              ["DEBUG:",<input-value>]
+
+          where `<input-value>` is a compact rendition of the input
+          value.  This format may change in the future.
+
+          The `debug(msgs)` filter is defined as `(msgs | debug | empty), .`
+          thus allowing great flexibility in the content of the message,
+          while also allowing multi-line debugging statements to be created.
+
+          For example, the expression:
+
+              1 as $x | 2 | debug("Entering function foo with $x == \($x)", .) | (.+1)
+
+          would produce the value 3 but with the following two lines
+          being written to stderr:
+
+              ["DEBUG:","Entering function foo with $x == 1"]
+              ["DEBUG:",2]
 
       - title: "`stderr`"
         body: |
@@ -2921,8 +3385,8 @@ sections:
       Streaming forms include `[<path>, <leaf-value>]` (to indicate any
       scalar value, empty array, or empty object), and `[<path>]` (to
       indicate the end of an array or object).  Future versions of jq
-      run with `--stream` and `-seq` may output additional forms such as
-      `["error message"]` when an input text fails to parse.
+      run with `--stream` and `--seq` may output additional forms such
+      as `["error message"]` when an input text fails to parse.
 
     entries:
       - title: "`truncate_stream(stream_expression)`"
@@ -2933,9 +3397,9 @@ sections:
           given streaming expression.
 
         examples:
-          - program: '[1|truncate_stream([[0],1],[[1,0],2],[[1,0]],[[1]])]'
+          - program: 'truncate_stream([[0],1],[[1,0],2],[[1,0]],[[1]])'
             input: '1'
-            output: ['[[[0],2],[[0]]]']
+            output: ['[[0],2]', '[[0]]']
 
       - title: "`fromstream(stream_expression)`"
         body: |
@@ -2970,7 +3434,7 @@ sections:
       and you append something to `.foo`, then `.bar` will not get
       bigger, even if you've previously set `.bar = .foo`.  If you're
       used to programming in languages like Python, Java, Ruby,
-      Javascript, etc. then you can think of it as though jq does a full
+      JavaScript, etc. then you can think of it as though jq does a full
       deep copy of every object before it does the assignment (for
       performance it doesn't actually do that, but that's the general
       idea).
@@ -3007,16 +3471,16 @@ sections:
     entries:
       - title: "Update-assignment: `|=`"
         body: |
-          This is the "update" operator '|='.  It takes a filter on the
+          This is the "update" operator `|=`.  It takes a filter on the
           right-hand side and works out the new value for the property
           of `.` being assigned to by running the old value through this
-          expression. For instance, (.foo, .bar) |= .+1 will build an
-          object with the "foo" field set to the input's "foo" plus 1,
-          and the "bar" field set to the input's "bar" plus 1.
+          expression. For instance, `(.foo, .bar) |= .+1` will build an
+          object with the `foo` field set to the input's `foo` plus 1,
+          and the `bar` field set to the input's `bar` plus 1.
 
           The left-hand side can be any general path expression; see `path()`.
 
-          Note that the left-hand side of '|=' refers to a value in `.`.
+          Note that the left-hand side of `|=` refers to a value in `.`.
           Thus `$var.foo |= . + 1` won't work as expected (`$var.foo` is
           not a valid or useful path expression in `.`); use `$var |
           .foo |= . + 1` instead.
@@ -3049,41 +3513,52 @@ sections:
         body: |
 
           This is the plain assignment operator.  Unlike the others, the
-          input to the right-hand-side (RHS) is the same as the input to
-          the left-hand-side (LHS) rather than the value at the LHS
+          input to the right-hand side (RHS) is the same as the input to
+          the left-hand side (LHS) rather than the value at the LHS
           path, and all values output by the RHS will be used (as shown
           below).
 
-          If the RHS of '=' produces multiple values, then for each such
+          If the RHS of `=` produces multiple values, then for each such
           value jq will set the paths on the left-hand side to the value
           and then it will output the modified `.`.  For example,
-          `(.a,.b)=range(2)` outputs `{"a":0,"b":0}`, then
+          `(.a,.b) = range(2)` outputs `{"a":0,"b":0}`, then
           `{"a":1,"b":1}`.  The "update" assignment forms (see above) do
           not do this.
 
-          This example should show the difference between '=' and '|=':
+          This example should show the difference between `=` and `|=`:
 
-          Provide input '{"a": {"b": 10}, "b": 20}' to the programs:
+          Provide input `{"a": {"b": 10}, "b": 20}` to the programs
 
-          .a = .b
+              .a = .b
 
-          .a |= .b
+          and
 
-          The former will set the "a" field of the input to the "b"
-          field of the input, and produce the output {"a": 20, "b": 20}.
-          The latter will set the "a" field of the input to the "a"
-          field's "b" field, producing {"a": 10, "b": 20}.
+              .a |= .b
 
-          Another example of the difference between '=' and '|=':
+          The former will set the `a` field of the input to the `b`
+          field of the input, and produce the output `{"a": 20, "b": 20}`.
+          The latter will set the `a` field of the input to the `a`
+          field's `b` field, producing `{"a": 10, "b": 20}`.
 
-          null|(.a,.b)=range(3)
+        examples:
+          - program: .a = .b
+            input: '{"a": {"b": 10}, "b": 20}'
+            output: ['{"a":20,"b":20}']
 
-          outputs '{"a":0,"b":0}', '{"a":1,"b":1}', and '{"a":2,"b":2}',
-          while
+          - program: .a |= .b
+            input: '{"a": {"b": 10}, "b": 20}'
+            output: ['{"a":10,"b":20}']
 
-          null|(.a,.b)|=range(3)
+          - program: (.a, .b) = range(3)
+            input: 'null'
+            output:
+              - '{"a":0,"b":0}'
+              - '{"a":1,"b":1}'
+              - '{"a":2,"b":2}'
 
-          outputs just '{"a":0,"b":0}'.
+          - program: (.a, .b) |= range(3)
+            input: 'null'
+            output: ['{"a":0,"b":0}']
 
       - title: Complex assignments
         body: |
@@ -3125,6 +3600,68 @@ sections:
               (.posts[] | select(.author == "stedolan") | .comments) |=
                   . + ["terrible."]
 
+  - title: Comments
+
+    body: |
+
+      You can write comments in your jq filters using `#`.
+
+      A `#` character (not part of a string) starts a comment.
+      All characters from `#` to the end of the line are ignored.
+
+      If the end of the line is preceded by an odd number of backslash
+      characters, the following line is also considered part of the
+      comment and is ignored.
+
+      For example, the following code outputs `[1,3,4,7]`
+
+          [
+            1,
+            # foo \
+            2,
+            # bar \\
+            3,
+            4, # baz \\\
+            5, \
+            6,
+            7
+            # comment \
+              comment \
+              comment
+          ]
+
+      Backslash continuing the comment on the next line can be useful
+      when writing the "shebang" for a jq script:
+
+          #!/bin/sh --
+          # total - Output the sum of the given arguments (or stdin)
+          # usage: total [numbers...]
+          # \
+          exec jq --args -MRnf -- "$0" "$@"
+
+          $ARGS.positional |
+          reduce (
+            if . == []
+              then inputs
+              else .[]
+            end |
+            . as $dot |
+            try tonumber catch false |
+            if not or isnan then
+              @json "total: Invalid number \($dot).\n" | halt_error(1)
+            end
+          ) as $n (0; . + $n)
+
+      The `exec` line is considered a comment by jq, so it is ignored.
+      But it is not ignored by `sh`, since in `sh` a backslash at the
+      end of the line does not continue the comment.
+      With this trick, when the script is invoked as `total 1 2`,
+      `/bin/sh -- /path/to/total 1 2` will be run, and `sh` will then
+      run `exec jq --args -MRnf -- /path/to/total 1 2` replacing itself
+      with a `jq` interpreter invoked with the specified options (`-M`,
+      `-R`, `-n`, `--args`), that evaluates the current file (`$0`),
+      with the arguments (`$@`) that were passed to `sh`.
+
   - title: Modules
     body: |
 
@@ -3135,16 +3672,16 @@ sections:
       path (see below).  The `import` and `include` directives allow the
       importer to alter this path.
 
-      Paths in the a search path are subject to various substitutions.
+      Paths in the search path are subject to various substitutions.
 
-      For paths starting with "~/", the user's home directory is
-      substituted for "~".
+      For paths starting with `~/`, the user's home directory is
+      substituted for `~`.
 
-      For paths starting with "$ORIGIN/", the path of the jq executable
-      is substituted for "$ORIGIN".
+      For paths starting with `$ORIGIN/`, the directory where the jq
+      executable is located is substituted for `$ORIGIN`.
 
-      For paths starting with "./" or paths that are ".", the path of
-      the including file is substituted for ".".  For top-level programs
+      For paths starting with `./` or paths that are `.`, the path of
+      the including file is substituted for `.`.  For top-level programs
       given on the command-line, the current directory is used.
 
       Import directives can optionally specify a search path to which
@@ -3157,36 +3694,37 @@ sections:
       Null and empty string path elements terminate search path
       processing.
 
-      A dependency with relative path "foo/bar" would be searched for in
-      "foo/bar.jq" and "foo/bar/bar.jq" in the given search path. This
+      A dependency with relative path `foo/bar` would be searched for in
+      `foo/bar.jq` and `foo/bar/bar.jq` in the given search path. This
       is intended to allow modules to be placed in a directory along
       with, for example, version control files, README files, and so on,
       but also to allow for single-file modules.
 
       Consecutive components with the same name are not allowed to avoid
-      ambiguities (e.g., "foo/foo").
+      ambiguities (e.g., `foo/foo`).
 
       For example, with `-L$HOME/.jq` a module `foo` can be found in
       `$HOME/.jq/foo.jq` and `$HOME/.jq/foo/foo.jq`.
 
-      If "$HOME/.jq" is a file, it is sourced into the main program.
+      If `.jq` exists in the user's home directory, and is a file (not a
+      directory), it is automatically sourced into the main program.
 
     entries:
       - title: "`import RelativePathString as NAME [<metadata>];`"
         body: |
 
           Imports a module found at the given path relative to a
-          directory in a search path.  A ".jq" suffix will be added to
+          directory in a search path.  A `.jq` suffix will be added to
           the relative path string.  The module's symbols are prefixed
-          with "NAME::".
+          with `NAME::`.
 
           The optional metadata must be a constant jq expression.  It
-          should be an object with keys like "homepage" and so on.  At
-          this time jq only uses the "search" key/value of the metadata.
+          should be an object with keys like `homepage` and so on.  At
+          this time jq only uses the `search` key/value of the metadata.
           The metadata is also made available to users via the
           `modulemeta` builtin.
 
-          The "search" key in the metadata, if present, should have a
+          The `search` key in the metadata, if present, should have a
           string or array value (array of strings); this is the search
           path to be prefixed to the top-level search path.
 
@@ -3195,13 +3733,13 @@ sections:
 
           Imports a module found at the given path relative to a
           directory in a search path as if it were included in place.  A
-          ".jq" suffix will be added to the relative path string.  The
+          `.jq` suffix will be added to the relative path string.  The
           module's symbols are imported into the caller's namespace as
           if the module's content had been included directly.
 
           The optional metadata must be a constant jq expression.  It
-          should be an object with keys like "homepage" and so on.  At
-          this time jq only uses the "search" key/value of the metadata.
+          should be an object with keys like `homepage` and so on.  At
+          this time jq only uses the `search` key/value of the metadata.
           The metadata is also made available to users via the
           `modulemeta` builtin.
 
@@ -3209,17 +3747,17 @@ sections:
         body: |
 
           Imports a JSON file found at the given path relative to a
-          directory in a search path.  A ".json" suffix will be added to
+          directory in a search path.  A `.json` suffix will be added to
           the relative path string.  The file's data will be available
           as `$NAME::NAME`.
 
           The optional metadata must be a constant jq expression.  It
-          should be an object with keys like "homepage" and so on.  At
-          this time jq only uses the "search" key/value of the metadata.
+          should be an object with keys like `homepage` and so on.  At
+          this time jq only uses the `search` key/value of the metadata.
           The metadata is also made available to users via the
           `modulemeta` builtin.
 
-          The "search" key in the metadata, if present, should have a
+          The `search` key in the metadata, if present, should have a
           string or array value (array of strings); this is the search
           path to be prefixed to the top-level search path.
 
@@ -3231,7 +3769,7 @@ sections:
           metadata that can be read with the `modulemeta` builtin.
 
           The metadata must be a constant jq expression.  It should be
-          an object with keys like "homepage".  At this time jq doesn't
+          an object with keys like `homepage`.  At this time jq doesn't
           use this metadata, but it is made available to users via the
           `modulemeta` builtin.
 
@@ -3240,7 +3778,8 @@ sections:
 
           Takes a module name as input and outputs the module's metadata
           as an object, with the module's imports (including metadata)
-          as an array value for the "deps" key.
+          as an array value for the `deps` key and the module's defined
+          functions as an array value for the `defs` key.
 
           Programs can use this to query a module's metadata, which they
           could then use to, for example, search for, download, and
@@ -3260,9 +3799,10 @@ sections:
         - color for strings
         - color for arrays
         - color for objects
+        - color for object keys
 
       The default color scheme is the same as setting
-      `"JQ_COLORS=1;30:0;39:0;39:0;39:0;32:1;39:1;39"`.
+      `JQ_COLORS="0;90:0;39:0;39:0;39:0;32:1;39:1;39:1;34"`.
 
       This is not a manual for VT100/ANSI escapes.  However, each of
       these color specifications should consist of two numbers separated