Add fixes for manual (#2391)

1 files changed, 57 insertions, 46 deletions

diff --git a/docs/content/manual/manual.yml b/docs/content/manual/manual.yml
index a8f4f318..fdaf5bec 100644
--- a/docs/content/manual/manual.yml
+++ b/docs/content/manual/manual.yml
@@ -3114,16 +3114,16 @@ sections:
     entries:
       - title: "Update-assignment: `|=`"
         body: |
-          This is the "update" operator '|='.  It takes a filter on the
+          This is the "update" operator `|=`.  It takes a filter on the
           right-hand side and works out the new value for the property
           of `.` being assigned to by running the old value through this
-          expression. For instance, (.foo, .bar) |= .+1 will build an
-          object with the "foo" field set to the input's "foo" plus 1,
-          and the "bar" field set to the input's "bar" plus 1.
+          expression. For instance, `(.foo, .bar) |= .+1` will build an
+          object with the `foo` field set to the input's `foo` plus 1,
+          and the `bar` field set to the input's `bar` plus 1.
 
           The left-hand side can be any general path expression; see `path()`.
 
-          Note that the left-hand side of '|=' refers to a value in `.`.
+          Note that the left-hand side of `|=` refers to a value in `.`.
           Thus `$var.foo |= . + 1` won't work as expected (`$var.foo` is
           not a valid or useful path expression in `.`); use `$var |
           .foo |= . + 1` instead.
@@ -3156,41 +3156,52 @@ sections:
         body: |
 
           This is the plain assignment operator.  Unlike the others, the
-          input to the right-hand-side (RHS) is the same as the input to
-          the left-hand-side (LHS) rather than the value at the LHS
+          input to the right-hand side (RHS) is the same as the input to
+          the left-hand side (LHS) rather than the value at the LHS
           path, and all values output by the RHS will be used (as shown
           below).
 
-          If the RHS of '=' produces multiple values, then for each such
+          If the RHS of `=` produces multiple values, then for each such
           value jq will set the paths on the left-hand side to the value
           and then it will output the modified `.`.  For example,
-          `(.a,.b)=range(2)` outputs `{"a":0,"b":0}`, then
+          `(.a,.b) = range(2)` outputs `{"a":0,"b":0}`, then
           `{"a":1,"b":1}`.  The "update" assignment forms (see above) do
           not do this.
 
-          This example should show the difference between '=' and '|=':
+          This example should show the difference between `=` and `|=`:
 
-          Provide input '{"a": {"b": 10}, "b": 20}' to the programs:
+          Provide input `{"a": {"b": 10}, "b": 20}` to the programs
 
               .a = .b
 
-              .a |= .b
+          and
 
-          The former will set the "a" field of the input to the "b"
-          field of the input, and produce the output {"a": 20, "b": 20}.
-          The latter will set the "a" field of the input to the "a"
-          field's "b" field, producing {"a": 10, "b": 20}.
+              .a |= .b
 
-          Another example of the difference between '=' and '|=':
+          The former will set the `a` field of the input to the `b`
+          field of the input, and produce the output `{"a": 20, "b": 20}`.
+          The latter will set the `a` field of the input to the `a`
+          field's `b` field, producing `{"a": 10, "b": 20}`.
 
-              null|(.a,.b)=range(3)
+        examples:
+          - program: .a = .b
+            input: '{"a": {"b": 10}, "b": 20}'
+            output: '{"a":20,"b":20}'
 
-          outputs '{"a":0,"b":0}', '{"a":1,"b":1}', and '{"a":2,"b":2}',
-          while
+          - program: .a |= .b
+            input: '{"a": {"b": 10}, "b": 20}'
+            output: '{"a":10,"b":20}'
 
-              null|(.a,.b)|=range(3)
+          - program: (.a, .b) = range(3)
+            input: 'null'
+            output:
+              - '{"a":0,"b":0}'
+              - '{"a":1,"b":1}'
+              - '{"a":2,"b":2}'
 
-          outputs just '{"a":0,"b":0}'.
+          - program: (.a, .b) |= range(3)
+            input: 'null'
+            output: '{"a":0,"b":0}'
 
       - title: Complex assignments
         body: |
@@ -3244,14 +3255,14 @@ sections:
 
       Paths in the a search path are subject to various substitutions.
 
-      For paths starting with "~/", the user's home directory is
-      substituted for "~".
+      For paths starting with `~/`, the user's home directory is
+      substituted for `~`.
 
-      For paths starting with "$ORIGIN/", the path of the jq executable
-      is substituted for "$ORIGIN".
+      For paths starting with `$ORIGIN/`, the path of the jq executable
+      is substituted for `$ORIGIN`.
 
