Various improvements from my personal git stash

More to come soonish.

doc/sphinx/reference/varnish-cli.rst

@@ -52,7 +52,7 @@ Syntax
 ------
 
 Commands are usually terminated with a newline. Long command can be
-entered using shell style *here document* (here-document or heredoc).
+entered using shell-style *here document* (here-document or heredoc).
 The format of here document is::
 
    << word
@@ -85,9 +85,8 @@ Backend Pattern
 
 A backend pattern can be a backend name or a combination of a VCL name
 and backend name in "VCL.backend" format.  If the VCL name is omitted,
-the active VCL is assumed.  Partial matching on the backend name, VCL
-name or both is possible using shell-style wilcards, i.e. asterisk (*),
-question mark (?) and brackets ([]).
+the active VCL is assumed.  Partial matching on the backend and VCL
+names is supported using shell-style wilcards, e.g. asterisk (*).
 
 Examples::
 
@@ -122,20 +121,22 @@ fields.
 VCL Temperature
 ---------------
 
-A VCL program goes through several states related to the different commands: it
-can be loaded, used, and later discarded. You can load several VCL programs and
-switch at any time from one to another. There is only one active VCL, but the
-previous active VCL will be maintained active until all its transactions are
-over.
-
-Over time, if you often refresh your VCL and keep the previous versions around,
-resource consumption will increase, you can't escape that. However, most of the
-time you want only one to pay the price only for the active VCL and keep older
-VCLs in case you'd need to rollback to a previous version.
-
-The VCL temperature allows you to minimize the footprint of inactive VCLs. Once
-a VCL becomes cold, Varnish will release all the resources that can be be later
-reacquired. You can manually set the temperature of a VCL or let varnish
+A VCL program goes through several states related to the different
+commands: it can be loaded, used, and later discarded. You can load
+several VCL programs and switch at any time from one to another. There
+is only one active VCL, but the previous active VCL will be maintained
+active until all its transactions are over.
+
+Over time, if you often refresh your VCL and keep the previous
+versions around, resource consumption will increase, you can't escape
+that. However, most of the time you want only one to pay the price only
+for the active VCL and keep older VCLs in case you'd need to rollback
+to a previous version.
+
+The VCL temperature allows you to minimize the footprint of inactive
+VCLs. Once a VCL becomes cold, Varnish will release all the resources
+that can be be later reacquired. You can manually set the temperature
+of a VCL or let varnish
 automatically handle it.
 
 
@@ -236,7 +237,7 @@ secret file, and the challenge string.
 EXAMPLES
 ========
 
-Load a multi-line VCL using shell style *here document*::
+Load a multi-line VCL using shell-style *here document*::
 
     vcl.inline example << EOF
     vcl 4.0;
@@ -260,9 +261,9 @@ backend contains "USERID=1663"::
 AUTHORS
 =======
 
-This manual page was originally written by Per Buer and later modified by
-Federico G. Schwindt, Dridi Boukelmoune, Lasse Karstensen and Poul-Henning
-Kamp.
+This manual page was originally written by Per Buer and later modified
+by Federico G. Schwindt, Dridi Boukelmoune, Lasse Karstensen and
+Poul-Henning Kamp.
 
 SEE ALSO
 ========

doc/sphinx/reference/varnishtest.rst

@@ -109,21 +109,22 @@ An example::
                 expect resp.bodylen == 21
         } -run
 
-When run, the above script will simulate a server (s1) that expects two
-different requests. It will start a Varnish server (v1) and add the backend
-definition to the VCL specified (-vcl+backend). Finally it starts the
-c1-client, which is a single client sending two requests.
+When run, the above script will simulate a server (s1) that expects
+two different requests. It will start a Varnish server (v1) and add the
+backend definition to the VCL specified (-vcl+backend). Finally it starts
+the c1-client, which is a single client sending two requests.
 
 TESTING A BUILD TREE
 ====================
 
