Revert "lexer: temporarily revert #\ patch; keep CR in comment bug fix"

This reverts commit 5d95791a6795bfc44380c2e6e343ee66dd891e8b.

1 files changed, 63 insertions, 1 deletions

diff --git a/docs/content/manual/manual.yml b/docs/content/manual/manual.yml
index faf3a22d..412febdc 100644
--- a/docs/content/manual/manual.yml
+++ b/docs/content/manual/manual.yml
@@ -229,7 +229,7 @@ sections:
       * `-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.
+        awk's -f option.
 
       * `-L directory`:
 
@@ -3537,6 +3537,68 @@ sections:
               (.posts[] | select(.author == "stedolan") | .comments) |=
                   . + ["terrible."]
 
+  - title: Comments
+
+    body: |
+
+      You can write comments in your jq filters using `#`.
+
+      A `#` character (not part of a string) starts a comment.
+      All characters from `#` to the end of the line are ignored.
+
+      If the end of the line is preceded by an odd number of backslash
+      characters, the following line is also considered part of the
+      comment and is ignored.
+
+      For example, the following code outputs `[1,3,4,7]`
+
+          [
+            1,
+            # foo \
+            2,
+            # bar \\
+            3,
+            4, # baz \\\
+            5, \
+            6,
+            7
+            # comment \
+              comment \
+              comment
+          ]
+
+      Backslash continuing the comment on the next line can be useful
+      when writing the "shebang" for a jq script:
+
+          #!/bin/sh --
+          # sum - Output the sum of the given arguments (or stdin)
+          # usage: sum [numbers...]
+          # \
+          exec jq --args -MRnf "$0" -- "$@"
+
+          $ARGS.positional |
+          reduce (
+            if . == []
+              then inputs
+              else .[]
+            end |
+            . as $dot |
+            try tonumber catch false |
+            if not or isnan then
+              @json "sum: Invalid number \($dot).\n" | halt_error(1)
+            end
+          ) as $n (0; . + $n)
+
+      The `exec` line is considered a comment by jq, so it is ignored.
+      But it is not ignored by `sh`, since in `sh` a backslash at the
+      end of the line does not continue the comment.
+      With this trick, when the script is invoked as `sum 1 2`,
+      `/bin/sh -- /path/to/sum 1 2` will be run, and `sh` will then
+      run `exec jq --args -MRnf /path/to/sum -- 1 2` replacing itself
+      with a `jq` interpreter invoked with the specified options (`-M`,
+      `-R`, `-n`, `--args`), that evaluates the current file (`$0`),
+      with the arguments (`$@`) that were passed to `sh`.
+
   - title: Modules
     body: |