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

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

@@ -1,11 +1,5 @@
 ---
-headline: jq Manual (development version)
-
-history: |
-
-  *For released versions, see [jq 1.6](/jq/manual/v1.6),
-  [jq 1.5](/jq/manual/v1.5),  [jq 1.4](/jq/manual/v1.4)
-  or [jq 1.3](/jq/manual/v1.3).*
+headline: jq 1.6 Manual
 
 body: |
 
@@ -66,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
 
@@ -79,8 +73,8 @@ 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.
 
       Note: it is important to mind the shell's quoting rules.  As a
       general rule it's best to always quote (with single-quote
@@ -91,55 +85,37 @@ sections:
       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.
+      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.
+
+      * Unix shells: `jq '.["foo"]'`
+      * Powershell: `jq '.[\"foo\"]'`
+      * Windows command shell: `jq ".[\"foo\"]"`
 
       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.
-
-      * `--stream`:
-
-        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"]`.
-
-        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.
+      * `--null-input` / `-n`:
 
-      * `--slurp`/`-s`:
-
-        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`:
 
@@ -147,13 +123,28 @@ 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`:
+      * `--join-output` / `-j`:
+
+        Like `-r` but jq won't print a newline after each output.
+
+      * `--ascii-output` / `-a`:
 
-        Use the given number of spaces (no more than 8) for indentation.
+        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.
+
+      * `--sort-keys` / `-S`:
+
+        Output the fields of each object with the keys in sorted order.
 
       * `--color-output` / `-C` and `--monochrome-output` / `-M`:
 
@@ -164,58 +155,53 @@ sections:
         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`:
-
-        Output the fields of each object with the keys in sorted order.
+      * `--stream`:
 
-      * `--raw-output` / `-r`:
+        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"]`.
 
-        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.
+        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.
 
-      * `--join-output` / `-j`:
+      * `--seq`:
 
-        Like `-r` but jq won't print a newline after each output.
+        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`:
 
         Read filter from the file rather than from a command line, like
         awk's -f option. You can also use '#' to make comments.
 
-      * `-Ldirectory` / `-L directory`:
+      * `-L 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
@@ -245,7 +231,7 @@ 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`:
@@ -266,6 +252,26 @@ 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.
+
+      * `--version` / `-V`:
+
+        Output the jq version and exit with zero.
+
+      * `--help` / `-h`:
+
+        Output the jq help and exit with zero.
+
       * `--run-tests [filename]`:
 
         Runs the tests in the given file or standard input.  This must
@@ -274,7 +280,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.
 
@@ -298,6 +304,7 @@ sections:
             input: '"Hello, world!"'
             output: ['"Hello, world!"']
 
+
       - title: "Object Identifier-Index: `.foo`, `.foo.bar`"
         body: |
 
@@ -311,8 +318,9 @@ sections:
           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"]`.
@@ -320,45 +328,45 @@ sections:
         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.
 
@@ -378,16 +386,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]'
@@ -413,7 +422,8 @@ 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.
@@ -429,6 +439,10 @@ sections:
             input: '[]'
             output: []
 
+          - program: '.foo[]'
+            input: '{"foo":[1,2,3]}'
+            output: ['1','2','3']
+
           - program: '.[]'
             input: '{"a": 1, "b": 1}'
             output: ['1', '1']
@@ -437,7 +451,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: |
@@ -497,7 +512,7 @@ sections:
         examples:
           - program: '(. + 2) * 5'
             input: '1'
-            output: [15]
+            output: ['15']
 
   - title: Types and Values
     body: |
