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

5 files changed, 283 insertions, 311 deletions

diff --git a/docs/content/manual/manual.yml b/docs/content/manual/manual.yml
index 454c05ce..68cc091f 100644
--- a/docs/content/manual/manual.yml
+++ b/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,7 +1013,7 @@ sections:
             input: '{"a":{"b":1},"x":{"y":2}}'
             output: ['{"a":{},"x":{"y":2}}']
 
-      - title: "`to_entries`, `from_entries`, `with_entries`"
+      - title: "`to_entries`, `from_entries`, `with_entries(f)`"
         body: |
 
           These functions convert between an object and an array of
@@ -1021,11 +1021,11 @@ sections:
           for each `k: v` entry in the input, the output array
           includes `{"key": k, "value": v}`.
 
-          `from_entries` does the opposite conversion, and
-          `with_entries(foo)` is a shorthand for `to_entries |
-          map(foo) | from_entries`, useful for doing some operation to
-          all keys and values of an object. `from_entries` accepts key, Key,
-          name, Name, value and Value as keys.
+          `from_entries` does the opposite conversion, and `with_entries(f)`
+          is a shorthand for `to_entries | map(f) | from_entries`, useful for
+          doing some operation to all keys and values of an object.
+          `from_entries` accepts `"key"`, `"Key"`, `"name"`, `"Name"`,
+          `"value"`, and `"Value"` as keys.
 
         examples:
           - program: 'to_entries'
@@ -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,7 +2563,7 @@ sections:
           fields, and another object which is used to map author usernames to
           real names. Our input looks like:
 