-Whether you are building a VMOD or trying to use one that you freshly built,
-you can tell ``varnishtest`` to pass a *vmod_path* to ``varnishd`` instances
-started using the ``varnish -start`` command in your test case::
+Whether you are building a VMOD or trying to use one that you freshly
+built, you can tell ``varnishtest`` to pass a *vmod_path* to ``varnishd``
+instances started using the ``varnish -start`` command in your test case::
 
     varnishtest -p vmod_path=... /path/to/*.vtc
 
-This way you can use the same test cases on both installed and built VMODs::
+This way you can use the same test cases on both installed and built
+VMODs::
 
     server s1 {...} -start
 
@@ -135,30 +136,31 @@ This way you can use the same test cases on both installed and built VMODs::
 
     ...
 
-You are not limited to the *vmod_path* and can pass any parameter, allowing
-you to run a build matrix without changing the test suite. You can achieve the
-same with macros, but then they need to be defined on each run.
+You are not limited to the *vmod_path* and can pass any parameter,
+allowing you to run a build matrix without changing the test suite. You
+can achieve the same with macros, but then they need to be defined on
+each run.
 
-You can see the actual ``varnishd`` command lines in test outputs, they look
-roughly like this::
+You can see the actual ``varnishd`` command lines in test outputs,
+they look roughly like this::
 
     exec varnishd [varnishtest -p params] [testing params] [vtc -arg params]
 
-Parameters you define with ``varnishtest -p`` may be overriden by parameters
-needed by ``varnishtest`` to run properly, and they may in turn be overriden
-by parameters set in test scripts.
+Parameters you define with ``varnishtest -p`` may be overriden by
+parameters needed by ``varnishtest`` to run properly, and they may in
+turn be overriden by parameters set in test scripts.
 
-There's also a special mode in which ``varnishtest`` builds itself a PATH and
-a *vmod_path* in order to find Varnish binaries (programs and VMODs) in the
-build tree surrounding the ``varnishtest`` binary. This is meant for testing
-of Varnish under development and will disregard your *vmod_path* if you set
-one.
+There's also a special mode in which ``varnishtest`` builds itself a
+PATH and a *vmod_path* in order to find Varnish binaries (programs and
+VMODs) in the build tree surrounding the ``varnishtest`` binary. This
+is meant for testing of Varnish under development and will disregard
+your *vmod_path* if you set one.
 
-If you need to test your VMOD against a Varnish build tree, you must install
-it first, in a temp directory for instance. With information provided by the
-installation's *pkg-config(1)* you can build a proper PATH in order to access
-Varnish programs, and a *vmod_path* to access both your VMOD and the built-in
-VMODs::
+If you need to test your VMOD against a Varnish build tree, you must
+install it first, in a temp directory for instance. With information
+provided by the installation's *pkg-config(1)* you can build a proper
+PATH in order to access Varnish programs, and a *vmod_path* to access
+both your VMOD and the built-in VMODs::
 
     export PKG_CONFIG_PATH=/path/to/install/lib/pkgconfig
 
@@ -187,8 +189,9 @@ responses. Accepted parameters:
 client
 ******
 
-Creates a client instance that sends requests to Varnish and receives responses.
-By default, a client will try and connect to the first varnish server available.
+Creates a client instance that sends requests to Varnish and receives
+responses.  By default, a client will try and connect to the first
+varnish server available.
 
 Accepted parameters:
 
@@ -223,11 +226,11 @@ Starts Varnish instance. Accepted arguments:
  executes a command and expect it to error with given status
  (e.g. "-clierr 300 panic.clear")
 \-vcl STRING
- specify VCL for the instance. You can create multiline strings by encasing them
- in curly braces.
+ specify VCL for the instance. You can create multiline strings by
+ encasing them in curly braces.
 \-vcl+backend STRING
- specifes VCL for the instance, and automatically inject backends definition
- of currently defined servers.
+ specifes VCL for the instance, and automatically inject backends
+ definition of currently defined servers.
 \-errvcl
  tests that invalid VCL results in an error.
 \-stop
@@ -242,67 +245,79 @@ Starts Varnish instance. Accepted arguments:
  sets up a test for asserting variables against expected results.
  Syntax: "-expect <var> <comparison> <const>"
 
-See tests supplied with Varnish distribution for usage examples for all these
-directives.
+See tests supplied with Varnish distribution for usage examples for all
+these directives.
 
 delay
 *****
-Sleeps for specified number of seconds. Can accept floating point numbers.
+
+Sleeps for specified number of seconds.
 
 Usage: ``delay FLOAT``
 
 varnishtest
 ***********
 
-Accepts a string as an only argument. This being a test name that is being output
-into the log. By default, test name is not shown, unless it fails.
+Accepts a string as an only argument. This being a test name that is being
+output into the log. By default, test name is not shown, unless it fails.
 
 shell
 *****
 
-Executes a shell command. Accepts one argument as a string, and runs the command
-as is.
+Executes a shell command. Accepts one argument as a string, and runs
+the command as is.
 
 Usage: ``shell "CMD"``
 
-sema
-****
+err_shell
+*********
 
-Semaphores mostly used to synchronize clients and servers "around"
-varnish, so that the server will not send something particular
-until the client tells it to, but it can also be used synchronize
-multiple clients or servers running in parallel.
+Usage: ``err_shell "STRING" "CMD"``
 
-Usage: ``sema NAME sync INT``
+barrier
+*******
 
-NAME is of the form 'rX', X being a positive integer. This command blocks until,
-in total, INT semaphores named NAME block.
+Usage: ``barrier NAME [arguments]``
 
 random
 ******
 
-Initializes random generator (need to call std.random() in vcl). See m00002.vtc
-for more info
+Initializes random generator (need to call std.random() in vcl). See
+m00002.vtc for more info.
 
 feature
 *******
 
-Checks for features to be present in the test environment. If feature is not present, test is skipped.
+Checks for features to be present in the test environment. If feature
+is not present, test is skipped.
 
 Usage: ``feature STRING [STRING...]``
 
 Possible checks:
 
 SO_RCVTIMEO_WORKS
- runs the test only if SO_RCVTIMEO option works in the environment
+ The SO_RCVTIMEO socket option is working
 64bit
- runs the test only if environment is 64 bit
+ The environment is 64 bits
 !OSX
- skips the test if ran on OSX
+ The environment is not OSX
+dns
+ DNS lookups are working
 topbuild
- varnishtest has been started with '-i' and set the ${topbuild} macro.
+ varnishtest has been started with '-i'
+root
+ varnishtest has been invoked by the root user
+user_varnish
+ The varnish user is present
+user_vcache
+ The vcache user is present
+group_varnish
+ The varnish group is present
+
 logexpect
- This allows checking order and contents of VSL records in varnishtest.
+*********
+
+This allows checking order and contents of VSL records in varnishtest.
 
 SEE ALSO
 ========
@@ -319,10 +334,9 @@ HISTORY
 =======
 
 The varnishtest program was developed by Poul-Henning Kamp
-<phk@phk.freebsd.dk> in cooperation with Varnish Software AS.
-This manual page was originally written by Stig Sandbeck Mathisen
-<ssm@linpro.no> and updated by Kristian Lyngstøl
-<kristian@varnish-cache.org>.
+<phk@phk.freebsd.dk> in cooperation with Varnish Software AS.  This manual
+page was originally written by Stig Sandbeck Mathisen <ssm@linpro.no>
+and updated by Kristian Lyngstøl <kristian@varnish-cache.org>.
 
 
 COPYRIGHT