Log a notice message when delaying a conditional fetch and the stale
template object is still streaming.

This VSL tag will be used for informational messages related to
exceptional handling of requests.

Wait for the stale object to become fully fetched, so that we can catch
fetch errors, before we unbusy the new object. This serves two
purposes. First it helps with request coalescing, and stops long chains of
IMS-updated short-TTL objects all streaming from a single slow body
fetch. Second it makes sure that all the object attributes are complete
when we copy them (this would be an issue for ie OA_GZIPBITS).

This patch OBE's r01646.vtc, and slightly patches r01648.vtc to expect a
503 instead of a 200 and a broken connection on the failing client.

Fixes: #3089

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.

as promised in #3161

Notice: The boolean expression does not lack parantheses, the test for
generate.py is only to be and'ed with the test for .git

Fixes #3165

Before:

    ...called from "foo"
    ('<vcl.inline>' Line 5 Pos 27)
            sub bar { call foo; }
    --------------------------#--

After:

    ...called from "bar"
    ('<vcl.inline>' Line 5 Pos 24)
            sub bar { call foo; }
    -----------------------###---

This fixes the "called from" part of the message to refer to the caller
instead of the callee, and underlines the symbol token instead of the
semi-colon.

We had two places where we documented common actions, and one of them
was outdated.

...even after ~11 years of experience with varnish.

today: return without an action from a custom subroutine.

it is not before we have parsed parameters

Fixes #3160

Spotted via vtest: l1 timed out despite varnishd logging what was
expected next. This is tightening l1's expectation in the hope that
r2339 will no longer flake.

I wasn't able to reproduce this even on my vtest box where it failed.

we already check for unused subs in vcc_checkref()

Fixes #3159

$ nslookup dns-canary.freebsd.dk

Non-authoritative answer:
*** Can't find dns-canary.freebsd.dk: No answer

if anyone has a more reliable server to test, please just change it
again.

Ref #2575

Under stress we might otherwise check n_objectcore before it gets a
chance to decrease completely.

Spotted via vtest.

This test was failing before silently: It seems these vtest machines do
not resolve localhost to the address passed as the localhost define to
vtest, so use the latter in order to stabilize.

I should have included the netnotation right away

Every time I read this code I fail to remember which symbol is which, so
from now on the instance symbol will be called isym, the object symbol
osym and the method symbols msym.

They fit within 80 columns.

Instead, the comma is emitted when there is indeed an extra argument.

This change was initially submitted in #3147 and is needed when the
extra argument may vary for a given symbol. More specifically, when
a method symbol may be shared by several instance symbols, it becomes
really difficult to find a spot where that extra comma might be added.

Removing it from the extra argument itself makes this easier once we
reach the point where method symbols are unique (per object) instead
of repeated (per instance).

At the end of the VGC we output the contents of the symbol table inside
a C comment. It might look like this:

    /*
     * Symbol Table
     *
     * reserved  VOID       41 41 acl
     * reserved  VOID       41 41 backend
     * action    VOID       40 41 ban
     * var       HTTP        0 99 bereq
     * var       BACKEND     0 99 bereq.backend
     * [...]
     */

All columns are currently aligned because we know all the native VCL
types and only the last column with the symbol names has unpredictable
and arbitrary entries lengths.

However, considering the following snippet:

    new fb = directors.fallback();

The involved symbols will look like:

    object    VOID      41 41 directors.fallback
    instance  INSTANCE  41 41 fb
    func      VOID      40 41 fb.add_backend
    func      BACKEND   40 41 fb.backend
    func      VOID      40 41 fb.remove_backend

In the future VMOD objects will likely grow their own types and for the
same snippet we may have this instead:

    object    directors.fallback  41 41 directors.fallback
    method    VOID                40 41 directors.fallback.add_backend
    method    BACKEND             40 41 directors.fallback.backend
    method    VOID                40 41 directors.fallback.remove_backend
    instance  directors.fallback  41 41 fb

This change was initially submitted as part of #3147, but was considered
trivial and fast-track-able by PHK.