[master] 255ec5bf5 varnishncsa.rst: Document the new [:first|last] arguments

[Walid Boudebouda]

commit 255ec5bf5b9b9059f349c6f0c20ff7da7f1388e9
Author: Walid Boudebouda <walid.boudebouda at gmail.com>
Date:   Thu Sep 4 10:22:26 2025 +0200

    varnishncsa.rst: Document the new [:first|last] arguments

diff --git a/doc/sphinx/reference/varnishncsa.rst b/doc/sphinx/reference/varnishncsa.rst
index e9d1c57eb..0b5c7eece 100644
--- a/doc/sphinx/reference/varnishncsa.rst
+++ b/doc/sphinx/reference/varnishncsa.rst
@@ -104,24 +104,33 @@ Supported formatters are:
   In client mode, total bytes received from client.  In backend mode,
   total bytes sent to the backend.
 
-%{X}i
+%{X[:first|last]}i
   The contents of request header X before any VCL processing for client side,
   and before vcl_backend_response for backend side. If the header appears
   multiple times in a single transaction, the last occurrence is used in
   backend mode and the first one in client mode.
 
+  If an optional `:first` or `:last` is used, VCL processing will be taken into
+  account and the matching rule will be first match or last match respectively.
+  When using `:last`, unset headers will still be captured.
+
+
 %l
   Remote logname. Always '-'.
 
 %m
   Request method. Defaults to '-' if not known.
 
-%{X}o
+%{X[:first|last]}o
   The contents of response header X, as it was delivered for client mode, and
   before VCL processing for backend mode. If the header appears multiple times
   in a single transaction, the last occurrence is used in client mode and the
   first one in backend mode.
 
+  If an optional `:first` or `:last` is used, VCL processing will be taken into
+  account and the matching rule will be first match or last match respectively.
+  When using `:last`, unset headers will still be captured.
+
 %O
   In client mode, total bytes sent to client.  In backend mode, total
   bytes received from the backend.
@@ -279,6 +288,11 @@ for all inputs::
 
   varnishncsa -j -F '{"size": %b, "time": "%t", "ua": "%{User-Agent}i"}'
 
+Log the first and last values of a request header that is modified multiple
+times in VCL:
+
+  varnishncsa -F "%{x-custom-header:first}i %{x-custom-header:last}i"
+
 SEE ALSO
 ========