From 6bac4ed059966007a6bc0e4a3639aca7d59f3b10 Mon Sep 17 00:00:00 2001
From: Nicolas Williams <nico@cryptonector.com>
Date: Wed, 22 Feb 2017 23:01:39 -0600
Subject: Document `stderr`

---
 docs/content/3.manual/manual.yml | 16 ++++++++++++----
 jq.1.prebuilt                    |  5 ++++-
 src/builtin.c                    |  1 -
 3 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/docs/content/3.manual/manual.yml b/docs/content/3.manual/manual.yml
index 84675182..cadc6fbd 100644
--- a/docs/content/3.manual/manual.yml
+++ b/docs/content/3.manual/manual.yml
@@ -2763,11 +2763,13 @@ sections:
       jq itself.  These two builtins, and jq's own reading actions, can
       be interleaved with each other.
 
-      One builtin provides minimal output capabilities, `debug`.
-      (Recall that a jq program's output values are always output as
-      JSON texts on `stdout`.)  The `debug` builtin can have
+      Two builtins provide minimal output capabilities, `debug`, and
+      `stderr`.  (Recall that a jq program's output values are always
+      output as JSON texts on `stdout`.)  The `debug` builtin can have
       application-specific behavior, such as for executables that use
-      the libjq C API but aren't the jq executable itself.
+      the libjq C API but aren't the jq executable itself.  The `stderr`
+      builtin outputs its input in raw mode to stder with no additional
+      decoration, not even a newline.
 
       Most jq builtins are referentially transparent, and yield constant
       and repeatable value streams when applied to constant inputs.
@@ -2795,6 +2797,12 @@ sections:
           `["DEBUG:", <input-value>]` and prints that and a newline on
           stderr, compactly.  This may change in the future.
 
+      - title: "`stderr`"
+        body: |
+
+          Prints its input in raw and compact mode to stderr with no
+          additional decoration, not even a newline.
+
       - title: "`input_filename`"
         body: |
 
diff --git a/jq.1.prebuilt b/jq.1.prebuilt
index 04b90715..efd1307a 100644
--- a/jq.1.prebuilt
+++ b/jq.1.prebuilt
@@ -3017,7 +3017,7 @@ See your system\'s manual for more information on each of these\.
 At this time jq has minimal support for I/O, mostly in the form of control over when inputs are read\. Two builtins functions are provided for this, \fBinput\fR and \fBinputs\fR, that read from the same sources (e\.g\., \fBstdin\fR, files named on the command\-line) as jq itself\. These two builtins, and jq\'s own reading actions, can be interleaved with each other\.
 .
 .P
-One builtin provides minimal output capabilities, \fBdebug\fR\. (Recall that a jq program\'s output values are always output as JSON texts on \fBstdout\fR\.) The \fBdebug\fR builtin can have application\-specific behavior, such as for executables that use the libjq C API but aren\'t the jq executable itself\.
+Two builtins provide minimal output capabilities, \fBdebug\fR, and \fBstderr\fR\. (Recall that a jq program\'s output values are always output as JSON texts on \fBstdout\fR\.) The \fBdebug\fR builtin can have application\-specific behavior, such as for executables that use the libjq C API but aren\'t the jq executable itself\. The \fBstderr\fR builtin outputs its input in raw mode to stder with no additional decoration, not even a newline\.
 .
 .P
 Most jq builtins are referentially transparent, and yield constant and repeatable value streams when applied to constant inputs\. This is not true of I/O builtins\.
@@ -3034,6 +3034,9 @@ This is primarily useful for reductions over a program\'s inputs\.
 .SS "debug"
 Causes a debug message based on the input value to be produced\. The jq executable wraps the input value with \fB["DEBUG:", <input\-value>]\fR and prints that and a newline on stderr, compactly\. This may change in the future\.
 .
+.SS "stderr"
+Prints its input in raw and compact mode to stderr with no additional decoration, not even a newline\.
+.
 .SS "input_filename"
 Returns the name of the file whose input is currently being filtered\. Note that this will not work well unless jq is running in a UTF\-8 locale\.
 .
diff --git a/src/builtin.c b/src/builtin.c
index 3fa65a4e..30714aa8 100644
--- a/src/builtin.c
+++ b/src/builtin.c
@@ -1112,7 +1112,6 @@ static jv f_debug(jq_state *jq, jv input) {
 
 static jv f_stderr(jq_state *jq, jv input) {
   jv_dumpf(jv_copy(input), stderr, 0);
-  fprintf(stderr, "\n");
   return input;
 }
 
-- 
cgit v1.2.3