@@ -507,7 +522,7 @@ 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.
@@ -609,22 +624,22 @@ 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
@@ -645,10 +660,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.
@@ -685,7 +700,7 @@ 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.
@@ -704,8 +719,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"]']
@@ -727,16 +742,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`"
@@ -748,7 +767,7 @@ sections:
         examples:
           - program: 'utf8bytelength'
             input: '"\u03bc"'
-            output: [2]
+            output: ['2']
 
       - title: "`keys`, `keys_unsorted`"
         body: |
@@ -812,18 +831,18 @@ 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
+          For any filter `f`, `map(f)` 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.
 
-          Similarly, `map_values(x)` will run that filter for each element,
+          Similarly, `map_values(f)` will run that filter for each element,
           but it will return an object when an object is passed.
 
-          `map(x)` is equivalent to `[.[] | x]`. In fact, this is how
-          it's defined. Similarly, `map_values(x)` is defined as `.[] |= x`.
+          `map(f)` is equivalent to `[.[] | f]`. In fact, this is how
+          it's defined. Similarly, `map_values(f)` is defined as `.[] |= f`.
 
         examples:
           - program: 'map(.+1)'
@@ -922,7 +941,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
@@ -930,11 +949,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'
@@ -951,8 +970,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))`
@@ -990,17 +1009,30 @@ 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.
+
+          When the error value is `null`, it produces nothing and works
+          just like `empty`. So `[null | error]` and `[error(null)]` both
+          emit `[]`.
+
+        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: |
@@ -1018,7 +1050,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: |
@@ -1039,8 +1071,8 @@ sections:
           (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
@@ -1050,7 +1082,7 @@ sections:
           - 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"]]']
 
@@ -1071,7 +1103,7 @@ sections:
             output: ['"abc"']
           - program: add
             input: '[1, 2, 3]'
-            output: [6]
+            output: ['6']
           - program: add
             input: '[]'
             output: ["null"]
@@ -1153,12 +1185,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
@@ -1171,22 +1203,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]']
 
@@ -1220,7 +1252,7 @@ sections:
         examples:
           - program: '.[] | tonumber'
             input: '[1, "1"]'
-            output: [1, 1]
+            output: ['1', '1']
 
       - title: "`tostring`"
         body: |
@@ -1270,7 +1302,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
@@ -1289,19 +1321,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: |
@@ -1428,9 +1466,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: |
@@ -1570,10 +1620,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: |
@@ -1635,7 +1685,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
@@ -1670,11 +1720,8 @@ sections:
               - '1'
 
           - program: 'recurse(. * .; . < 20)'
-            input: 2
-            output:
-                - 2
-                - 4
-                - 16
+            input: '2'
+            output: ['2', '4', '16']
 
       - title: "`walk(f)`"
         body: |
@@ -1736,13 +1783,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:
@@ -1756,7 +1803,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
@@ -1772,9 +1819,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]'
@@ -1866,10 +1913,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'\""]
@@ -1914,7 +1957,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
@@ -1930,7 +1973,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
@@ -1962,40 +2005,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: |
@@ -2013,8 +2056,8 @@ sections:
           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
           '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
+          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.
 
           != is "not equal", and 'a != b' returns the opposite value of 'a == b'
@@ -2024,7 +2067,7 @@ sections:
             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`
@@ -2032,12 +2075,11 @@ sections:
           as `C` otherwise.
 
           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
+          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.
+          need something more 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
@@ -2054,10 +2096,10 @@ sections:
               else
                 "many"
               end
-            input: 2
+            input: '2'
             output: ['"many"']
 
-      - title: "`>, >=, <=, <`"
+      - title: "`>`, `>=`, `<=`, `<`"
         body: |
 
           The comparison operators `>`, `>=`, `<=`, `<` return whether
@@ -2069,15 +2111,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.
@@ -2087,12 +2130,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"'
@@ -2101,9 +2144,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']
@@ -2127,10 +2167,10 @@ sections:
         examples:
           - program: '.foo // 42'
             input: '{"foo": 19}'
-            output: [19]
+            output: ['19']
           - program: '.foo // 42'
             input: '{}'
-            output: [42]
+            output: ['42']
 
       - title: try-catch
         body: |
@@ -2165,14 +2205,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`
@@ -2194,51 +2234,54 @@ 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
+      jq uses the Oniguruma regular expression library, as do PHP,
+      Ruby, TextMate, Sublime Text, etc, so the description here
       will focus on jq specifics.
 
       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.
 
       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)`"
@@ -2297,7 +2340,7 @@ sections:
 
           - program: '[ match("."; "g")] | length'
             input: '"abc"'
-            output: [3]
+            output: ['3']
 
 
       - title: "`capture(val)`, `capture(regex; flags)`"
@@ -2321,24 +2364,20 @@ 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.
 
-        example:
+        examples:
           - program: 'split(", *"; null)'
             input: '"ab,cd, ef"'
-            output: ['"ab","cd","ef"']
+            output: ['["ab","cd","ef"]']
 
 
       - title: "`splits(regex)`, `splits(regex; flags)`"
@@ -2347,12 +2386,12 @@ 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; string; flags)`"
         body: |
 
           Emit the string obtained by replacing the first match of regex in the
