doc: Release notes cross references and improvements

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.

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

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
 ======
 

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)
 -------------------------
 

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
 ======
 

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*

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
 ======================
 

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*
 ~~~~~~~