-      For paths starting with "./" or paths that are ".", the path of
-      the including file is substituted for ".".  For top-level programs
+      For paths starting with `./` or paths that are `.`, the path of
+      the including file is substituted for `.`.  For top-level programs
       given on the command-line, the current directory is used.
 
       Import directives can optionally specify a search path to which
@@ -3264,36 +3275,36 @@ sections:
       Null and empty string path elements terminate search path
       processing.
 
-      A dependency with relative path "foo/bar" would be searched for in
-      "foo/bar.jq" and "foo/bar/bar.jq" in the given search path. This
+      A dependency with relative path `foo/bar` would be searched for in
+      `foo/bar.jq` and `foo/bar/bar.jq` in the given search path. This
       is intended to allow modules to be placed in a directory along
       with, for example, version control files, README files, and so on,
       but also to allow for single-file modules.
 
       Consecutive components with the same name are not allowed to avoid
-      ambiguities (e.g., "foo/foo").
+      ambiguities (e.g., `foo/foo`).
 
       For example, with `-L$HOME/.jq` a module `foo` can be found in
       `$HOME/.jq/foo.jq` and `$HOME/.jq/foo/foo.jq`.
 
-      If "$HOME/.jq" is a file, it is sourced into the main program.
+      If `$HOME/.jq` is a file, it is sourced into the main program.
 
     entries:
       - title: "`import RelativePathString as NAME [<metadata>];`"
         body: |
 
           Imports a module found at the given path relative to a
-          directory in a search path.  A ".jq" suffix will be added to
+          directory in a search path.  A `.jq` suffix will be added to
           the relative path string.  The module's symbols are prefixed
-          with "NAME::".
+          with `NAME::`.
 
           The optional metadata must be a constant jq expression.  It
-          should be an object with keys like "homepage" and so on.  At
-          this time jq only uses the "search" key/value of the metadata.
+          should be an object with keys like `homepage` and so on.  At
+          this time jq only uses the `search` key/value of the metadata.
           The metadata is also made available to users via the
           `modulemeta` builtin.
 
-          The "search" key in the metadata, if present, should have a
+          The `search` key in the metadata, if present, should have a
           string or array value (array of strings); this is the search
           path to be prefixed to the top-level search path.
 
@@ -3302,13 +3313,13 @@ sections:
 
           Imports a module found at the given path relative to a
           directory in a search path as if it were included in place.  A
-          ".jq" suffix will be added to the relative path string.  The
+          `.jq` suffix will be added to the relative path string.  The
           module's symbols are imported into the caller's namespace as
           if the module's content had been included directly.
 
           The optional metadata must be a constant jq expression.  It
-          should be an object with keys like "homepage" and so on.  At
-          this time jq only uses the "search" key/value of the metadata.
+          should be an object with keys like `homepage` and so on.  At
+          this time jq only uses the `search` key/value of the metadata.
           The metadata is also made available to users via the
           `modulemeta` builtin.
 
@@ -3316,17 +3327,17 @@ sections:
         body: |
 
           Imports a JSON file found at the given path relative to a
-          directory in a search path.  A ".json" suffix will be added to
+          directory in a search path.  A `.json` suffix will be added to
           the relative path string.  The file's data will be available
           as `$NAME::NAME`.
 
           The optional metadata must be a constant jq expression.  It
-          should be an object with keys like "homepage" and so on.  At
-          this time jq only uses the "search" key/value of the metadata.
+          should be an object with keys like `homepage` and so on.  At
+          this time jq only uses the `search` key/value of the metadata.
           The metadata is also made available to users via the
           `modulemeta` builtin.
 
-          The "search" key in the metadata, if present, should have a
+          The `search` key in the metadata, if present, should have a
           string or array value (array of strings); this is the search
           path to be prefixed to the top-level search path.
 
@@ -3338,7 +3349,7 @@ sections:
           metadata that can be read with the `modulemeta` builtin.
 
           The metadata must be a constant jq expression.  It should be
-          an object with keys like "homepage".  At this time jq doesn't
+          an object with keys like `homepage`.  At this time jq doesn't
           use this metadata, but it is made available to users via the
           `modulemeta` builtin.
 
@@ -3347,7 +3358,7 @@ sections:
 
           Takes a module name as input and outputs the module's metadata
           as an object, with the module's imports (including metadata)
-          as an array value for the "deps" key.
+          as an array value for the `deps` key.
 
           Programs can use this to query a module's metadata, which they
           could then use to, for example, search for, download, and