@@ -2360,12 +2399,12 @@ sections:
           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)".
+          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"']
 
 
       - title: "`gsub(regex; string)`, `gsub(regex; string; flags)`"
@@ -2374,10 +2413,10 @@ sections:
           `gsub` is like `sub` but all the non-overlapping occurrences of the regex are
           replaced by the string, after interpolation.
 
-        example:
+        examples:
           - program: 'gsub("(?<x>.)[^a]*"; "+\(.x)-")'
             input: '"Abcabc"'
-            output: '"+A-+a-"'
+            output: ['"+A-+a-"']
 
 
   - title: Advanced features
@@ -2394,7 +2433,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
@@ -2444,7 +2483,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"}}
@@ -2452,7 +2491,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
@@ -2466,7 +2505,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
@@ -2513,7 +2552,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.
 
@@ -2522,10 +2561,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}
@@ -2627,34 +2666,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: |
 
@@ -2665,6 +2681,14 @@ sections:
             input: 'null'
             output: ['true']
 
+          - program: 'isempty(.[])'
+            input: '[]'
+            output: ['true']
+
+          - program: 'isempty(.[])'
+            input: '[1,2,3]'
+            output: ['false']
+
       - title: "`limit(n; exp)`"
         body: |
 
@@ -2704,32 +2728,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:
+
+              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]
 
-          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).
+          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: |
@@ -2868,6 +2939,8 @@ sections:
 
           Outputs one new input.
 
+              echo 1 2 3 4 | jq '[., input]' # [1,2] [3,4]
+
       - title: "`inputs`"
         body: |
 
@@ -2876,6 +2949,8 @@ sections:
           This is primarily useful for reductions over a program's
           inputs.
 
+              echo 1 2 3 | jq -n 'reduce inputs as $i (0; . + $i)' # 6
+
       - title: "`debug`"
         body: |
 
@@ -2922,8 +2997,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)`"
@@ -2934,9 +3009,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: |
@@ -2971,7 +3046,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).
@@ -3008,16 +3083,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
+          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.
@@ -3064,27 +3139,27 @@ sections:
 
           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
+          `.a |= .b`
 
           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}.
+          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}.
+          field's "b" field, producing `{"a": 10, "b": 20}`.
 
-          Another example of the difference between '=' and '|=':
+          Another example of the difference between `=` and `|=`:
 
-          null|(.a,.b)=range(3)
+          `null|(.a,.b)=range(3)`
 
-          outputs '{"a":0,"b":0}', '{"a":1,"b":1}', and '{"a":2,"b":2}',
+          outputs `{"a":0,"b":0}, {"a":1,"b":1}, {"a":2,"b":2}`,
           while
 
-          null|(.a,.b)|=range(3)
+          `null|(.a,.b)|=range(3)`
 
-          outputs just '{"a":0,"b":0}'.
+          outputs just `{"a":0,"b":0}`.
 
       - title: Complex assignments
         body: |
@@ -3136,13 +3211,13 @@ 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 "$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