[master] 04455d6c3 doc: Release notes cross references and improvements
Dridi Boukelmoune
dridi.boukelmoune at gmail.com
Tue Sep 14 09:56:07 UTC 2021
commit 04455d6c3d8b2d810007239cb1cb2b740d7ec8ab
Author: Dridi Boukelmoune <dridi.boukelmoune at gmail.com>
Date: Tue Sep 14 11:53:30 2021 +0200
doc: Release notes cross references and improvements
diff --git a/bin/varnishtest/vtc_barrier.c b/bin/varnishtest/vtc_barrier.c
index 05b3ef9e9..9b1f6a026 100644
--- a/bin/varnishtest/vtc_barrier.c
+++ b/bin/varnishtest/vtc_barrier.c
@@ -430,9 +430,9 @@ barrier_sync(struct barrier *b, struct vtclog *vl)
*
* If you wish to synchronize the VCL, you need to declare a "sock" barrier.
* This will emit a macro definition named "bNAME_sock" that you can use in
- * VCL (after importing the debug vmod)::
+ * VCL (after importing the vtc vmod)::
*
- * debug.barrier_sync("${bNAME_sock}");
+ * vtc.barrier_sync("${bNAME_sock}");
*
* This function returns 0 if everything went well and is the equivalent of
* ``barrier bNAME sync`` at the VTC top-level.
diff --git a/bin/varnishtest/vtc_misc.c b/bin/varnishtest/vtc_misc.c
index 9efe6fd5a..ac5f6df96 100644
--- a/bin/varnishtest/vtc_misc.c
+++ b/bin/varnishtest/vtc_misc.c
@@ -321,7 +321,6 @@ cmd_setenv(CMD_ARGS)
*
* Sleep for the number of seconds specified in the argument. The number
* can include a fractional part, e.g. 1.5.
- *
*/
void
cmd_delay(CMD_ARGS)
@@ -454,7 +453,7 @@ addr_no_randomize_works(void)
* Varnish was built with its workspace emulator.
*
* A feature name can be prefixed with an exclamation mark (!) to skip a
- * test if a feature is present.
+ * test if the feature is present.
*
* Be careful with ignore_unknown_macro, because it may cause a test with a
* misspelled macro to fail silently. You should only need it if you must
diff --git a/doc/sphinx/reference/varnishncsa.rst b/doc/sphinx/reference/varnishncsa.rst
index 51b9316ab..863856505 100644
--- a/doc/sphinx/reference/varnishncsa.rst
+++ b/doc/sphinx/reference/varnishncsa.rst
@@ -68,6 +68,8 @@ considers varnish to be the client.
It is possible to keep two varnishncsa instances running, one in
backend mode, and one in client mode, logging to different files.
+.. _ncsa-format:
+
FORMAT
======
diff --git a/doc/sphinx/reference/vcl.rst b/doc/sphinx/reference/vcl.rst
index 3513f0eb6..b309a737c 100644
--- a/doc/sphinx/reference/vcl.rst
+++ b/doc/sphinx/reference/vcl.rst
@@ -205,14 +205,19 @@ the flag within parens following a question mark, like this::
...
}
+.. _vcl-include:
Include statement
-----------------
-To include a VCL file in another file use the include keyword::
+To include a VCL file in another file use the ``include`` keyword::
include "foo.vcl";
+Optionally, the ``include`` keyword can take a ``+glob`` flag to include all
+files matching a glob pattern::
+
+ include +glob "example.org/*.vcl";
Import statement
----------------
@@ -248,6 +253,8 @@ Backends and health probes
Please see :ref:`vcl-backend(7)` and :ref:`vcl-probe(7)`
+.. _vcl-acl:
+
Access Control List (ACL)
-------------------------
diff --git a/doc/sphinx/reference/vtc.rst b/doc/sphinx/reference/vtc.rst
index cd74e6c70..13fd80295 100644
--- a/doc/sphinx/reference/vtc.rst
+++ b/doc/sphinx/reference/vtc.rst
@@ -57,6 +57,8 @@ being the command and the following ones being its arguments. To continue over
to a new line without breaking the argument string, you can escape the newline
character (\\n) with a backslash (\\).
+.. _vtc-macros:
+
MACROS
======
diff --git a/doc/sphinx/whats-new/changes-trunk.rst b/doc/sphinx/whats-new/changes-trunk.rst
index 0ccb84325..66aec6c01 100644
--- a/doc/sphinx/whats-new/changes-trunk.rst
+++ b/doc/sphinx/whats-new/changes-trunk.rst
@@ -44,6 +44,7 @@ which culminated with the publication of `RFC 8941 Structured Fields`_.
The syntax in Structured Fields is distilled from current standardized headers,
which means that the vast majority of existing HTTP headers are already
covered.
+
There are unfortunate exceptions, most notably the Cookie headers.
Starting with this release, we are gently migrating VCL towards the
@@ -54,6 +55,11 @@ by using the RFC 8941 syntax of::
':' + <base64> + ':'
+For example, the VCL string ``"helloworld"`` can be represented as the BLOB
+literal ``:aGVsbG93b3JsZA==:`` without involving a VMOD.
+
+See :ref:`vmod_blob(3)`.
+
The second and likely more significant change is numbers in VCL
now conform to RFC8941 as well: Up to 15 digits and at most 3
decimal places, and "scientific notation" is no longer allowed.
@@ -61,7 +67,7 @@ decimal places, and "scientific notation" is no longer allowed.
(These restrictions were chosen after much careful deliberation, to
ensure that no overflows would occur, even when HTTP headers are
processed in languages where numbers are represented by IEEE-754
-64 binary floating point variables,)
+64 binary floating point variables.)
.. _RFC 8941 Structured Fields: https://www.rfc-editor.org/rfc/rfc8941.html
@@ -163,12 +169,16 @@ For example::
acl <name> +log -pedantic { ... }
+See :ref:`vcl-acl`.
+
The ``include`` keyword supports a ``glob`` flag.
For example::
include +glob "example.org/*.vcl";
+See :ref:`vcl-include`.
+
See upgrade notes for more details.
VMODs
@@ -183,6 +193,8 @@ New ``BASE64CF`` encoding scheme in ``vmod_blob``. It is similar to
It is used by a certain CDN provider who also inspired the name.
+See the ``vmod_blob`` manual (:ref:`vmod_blob-base64`).
+
varnishlog
==========
@@ -191,9 +203,13 @@ fetched, ``Hit`` records contain progress of the fetch task. This should help
troubleshooting when cache hits appear to be slow, whether or not the backend
is still serving the response.
+See :ref:`vcl(7)`.
+
By default ``VCL_acl`` records are no longer emitted. They can be brought back
by adding a ``+log`` flag to the ACL declaration.
+See :ref:`vcl-acl`.
+
varnishncsa
===========
@@ -205,7 +221,7 @@ New ``%{...}t`` time formats:
- ``msec_frac``
- ``usec_frac``
-See the varnishncsa manual for more information.
+See the ``varnishncsa`` manual (:ref:`ncsa-format`) for more information.
varnishadm
==========
@@ -220,7 +236,7 @@ varnishtest
Test cases should be generally more reactive, whether it is detecting
a ``varnishd`` startup failure, waiting for ``varnishd`` to stop, or
-when fail tests and there are barriers waiting for a synchronization.
+when tests fail and there are barriers waiting for a synchronization.
Clients and servers can have up to 64 headers in requests and responses.
@@ -245,11 +261,15 @@ There are new feature checks:
The undocumented ``pcre_jit`` feature check is gone.
+See the VTC manual (:ref:`vtc-feature`) for more details.
+
There is a new ``tunnel`` command that acts as a proxy between two peers. A
tunnel can pause and control how much data goes in each direction, and can
be used to trigger socket timeouts, possibly in the middle of protocol frames,
without having to change how the peers are implemented.
+See the VTC manual (:ref:`vtc-tunnel`) for more details.
+
There is a new dynamic macro ``${string,repeat,<uint>,<string>}`` to avoid
very long lines or potential mistakes when maintained by hand. For example,
the two following strings are equivalent::
@@ -257,6 +277,8 @@ the two following strings are equivalent::
"AAA"
"${string,repeat,3,A}"
+See the VTC manual (:ref:`vtc-macros`) for more details.
+
There were also various improvements to HTTP/2 testing, and more should be
expected.
@@ -289,7 +311,4 @@ The deprecated functions ``VSB_new()`` and ``VSB_delete()`` were removed.
See upgrade notes for more information.
-**XXX changes concerning VRT, the public APIs, source code organization,
-builds etc.**
-
*eof*
diff --git a/doc/sphinx/whats-new/upgrading-trunk.rst b/doc/sphinx/whats-new/upgrading-trunk.rst
index a96a10b20..a6b127ee8 100644
--- a/doc/sphinx/whats-new/upgrading-trunk.rst
+++ b/doc/sphinx/whats-new/upgrading-trunk.rst
@@ -30,11 +30,16 @@ The new ``varnishd`` parameter ``pcre2_jit_compilation`` controls whether
jit compilation should be attempted and has no effect if jit support was
disabled at configure time.
+See :ref:`ref_param_pcre2_jit_compilation`.
+
The former parameters ``pcre_match_limit`` and ``pcre_match_limit_recursion``
were renamed to ``pcre2_match_limit`` and ``pcre2_depth_limit``. With older
PCRE2 libraries, it is possible to see the depth limit being referred to as
recursion limit in error messages.
+See :ref:`ref_param_pcre2_depth_limit` and :ref:`ref_param_pcre2_depth_limit`
+for more information.
+
The syntax of regular expression should be the same, but it is possible to
run into subtle differences. We are aware one such difference, PCRE2 fails
the compilation of unknown escape sequences. For example PCRE interprets
@@ -160,6 +165,8 @@ ACLs are optimized for runtime performance by default, which can increase
significantly the VCL compilation time with very large ACLs. The ``table``
flag improves compilation time at the expense of runtime performance.
+See :ref:`vcl-acl`.
+
Changes for developers
======================
diff --git a/vmod/vmod_blob.vcc b/vmod/vmod_blob.vcc
index b3644c66c..b6256eeac 100644
--- a/vmod/vmod_blob.vcc
+++ b/vmod/vmod_blob.vcc
@@ -122,6 +122,8 @@ also be written as::
The *case* ENUM MUST be set to ``DEFAULT`` for ``IDENTITY`` encodings.
+.. _vmod_blob-base64:
+
BASE64*
~~~~~~~
More information about the varnish-commit
mailing list