From: Jay Satiro <raysatiro@yahoo.com>
Date: Wed, 12 Feb 2025 04:20:22 +0000 (-0500)
Subject: write-out.md: add 'header' and 'output' to the variable list
X-Git-Tag: curl-8_12_1~2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=42960ebec030ab46369516276872989a5ba18ab6;p=thirdparty%2Fcurl.git

write-out.md: add 'header' and 'output' to the variable list

Prior to this change %header{} and %output{} were explained in remarks
but not listed in the --write-out variable list.

Closes https://github.com/curl/curl/pull/16299
---

diff --git a/docs/cmdline-opts/write-out.md b/docs/cmdline-opts/write-out.md
index f11c280864..7b7284c7c0 100644
--- a/docs/cmdline-opts/write-out.md
+++ b/docs/cmdline-opts/write-out.md
@@ -32,10 +32,11 @@ output a newline by using \n, a carriage return with \r and a tab space with
 The output is by default written to standard output, but can be changed with
 %{stderr} and %output{}.
 
-Output HTTP headers from the most recent request by using *%header{name}*
-where *name* is the case insensitive name of the header (without the trailing
-colon). The header contents are exactly as sent over the network, with leading
-and trailing whitespace trimmed (added in 7.84.0).
+Output HTTP header values from the transfer's most recent server response by
+using *%header{name}* where *name* is the case insensitive name of the header
+(without the trailing colon). The header contents are exactly as delivered over
+the network but with leading and trailing whitespace and newlines stripped off
+(added in 7.84.0).
 
 Select a specific target destination file to write the output to, by using
 *%output{name}* (added in curl 8.3.0) where *name* is the full filename. The
@@ -87,6 +88,11 @@ most useful in combination with the --remote-header-name option.
 The initial path curl ended up in when logging on to the remote FTP
 server. (Added in 7.15.4)
 
+## `header{name}`
+The value of header `name` from the transfer's most recent server response.
+Unlike other variables, the variable name `header` is not in braces. For
+example `%header{date}`. Refer to --write-out remarks. (Added in 7.84.0)
+
 ## `header_json`
 A JSON object with all HTTP response headers from the recent transfer. Values
 are provided as arrays, since in the case of multiple headers there can be
@@ -143,6 +149,12 @@ Number of retries actually performed when `--retry` has been used.
 The rest of the output is only shown if the transfer returned a non-zero error.
 (Added in 7.75.0)
 
+## `output{filename}`
+From this point on, the --write-out output is written to the filename specified
+in braces. The filename can be prefixed with `>>` to append to the file. Unlike
+other variables, the variable name `output` is not in braces. For example
+`%output{>>stats.txt}`. Refer to --write-out remarks. (Added in 8.3.0)
+
 ## `proxy_ssl_verify_result`
 The result of the HTTPS proxy's SSL peer certificate verification that was
 requested. 0 means the verification was successful. (Added in 7.52.0)
diff --git a/tests/test1486.pl b/tests/test1486.pl
index eb70d02d74..99aa1574c7 100755
--- a/tests/test1486.pl
+++ b/tests/test1486.pl
@@ -60,7 +60,9 @@ sub getdocsvars {
     open(my $f, "<", "$root/../docs/cmdline-opts/write-out.md");
     while(<$f>) {
         if($_ =~ /^\#\# \`([^\`]*)\`/) {
-            $indocs{$1} = 1;
+            if($1 ne "header{name}" && $1 ne "output{filename}") {
+                $indocs{$1} = 1;
+            }
         }
     }
     close($f);