[master] dc620277d Add individual hyperlink targets for vcl variables
Nils Goroll
nils.goroll at uplex.de
Sat Apr 1 12:48:09 UTC 2023
commit dc620277ddd49e53cdd486d6f0648f98b3b14f0d
Author: Nils Goroll <nils.goroll at uplex.de>
Date: Sat Apr 1 14:31:32 2023 +0200
Add individual hyperlink targets for vcl variables
in order to improve references to the documentation.
With this change, VCL variable documentation can be referenced
externally by replacing the dot in the variable name with a hyphen and
use that as a target, for example:
https://varnish-cache.org/docs/trunk/reference/vcl-var.html#resp-filters
Rules:
- only current (VCL >= 4.1) variables gain a target
- if there is a section by the same name as a target, do not change it
- No .* for HEADERS like req.http.*
Notes:
This turned out to be more work than anticipated for presumably a
minor change. First I tried to avoid adding target names by turning
the definition list items into subsections, which, with a simple
change to generate.py, worked ok for HTML, but looked terrible for the
man page, which only has three section levels: The variables appeared
on the same indentation level as the section headers.
So next I tried writing code to perform the change automatically, but
this also turned out to be tedious. So ultimately, I used an emacs
macro with manual polishing and the work was done in minutes.
Code is not always the answer...
diff --git a/doc/sphinx/reference/vcl_var.rst b/doc/sphinx/reference/vcl_var.rst
index 024366a11..edb9761bb 100644
--- a/doc/sphinx/reference/vcl_var.rst
+++ b/doc/sphinx/reference/vcl_var.rst
@@ -29,6 +29,8 @@ With PROXY protocol::
CLIENT ------------ PROXY ------------ VARNISHD
+.. _client.identity:
+
client.identity
Type: STRING
@@ -46,6 +48,8 @@ client.identity
header.
+.. _client.ip:
+
client.ip
Type: IP
@@ -57,6 +61,8 @@ client.ip
or what the PROXY protocol told us.
+.. _server.hostname:
+
server.hostname
Type: STRING
@@ -67,6 +73,8 @@ server.hostname
`gethostname(3)` system function.
+.. _server.identity:
+
server.identity
Type: STRING
@@ -79,6 +87,8 @@ server.identity
value from `gethostname(3)` system function will be used.
+.. _server.ip:
+
server.ip
Type: IP
@@ -91,6 +101,8 @@ server.ip
or what the PROXY protocol told us.
+.. _remote.ip:
+
remote.ip
Type: IP
@@ -105,6 +117,8 @@ remote.ip
will be ``0.0.0.0:0``
+.. _local.endpoint:
+
local.endpoint ``VCL >= 4.1``
Type: STRING
@@ -116,6 +130,8 @@ local.endpoint ``VCL >= 4.1``
If the argument was ``-a foo=:81`` this would be ":81"
+.. _local.ip:
+
local.ip
Type: IP
@@ -129,6 +145,8 @@ local.ip
will be ``0.0.0.0:0``
+.. _local.socket:
+
local.socket ``VCL >= 4.1``
Type: STRING
@@ -150,6 +168,8 @@ These variables describe the present request, and when ESI:include
requests are being processed, req_top points to the request received
from the client.
+.. _req:
+
req
Type: HTTP
@@ -161,6 +181,8 @@ req
Mostly useful for passing to VMODs.
+.. _req.backend_hint:
+
req.backend_hint
Type: BACKEND
@@ -177,6 +199,8 @@ req.backend_hint
or backend, respectively.
+.. _req.can_gzip:
+
req.can_gzip
Type: BOOL
@@ -201,6 +225,8 @@ req.esi ``VCL <= 4.0``
in VCL 4.1.
+.. _req.esi_level:
+
req.esi_level
Type: INT
@@ -210,6 +236,8 @@ req.esi_level
A count of how many levels of ESI requests we're currently at.
+.. _req.grace:
+
req.grace
Type: DURATION
@@ -225,6 +253,8 @@ req.grace
grace value will be used as the object's grace.
+.. _req.hash:
+
req.hash
Type: BLOB
@@ -237,6 +267,8 @@ req.hash
for debugging hit/miss status.
+.. _req.hash_always_miss:
+
req.hash_always_miss
Type: BOOL
@@ -254,6 +286,8 @@ req.hash_always_miss
existing entries in case the fetch fails.
+.. _req.hash_ignore_busy:
+
req.hash_ignore_busy
Type: BOOL
@@ -270,6 +304,8 @@ req.hash_ignore_busy
up content sideways from each other to avoid deadlocks.
+.. _req.hash_ignore_vary:
+
req.hash_ignore_vary
Type: BOOL
@@ -291,6 +327,8 @@ req.hash_ignore_vary
Use with caution.
+.. _req.http:
+
req.http.*
Type: HEADER
@@ -316,6 +354,8 @@ req.http.*
quoted syntax is discouraged but available for interoperability.
+.. _req.is_hitmiss:
+
req.is_hitmiss
Type: BOOL
@@ -325,6 +365,8 @@ req.is_hitmiss
If this request resulted in a hitmiss
+.. _req.is_hitpass:
+
req.is_hitpass
Type: BOOL
@@ -334,6 +376,8 @@ req.is_hitpass
If this request resulted in a hitpass
+.. _req.method:
+
req.method
Type: STRING
@@ -357,6 +401,8 @@ req.proto ``VCL <= 4.0``
The HTTP protocol version used by the client, usually "HTTP/1.1"
or "HTTP/2.0".
+.. _req.proto:
+
req.proto ``VCL >= 4.1``
Type: STRING
@@ -367,6 +413,8 @@ req.proto ``VCL >= 4.1``
or "HTTP/2.0".
+.. _req.restarts:
+
req.restarts
Type: INT
@@ -377,6 +425,8 @@ req.restarts
A count of how many times this request has been restarted.
+.. _req.storage:
+
req.storage
Type: STEVEDORE
@@ -389,6 +439,8 @@ req.storage
The storage backend to use to save this request body.
+.. _req.time:
+
req.time
Type: TIME
@@ -399,6 +451,8 @@ req.time
across restarts.
+.. _req.transport:
+
req.transport
Type: STRING
@@ -408,6 +462,8 @@ req.transport
The transport protocol which brought this request.
+.. _req.ttl:
+
req.ttl
Type: DURATION
@@ -420,6 +476,8 @@ req.ttl
Upper limit on the object age for cache lookups to return hit.
+.. _req.url:
+
req.url
Type: STRING
@@ -432,6 +490,8 @@ req.url
The requested URL, for instance "/robots.txt".
+.. _req.xid:
+
req.xid
Type: INT
@@ -441,6 +501,8 @@ req.xid
Unique ID of this request.
+.. _req_top.http:
+
req_top.http.*
Type: HEADER
@@ -453,6 +515,8 @@ req_top.http.*
See ``req.http.*`` for general notes.
+.. _req_top.method:
+
req_top.method
Type: STRING
@@ -464,6 +528,8 @@ req_top.method
Identical to req.method in non-ESI requests.
+.. _req_top.proto:
+
req_top.proto
Type: STRING
@@ -475,6 +541,8 @@ req_top.proto
Identical to req.proto in non-ESI requests.
+.. _req_top.time:
+
req_top.time
Type: TIME
@@ -485,6 +553,8 @@ req_top.time
remains constant across restarts.
+.. _req_top.url:
+
req_top.url
Type: STRING
@@ -516,6 +586,8 @@ bereq
Mostly useful as argument to VMODs.
+.. _bereq.backend:
+
bereq.backend
Type: BACKEND
@@ -532,6 +604,8 @@ bereq.backend
or backend, respectively.
+.. _bereq.between_bytes_timeout:
+
bereq.between_bytes_timeout
Type: DURATION
@@ -548,6 +622,8 @@ bereq.between_bytes_timeout
backend. Not available in pipe mode.
+.. _bereq.body:
+
bereq.body
Type: BODY
@@ -558,6 +634,8 @@ bereq.body
Unset will also remove ``bereq.http.Content-Length``.
+.. _bereq.connect_timeout:
+
bereq.connect_timeout
Type: DURATION
@@ -574,6 +652,8 @@ bereq.connect_timeout
established.
+.. _bereq.first_byte_timeout:
+
bereq.first_byte_timeout
Type: DURATION
@@ -590,6 +670,8 @@ bereq.first_byte_timeout
from the backend. Not available in pipe mode.
+.. _bereq.hash:
+
bereq.hash
Type: BLOB
@@ -599,6 +681,8 @@ bereq.hash
The hash key of this request, a copy of ``req.hash``.
+.. _bereq.http:
+
bereq.http.*
Type: HEADER
@@ -614,6 +698,8 @@ bereq.http.*
See ``req.http.*`` for general notes.
+.. _bereq.is_bgfetch:
+
bereq.is_bgfetch
Type: BOOL
@@ -625,6 +711,8 @@ bereq.is_bgfetch
a fresh copy.
+.. _bereq.is_hitmiss:
+
bereq.is_hitmiss
Type: BOOL
@@ -634,6 +722,8 @@ bereq.is_hitmiss
If this backend request was caused by a hitmiss.
+.. _bereq.is_hitpass:
+
bereq.is_hitpass
Type: BOOL
@@ -643,6 +733,8 @@ bereq.is_hitpass
If this backend request was caused by a hitpass.
+.. _bereq.method:
+
bereq.method
Type: STRING
@@ -667,6 +759,8 @@ bereq.proto ``VCL <= 4.0``
The HTTP protocol version, "HTTP/1.1" unless a pass or pipe
request has "HTTP/1.0" in ``req.proto``
+.. _bereq.proto:
+
bereq.proto ``VCL >= 4.1``
Type: STRING
@@ -677,6 +771,8 @@ bereq.proto ``VCL >= 4.1``
request has "HTTP/1.0" in ``req.proto``
+.. _bereq.retries:
+
bereq.retries
Type: INT
@@ -686,6 +782,8 @@ bereq.retries
A count of how many times this request has been retried.
+.. _bereq.time:
+
bereq.time
Type: TIME
@@ -696,6 +794,8 @@ bereq.time
remains constant across retries.
+.. _bereq.uncacheable:
+
bereq.uncacheable
Type: BOOL
@@ -707,6 +807,8 @@ bereq.uncacheable
`pass` in the client side or a hit on an hit-for-pass object.
+.. _bereq.url:
+
bereq.url
Type: STRING
@@ -718,6 +820,8 @@ bereq.url
The requested URL, copied from ``req.url``
+.. _bereq.xid:
+
bereq.xid
Type: INT
@@ -742,6 +846,8 @@ beresp
The entire backend response HTTP data structure, useful as
argument to VMOD functions.
+.. _beresp.age:
+
beresp.age
Type: DURATION
@@ -753,6 +859,8 @@ beresp.age
The age of the object.
+.. _beresp.backend:
+
beresp.backend
Type: BACKEND
@@ -774,6 +882,8 @@ beresp.backend.ip ``VCL <= 4.0``
IP of the backend this response was fetched from.
+.. _beresp.backend.name:
+
beresp.backend.name
Type: STRING
@@ -784,6 +894,8 @@ beresp.backend.name
Same as beresp.backend.
+.. _beresp.body:
+
beresp.body
Type: BODY
@@ -793,6 +905,8 @@ beresp.body
For producing a synthetic body.
+.. _beresp.do_esi:
+
beresp.do_esi
Type: BOOL
@@ -812,6 +926,8 @@ beresp.do_esi
It is a VCL error to use beresp.do_esi after setting beresp.filters.
+.. _beresp.do_gunzip:
+
beresp.do_gunzip
Type: BOOL
@@ -831,6 +947,8 @@ beresp.do_gunzip
It is a VCL error to use beresp.do_gunzip after setting beresp.filters.
+.. _beresp.do_gzip:
+
beresp.do_gzip
Type: BOOL
@@ -849,6 +967,8 @@ beresp.do_gzip
It is a VCL error to use beresp.do_gzip after setting beresp.filters.
+.. _beresp.do_stream:
+
beresp.do_stream
Type: BOOL
@@ -870,6 +990,8 @@ beresp.do_stream
the response body is empty.
+.. _beresp.filters:
+
beresp.filters
Type: STRING
@@ -930,6 +1052,8 @@ beresp.filters
``beresp.do_*`` switches is a VCL error.
+.. _beresp.grace:
+
beresp.grace
Type: DURATION
@@ -944,6 +1068,8 @@ beresp.grace
Set to a period to enable grace.
+.. _beresp.http:
+
beresp.http.*
Type: HEADER
@@ -959,6 +1085,8 @@ beresp.http.*
See ``req.http.*`` for general notes.
+.. _beresp.keep:
+
beresp.keep
Type: DURATION
@@ -989,6 +1117,8 @@ beresp.proto ``VCL <= 4.0``
The HTTP protocol version the backend replied with.
+.. _beresp.proto:
+
beresp.proto ``VCL >= 4.1``
Type: STRING
@@ -998,6 +1128,8 @@ beresp.proto ``VCL >= 4.1``
The HTTP protocol version the backend replied with.
+.. _beresp.reason:
+
beresp.reason
Type: STRING
@@ -1009,6 +1141,8 @@ beresp.reason
The HTTP status message returned by the server.
+.. _beresp.status:
+
beresp.status
Type: INT
@@ -1022,6 +1156,8 @@ beresp.status
More information in the `HTTP response status`_ section.
+.. _beresp.storage:
+
beresp.storage
Type: STEVEDORE
@@ -1049,6 +1185,8 @@ beresp.storage_hint ``VCL <= 4.0``
particular storage backend.
+.. _beresp.time:
+
beresp.time
Type: TIME
@@ -1059,6 +1197,8 @@ beresp.time
``vcl_backend_response {}`` was entered, or when
``vcl_backend_error {}`` was entered.
+.. _beresp.transit_buffer:
+
beresp.transit_buffer
Type: BYTES
@@ -1075,6 +1215,8 @@ beresp.transit_buffer
documentation in :ref:`varnishd(1)`.
+.. _beresp.ttl:
+
beresp.ttl
Type: DURATION
@@ -1090,6 +1232,8 @@ beresp.ttl
The object's remaining time to live, in seconds.
+.. _beresp.uncacheable:
+
beresp.uncacheable
Type: BOOL
@@ -1108,6 +1252,8 @@ beresp.uncacheable
"Ignoring attempt to reset beresp.uncacheable".
+.. _beresp.was_304:
+
beresp.was_304
Type: BOOL
@@ -1125,6 +1271,8 @@ obj
This is the object we found in cache. It cannot be modified.
+.. _obj.age:
+
obj.age
Type: DURATION
@@ -1134,6 +1282,8 @@ obj.age
The age of the object.
+.. _obj.can_esi:
+
obj.can_esi
Type: BOOL
@@ -1146,6 +1296,8 @@ obj.can_esi
processed.
+.. _obj.grace:
+
obj.grace
Type: DURATION
@@ -1155,6 +1307,8 @@ obj.grace
The object's grace period in seconds.
+.. _obj.hits:
+
obj.hits
Type: INT
@@ -1167,6 +1321,8 @@ obj.hits
In `vcl_deliver` a value of 0 indicates a cache miss.
+.. _obj.http:
+
obj.http.*
Type: HEADER
@@ -1178,6 +1334,8 @@ obj.http.*
See ``req.http.*`` for general notes.
+.. _obj.keep:
+
obj.keep
Type: DURATION
@@ -1187,6 +1345,8 @@ obj.keep
The object's keep period in seconds.
+.. _obj.proto:
+
obj.proto
Type: STRING
@@ -1196,6 +1356,8 @@ obj.proto
The HTTP protocol version stored in the object.
+.. _obj.reason:
+
obj.reason
Type: STRING
@@ -1206,6 +1368,8 @@ obj.reason
The HTTP reason phrase stored in the object.
+.. _obj.status:
+
obj.status
Type: INT
@@ -1218,6 +1382,8 @@ obj.status
More information in the `HTTP response status`_ section.
+.. _obj.storage:
+
obj.storage
Type: STEVEDORE
@@ -1227,6 +1393,8 @@ obj.storage
The storage backend where this object is stored.
+.. _obj.time:
+
obj.time
Type: TIME
@@ -1238,6 +1406,8 @@ obj.time
``now`` - ``obj.age``.
+.. _obj.ttl:
+
obj.ttl
Type: DURATION
@@ -1247,6 +1417,8 @@ obj.ttl
The object's remaining time to live, in seconds.
+.. _obj.uncacheable:
+
obj.uncacheable
Type: BOOL
@@ -1276,6 +1448,8 @@ resp
to VMODs.
+.. _resp.body:
+
resp.body
Type: BODY
@@ -1285,6 +1459,8 @@ resp.body
To produce a synthetic response body, for instance for errors.
+.. _resp.do_esi:
+
resp.do_esi ``VCL >= 4.1``
Type: BOOL
@@ -1302,6 +1478,8 @@ resp.do_esi ``VCL >= 4.1``
It is a VCL error to use resp.do_esi after setting resp.filters.
+.. _resp.filters:
+
resp.filters
Type: STRING
@@ -1322,6 +1500,8 @@ resp.filters
set.
+.. _resp.http:
+
resp.http.*
Type: HEADER
@@ -1337,6 +1517,8 @@ resp.http.*
See ``req.http.*`` for general notes.
+.. _resp.is_streaming:
+
resp.is_streaming
Type: BOOL
@@ -1358,6 +1540,8 @@ resp.proto ``VCL <= 4.0``
The HTTP protocol version to use for the response.
+.. _resp.proto:
+
resp.proto ``VCL >= 4.1``
Type: STRING
@@ -1367,6 +1551,8 @@ resp.proto ``VCL >= 4.1``
The HTTP protocol version to use for the response.
+.. _resp.reason:
+
resp.reason
Type: STRING
@@ -1378,6 +1564,8 @@ resp.reason
The HTTP status message that will be returned.
+.. _resp.status:
+
resp.status
Type: INT
@@ -1407,6 +1595,8 @@ resp.status
modified based on that comparison, a 304 is sent.
+.. _resp.time:
+
resp.time
Type: TIME
@@ -1420,6 +1610,8 @@ resp.time
Special variables
-----------------
+.. _now:
+
now
Type: TIME
@@ -1452,6 +1644,8 @@ transactions may take place. It may comprise the traffic over an
HTTP/1 keep-alive connection, or the multiplexed traffic over an
HTTP/2 connection.
+.. _sess.idle_send_timeout:
+
sess.idle_send_timeout
Type: DURATION
@@ -1465,6 +1659,8 @@ sess.idle_send_timeout
see :ref:`varnishd(1)`
+.. _sess.send_timeout:
+
sess.send_timeout
Type: DURATION
@@ -1477,6 +1673,8 @@ sess.send_timeout
``send_timeout`` parameter, see :ref:`varnishd(1)`
+.. _sess.timeout_idle:
+
sess.timeout_idle
Type: DURATION
@@ -1489,6 +1687,8 @@ sess.timeout_idle
``timeout_idle`` parameter, see :ref:`varnishd(1)`
+.. _sess.timeout_linger:
+
sess.timeout_linger
Type: DURATION
@@ -1501,6 +1701,8 @@ sess.timeout_linger
``timeout_linger`` parameter, see :ref:`varnishd(1)`
+.. _sess.xid:
+
sess.xid ``VCL >= 4.1``
Type: INT
@@ -1513,6 +1715,8 @@ sess.xid ``VCL >= 4.1``
storage
-------
+.. _storage.free_space:
+
storage.<name>.free_space
Type: BYTES
@@ -1524,6 +1728,8 @@ storage.<name>.free_space
the malloc stevedore.
+.. _storage.happy:
+
storage.<name>.happy
Type: BOOL
@@ -1535,6 +1741,8 @@ storage.<name>.happy
current stevedores.
+.. _storage.used_space:
+
storage.<name>.used_space
Type: BYTES
More information about the varnish-commit
mailing list