Update website with details for jq-1.6

4 files changed, 3314 insertions, 2 deletions

diff --git a/docs/content/2.download/default.yml b/docs/content/2.download/default.yml
index fc516f4b..2cf7d125 100644
--- a/docs/content/2.download/default.yml
+++ b/docs/content/2.download/default.yml
@@ -31,6 +31,11 @@ body:
          [Arch](https://www.archlinux.org/packages/?sort=&q=jq&maintainer=&flagged=)
          repository.  Install using `sudo pacman -Sy jq`.
 
+       * jq 1.6 binaries for
+         [64-bit](https://github.com/stedolan/jq/releases/download/jq-1.6/jq-linux64)
+         or
+         [32-bit](https://github.com/stedolan/jq/releases/download/jq-1.6/jq-linux32).
+
        * jq 1.5 binaries for
          [64-bit](https://github.com/stedolan/jq/releases/download/jq-1.5/jq-linux64)
          or
@@ -51,6 +56,9 @@ body:
        * Use [Homebrew](http://brew.sh/) to install jq 1.5 with
          `brew install jq`.
 
+       * jq 1.6 binary for
+         [64-bit](https://github.com/stedolan/jq/releases/download/jq-1.6/jq-osx-amd64).
+
        * jq 1.5 binary for
          [64-bit](https://github.com/stedolan/jq/releases/download/jq-1.5/jq-osx-amd64).
 
@@ -89,6 +97,11 @@ body:
        * Use [Chocolatey NuGet](https://chocolatey.org/) to install jq 1.5 with
          `chocolatey install jq`.
 
+       * jq 1.6 executables for
+         [64-bit](https://github.com/stedolan/jq/releases/download/jq-1.6/jq-win64.exe)
+         or
+         [32-bit](https://github.com/stedolan/jq/releases/download/jq-1.6/jq-win32.exe).
+
        * jq 1.5 executables for
          [64-bit](https://github.com/stedolan/jq/releases/download/jq-1.5/jq-win64.exe)
          or
@@ -109,6 +122,8 @@ body:
       SHA-256 checksums are provided for all release and pre-release binaries.
       They can be found under
       [sig/v1.x/sha256sum.txt](https://github.com/stedolan/jq/tree/master/sig).
+      The checksums for jq 1.6 are in
+      [sig/v1.6/sha256sum.txt](https://raw.githubusercontent.com/stedolan/jq/master/sig/v1.6/sha256sum.txt).
       The checksums for jq 1.5 are in
       [sig/v1.5/sha256sum.txt](https://raw.githubusercontent.com/stedolan/jq/master/sig/v1.5/sha256sum.txt).
 
@@ -116,6 +131,8 @@ body:
       [jq Package Signing Key](https://raw.githubusercontent.com/stedolan/jq/master/sig/jq-release.key).
       The signatures can be found under
       [sig/v1.x/\*.asc](https://github.com/stedolan/jq/tree/master/sig).
+      The signatures for jq 1.6 are in
+      [sig/v1.5/\*.asc](https://github.com/stedolan/jq/tree/master/sig/v1.6).
       The signatures for jq 1.5 are in
       [sig/v1.5/\*.asc](https://github.com/stedolan/jq/tree/master/sig/v1.5).
       You can use [GnuPG](https://gnupg.org/) to verify a signature by downloading
@@ -123,6 +140,7 @@ body:
 
       ### From source on Linux, OS X, Cygwin, and other POSIX-like operating systems
 
+       * [Source tarball for jq 1.6](https://github.com/stedolan/jq/releases/download/jq-1.6/jq-1.6.tar.gz)
        * [Source tarball for jq 1.5](https://github.com/stedolan/jq/releases/download/jq-1.5/jq-1.5.tar.gz)
 
       You can build it using the usual `./configure && make && sudo
diff --git a/docs/content/3.manual/manual.yml b/docs/content/3.manual/manual.yml
index 3f385e9f..bfb17f48 100644
--- a/docs/content/3.manual/manual.yml
+++ b/docs/content/3.manual/manual.yml
@@ -3,8 +3,9 @@ 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).*
+  *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).*
 
 body: |
 
diff --git a/docs/content/3.manual/v1.6/manual.yml b/docs/content/3.manual/v1.6/manual.yml
new file mode 100644
index 00000000..3f385e9f
--- /dev/null
+++ b/docs/content/3.manual/v1.6/manual.yml
@@ -0,0 +1,3287 @@
+---
+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
+  output. There are a lot of builtin filters for extracting a
+  particular field of an object, or converting a number to a string,
+  or various other standard tasks.
+
+  Filters can be combined in various ways - you can pipe the output of
+  one filter into another filter, or collect the output of a filter
+  into an array.
+
+  Some filters produce multiple results, for instance there's one that
+  produces all the elements of its input array. Piping that filter
+  into a second runs the second filter for each element of the
+  array. Generally, things that would be done with loops and iteration
+  in other languages are just done by gluing filters together in jq.
+
+  It's important to remember that every filter has an input and an
+  output. Even literals like "hello" or 42 are filters - they take an
+  input but always produce the same literal as output. Operations that
+  combine two filters, like addition, generally feed the same input to
+  both and combine the results. So, you can implement an averaging
+  filter as `add / length` - feeding the input array both to the `add`
+  filter and the `length` filter and then performing the division.
+
+  But that's getting ahead of ourselves. :) Let's start with something
+  simpler:
+
+manpage_intro: |
+  jq(1) -- Command-line JSON processor
+  ====================================
+
+  ## SYNOPSIS
+
+  `jq` [<options>...] <filter> [<files>...]
+
+  `jq` can transform JSON in various ways, by selecting, iterating,
+  reducing and otherwise mangling JSON documents. For instance,
+  running the command `jq 'map(.price) | add'` will take an array of
+  JSON objects as input and return the sum of their "price" fields.
+
+  `jq` can accept text input as well, but by default, `jq` reads a
+  stream of JSON entities (including numbers and other literals) from
+  `stdin`. Whitespace is only needed to separate entities such as 1
+  and 2, and true and false.  One or more <files> may be specified, in
+  which case `jq` will read input from those instead.
+
+  The <options> are described in the [INVOKING JQ] section; they
+  mostly concern input and output formatting. The <filter> is written
+  in the jq language and specifies how to transform the input
+  file or document.
+
+  ## FILTERS
+
+manpage_epilogue: |
+  ## BUGS
+
+  Presumably. Report them or discuss them at:
+
+      https://github.com/stedolan/jq/issues
+
+  ## AUTHOR
+
+  Stephen Dolan `<mu@netsoc.tcd.ie>`
+
+sections:
+  - title: Invoking jq
+    body: |
+
+      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.
+
+      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
+      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.
+
+      * `--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.
+
+      * `--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.
+
+      * `--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`:
+
+        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.
+
+      * `--compact-output` / `-c`:
+
+        By default, jq pretty-prints JSON output. Using this option
+        will result in more compact output by instead putting each
+        JSON object on a single line.
+
+      * `--tab`:
+
+        Use a tab for each indentation level instead of two spaces.
+
+      * `--indent n`:
+
+        Use the given number of spaces (no more than 8) for indentation.
+
+      * `--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`.
+
+        Colors can be configured with the `JQ_COLORS` environment
+        variable (see below).
+
+      * `--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.
+
+      * `--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.
+
+      * `--raw-output` / `-r`:
+
+        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.
+
+      * `--join-output` / `-j`:
+
+        Like `-r` but jq won't print a newline after each output.
+
+      * `-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`:
+
+        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
+        variable. If you run jq with `--arg foo bar`, then `$foo` is
+        available in the program and has the value `"bar"`. Note that
+        `value` will be treated as a string, so `--arg foo 123` will
+        bind `$foo` to `"123"`.
+
+        Named arguments are also available to the jq program as
+        `$ARGS.named`.
+
+      * `--argjson name JSON-text`:
+
+        This option passes a JSON-encoded value to the jq program as a
+        predefined variable. If you run jq with `--argjson foo 123`, then
+        `$foo` is available in the program and has the value `123`.
+
+      * `--slurpfile variable-name filename`:
+
+        This option reads all the JSON texts in the named file and binds
+        an array of the parsed JSON values to the given global variable.
+        If you run jq with `--slurpfile foo bar`, then `$foo` is available
+        in the program and has an array whose elements correspond to the
+        texts in the file named `bar`.
+
+      * `--rawfile variable-name filename`:
+
+        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
+        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
+        available to the jq program as `$ARGS.positional[]`.
+
+      * `--jsonargs`:
+
+        Remaining arguments are positional JSON text arguments.  These
+        are available to the jq program as `$ARGS.positional[]`.
+
+      * `--run-tests [filename]`:
+
+        Runs the tests in the given file or standard input.  This must
+        be the last option given and does not honor all preceding
+        options.  The input consists of comment lines, empty lines, and
+        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,
+        then a line containing an error message to compare to the
+        actual.
+
+        Be warned that this option can change backwards-incompatibly.
+
+  - title: Basic filters
+    entries:
+      - title: "Identity: `.`"
+        body: |
+
+          The absolute simplest filter is `.` .  This is a filter that
+          takes its input and produces it unchanged as output.  That is,
+          this is the identity operator.
+
+          Since jq by default pretty-prints all output, this trivial
+          program can be a useful way of formatting JSON output from,
+          say, `curl`.
+
+        examples:
+          - program: '.'
+            input: '"Hello, world!"'
+            output: ['"Hello, world!"']
+
+      - 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.
+
+          A filter of the form `.foo.bar` is equivalent to `.foo|.bar`.
+
+          This 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$"]`.
+
+          For example `.["foo::bar"]` and `.["foo.bar"]` work while
+          `.foo::bar` does not, and `.foo.bar` means `.["foo"].["bar"]`.
+
+        examples:
+          - program: '.foo'
+            input: '{"foo": 42, "bar": "less interesting data"}'
+            output: [42]
+          - program: '.foo'
+            input: '{"notfoo": true, "alsonotfoo": false}'
+            output: ['null']
+          - program: '.["foo"]'
+            input: '{"foo": 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.
+
+        examples:
+          - program: '.foo?'
+            input: '{"foo": 42, "bar": "less interesting data"}'
+            output: [42]
+          - program: '.foo?'
+            input: '{"notfoo": true, "alsonotfoo": false}'
+            output: ['null']
+          - program: '.["foo"]?'
+            input: '{"foo": 42}'
+            output: [42]
+          - program: '[.foo?]'
+            input: '[1,2]'
+            output: ['[]']
+
+      - title: "Generic 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
+          only for identifier-like strings).
+
+      - title: "Array Index: `.[2]`"
+        body: |
+
+          When the index value is an integer, `.[<value>]` can index
+          arrays.  Arrays are zero-based, so `.[2]` returns the third
+          element.
+
+          Negative indices are allowed, with -1 referring to the last
+          element, -2 referring to the next to last element, and so on.
+
+        examples:
+          - program: '.[0]'
+            input: '[{"name":"JSON", "good":true}, {"name":"XML", "good":false}]'
+            output: ['{"name":"JSON", "good":true}']
+
+          - program: '.[2]'
+            input: '[{"name":"JSON", "good":true}, {"name":"XML", "good":false}]'
+            output: ['null']
+
+          - program: '.[-2]'
+            input: '[1,2,3]'
+            output: ['2']
+
+      - title: "Array/String Slice: `.[10:15]`"
+        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).
+
+        examples:
+          - program: '.[2:4]'
+            input: '["a","b","c","d","e"]'
+            output: ['["c", "d"]']
+
+          - program: '.[2:4]'
+            input: '"abcdefghi"'
+            output: ['"cd"']
+
+          - program: '.[:3]'
+            input: '["a","b","c","d","e"]'
+            output: ['["a", "b", "c"]']
+
+          - program: '.[-2:]'
+            input: '["a","b","c","d","e"]'
+            output: ['["d", "e"]']
+
+      - title: "Array/Object Value Iterator: `.[]`"
+        body: |
+
+          If you use the `.[index]` syntax, but omit the index
+          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.
+
+          You can also use this on an object, and it will return all
+          the values of the object.
+
+        examples:
+          - program: '.[]'
+            input: '[{"name":"JSON", "good":true}, {"name":"XML", "good":false}]'
+            output:
+              - '{"name":"JSON", "good":true}'
+              - '{"name":"XML", "good":false}'
+
+          - program: '.[]'
+            input: '[]'
+            output: []
+
+          - program: '.[]'
+            input: '{"a": 1, "b": 1}'
+            output: ['1', '1']
+
+      - title: "`.[]?`"
+        body: |
+
+          Like `.[]`, but no errors will be output if . is not an array
+          or object.
+
+      - title: "Comma: `,`"
+        body: |
+
+          If two filters are separated by a comma, then the
+          same input will be fed into both and the two filters' output
+          value streams will be concatenated in order: first, all of the
+          outputs produced by the left expression, and then all of the
+          outputs produced by the right. For instance, filter `.foo,
+          .bar`, produces both the "foo" fields and "bar" fields as
+          separate outputs.
+
+        examples:
+          - program: '.foo, .bar'
+            input: '{"foo": 42, "bar": "something else", "baz": true}'
+            output: ['42', '"something else"']
+
+          - program: ".user, .projects[]"
+            input: '{"user":"stedolan", "projects": ["jq", "wikiflow"]}'
+            output: ['"stedolan"', '"jq"', '"wikiflow"']
+
+          - program: '.[4,2]'
+            input: '["a","b","c","d","e"]'
+            output: ['"e"', '"c"']
+
+      - title: "Pipe: `|`"
+        body: |
+
+          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.
+
+          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.
+
+          Note that `.a.b.c` is the same as `.a | .b | .c`.
+
+          Note too that `.` is the input value at the particular stage
+          in a "pipeline", specifically: where the `.` expression appears.
+          Thus `.a | . | .b` is the same as `.a.b`, as the `.` in the
+          middle refers to whatever value `.a` produced.
+
+        examples:
+          - program: '.[] | .name'
+            input: '[{"name":"JSON", "good":true}, {"name":"XML", "good":false}]'
+            output: ['"JSON"', '"XML"']
+
+      - title: "Parenthesis"
+        body: |
+
+          Parenthesis work as a grouping operator just as in any typical
+          programming language.
+
+        examples:
+          - program: '(. + 2) * 5'
+            input: '1'
+            output: [15]
+
+  - title: Types and Values
+    body: |
+
+      jq supports the same set of datatypes as JSON - numbers,
+      strings, booleans, arrays, objects (which in JSON-speak are
+      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
+      values take an input and produce an output - `42` is a valid jq
+      expression that takes an input, ignores it, and returns 42
+      instead.
+
+    entries:
+      - title: "Array construction: `[]`"
+        body: |
+
+          As in JSON, `[]` is used to construct arrays, as in
+          `[1,2,3]`. The elements of the arrays can be any jq
+          expression, including a pipeline. All of the results produced
+          by all of the expressions are collected into one big array.
+          You can use it to construct an array out of a known quantity
+          of values (as in `[.foo, .bar, .baz]`) or to "collect" all the
+          results of a filter into an array (as in `[.items[].name]`)
+
+          Once you understand the "," operator, you can look at jq's array
+          syntax in a different light: the expression `[1,2,3]` is not using a
+          built-in syntax for comma-separated arrays, but is instead applying
+          the `[]` operator (collect results) to the expression 1,2,3 (which
+          produces three different results).
+
+          If you have a filter `X` that produces four results,
+          then the expression `[X]` will produce a single result, an
+          array of four elements.
+
+        examples:
+          - program: "[.user, .projects[]]"
+            input: '{"user":"stedolan", "projects": ["jq", "wikiflow"]}'
+            output: ['["stedolan", "jq", "wikiflow"]']
+          - program: "[ .[] | . * 2]"
+            input: '[1, 2, 3]'
+            output: ['[2, 4, 6]']
+
+      - title: "Object Construction: `{}`"
+        body: |
+
+          Like JSON, `{}` is for constructing objects (aka
+          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}`.
+
+          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).
+
+              {foo: .bar}
+
+          will produce the JSON object `{"foo": 42}` if given the JSON
+          object `{"bar":42, "baz":43}` as its input. You can use this
+          to select particular fields of an object: if the input is an
+          object with "user", "title", "id", and "content" fields and
+          you just want "user" and "title", you can write
+
+              {user: .user, title: .title}
+
+          Because that is so common, there's a shortcut syntax for it:
+          `{user, title}`.
+
+          If one of the expressions produces multiple results,
+          multiple dictionaries will be produced. If the input's
+
+              {"user":"stedolan","titles":["JQ Primer", "More JQ"]}
+
+          then the expression
+
+              {user, title: .titles[]}
+
+          will produce two outputs:
+
+              {"user":"stedolan", "title": "JQ Primer"}
+              {"user":"stedolan", "title": "More JQ"}
+
+          Putting parentheses around the key means it will be evaluated as an
+          expression. With the same input as above,
+
+              {(.user): .titles}
+
+          produces
+
+              {"stedolan": ["JQ Primer", "More JQ"]}
+
+        examples:
+          - program: '{user, title: .titles[]}'
+            input: '{"user":"stedolan","titles":["JQ Primer", "More JQ"]}'
+            output:
+              - '{"user":"stedolan", "title": "JQ Primer"}'
+              - '{"user":"stedolan", "title": "More JQ"}'
+          - program: '{(.user): .titles}'
+            input: '{"user":"stedolan","titles":["JQ Primer", "More JQ"]}'
+            output: ['{"stedolan": ["JQ Primer", "More JQ"]}']
+
+      - title: "Recursive Descent: `..`"
+        body: |
+
+          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" in any object found "below" `.`.
+
+          This is particularly useful in conjunction with `path(EXP)`
+          (also see below) and the `?` operator.
+
+        examples:
+          - program: '..|.a?'
+            input: '[[{"a":1}]]'
+            output: ['1']
+
+  - title: Builtin operators and functions
+    body: |
+
+      Some jq operator (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.
+
+    entries:
+      - title: "Addition: `+`"
+        body: |
+
+          The operator `+` takes two filters, applies them both
+          to the same input, and adds the results together. What
+          "adding" means depends on the types involved:
+
+          - **Numbers** are added by normal arithmetic.
+
+          - **Arrays** are added by being concatenated into a larger array.
+
+          - **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.)
+
+          `null` can be added to any value, and returns the other
+          value unchanged.
+
+        examples:
+          - program: '.a + 1'
+            input: '{"a": 7}'
+            output: ['8']
+          - program: '.a + .b'
+            input: '{"a": [1,2], "b": [3,4]}'
+            output: ['[1,2,3,4]']
+          - program: '.a + null'
+            input: '{"a": 1}'
+            output: ['1']
+          - program: '.a + 1'
+            input: '{}'
+            output: ['1']
+          - program: '{a: 1} + {b: 2} + {c: 3} + {a: 42}'
+            input: 'null'
+            output: ['{"a": 42, "b": 2, "c": 3}']
+
+      - title: "Subtraction: `-`"
+        body: |
+
+          As well as normal arithmetic subtraction on numbers, the `-`
+          operator can be used on arrays to remove all occurrences of
+          the second array's elements from the first array.
+
+        examples:
+          - program: '4 - .a'
+            input: '{"a":3}'
+            output: ['1']
+          - program: . - ["xml", "yaml"]
+            input: '["xml", "yaml", "json"]'
+            output: ['["json"]']
+
+      - title: "Multiplication, division, modulo: `*`, `/`, and `%`"
+        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**.
+
+          Dividing a string by another splits the first using the second
+          as separators.
+
+          Multiplying two objects will merge them recursively: this works
+          like addition but if both objects contain a value for the
+          same key, and the values are objects, the two are merged with
+          the same strategy.
+
+        examples:
+          - program: '10 / . * 3'
+            input: 5
+            output: [6]
+          - program: '. / ", "'
+            input: '"a, b,c,d, e"'
+            output: ['["a","b,c,d","e"]']
+          - program: '{"k": {"a": 1, "b": 2}} * {"k": {"a": 0,"c": 3}}'
+            input: 'null'
+            output: ['{"k": {"a": 0, "b": 2, "c": 3}}']
+          - program: '.[] | (1 / .)?'
+            input: '[1,0,-1]'
+            output: ['1', '-1']
+
+
+      - title: "`length`"
+        body: |
+
+          The builtin function `length` gets the length of various
+          different types of value:
+
+          - The length of a **string** is the number of Unicode
+            codepoints it contains (which will be the same as its
+            JSON-encoded length in bytes if it's pure ASCII).
+
+          - 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.
+
+        examples:
+          - program: '.[] | length'
+            input: '[[1,2], "string", {"a":2}, null]'
+            output: [2, 6, 1, 0]
+
+
+      - title: "`utf8bytelength`"
+        body: |
+
+          The builtin function `utf8bytelength` outputs the number of
+          bytes used to encode a string in UTF-8.
+
+        examples:
+          - program: 'utf8bytelength'
+            input: '"\u03bc"'
+            output: [2]
+
+      - title: "`keys`, `keys_unsorted`"
+        body: |
+
+          The builtin function `keys`, when given an object, returns
+          its keys in an array.
+
+          The keys are sorted "alphabetically", by unicode codepoint
+          order. This is not an order that makes particular sense in
+          any particular language, but you can count on it being the
+          same for any two objects with the same set of keys,
+          regardless of locale settings.
+
+          When `keys` is given an array, it returns the valid indices
+          for that array: the integers from 0 to length-1.
+
+          The `keys_unsorted` function is just like `keys`, but if
+          the input is an object then the keys will not be sorted,
+          instead the keys will roughly be in insertion order.
+
+        examples:
+          - program: 'keys'
+            input: '{"abc": 1, "abcd": 2, "Foo": 3}'
+            output: ['["Foo", "abc", "abcd"]']
+          - program: 'keys'
+            input: '[42,3,35]'
+            output: ['[0,1,2]']
+
+      - title: "`has(key)`"
+        body: |
+
+          The builtin function `has` returns whether the input object
+          has the given key, or the input array has an element at the
+          given index.
+
+          `has($key)` has the same effect as checking whether `$key`
+          is a member of the array returned by `keys`, although `has`
+          will be faster.
+
+        examples:
+          - program: 'map(has("foo"))'
+            input: '[{"foo": 42}, {}]'
+            output: ['[true, false]']
+          - program: 'map(has(2))'
+            input: '[[0,1], ["a","b","c"]]'
+            output: ['[false, true]']
+
+      - title: "`in`"
+        body: |
+
+          The builtin function `in` returns whether or not the input key is in the
+          given object, or the input index corresponds to an element
+          in the given array. It is, essentially, an inversed version
+          of `has`.
+
+        examples:
+          - program: '.[] | in({"foo": 42})'
+            input: '["foo", "bar"]'
+            output: ['true', 'false']
+          - program: 'map(in([0,1]))'
+            input: '[2, 0]'
+            output: ['[false, true]']
+
+      - title: "`map(x)`, `map_values(x)`"
+        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.
+
+          Similarly, `map_values(x)` 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`.
+
+        examples:
+          - program: 'map(.+1)'
+            input: '[1,2,3]'
+            output: ['[2,3,4]']
+
+          - program: 'map_values(.+1)'
+            input: '{"a": 1, "b": 2, "c": 3}'
+            output: ['{"a": 2, "b": 3, "c": 4}']
+
+      - title: "`path(path_expression)`"
+        body: |
+
+          Outputs array representations of the given path expression
+          in `.`.  The outputs are arrays of strings (object keys)
+          and/or numbers (array indices).
+
+          Path expressions are jq expressions like `.a`, but also `.[]`.
+          There are two types of path expressions: ones that can match
+          exactly, and ones that cannot.  For example, `.a.b.c` is an
+          ex