From 3553a9d617471d31b029b4d025363ac2232934ae Mon Sep 17 00:00:00 2001
From: pkoppstein <pkoppstein@gmail.com>
Date: Fri, 21 Jul 2023 08:33:03 -0400
Subject: [PATCH] manual.yml: some clarifications plus fixes for markdown
 bloopers (#2737)

---
 docs/content/manual/manual.yml | 26 ++++++++++++++------------
 jq.1.prebuilt                  | 26 ++++++++++++++++++--------
 2 files changed, 32 insertions(+), 20 deletions(-)

diff --git a/docs/content/manual/manual.yml b/docs/content/manual/manual.yml
index 2f4bd3c0..ff68482a 100644
--- a/docs/content/manual/manual.yml
+++ b/docs/content/manual/manual.yml
@@ -325,7 +325,7 @@ sections:
           it does.  For example, using the current implementation of
           jq, we would see that the expression:
           
-              `1E1234567890 | .`
+              1E1234567890 | .
 
           produces `1.7976931348623157e+308` on at least one platform.
           This is because, in the process of parsing the number, this
@@ -384,13 +384,13 @@ sections:
       - title: "Object Identifier-Index: `.foo`, `.foo.bar`"
         body: |
 
-          The simplest *useful* filter is `.foo`. When given a
-          JSON object (aka dictionary or hash) as input, it produces
-          the value at the key "foo", or null if there's none present.
+          The simplest *useful* filter has the form `.foo`. When given a
+          JSON object (aka dictionary or hash) as input, `.foo` produces
+          the value at the key "foo" if the key is present, or null otherwise.
 
           A filter of the form `.foo.bar` is equivalent to `.foo|.bar`.
 
-          This syntax only works for simple, identifier-like keys, that
+          The `.foo` syntax only works for simple, identifier-like keys, that
           is, keys that are all made of alphanumeric characters and
           underscore, and which do not start with a digit.
 
@@ -399,15 +399,17 @@ sections:
           `."foo$"`, or else `.["foo$"]`.
 
           For example `.["foo::bar"]` and `.["foo.bar"]` work while
-          `.foo::bar` does not, and `.foo.bar` means `.["foo"].["bar"]`.
+          `.foo::bar` does not.
 
         examples:
           - program: '.foo'
             input: '{"foo": 42, "bar": "less interesting data"}'
             output: [42]
+
           - program: '.foo'
             input: '{"notfoo": true, "alsonotfoo": false}'
             output: ['null']
+
           - program: '.["foo"]'
             input: '{"foo": 42}'
             output: [42]
@@ -967,13 +969,13 @@ sections:
           `map_values` when applied to arrays. These examples assume the
           input is `[1]` in all cases:
 
-          map(.+1)          #=>  [2]
-          map(., .)         #=>  [1,1]
-          map(empty)        #=>  []
+              map(.+1)          #=>  [2]
+              map(., .)         #=>  [1,1]
+              map(empty)        #=>  []
 
-          map_values(.+1)   #=>  [2]
-          map_values(., .)  #=>  [1]
-          map_values(empty) #=>  []
+              map_values(.+1)   #=>  [2]
+              map_values(., .)  #=>  [1]
+              map_values(empty) #=>  []
 
           `map(f)` is equivalent to `[.[] | f]` and
           `map_values(f)` is equivalent to `.[] |= f`.
diff --git a/jq.1.prebuilt b/jq.1.prebuilt
index c4f99dd6..80933f74 100644
--- a/jq.1.prebuilt
+++ b/jq.1.prebuilt
@@ -258,7 +258,7 @@ Although the identity filter never modifies the value of its input, jq processin
 .
 .nf
 
-`1E1234567890 | \.`
+1E1234567890 | \.
 .
 .fi
 .
@@ -315,19 +315,19 @@ jq \'\. as $big | [$big, $big + 1] | map(\. > 10000000000000000000000000000000)\
 .IP "" 0
 .
 .SS "Object Identifier\-Index: \.foo, \.foo\.bar"
-The simplest \fIuseful\fR filter is \fB\.foo\fR\. When given a JSON object (aka dictionary or hash) as input, it produces the value at the key "foo", or null if there\'s none present\.
+The simplest \fIuseful\fR filter has the form \fB\.foo\fR\. When given a JSON object (aka dictionary or hash) as input, \fB\.foo\fR produces the value at the key "foo" if the key is present, or null otherwise\.
 .
 .P
 A filter of the form \fB\.foo\.bar\fR is equivalent to \fB\.foo|\.bar\fR\.
 .
 .P
-This syntax only works for simple, identifier\-like keys, that is, keys that are all made of alphanumeric characters and underscore, and which do not start with a digit\.
+The \fB\.foo\fR syntax only works for simple, identifier\-like keys, that is, keys that are all made of alphanumeric characters and underscore, and which do not start with a digit\.
 .
 .P
 If the key contains special characters or starts with a digit, you need to surround it with double quotes like this: \fB\."foo$"\fR, or else \fB\.["foo$"]\fR\.
 .
 .P
-For example \fB\.["foo::bar"]\fR and \fB\.["foo\.bar"]\fR work while \fB\.foo::bar\fR does not, and \fB\.foo\.bar\fR means \fB\.["foo"]\.["bar"]\fR\.
+For example \fB\.["foo::bar"]\fR and \fB\.["foo\.bar"]\fR work while \fB\.foo::bar\fR does not\.
 .
 .IP "" 4
 .
@@ -960,11 +960,21 @@ Specifically, for object inputs, \fBmap_value(f)\fR constructs the output object
 .P
 Here are some examples to clarify the behavior of \fBmap\fR and \fBmap_values\fR when applied to arrays\. These examples assume the input is \fB[1]\fR in all cases:
 .
-.P
-map(\.+1) #=> [2] map(\., \.) #=> [1,1] map(empty) #=> []
+.IP "" 4
 .
-.P
-map_values(\.+1) #=> [2] map_values(\., \.) #=> [1] map_values(empty) #=> []
+.nf
+
+map(\.+1)          #=>  [2]
+map(\., \.)         #=>  [1,1]
+map(empty)        #=>  []
+
+map_values(\.+1)   #=>  [2]
+map_values(\., \.)  #=>  [1]
+map_values(empty) #=>  []
+.
+.fi
+.
+.IP "" 0
 .
 .P
 \fBmap(f)\fR is equivalent to \fB[\.[] | f]\fR and \fBmap_values(f)\fR is equivalent to \fB\.[] |= f\fR\.