Fix manual section titles, minor typos, and improve inline codes (#2626)

Author: itchyny

docs/content/manual/manual.yml

@@ -97,9 +97,9 @@ sections:
       program and backslash-escaped double-quotes (`\"`) inside the jq
       program.
 
-      Unix shells: `jq '.["foo"]'`
-      Powershell: `jq '.[\"foo\"]'`
-      Windows command shell: `jq ".[\"foo\"]"`
+      * 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:
@@ -284,7 +284,7 @@ sections:
 
         Remaining arguments are positional JSON text arguments.  These
         are available to the jq program as `$ARGS.positional[]`.
-        
+
       * `--`:
 
         Terminates argument processing.  Remaining arguments are
@@ -318,19 +318,19 @@ sections:
           program can be a useful way of formatting JSON output from,
           say, `curl`.
 
-          An important point about the identity filter is that it 
-          guarantees to preserve the literal decimal representation 
-          of values. This is particularly important when dealing with numbers 
-          which can't be losslessly converted to an IEEE754 double precision 
+          An important point about the identity filter is that it
+          guarantees to preserve the literal decimal representation
+          of values. This is particularly important when dealing with numbers
+          which can't be losslessly converted to an IEEE754 double precision
           representation.
 
           jq doesn't truncate the literal numbers to double unless there
           is a need to make arithmetic operations with the number.
-          Comparisons are carried out over the untruncated big decimal 
+          Comparisons are carried out over the untruncated big decimal
           representation of the number.
 
           jq will also try to maintain the original decimal precision of the provided
-          number literal. See below for examples. 
+          number literal. See below for examples.
 
         examples:
           - program: '.'
@@ -400,17 +400,17 @@ sections:
             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.
 
@@ -430,16 +430,16 @@ 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).
 
         examples:
           - program: '.[2:4]'
@@ -564,15 +564,15 @@ sections:
       expression that takes an input, ignores it, and returns 42
       instead.
 
-      Numbers in jq are internally represented by their IEEE754 double 
-      precision approximation. Any arithmetic operation with numbers, 
-      whether they are literals or results of previous filters, will 
+      Numbers in jq are internally represented by their IEEE754 double
+      precision approximation. Any arithmetic operation with numbers,
+      whether they are literals or results of previous filters, will
       produce a double precision floating point result.
 
       However, when parsing a literal jq will store the original literal
       string. If no mutation is applied to this value then it will make
-      to the output in its original form, even if conversion to double 
-      would result in a loss. 
+      to the output in its original form, even if conversion to double
+      would result in a loss.
 
     entries:
       - title: "Array construction: `[]`"
@@ -699,21 +699,21 @@ sections:
   - title: Builtin operators and functions
     body: |
 
-      Some jq operator (for instance, `+`) do different things
+      Some jq operators (for instance, `+`) do different things
       depending on the type of their arguments (arrays, numbers,
       etc.). However, jq never does implicit type conversions. If you
       try to add a string to an object you'll get an error message and
       no result.
 
-      Please note that all numbers are converted to IEEE754 double precision 
+      Please note that all numbers are converted to IEEE754 double precision
       floating point representation. Arithmetic and logical operators are working
-      with these converted doubles. Results of all such operations are also limited 
-      to the double precision. 
+      with these converted doubles. Results of all such operations are also limited
+      to the double precision.
 
-      The only exception to this behaviour of number is a snapshot of original number 
+      The only exception to this behaviour of number is a snapshot of original number
       literal. When a number which originally was provided as a literal is never
-      mutated until the end of the program then it is printed to the output in its 
-      original literal form. This also includes cases when the original literal 
+      mutated until the end of the program then it is printed to the output in its
+      original literal form. This also includes cases when the original literal
       would be truncated when converted to the IEEE754 double precision floating point
       number.
 
@@ -772,7 +772,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.
@@ -903,18 +903,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)'
@@ -1013,19 +1013,19 @@ 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
           key-value pairs. If `to_entries` is passed an object, then
           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'
@@ -1042,8 +1042,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))`
@@ -1244,12 +1244,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
@@ -1262,22 +1262,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]']
 
@@ -1383,8 +1383,8 @@ sections:
           `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(f)` compares two elements by comparing the result of
+          `f` on each element.
 
         examples:
           - program: 'sort'
@@ -1866,7 +1866,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
@@ -1976,10 +1976,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'\""]
@@ -2134,7 +2130,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`
@@ -2159,17 +2155,18 @@ sections:
           More cases can be added to an if using `elif A then B` syntax.
 
         examples:
-          - program: 'if . == 0 then
+          - program: |-
+              if . == 0 then
                 "zero"
               elif . == 1 then
                 "one"
               else
                 "many"
-              end'
+              end
             input: 2
             output: ['"many"']
 
-      - title: "`>, >=, <=, <`"
+      - title: "`>`, `>=`, `<=`, `<`"
         body: |
 
           The comparison operators `>`, `>=`, `<=`, `<` return whether
@@ -2184,12 +2181,13 @@ sections:
             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.
@@ -2199,12 +2197,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"'
@@ -2213,9 +2211,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']
@@ -2568,15 +2563,15 @@ 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"}}
 
           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
@@ -2590,7 +2585,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