DOC: Improve documentation of the various hdr() fetches

GitHub issue #796 notes that many administrators miss the fact that the `hdr()`
fetch (without the `f`) splits the header value at commas. This is only
mentioned at the end of a long paragraph.

This patch attempts to improve the documentation by:
- Explaning the "comma issue" as early as possible.
- Adding newlines to split the explanation into distinct sections.
- Reducing duplication by making the `res` siblings refer to their `req`
  counterparts.

This patch may be backported as long as it applies cleanly. During the
refactoring I needed to adjust several explanations for consistency and not all
of them might be available in older branches.

doc/configuration.txt

@@ -18509,33 +18509,44 @@ hdr([<name>[,<occ>]]) : string
   unambiguously apply to the request headers.
 
 req.fhdr(<name>[,<occ>]) : string
-  This extracts the last occurrence of header <name> in an HTTP request. When
+  This returns the full value of the last occurrence of header <name> in an
-  used from an ACL, all occurrences are iterated over until a match is found.
+  HTTP request. It differs from req.hdr() in that any commas present in the
+  value are returned and are not used as delimiters. This is sometimes useful
+  with headers such as User-Agent.
+
+  When used from an ACL, all occurrences are iterated over until a match is
+  found.
+
   Optionally, a specific occurrence might be specified as a position number.
   Positive values indicate a position from the first occurrence, with 1 being
   the first one. Negative values indicate positions relative to the last one,
-  with -1 being the last one. It differs from req.hdr() in that any commas
+  with -1 being the last one.
-  present in the value are returned and are not used as delimiters. This is
-  sometimes useful with headers such as User-Agent.
 
 req.fhdr_cnt([<name>]) : integer
   Returns an integer value representing the number of occurrences of request
   header field name <name>, or the total number of header fields if <name> is
-  not specified. Contrary to its req.hdr_cnt() cousin, this function returns
+  not specified. Like req.fhdr() it differs from res.hdr_cnt() by not splitting
-  the number of full line headers and does not stop on commas.
+  headers at commas.
 
 req.hdr([<name>[,<occ>]]) : string
-  This extracts the last occurrence of header <name> in an HTTP request. When
+  This returns the last comma-separated value of the header <name> in an HTTP
-  used from an ACL, all occurrences are iterated over until a match is found.
+  request. The fetch considers any comma as a delimiter for distinct values.
+  This is useful if you need to process headers that are defined to be a list
+  of values, such as Accept, or X-Forwarded-For. If full-line headers are
+  desired instead, use req.fhdr(). Please carefully check RFC 7231 to know how
+  certain headers are supposed to be parsed. Also, some of them are case
+  insensitive (e.g. Connection).
+
+  When used from an ACL, all occurrences are iterated over until a match is
+  found.
+
   Optionally, a specific occurrence might be specified as a position number.
   Positive values indicate a position from the first occurrence, with 1 being
   the first one. Negative values indicate positions relative to the last one,
-  with -1 being the last one. A typical use is with the X-Forwarded-For header
+  with -1 being the last one.
-  once converted to IP, associated with an IP stick-table. The function
+
-  considers any comma as a delimiter for distinct values. If full-line headers
+  A typical use is with the X-Forwarded-For header once converted to IP,
-  are desired instead, use req.fhdr(). Please carefully check RFC7231 to know
+  associated with an IP stick-table.
-  how certain headers are supposed to be parsed. Also, some of them are case
-  insensitive (e.g. Connection).
 
   ACL derivatives :
     hdr([<name>[,<occ>]])     : exact string match
@@ -18551,34 +18562,36 @@ req.hdr_cnt([<name>]) : integer
 hdr_cnt([<header>]) : integer (deprecated)
   Returns an integer value representing the number of occurrences of request
   header field name <name>, or the total number of header field values if