-              {"posts": [{"title": "Frist psot", "author": "anon"},
+              {"posts": [{"title": "First post", "author": "anon"},
                          {"title": "A well-written article", "author": "person1"}],
                "realnames": {"anon": "Anonymous Coward",
                              "person1": "Person McPherson"}}
@@ -2576,7 +2571,7 @@ sections:
           We want to produce the posts with the author field containing a real
           name, as in:
 
-              {"title": "Frist psot", "author": "Anonymous Coward"}
+              {"title": "First post", "author": "Anonymous Coward"}
               {"title": "A well-written article", "author": "Person McPherson"}
 
           We use a variable, $names, to store the realnames object, so that we
@@ -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
diff --git a/docs/content/manual/v1.3/manual.yml b/docs/content/manual/v1.3/manual.yml
index 95c759d4..34ddcf72 100644
--- a/docs/content/manual/v1.3/manual.yml
+++ b/docs/content/manual/v1.3/manual.yml
@@ -171,7 +171,7 @@ sections:
         body: |
 
           You can also look up fields of an object using syntax like
-          `.["foo"]` (.foo above is a shorthand version of this). This
+          `.["foo"]` (`.foo` above is a shorthand version of this). This
           one works for arrays as well, if the key is an
           integer. Arrays are zero-based (like javascript), so `.[2]`
           returns the third element of the array.
@@ -285,7 +285,7 @@ sections:
       instead.
 
     entries:
-      - title: Array construction - `[]`
+      - title: "Array construction: `[]`"
         body: |
 
           As in JSON, `[]` is used to construct arrays, as in
@@ -310,7 +310,7 @@ sections:
           - program: "[.user, .projects[]]"
             input: '{"user":"stedolan", "projects": ["jq", "wikiflow"]}'
             output: ['["stedolan", "jq", "wikiflow"]']
-      - title: Objects - `{}`
+      - title: "Objects: `{}`"
         body: |
 
           Like JSON, `{}` is for constructing objects (aka
@@ -371,14 +371,14 @@ 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.
 
     entries:
-      - title: Addition - `+`
+      - title: "Addition: `+`"
         body: |
 
           The operator `+` takes two filters, applies them both
@@ -416,7 +416,7 @@ sections:
             input: 'null'
             output: ['{"a": 42, "b": 2, "c": 3}']
 
-      - title: Subtraction - `-`
+      - title: "Subtraction: `-`"
         body: |
 
           As well as normal arithmetic subtraction on numbers, the `-`
@@ -431,7 +431,7 @@ sections:
             input: '["xml", "yaml", "json"]'
             output: ['["json"]']
 
-      - title: Multiplication, division - `*` and `/`
+      - title: "Multiplication, division: `*` and `/`"
         body: |
 
           These operators only work on numbers, and do the expected.
@@ -504,7 +504,7 @@ sections:
             input: '[[0,1], ["a","b","c"]]'
             output: ['[false, true]']
 
-      - 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
@@ -513,9 +513,9 @@ sections:
           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.
+          `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.
 
         examples:
           - program: 'to_entries'
@@ -559,14 +559,14 @@ sections:
             input: 'null'
             output: ['[1,2,3]']
 
-      - title: '`map(x)`'
+      - title: '`map(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 produce the outputs a new
           array. `map(.+1)` will increment each element of an array of numbers.
 
-          `map(x)` is equivalent to `[.[] | x]`. In fact, this is how
+          `map(f)` is equivalent to `[.[] | f]`. In fact, this is how
           it's defined.
 
         examples:
@@ -648,7 +648,7 @@ sections:
             input: '[0, false, [], {}, null, "hello"]'
             output: ['["number", "boolean", "array", "object", "null", "string"]']
 
-      - title: '`sort, sort_by`'
+      - title: '`sort`, `sort_by`'
         body: |
 
           The `sort` functions sorts its input, which must be an
@@ -796,7 +796,7 @@ sections:
               - '{"foo":[]}'
 
 
-      - title: String interpolation - `\(foo)`
+      - title: "String interpolation: `\\(exp)`"
         body: |
 
           Inside a string, you can put an expression inside parens
@@ -872,10 +872,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'\""]
@@ -898,7 +894,8 @@ sections:
           - program: '.[] == 1'
             input: '[1, 1.0, "1", "banana"]'
             output: ['true', 'true', 'false', 'false']
-      - title: if-then-else
+
+      - title: if-then-else-end
         body: |
 
           `if A then B else C end` will act the same as `B` if `A`
@@ -931,7 +928,7 @@ sections:
             input: 2
             output: ['"many"']
 
-      - title: '`>, >=, <=, <`'
+      - title: "`>`, `>=`, `<=`, `<`"
         body: |
 
           The comparison operators `>`, `>=`, `<=`, `<` return whether
@@ -946,12 +943,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.
@@ -961,12 +959,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"'
@@ -975,9 +973,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']
@@ -985,7 +980,7 @@ sections:
             input: 'null'
             output: ['[false, true]']
 
-      - title: Alternative operator - `//`
+      - title: "Alternative operator: `//`"
         body: |
 
           A filter of the form `a // b` produces the same
@@ -1061,7 +1056,7 @@ sections:
           fields, and another object which is used to map author usernames to
           real names. Our input looks like:
 
-              {"posts": [{"title": "Frist psot", "author": "anon"},
+              {"posts": [{"title": "First post", "author": "anon"},
                          {"title": "A well-written article", "author": "person1"}],
                "realnames": {"anon": "Anonymous Coward",
                              "person1": "Person McPherson"}}
@@ -1069,7 +1064,7 @@ sections:
           We want to produce the posts with the author field containing a real
           name, as in:
 
-              {"title": "Frist psot", "author": "Anonymous Coward"}
+              {"title": "First post", "author": "Anonymous Coward"}
               {"title": "A well-written article", "author": "Person McPherson"}
 
           We use a variable, $names, to store the realnames object, so that we
diff --git a/docs/content/manual/v1.4/manual.yml b/docs/content/manual/v1.4/manual.yml
index a8923e11..b51b3b1a 100644
--- a/docs/content/manual/v1.4/manual.yml
+++ b/docs/content/manual/v1.4/manual.yml
@@ -142,7 +142,7 @@ sections:
         ASCII output with every non-ASCII character replaced with the
         equivalent escape sequence.
 
-      * `--unbuffered`
+      * `--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
@@ -166,7 +166,7 @@ sections:
 
       * `-e` / `--exit-status`:
 
-        Sets the exit status of jq to 0 if the last output values was
+        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
@@ -248,11 +248,11 @@ sections:
             input: '[1,2]'
             output: ['[]']
 
-      - title: "`.[<string>]`, `.[2]`, `.[10:15]`"
+      - title: "`.[<string>]`, `.[<number>]`, `.[<number>:<number>]`"
         body: |
 
           You can also look up fields of an object using syntax like
-          `.["foo"]` (.foo above is a shorthand version of this). This
+          `.["foo"]` (`.foo` above is a shorthand version of this). This
           one works for arrays as well, if the key is an
           integer. Arrays are zero-based (like javascript), so `.[2]`
           returns the third element of the array.
@@ -381,7 +381,7 @@ sections:
       instead.
 
     entries:
-      - title: Array construction - `[]`
+      - title: "Array construction: `[]`"
         body: |
 
           As in JSON, `[]` is used to construct arrays, as in
@@ -406,7 +406,7 @@ sections:
           - program: "[.user, .projects[]]"
             input: '{"user":"stedolan", "projects": ["jq", "wikiflow"]}'
             output: ['["stedolan", "jq", "wikiflow"]']
-      - title: Objects - `{}`
+      - title: "Objects: `{}`"
         body: |
 
           Like JSON, `{}` is for constructing objects (aka
@@ -467,14 +467,14 @@ 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.
 
     entries:
-      - title: Addition - `+`
+      - title: "Addition: `+`"
         body: |
 
           The operator `+` takes two filters, applies them both
@@ -513,7 +513,7 @@ sections:
             input: 'null'
             output: ['{"a": 42, "b": 2, "c": 3}']
 
-      - title: Subtraction - `-`
+      - title: "Subtraction: `-`"
         body: |
 
           As well as normal arithmetic subtraction on numbers, the `-`
@@ -528,7 +528,7 @@ sections:
             input: '["xml", "yaml", "json"]'
             output: ['["json"]']
 
-      - title: Multiplication, division, modulo - `*`, `/`, and `%`
+      - title: "Multiplication, division, modulo: `*`, `/`, `%`"
         body: |
 
           These operators only work on numbers, and do the expected.
@@ -632,7 +632,7 @@ sections:
             input: '["foo", "bar", "baz"]'
             output: ['["foo"]']
 
-      - 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
@@ -641,9 +641,9 @@ sections:
           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.
+          `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.
 
         examples:
           - program: 'to_entries'
@@ -700,14 +700,14 @@ sections:
             input: 'null'
             output: ['[1,2,3]']
 
-      - title: "`map(x)`"
+      - title: "`map(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 produce the outputs a new
           array. `map(.+1)` will increment each element of an array of numbers.
 
-          `map(x)` is equivalent to `[.[] | x]`. In fact, this is how
+          `map(f)` is equivalent to `[.[] | f]`. In fact, this is how
           it's defined.
 
         examples:
@@ -875,7 +875,7 @@ sections:
             input: '[0, false, [], {}, null, "hello"]'
             output: ['["number", "boolean", "array", "object", "null", "string"]']
 
-      - title: "`sort, sort_by`"
+      - title: "`sort`, `sort_by`"
         body: |
 
           The `sort` functions sorts its input, which must be an
@@ -1179,7 +1179,7 @@ sections:
             input: '[[{"a":1}]]'
             output: ['1']
 
-      - title: "String interpolation - `\\(foo)`"
+      - title: "String interpolation: `\\(exp)`"
         body: |
 
           Inside a string, you can put an expression inside parens
@@ -1274,10 +1274,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'\""]
@@ -1300,7 +1296,8 @@ sections:
           - program: '.[] == 1'
             input: '[1, 1.0, "1", "banana"]'
             output: ['true', 'true', 'false', 'false']
-      - title: if-then-else
+
+      - title: if-then-else-end
         body: |
 
           `if A then B else C end` will act the same as `B` if `A`
@@ -1333,7 +1330,7 @@ sections:
             input: 2
             output: ['"many"']
 
-      - title: "`>, >=, <=, <`"
+      - title: "`>`, `>=`, `<=`, `<`"
         body: |
 
           The comparison operators `>`, `>=`, `<=`, `<` return whether
@@ -1348,12 +1345,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.
@@ -1363,12 +1361,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"'
@@ -1377,9 +1375,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']
@@ -1387,7 +1382,7 @@ sections:
             input: 'null'
             output: ['[false, true]']
 
-      - title: Alternative operator - `//`
+      - title: "Alternative operator: `//`"
         body: |
 
           A filter of the form `a // b` produces the same
@@ -1463,7 +1458,7 @@ sections:
           fields, and another object which is used to map author usernames to
           real names. Our input looks like:
 
-              {"posts": [{"title": "Frist psot", "author": "anon"},
+              {"posts": [{"title": "First post", "author": "anon"},
                          {"title": "A well-written article", "author": "person1"}],
                "realnames": {"anon": "Anonymous Coward",
                              "person1": "Person McPherson"}}
@@ -1471,7 +1466,7 @@ sections:
           We want to produce the posts with the author field containing a real
           name, as in:
 
-              {"title": "Frist psot", "author": "Anonymous Coward"}
+              {"title": "First post", "author": "Anonymous Coward"}
               {"title": "A well-written article", "author": "Person McPherson"}
 
           We use a variable, $names, to store the realnames object, so that we
diff --git a/docs/content/manual/v1.5/manual.yml b/docs/content/manual/v1.5/manual.yml
index 2ef584af..64bee206 100644
--- a/docs/content/manual/v1.5/manual.yml
+++ b/docs/content/manual/v1.5/manual.yml
@@ -107,7 +107,7 @@ sections:
         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.