Avoid loose vocabulary around VCL sub

The code base and documentation refer to ``sub`` symbols as:

- subroutines
- functions
- methods
- procedures
- callbacks

This change focuses on always referring to them as subroutines in the
documentation. During this documentation sweep, there were a lot of
false positives since VCL, VMODs and HTTP also share that vocabulary
and I may have missed false negatives, especially for generated bits
of documentation.

Some parts of the documentation were not touched on purpose: upgrade
notes and changelogs of past releases, PHK random outbursts, etc.

Now that the documentation is hopefully taken care of the same needs
to happen in the code base, starting with user-facing error messages
and then data structures names, function names etc.

There will be however one exception. Anything referring to the scope
of a subroutine, but being worded as if it referred to the subroutine
itself will use scope instead.

As this will touch a lot of code, it will be done incrementally, much
like this change focused on non-generated documentation (and VCC files
don't count as generated in this context).

I also fixed RST formatting issues I noticed during my sweep.

Better diff with the --word-diff --ignore-all-space options.

doc/changes.rst

@@ -36,7 +36,7 @@ NEXT (2020-03-15)
   `libexecinfo` implementation that crashes when called by Varnish, this
   offers the alternative of using `libunwind` instead.
 
-* backend ``none`` was added for "no backend"
+* backend ``none`` was added for "no backend".
 
 * Log records can safely have empty fields or fields containing blanks if
   they are delimited by "double quotes". This was applied to ``SessError``
@@ -46,11 +46,11 @@ NEXT (2020-03-15)
   ``varnishtest -p debug=+witness``.
 
 * The ``Process`` timestamp for ``vcl_synth {}`` was wrongly issued
-  before the VCL callback, now it gets emitted after VCL returns for
-  consistency with ``vcl_deliver {}``
+  before the VCL subroutine, now it gets emitted after VCL returns for
+  consistency with ``vcl_deliver {}``.
 
 * The ``if-range`` header is now handled, allowing clients to conditionally
-  request a range based on a date or an ETag
+  request a range based on a date or an ETag.
 
 ================================
 Varnish Cache 6.3.0 (2019-09-15)

doc/sphinx/reference/index.rst

@@ -53,7 +53,7 @@ The Varnish Reference Manual
 	. - start
 	. - ...
 	VCL language
-	. The functions:
+	. The subroutines:
 	. - vcl_recv
 	. - vcl_miss
 	. ---

doc/sphinx/reference/vcl.rst

@@ -111,8 +111,8 @@ In string context they return a formatted string in RFC1123 format,
 e.g. ``Sun, 06 Nov 1994 08:49:37 GMT``.
 
 The keyword ``now`` returns a notion of the current time, which is
-kept consistent during vcl subroutine invocations, so during the
-execution of a vcl subroutine callback (``vcl_* {}``), including all
+kept consistent during VCL subroutine invocations, so during the
+execution of a VCL state subroutine (``vcl_* {}``), including all
 user-defined subroutines being called, ``now`` always returns the
 same value.
 

doc/sphinx/reference/vcl_var.rst

@@ -24,8 +24,8 @@ possible, is done with a `unset` statement::
 
 Which operations are possible on each variable is described below,
 often with the shorthand "backend" which covers the `vcl_backend_*`
-methods and "client" which covers the rest, except `vcl_init` and
-`vcl_fini`.
+subroutines and "client" which covers the rest, except `vcl_init`
+and `vcl_fini`.
 
 When setting a variable, the right hand side of the equal sign
 must have the variables type, you cannot assign a STRING to

doc/sphinx/reference/vsl.rst

@@ -36,7 +36,7 @@ spent since the last timestamp was logged.
 The timestamps logged automatically by Varnish are inserted after
 completing events that are expected to have delays (e.g. network IO or
 spending time on a waitinglist). Timestamps can also be inserted from
-VCL using the std.timestamp() method. If one is doing time consuming
+VCL using the std.timestamp() function. If one is doing time consuming
 tasks in the VCL configuration, it's a good idea to log a timestamp
 after completing that task. This keeps the timing information in
 subsequent timestamps from including the time spent on the VCL event.

doc/sphinx/users-guide/performance.rst

@@ -6,12 +6,13 @@ Varnish and Website Performance
 This section focuses on how to tune the performance of your Varnish server,
 and how to tune the performance of your website using Varnish.
 
-The section is split in three subsections. The first subsection deals with the various tools and
-functions of Varnish that you should be aware of. The next subsection focuses
-on the how to purge content out of your cache. Purging of content is
-essential in a performance context because it allows you to extend the
-*time-to-live* (TTL) of your cached objects. Having a long TTL allows
-Varnish to keep the content in cache longer, meaning Varnish will make fewer requests to your relatively slower backend.
+The section is split in three subsections. The first subsection deals with the
+various tools and functions of Varnish that you should be aware of. The next
+subsection focuses on the how to purge content out of your cache. Purging of
+content is essential in a performance context because it allows you to extend
+the *time-to-live* (TTL) of your cached objects. Having a long TTL allows
+Varnish to keep the content in cache longer, meaning Varnish will make fewer
+requests to your relatively slower backend.
 
 The final subsection deals with compression of web content. Varnish can
 gzip content when fetching it from the backend and then deliver it

doc/sphinx/users-guide/purging.rst

@@ -23,9 +23,9 @@ through HTTP with the method `PURGE`.
 
 An HTTP purge is similar to an HTTP GET request, except that the
 *method* is `PURGE`. Actually you can call the method whatever you'd
-like, but most people refer to this as purging. Squid, for example, supports the
-same mechanism. In order to support purging in Varnish you need the
-following VCL in place::
+like, but most people refer to this as purging. Squid, for example,
+supports the same mechanism. In order to support purging in Varnish
+you need the following VCL in place::
 
   acl purge {
 	  "localhost";

doc/sphinx/users-guide/vcl-built-in-subs.rst

@@ -9,7 +9,7 @@ and backend requests as well as upon ``vcl.load`` and ``vcl.discard``.
 See :ref:`reference-states` for a detailed graphical overview of the
 states and how they relate to core code functions and VCL subroutines.
 
-Built-in subroutines always terminate with a ``return(<action>)``,
+Built-in subroutines always terminate with a ``return (<action>)``,
 where ``<action>`` determines how processing continues in the request
 processing state machine.
 

lib/libvmod_blob/vmod.vcc

@@ -381,7 +381,7 @@ If any of the VMOD's methods, functions or constructor fail, then VCL
 failure is invoked, just as if ``return(fail)`` had been called in the
 VCL source. This means that:
 
-* If the ``blob.blob()`_ object constructor fails, or if any methods or
+* If the `blob.blob()`_ object constructor fails, or if any methods or
   functions fail during ``vcl_init{}``, then the VCL program will fail
   to load, and the VCC compiler will emit an error message.
 

lib/libvmod_std/vmod.vcc

@@ -449,9 +449,9 @@ This will send a message to syslog using ``LOG_USER | LOG_ALERT``.
 $Function VOID timestamp(STRING s)
 
 Introduces a timestamp in the log with the current time, using the
-string *s* as the label. This is useful to time the execution of
-lengthy VCL procedures, and makes the timestamps inserted
-automatically by Varnish more accurate.
+string *s* as the label. This is useful to time the execution of lengthy
+VCL subroutines, and makes the timestamps inserted automatically by
+Varnish more accurate.
 
 Example::