From ef8701005969fb9ed44c3bf746b1b6f72babffb9 Mon Sep 17 00:00:00 2001
From: Nicolas Williams <nico@cryptonector.com>
Date: Sat, 25 Feb 2017 19:21:06 -0600
Subject: [PATCH] Document $ARGS and friends

---
 docs/content/3.manual/manual.yml | 13 +++++++++++++
 jq.1.prebuilt                    | 15 +++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/docs/content/3.manual/manual.yml b/docs/content/3.manual/manual.yml
index ae2b7f9..a0d713e 100644
--- a/docs/content/3.manual/manual.yml
+++ b/docs/content/3.manual/manual.yml
@@ -217,6 +217,9 @@ sections:
         `value` will be treated as a string, so `--arg foo 123` will
         bind `$foo` to `"123"`.
 
+        Named arguments are also available to the jq program as
+        `$ARGS.named`.
+
       * `--argjson name JSON-text`:
 
         This option passes a JSON-encoded value to the jq program as a
@@ -239,6 +242,16 @@ sections:
         one text, then that is used, else an array of texts is used as
         in `--slurpfile`.)
 
+      * `--args`:
+
+        Remaining arguments are positional string arguments.  These are
+        available to the jq program as `$ARGS.positional[]`.
+
+      * `--jsonargs`:
+
+        Remaining arguments are positional JSON text arguments.  These
+        are available to the jq program as `$ARGS.positional[]`.
+
       * `--run-tests [filename]`:
 
         Runs the tests in the given file or standard input.  This must
diff --git a/jq.1.prebuilt b/jq.1.prebuilt
index e07a142..c4d25ea 100644
--- a/jq.1.prebuilt
+++ b/jq.1.prebuilt
@@ -159,6 +159,9 @@ Sets the exit status of jq to 0 if the last output values was neither \fBfalse\f
 .IP
 This option passes a value to the jq program as a predefined variable\. If you run jq with \fB\-\-arg foo bar\fR, then \fB$foo\fR is available in the program and has the value \fB"bar"\fR\. Note that \fBvalue\fR will be treated as a string, so \fB\-\-arg foo 123\fR will bind \fB$foo\fR to \fB"123"\fR\.
 .
+.IP
+Named arguments are also available to the jq program as \fB$ARGS\.named\fR\.
+.
 .IP "\(bu" 4
 \fB\-\-argjson name JSON\-text\fR:
 .
@@ -181,6 +184,18 @@ Do not use\. Use \fB\-\-slurpfile\fR instead\.
 (This option is like \fB\-\-slurpfile\fR, but when the file has just one text, then that is used, else an array of texts is used as in \fB\-\-slurpfile\fR\.)
 .
 .IP "\(bu" 4
+\fB\-\-args\fR:
+.
+.IP
+Remaining arguments are positional string arguments\. These are available to the jq program as \fB$ARGS\.positional[]\fR\.
+.
+.IP "\(bu" 4
+\fB\-\-jsonargs\fR:
+.
+.IP
+Remaining arguments are positional JSON text arguments\. These are available to the jq program as \fB$ARGS\.positional[]\fR\.
+.
+.IP "\(bu" 4
 \fB\-\-run\-tests [filename]\fR:
 .
 .IP
-- 
2.40.0