-  <name> is not specified. It is important to remember that one header line may
+  <name> is not specified. Like req.hdr() it counts each comma separated
-  count as several headers if it has several values. The function considers any
+  part of the header's value. If counting of full-line headers is desired,
-  comma as a delimiter for distinct values. If full-line headers are desired
+  then req.fhdr_cnt() should be used instead.
-  instead, req.fhdr_cnt() should be used instead. With ACLs, it can be used to
+
-  detect presence, absence or abuse of a specific header, as well as to block
+  With ACLs, it can be used to detect presence, absence or abuse of a specific
-  request smuggling attacks by rejecting requests which contain more than one
+  header, as well as to block request smuggling attacks by rejecting requests
-  of certain headers. See "req.hdr" for more information on header matching.
+  which contain more than one of certain headers.
+
+  Refer to req.hdr() for more information on header matching.
 
 req.hdr_ip([<name>[,<occ>]]) : ip
 hdr_ip([<name>[,<occ>]]) : ip (deprecated)
   This extracts the last occurrence of header <name> in an HTTP request,
   converts it to an IPv4 or IPv6 address and returns this address. When used
   with ACLs, all occurrences are checked, and if <name> is omitted, every value
-  of every header is checked. Optionally, a specific occurrence might be
+  of every header is checked.
-  specified as a position number. Positive values indicate a position from the
+
-  first occurrence, with 1 being the first one. Negative values indicate
+  The <occ> parameter is processed as with req.hdr().
-  positions relative to the last one, with -1 being the last one. A typical use
+
-  is with the X-Forwarded-For and X-Client-IP headers.
+  A typical use is with the X-Forwarded-For and X-Client-IP headers.
 
 req.hdr_val([<name>[,<occ>]]) : integer
 hdr_val([<name>[,<occ>]]) : integer (deprecated)
   This extracts the last occurrence of header <name> in an HTTP request, and
   converts it to an integer value. When used with ACLs, all occurrences are
   checked, and if <name> is omitted, every value of every header is checked.
-  Optionally, a specific occurrence might be specified as a position number.
+
-  Positive values indicate a position from the first occurrence, with 1 being
+  The <occ> parameter is processed as with req.hdr().
-  the first one. Negative values indicate positions relative to the last one,
+
-  with -1 being the last one. A typical use is with the X-Forwarded-For header.
+  A typical use is with the X-Forwarded-For header.
 
 req.hdrs : string
   Returns the current request headers as string including the last empty line
@@ -18710,22 +18723,25 @@ req_ver : string (deprecated)
 res.body : binary
   This returns the HTTP response's available body as a block of data. Unlike
   the request side, there is no directive to wait for the response's body. This
-  sample fetch is really useful (and usable) in the health-check context. It
+  sample fetch is really useful (and usable) in the health-check context.
-  may be used in tcp-check based expect rules.
+
+  It may be used in tcp-check based expect rules.
 
 res.body_len : integer
   This returns the length of the HTTP response available body in bytes. Unlike
   the request side, there is no directive to wait for the response's body. This
-  sample fetch is really useful (and usable) in the health-check context. It
+  sample fetch is really useful (and usable) in the health-check context.
-  may be used in tcp-check based expect rules.
+
+  It may be used in tcp-check based expect rules.
 
 res.body_size : integer
   This returns the advertised length of the HTTP response body in bytes. It
   will represent the advertised Content-Length header, or the size of the
   available data in case of chunked encoding. Unlike the request side, there is
   no directive to wait for the response body. This sample fetch is really
-  useful (and usable) in the health-check context. It may be used in tcp-check
+  useful (and usable) in the health-check context.
-  based expect rules.
+
+  It may be used in tcp-check based expect rules.
 
 res.cache_hit : boolean
   Returns the boolean "true" value if the response has been built out of an
@@ -18750,8 +18766,9 @@ res.cook([<name>]) : string
 scook([<name>]) : string (deprecated)
   This extracts the last occurrence of the cookie name <name> on a "Set-Cookie"
   header line from the response, and returns its value as string. If no name is
