Reorder the command line options in the manual (#2766)

docs/content/manual/manual.yml

@@ -104,60 +104,24 @@ sections:
       You can affect how jq reads and writes its input and output
       using some command-line options:
 
-      * `--version`/`-V`:
+      * `--null-input` / `-n`:
 
-        Output the jq version and exit with zero.
+        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.
 
-      * `--seq`:
+      * `--raw-input` / `-R`:
-
-        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, 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"]`.
-
-        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.
-
-      * `--stream-errors`:
-
-        Like `--stream`, but invalid JSON inputs yield array values
-        where the first element is the error and the second is a path.
-        For example, `["a",n]` produces ["Invalid literal at line 1,
-        column 9",[1]]`.
-
-        Implies `--stream`.  Invalid JSON inputs produce no error values
-        when `--stream` without `--stream-errors`.
-
-      * `--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`:
+      * `--slurp` / `-s`:
 
-        Don't read any input at all! Instead, the filter is run once
+        Instead of running the filter for each JSON object in the
-        using `null` as the input. This is useful when using jq as a
+        input, read the entire input stream into a large array and run
-        simple calculator or to construct JSON data from scratch.
+        the filter just once.
 
       * `--compact-output` / `-c`:
 
@@ -165,49 +129,6 @@ sections:
         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 7) 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`.
-        When the `NO_COLOR` environment variable is not empty, jq disables
-        colored output by default, but you can enable it by `-C`.
-
-        Colors can be configured with the `JQ_COLORS` environment
-        variable (see below).
-
-      * `--binary` / `-b`:
-
-        Windows users using WSL, MSYS2, or Cygwin, should use this option
-        when using a native jq.exe, otherwise jq will turn newlines (LFs)
-        into carriage-return-then-newline (CRLF).
-
-      * `--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
@@ -224,29 +145,86 @@ sections:
         Like `-r` but jq will print NUL instead of newline after each output.
         This can be useful when the values being output can contain newlines.
 
+      * `--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.
+
+      * `--sort-keys` / `-S`:
+
+        Output the fields of each object with the keys in sorted order.
+
+      * `--color-output` / `-C` and `--monochrome-output` / `-M`:
+
+        By default, jq outputs colored JSON if writing to a
+        terminal. You can force it to produce color even if writing to
+        a pipe or a file using `-C`, and disable color with `-M`.
+        When the `NO_COLOR` environment variable is not empty, jq disables
+        colored output by default, but you can enable it by `-C`.
+
+        Colors can be configured with the `JQ_COLORS` environment
+        variable (see below).
+
+      * `--tab`:
+
+        Use a tab for each indentation level instead of two spaces.
+
+      * `--indent n`:
+
+        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).
+
+      * `--stream`:
+
+        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"]`.
+
+        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.
+
+      * `--stream-errors`:
+
+        Like `--stream`, but invalid JSON inputs yield array values
+        where the first element is the error and the second is a path.
+        For example, `["a",n]` produces `["Invalid literal at line 1,
+        column 7",[1]]`.
+
+        Implies `--stream`.  Invalid JSON inputs produce no error values
+        when `--stream` without `--stream-errors`.
+
+      * `--seq`:
+
+        Use the `application/json-seq` MIME type scheme for separating
+        JSON texts in jq's input and output.  This means that an ASCII
+        RS (record separator) character is printed before each value on
+        output and an ASCII LF (line feed) is printed after every
+        output.  Input JSON texts that fail to parse are ignored (but
+        warned about), discarding all subsequent input until the next
+        RS.  This mode also parses the output of jq without the `--seq`
+        option.
+
       * `-f filename` / `--from-file filename`:
 
         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 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.
-
       * `--arg name value`:
 
         This option passes a value to the jq program as a predefined
@@ -297,6 +275,32 @@ sections:
         Remaining arguments are positional JSON text arguments.  These
         are available to the jq program as `$ARGS.positional[]`.
 
+      * `--exit-status` / `-e`:
+
+        Sets the exit status of jq to 0 if the last output value was
+        neither `false` nor `null`, 1 if the last output value was
+        either `false` or `null`, or 4 if no valid result was ever
+        produced.  Normally jq exits with 2 if there was any usage
+        problem or system error, 3 if there was a jq program compile
+        error, or 0 if the jq program ran.
+
+        Another way to set the exit status is with the `halt_error`
+        builtin function.
+
+      * `--binary` / `-b`:
+
+        Windows users using WSL, MSYS2, or Cygwin, should use this option
+        when using a native jq.exe, otherwise jq will turn newlines (LFs)
+        into carriage-return-then-newline (CRLF).
+
+      * `--version` / `-V`:
+
+        Output the jq version and exit with zero.
+
+      * `--help` / `-h`:
+
+        Output the jq help and exit with zero.
+
       * `--`:
 
         Terminates argument processing.  Remaining arguments are
@@ -311,7 +315,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.
 

docs/content/manual/v1.3/manual.yml

@@ -82,24 +82,24 @@ sections:
       You can affect how jq reads and writes its input and output
       using some command-line options:
 
-      * `--slurp`/`-s`:
+      * `--null-input` / `-n`:
 
-        Instead of running the filter for each JSON object in the
+        Don't read any input at all. Instead, the filter is run once
-        input, read the entire input stream into a large array and run
+        using `null` as the input. This is useful when using jq as a
-        the filter just once.
+        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
+        Instead of running the filter for each JSON object in the
-        using `null` as the input. This is useful when using jq as a
+        input, read the entire input stream into a large array and run
-        simple calculator or to construct JSON data from scratch.
+        the filter just once.
 
       * `--compact-output` / `-c`:
 
@@ -107,11 +107,12 @@ sections:
         will result in more compact output by instead putting each
         JSON object on a single line.
 
-      * `--color-output` / `-C` and `--monochrome-output` / `-M`:
+      * `--raw-output` / `-r`:
 
-        By default, jq outputs colored JSON if writing to a
+        With this option, if the filter's result is a string then it
-        terminal. You can force it to produce color even if writing to
+        will be written directly to standard output rather than being
-        a pipe or a file using `-C`, and disable color with `-M`.
+        formatted as a JSON string with quotes. This can be useful for
+        making jq filters talk to non-JSON-based systems.
 
       * `--ascii-output` / `-a`:
 
@@ -121,12 +122,11 @@ sections:
         ASCII output with every non-ASCII character replaced with the
         equivalent escape sequence.
 
-      * `--raw-output` / `-r`:
+      * `--color-output` / `-C` and `--monochrome-output` / `-M`:
 
-        With this option, if the filter's result is a string then it
+        By default, jq outputs colored JSON if writing to a
-        will be written directly to standard output rather than being
+        terminal. You can force it to produce color even if writing to
-        formatted as a JSON string with quotes. This can be useful for
+        a pipe or a file using `-C`, and disable color with `-M`.
-        making jq filters talk to non-JSON-based systems.
 
       * `--arg name value`:
 

docs/content/manual/v1.4/manual.yml

@@ -93,34 +93,30 @@ sections:
       You can affect how jq reads and writes its input and output
       using some command-line options:
 
-      * `--version`/`-V`:
+      * `--null-input` / `-n`:
 
-        Output the jq version and exit with zero.
+        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.
 
-      * `--slurp`/`-s`:
+      * `--raw-input` / `-R`:
-
-        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.
-
-      * `--online-input`/`-I`:
-
-        When the top-level input value is an array produce its elements
-        instead of the array.  This allows on-line processing of
-        potentially very large top-level arrays' elements.
-
-      * `--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
+        Instead of running the filter for each JSON object in the
-        using `null` as the input. This is useful when using jq as a
+        input, read the entire input stream into a large array and run
-        simple calculator or to construct JSON data from scratch.
+        the filter just once.
+
+      * `--online-input` / `-I`:
+
+        When the top-level input value is an array produce its elements
+        instead of the array.  This allows on-line processing of
+        potentially very large top-level arrays' elements.
 
       * `--compact-output` / `-c`:
 
@@ -128,11 +124,12 @@ sections:
         will result in more compact output by instead putting each
         JSON object on a single line.
 
-      * `--color-output` / `-C` and `--monochrome-output` / `-M`:
+      * `--raw-output` / `-r`:
 
-        By default, jq outputs colored JSON if writing to a
+        With this option, if the filter's result is a string then it
-        terminal. You can force it to produce color even if writing to
+        will be written directly to standard output rather than being
-        a pipe or a file using `-C`, and disable color with `-M`.
+        formatted as a JSON string with quotes. This can be useful for
+        making jq filters talk to non-JSON-based systems.
 
       * `--ascii-output` / `-a`:
 
@@ -142,37 +139,27 @@ sections:
         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`:
+
+        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`.
+
       * `--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.
-
       * `-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.
 
-      * `-e` / `--exit-status`:
-
-        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.
-
       * `--arg name value`:
 
         This option passes a value to the jq program as a predefined
@@ -187,6 +174,23 @@ sections:
         program and has the value resulting from parsing the content of
         the file named `bar`.
 
+      * `--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.
+
+      * `--version` / `-V`:
+
+        Output the jq version and exit with zero.
+
+      * `--help` / `-h`:
+
+        Output the jq help and exit with zero.
+
   - title: Basic filters
     entries:
       - title: "`.`"

docs/content/manual/v1.5/manual.yml

@@ -95,50 +95,24 @@ sections:
       You can affect how jq reads and writes its input and output
       using some command-line options:
 
-      * `--version`/`-V`:
+      * `--null-input` / `-n`:
 
-        Output the jq version and exit with zero.
+        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.
 
-      * `--seq`:
+      * `--raw-input` / `-R`:
-
-        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, 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"]`.
-
-        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`:
+      * `--slurp` / `-s`:
 
-        Don't read any input at all! Instead, the filter is run once
+        Instead of running the filter for each JSON object in the
-        using `null` as the input. This is useful when using jq as a
+        input, read the entire input stream into a large array and run
-        simple calculator or to construct JSON data from scratch.
+        the filter just once.
 
       * `--compact-output` / `-c`:
 
@@ -146,38 +120,6 @@ sections:
         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 7) 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`.
-
-      * `--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
@@ -189,26 +131,71 @@ sections:
 
         Like `-r` but jq won't print a newline after each output.
 
+      * `--ascii-output` / `-a`:
+
+        jq usually outputs non-ASCII Unicode codepoints as UTF-8, even
+        if the input specified them as escape sequences (like
+        "\u03bc"). Using this option, you can force jq to produce pure
+        ASCII output with every non-ASCII character replaced with the
+        equivalent escape sequence.
+
+      * `--sort-keys` / `-S`:
+
+        Output the fields of each object with the keys in sorted order.
+
+      * `--color-output` / `-C` and `--monochrome-output` / `-M`:
+
+        By default, jq outputs colored JSON if writing to a
+        terminal. You can force it to produce color even if writing to
+        a pipe or a file using `-C`, and disable color with `-M`.
+
+      * `--tab`:
+
+        Use a tab for each indentation level instead of two spaces.
+
+      * `--indent n`:
+
+        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).
+
+      * `--stream`:
+
+        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"]`.
+
+        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.
+
+      * `--seq`:
+
+        Use the `application/json-seq` MIME type scheme for separating
+        JSON texts in jq's input and output.  This means that an ASCII
+        RS (record separator) character is printed before each value on
+        output and an ASCII LF (line feed) is printed after every
+        output.  Input JSON texts that fail to parse are ignored (but
+        warned about), discarding all subsequent input until the next
+        RS.  This mode also parses the output of jq without the `--seq`
+        option.
+
       * `-f filename` / `--from-file filename`:
 
         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 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.
-
       * `--arg name value`:
 
         This option passes a value to the jq program as a predefined
@@ -227,7 +214,7 @@ sections:
 
         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 `--argfile foo bar`, then `$foo` is available
+        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`.
 
@@ -239,6 +226,23 @@ sections:
         one text, then that is used, else an array of texts is used as
         in `--slurpfile`.)
 
+      * `--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.
+
+      * `--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
@@ -247,7 +251,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.
 

docs/content/manual/v1.6/manual.yml

@@ -103,50 +103,24 @@ sections:
       You can affect how jq reads and writes its input and output
       using some command-line options:
 
-      * `--version`/`-V`:
+      * `--null-input` / `-n`:
 
-        Output the jq version and exit with zero.
+        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.
 
-      * `--seq`:
+      * `--raw-input` / `-R`:
-
-        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, 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"]`.
-
-        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`:
+      * `--slurp` / `-s`:
 
-        Don't read any input at all! Instead, the filter is run once
+        Instead of running the filter for each JSON object in the
-        using `null` as the input. This is useful when using jq as a
+        input, read the entire input stream into a large array and run
-        simple calculator or to construct JSON data from scratch.
+        the filter just once.
 
       * `--compact-output` / `-c`:
 
@@ -154,41 +128,6 @@ sections:
         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 7) 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
@@ -200,29 +139,74 @@ sections:
 
         Like `-r` but jq won't print a newline after each output.
 
+      * `--ascii-output` / `-a`:
+
+        jq usually outputs non-ASCII Unicode codepoints as UTF-8, even
+        if the input specified them as escape sequences (like
+        "\u03bc"). Using this option, you can force jq to produce pure
+        ASCII output with every non-ASCII character replaced with the
+        equivalent escape sequence.
+
+      * `--sort-keys` / `-S`:
+
+        Output the fields of each object with the keys in sorted order.
+
+      * `--color-output` / `-C` and `--monochrome-output` / `-M`:
+
+        By default, jq outputs colored JSON if writing to a
+        terminal. You can force it to produce color even if writing to
+        a pipe or a file using `-C`, and disable color with `-M`.
+
+        Colors can be configured with the `JQ_COLORS` environment
+        variable (see below).
+
+      * `--tab`:
+
+        Use a tab for each indentation level instead of two spaces.
+
+      * `--indent n`:
+
+        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).
+
+      * `--stream`:
+
+        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"]`.
+
+        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.
+
+      * `--seq`:
+
+        Use the `application/json-seq` MIME type scheme for separating
+        JSON texts in jq's input and output.  This means that an ASCII
+        RS (record separator) character is printed before each value on
+        output and an ASCII LF (line feed) is printed after every
+        output.  Input JSON texts that fail to parse are ignored (but
+        warned about), discarding all subsequent input until the next
+        RS.  This mode also parses the output of jq without the `--seq`
+        option.
+
       * `-f filename` / `--from-file filename`:
 
         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 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.
-
       * `--arg name value`:
 
         This option passes a value to the jq program as a predefined
@@ -273,6 +257,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
@@ -281,7 +285,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.
 

jq.1.prebuilt

@@ -52,52 +52,22 @@ Windows command shell: \fBjq "\.[\e"foo\e"]"\fR
 You can affect how jq reads and writes its input and output using some command\-line options:
 .
 .TP
-\fB\-\-version\fR/\fB\-V\fR:
+\fB\-\-null\-input\fR / \fB\-n\fR:
 .
 .IP
-Output the jq version and exit with zero\.
+Don\'t read any input at all\. Instead, the filter is run once using \fBnull\fR as the input\. This is useful when using jq as a simple calculator or to construct JSON data from scratch\.
 .
 .TP
-\fB\-\-seq\fR:
+\fB\-\-raw\-input\fR / \fB\-R\fR:
-.
-.IP
-Use the \fBapplication/json\-seq\fR 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 \fB\-\-seq\fR option\.
-.
-.TP
-\fB\-\-stream\fR:
-.
-.IP
-Parse the input in streaming fashion, outputting arrays of path and leaf values (scalars and empty arrays or empty objects)\. For example, \fB"a"\fR becomes \fB[[],"a"]\fR, and \fB[[],"a",["b"]]\fR becomes \fB[[0],[]]\fR, \fB[[1],"a"]\fR, and \fB[[2,0],"b"]\fR\.
-.
-.IP
-This is useful for processing very large inputs\. Use this in conjunction with filtering and the \fBreduce\fR and \fBforeach\fR syntax to reduce large inputs incrementally\.
-.
-.TP
-\fB\-\-stream\-errors\fR:
-.
-.IP
-Like \fB\-\-stream\fR, but invalid JSON inputs yield array values where the first element is the error and the second is a path\. For example, \fB["a",n]\fR produces ["Invalid literal at line 1, column 9",[1]]`\.
-.
-.IP
-Implies \fB\-\-stream\fR\. Invalid JSON inputs produce no error values when \fB\-\-stream\fR without \fB\-\-stream\-errors\fR\.
-.
-.TP
-\fB\-\-slurp\fR/\fB\-s\fR:
-.
-.IP
-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\.
-.
-.TP
-\fB\-\-raw\-input\fR/\fB\-R\fR:
 .
 .IP
 Don\'t parse the input as JSON\. Instead, each line of text is passed to the filter as a string\. If combined with \fB\-\-slurp\fR, then the entire input is passed to the filter as a single long string\.
 .
 .TP
-\fB\-\-null\-input\fR/\fB\-n\fR:
+\fB\-\-slurp\fR / \fB\-s\fR:
 .
 .IP
-Don\'t read any input at all! Instead, the filter is run once using \fBnull\fR 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\.
 .
 .TP
 \fB\-\-compact\-output\fR / \fB\-c\fR:
@@ -106,51 +76,6 @@ Don\'t read any input at all! Instead, the filter is run once using \fBnull\fR a
 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\.
 .
 .TP
-\fB\-\-tab\fR:
-.
-.IP
-Use a tab for each indentation level instead of two spaces\.
-.
-.TP
-\fB\-\-indent n\fR:
-.
-.IP
-Use the given number of spaces (no more than 7) for indentation\.
-.
-.TP
-\fB\-\-color\-output\fR / \fB\-C\fR and \fB\-\-monochrome\-output\fR / \fB\-M\fR:
-.
-.IP
-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 \fB\-C\fR, and disable color with \fB\-M\fR\. When the \fBNO_COLOR\fR environment variable is not empty, jq disables colored output by default, but you can enable it by \fB\-C\fR\.
-.
-.IP
-Colors can be configured with the \fBJQ_COLORS\fR environment variable (see below)\.
-.
-.TP
-\fB\-\-binary\fR / \fB\-b\fR:
-.
-.IP
-Windows users using WSL, MSYS2, or Cygwin, should use this option when using a native jq\.exe, otherwise jq will turn newlines (LFs) into carriage\-return\-then\-newline (CRLF)\.
-.
-.TP
-\fB\-\-ascii\-output\fR / \fB\-a\fR:
-.
-.IP
-jq usually outputs non\-ASCII Unicode codepoints as UTF\-8, even if the input specified them as escape sequences (like "\eu03bc")\. Using this option, you can force jq to produce pure ASCII output with every non\-ASCII character replaced with the equivalent escape sequence\.
-.
-.TP
-\fB\-\-unbuffered\fR:
-.
-.IP
-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)\.
-.
-.TP
-\fB\-\-sort\-keys\fR / \fB\-S\fR:
-.
-.IP
-Output the fields of each object with the keys in sorted order\.
-.
-.TP
 \fB\-\-raw\-output\fR / \fB\-r\fR:
 .
 .IP
@@ -169,27 +94,81 @@ Like \fB\-r\fR but jq won\'t print a newline after each output\.
 Like \fB\-r\fR but jq will print NUL instead of newline after each output\. This can be useful when the values being output can contain newlines\.
 .
 .TP
+\fB\-\-ascii\-output\fR / \fB\-a\fR:
+.
+.IP
+jq usually outputs non\-ASCII Unicode codepoints as UTF\-8, even if the input specified them as escape sequences (like "\eu03bc")\. Using this option, you can force jq to produce pure ASCII output with every non\-ASCII character replaced with the equivalent escape sequence\.
+.
+.TP
+\fB\-\-sort\-keys\fR / \fB\-S\fR:
+.
+.IP
+Output the fields of each object with the keys in sorted order\.
+.
+.TP
+\fB\-\-color\-output\fR / \fB\-C\fR and \fB\-\-monochrome\-output\fR / \fB\-M\fR:
+.
+.IP
+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 \fB\-C\fR, and disable color with \fB\-M\fR\. When the \fBNO_COLOR\fR environment variable is not empty, jq disables colored output by default, but you can enable it by \fB\-C\fR\.
+.
+.IP
+Colors can be configured with the \fBJQ_COLORS\fR environment variable (see below)\.
+.
+.TP
+\fB\-\-tab\fR:
+.
+.IP
+Use a tab for each indentation level instead of two spaces\.
+.
+.TP
+\fB\-\-indent n\fR:
+.
+.IP
+Use the given number of spaces (no more than 7) for indentation\.
+.
+.TP
+\fB\-\-unbuffered\fR:
+.
+.IP
+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)\.
+.
+.TP
+\fB\-\-stream\fR:
+.
+.IP
+Parse the input in streaming fashion, outputting arrays of path and leaf values (scalars and empty arrays or empty objects)\. For example, \fB"a"\fR becomes \fB[[],"a"]\fR, and \fB[[],"a",["b"]]\fR becomes \fB[[0],[]]\fR, \fB[[1],"a"]\fR, and \fB[[2,0],"b"]\fR\.
+.
+.IP
+This is useful for processing very large inputs\. Use this in conjunction with filtering and the \fBreduce\fR and \fBforeach\fR syntax to reduce large inputs incrementally\.
+.
+.TP
+\fB\-\-stream\-errors\fR:
+.
+.IP
+Like \fB\-\-stream\fR, but invalid JSON inputs yield array values where the first element is the error and the second is a path\. For example, \fB["a",n]\fR produces \fB["Invalid literal at line 1, column 7",[1]]\fR\.
+.
+.IP
+Implies \fB\-\-stream\fR\. Invalid JSON inputs produce no error values when \fB\-\-stream\fR without \fB\-\-stream\-errors\fR\.
+.
+.TP
+\fB\-\-seq\fR:
+.
+.IP
+Use the \fBapplication/json\-seq\fR 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 \fB\-\-seq\fR option\.
+.
+.TP
 \fB\-f filename\fR / \fB\-\-from\-file filename\fR:
 .
 .IP
 Read filter from the file rather than from a command line, like awk\'s \-f option\. You can also use \'#\' to make comments\.
 .
 .TP
-\fB\-Ldirectory\fR / \fB\-L directory\fR:
+\fB\-L directory\fR:
 .
 .IP
 Prepend \fBdirectory\fR to the search list for modules\. If this option is used then no builtin search list is used\. See the section on modules below\.
 .
 .TP
-\fB\-e\fR / \fB\-\-exit\-status\fR:
-.
-.IP
-Sets the exit status of jq to 0 if the last output value was neither \fBfalse\fR nor \fBnull\fR, 1 if the last output value was either \fBfalse\fR or \fBnull\fR, 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\.
-.
-.IP
-Another way to set the exit status is with the \fBhalt_error\fR builtin function\.
-.
-.TP
 \fB\-\-arg name value\fR:
 .
 .IP
@@ -238,6 +217,33 @@ Remaining arguments are positional string arguments\. These are available to the
 Remaining arguments are positional JSON text arguments\. These are available to the jq program as \fB$ARGS\.positional[]\fR\.
 .
 .TP
+\fB\-\-exit\-status\fR / \fB\-e\fR:
+.
+.IP
+Sets the exit status of jq to 0 if the last output value was neither \fBfalse\fR nor \fBnull\fR, 1 if the last output value was either \fBfalse\fR or \fBnull\fR, 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\.
+.
+.IP
+Another way to set the exit status is with the \fBhalt_error\fR builtin function\.
+.
+.TP
+\fB\-\-binary\fR / \fB\-b\fR:
+.
+.IP
+Windows users using WSL, MSYS2, or Cygwin, should use this option when using a native jq\.exe, otherwise jq will turn newlines (LFs) into carriage\-return\-then\-newline (CRLF)\.
+.
+.TP
+\fB\-\-version\fR / \fB\-V\fR:
+.
+.IP
+Output the jq version and exit with zero\.
+.
+.TP
+\fB\-\-help\fR / \fB\-h\fR:
+.
+.IP
+Output the jq help and exit with zero\.
+.
+.TP
 \fB\-\-\fR:
 .
 .IP
@@ -247,7 +253,7 @@ Terminates argument processing\. Remaining arguments are positional, either stri
 \fB\-\-run\-tests [filename]\fR:
 .
 .IP
-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\.
+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 \fB%%FAIL\fR, then a line containing the program to compile, then a line containing an error message to compare to the actual\.
 .
 .IP
 Be warned that this option can change backwards\-incompatibly\.

src/main.c

@@ -82,9 +82,9 @@ static void usage(int code, int keep_it_short) {
       "  -M, --monochrome-output   disable colored output;\n"
       "      --tab                 use tabs for indentation;\n"
       "      --indent n            use the given number of spaces (no more than 7) for indentation;\n"
+      "      --unbuffered          flush output stream after each output;\n"
       "      --stream              parse the input value in streaming fashion;\n"
       "      --stream-errors       implies --stream and report JSON parse error with an array;\n"
-      "      --unbuffered          flush output stream after each output;\n"
       "      --seq                 parse input and output in application/json-seq MIME type scheme;\n"
       "  -f, --from-file file      load filter from the file;\n"
       "  -L directory              search modules from the directory;\n"