-  specified, the first cookie value is returned. It may be used in tcp-check
+  specified, the first cookie value is returned.
-  based expect rules.
+
+  It may be used in tcp-check based expect rules.
 
   ACL derivatives :
     scook([<name>] : exact string match
@@ -18760,46 +18777,47 @@ res.cook_cnt([<name>]) : integer
 scook_cnt([<name>]) : integer (deprecated)
   Returns an integer value representing the number of occurrences of the cookie
   <name> in the response, or all cookies if <name> is not specified. This is
-  mostly useful when combined with ACLs to detect suspicious responses. It may
+  mostly useful when combined with ACLs to detect suspicious responses.
-  be used in tcp-check based expect rules.
+
+  It may be used in tcp-check based expect rules.
 
 res.cook_val([<name>]) : integer
 scook_val([<name>]) : integer (deprecated)
   This extracts the last occurrence of the cookie name <name> on a "Set-Cookie"
   header line from the response, and converts its value to an integer which is
-  returned. If no name is specified, the first cookie value is returned. It may
+  returned. If no name is specified, the first cookie value is returned.
-  be used in tcp-check based expect rules.
+
+  It may be used in tcp-check based expect rules.
 
 res.fhdr([<name>[,<occ>]]) : string
-  This extracts the last occurrence of header <name> in an HTTP response, or of
+  This fetch works like the req.fhdr() fetch with the difference that it acts
-  the last header if no <name> is specified. Optionally, a specific occurrence
+  on the headers within an HTTP response.
-  might be specified as a position number. Positive values indicate a position
+
-  from the first occurrence, with 1 being the first one. Negative values
+  Like req.fhdr() the res.fhdr() fetch returns full values. If the header is
-  indicate positions relative to the last one, with -1 being the last one. It
+  defined to be a list you should use res.hdr().
-  differs from res.hdr() in that any commas present in the value are returned
+
-  and are not used as delimiters. If this is not desired, the res.hdr() fetch
+  This fetch is sometimes useful with headers such as Date or Expires.
-  should be used instead. This is sometimes useful with headers such as Date or
+
-  Expires. It may be used in tcp-check based expect rules.
+  It may be used in tcp-check based expect rules.
 
 res.fhdr_cnt([<name>]) : integer
-  Returns an integer value representing the number of occurrences of response
+  This fetch works like the req.fhdr_cnt() fetch with the difference that it
-  header field name <name>, or the total number of header fields if <name> is
+  acts on the headers within an HTTP response.
-  not specified. Contrary to its res.hdr_cnt() cousin, this function returns
+
-  the number of full line headers and does not stop on commas. If this is not
+  Like req.fhdr_cnt() the res.fhdr_cnt() fetch acts on full values. If the
-  desired, the res.hdr_cnt() fetch should be used instead. It may be used in
+  header is defined to be a list you should use res.hdr_cnt().
-  tcp-check based expect rules.
+
+  It may be used in tcp-check based expect rules.
 
 res.hdr([<name>[,<occ>]]) : string
 shdr([<name>[,<occ>]]) : string (deprecated)
-  This extracts the last occurrence of header <name> in an HTTP response, or of
+  This fetch works like the req.hdr() fetch with the difference that it acts
-  the last header if no <name> is specified. Optionally, a specific occurrence
+  on the headers within an HTTP response.
-  might be specified as a position number. Positive values indicate a position
+
-  from the first occurrence, with 1 being the first one. Negative values
+  Like req.hdr() the res.hdr() fetch considers the comma to be a delimeter. If
-  indicate positions relative to the last one, with -1 being the last one. This
+  this is not desired res.fhdr() should be used.
-  can be useful to learn some data into a stick-table. The function considers
+
-  any comma as a delimiter for distinct values. If this is not desired, the
+  It may be used in tcp-check based expect rules.
-  res.fhdr() fetch should be used instead. It may be used in tcp-check based
-  expect rules.
 
   ACL derivatives :
     shdr([<name>[,<occ>]])     : exact string match
@@ -18813,45 +18831,47 @@ shdr([<name>[,<occ>]]) : string (deprecated)
 
 res.hdr_cnt([<name>]) : integer
 shdr_cnt([<name>]) : integer (deprecated)
-  Returns an integer value representing the number of occurrences of response
+  This fetch works like the req.hdr_cnt() fetch with the difference that it
-  header field name <name>, or the total number of header fields if <name> is
+  acts on the headers within an HTTP response.
-  not specified. The function considers any comma as a delimiter for distinct
+
-  values. If this is not desired, the res.fhdr_cnt() fetch should be used
+  Like req.hdr_cnt() the res.hdr_cnt() fetch considers the comma to be a
-  instead. It may be used in tcp-check based expect rules.
+  delimeter. If this is not desired res.fhdr_cnt() should be used.
+
+  It may be used in tcp-check based expect rules.
 
 res.hdr_ip([<name>[,<occ>]]) : ip
 shdr_ip([<name>[,<occ>]]) : ip (deprecated)
-  This extracts the last occurrence of header <name> in an HTTP response,
+  This fetch works like the req.hdr_ip() fetch with the difference that it
-  convert it to an IPv4 or IPv6 address and returns this address. Optionally, a
+  acts on the headers within an HTTP response.
-  specific occurrence might be specified as a position number. Positive values
+
-  indicate a position from the first occurrence, with 1 being the first one.
+  This can be useful to learn some data into a stick table.
-  Negative values indicate positions relative to the last one, with -1 being
+
-  the last one. This can be useful to learn some data into a stick table. It
+  It may be used in tcp-check based expect rules.
-  may be used in tcp-check based expect rules.
 
 res.hdr_names([<delim>]) : string
   This builds a string made from the concatenation of all header names as they
   appear in the response when the rule is evaluated. The default delimiter is
   the comma (',') but it may be overridden as an optional argument <delim>. In
-  this case, only the first character of <delim> is considered. It may be used
+  this case, only the first character of <delim> is considered.
-  in tcp-check based expect rules.
+
+  It may be used in tcp-check based expect rules.
 
 res.hdr_val([<name>[,<occ>]]) : integer
 shdr_val([<name>[,<occ>]]) : integer (deprecated)
-  This extracts the last occurrence of header <name> in an HTTP response, and
+  This fetch works like the req.hdr_val() fetch with the difference that it
-  converts it to an integer value. Optionally, a specific occurrence might be
+  acts on the headers within an HTTP response.
-  specified as a position number. Positive values indicate a position from the
+
-  first occurrence, with 1 being the first one. Negative values indicate
+  This can be useful to learn some data into a stick table.
-  positions relative to the last one, with -1 being the last one. This can be
+
-  useful to learn some data into a stick table. It may be used in tcp-check
+  It may be used in tcp-check based expect rules.
-  based expect rules.
 
 res.hdrs : string
   Returns the current response headers as string including the last empty line
   separating headers from the request body. The last empty line can be used to
   detect a truncated header block. This sample fetch is useful for some SPOE
-  headers analyzers and for advanced logging. It may also be used in tcp-check
+  headers analyzers and for advanced logging.
-  based expect rules.
+
+  It may also be used in tcp-check based expect rules.
 
 res.hdrs_bin : binary
   Returns the current response headers contained in preparsed binary form. This
@@ -18870,8 +18890,9 @@ res.hdrs_bin : binary
 res.ver : string
 resp_ver : string (deprecated)
   Returns the version string from the HTTP response, for example "1.1". This
-  can be useful for logs, but is mostly there for ACL. It may be used in
+  can be useful for logs, but is mostly there for ACL.
-  tcp-check based expect rules.
+
+  It may be used in tcp-check based expect rules.
 
   ACL derivatives :
     resp_ver : exact string match
@@ -18888,8 +18909,9 @@ set-cookie([<name>]) : string (deprecated)
 status : integer
   Returns an integer containing the HTTP status code in the HTTP response, for
   example, 302. It is mostly used within ACLs and integer ranges, for example,
-  to remove any Location header if the response is not a 3xx. It may be used in
+  to remove any Location header if the response is not a 3xx.
-  tcp-check based expect rules.
+
+  It may be used in tcp-check based expect rules.
 
 unique-id : string
   Returns the unique-id attached to the request. The directive