[4.0] 2d1a8c1 Assorted minor documentation fixes
Lasse Karstensen
lkarsten at varnish-software.com
Thu Mar 13 10:24:26 CET 2014
commit 2d1a8c11ea88e3fc394ba160183282ddbdcbd672
Author: Lasse Karstensen <lkarsten at varnish-software.com>
Date: Mon Feb 24 16:14:38 2014 +0100
Assorted minor documentation fixes
diff --git a/doc/sphinx/installation/bugs.rst b/doc/sphinx/installation/bugs.rst
index b1cb06a..16f0c51 100644
--- a/doc/sphinx/installation/bugs.rst
+++ b/doc/sphinx/installation/bugs.rst
@@ -28,7 +28,7 @@ Varnish crashes
Plain and simple: **boom**
Varnish is split over two processes, the manager and the child. The child
-does all the work, and the manager hangs around to resurect it, if it
+does all the work, and the manager hangs around to resurect it if it
crashes.
Therefore, the first thing to do if you see a Varnish crash, is to examine
@@ -77,9 +77,10 @@ general forms:
(yet) written the padded-box error handling code for.
The most likely cause here, is that you need a larger workspace
- for HTTP headers and Cookies. (XXX: which params to tweak)
+ for HTTP headers and Cookies.
Please try that before reporting a bug.
+.. (TODO: which params to tweak)
"Assert error in ..."
This is something bad that should never happen, and a bug
diff --git a/doc/sphinx/installation/help.rst b/doc/sphinx/installation/help.rst
index 5e62e77..4fb8362 100644
--- a/doc/sphinx/installation/help.rst
+++ b/doc/sphinx/installation/help.rst
@@ -33,23 +33,24 @@ families and jobs to deal with also.
You are more than welcome to just hang out, and while we don't mind
the occational intrusion of the real world into the flow, keep
-it mostly on topic, and dont paste random links unless they are
+it mostly on topic, and don't paste random links unless they are
*really* spectacular and intelligent.
Mailing Lists
=============
-Getting on or off our mailinglist happens through MailMan_.
+Getting on or off our mailing lists happens through MailMan_.
If you are going to use Varnish, subscribing to our ``varnish-announce``
-mailing list is probably a very good idea. The typical pattern is that
+mailing list is probably a very good idea. The typical pattern is that
people spend some time getting Varnish running, and then more or less
-forget about it. Therefore the announce list is a good way to be
+forget about it. Therefore the announce list is a good way to be
reminded about new releases, bad bugs or security holes.
+
The ``varnish-misc`` mailing list is for general banter, questions,
suggestions, ideas and so on. If you are new to Varnish it may pay
-off to subscribe to -misc, simply to have an ear to the telegraph-pole
+off to subscribe to it, simply to have an ear to the telegraph-pole
and learn some smart tricks. This is a good place to ask for help
with more complex issues, that require quoting of files and long
explanations.
@@ -59,6 +60,7 @@ thread changes, please change the subject to match, some of us deal
with hundreds of emails per day, after spam-filters, and we need all
the help we can get to pick the interesting ones.
+
The ``varnish-dev`` mailing list is used by the developers and is
usually quite focused on source-code and such. Everybody on
the -dev list is also on -misc, so cross-posting only serves to annoy
diff --git a/doc/sphinx/installation/index.rst b/doc/sphinx/installation/index.rst
index b1e0a23..60d43e0 100644
--- a/doc/sphinx/installation/index.rst
+++ b/doc/sphinx/installation/index.rst
@@ -5,7 +5,7 @@ Varnish Installation
%%%%%%%%%%%%%%%%%%%%
This document explains how to get Varnish onto your system, where
-to get help, how report bugs etc. In other words, it is a manual
+to get help, how report bugs and so on. In other words, it is a manual
about pretty much everything else than actually using Varnish to
move traffic.
diff --git a/doc/sphinx/installation/install.rst b/doc/sphinx/installation/install.rst
index ef31f86..45c5e4e 100644
--- a/doc/sphinx/installation/install.rst
+++ b/doc/sphinx/installation/install.rst
@@ -13,7 +13,7 @@ are most comfortable with.
Source or packages?
-------------------
-Installing Varnish on most relevant operating systems can usually
+Installing Varnish on most relevant operating systems can usually
be done with with the systems package manager, typical examples
being:
@@ -36,8 +36,9 @@ on `repo.varnish-cache.org <http://repo.varnish-cache.org/>`_. See the
Varnish is included in the `EPEL
<http://fedoraproject.org/wiki/EPEL>`_ repository, however due to
incompatible syntax changes in newer versions of Varnish, only older
-versions are available. We recommend that you install the latest
-version from our repository.
+versions are available.
+
+We recommend that you install the latest version from our repository.
Debian/Ubuntu
-------------
@@ -69,7 +70,7 @@ git repository by doing.
Please note that a git checkout will need some more build-dependencies
than listed below, in particular the Python Docutils and Sphinx.
-Build dependencies on Debian / Ubuntu
+Build dependencies on Debian / Ubuntu
--------------------------------------
In order to build Varnish from source you need a number of packages
@@ -77,7 +78,7 @@ installed. On a Debian or Ubuntu system these are:
* autotools-dev
* automake1.11
-* libtool
+* libtool
* autoconf
* libncurses-dev
* groff-base
@@ -89,7 +90,7 @@ installed. On a Debian or Ubuntu system these are:
If you're building from git, you also need the following:
* python-docutils
-* python-sphinx (optional, if you want the HTML docs built)
+* python-sphinx (optional, if you want to build the documentation)
Build dependencies on Red Hat / CentOS
--------------------------------------
@@ -97,8 +98,8 @@ Build dependencies on Red Hat / CentOS
To build Varnish on a Red Hat or CentOS system you need the following
packages installed:
-* automake
-* autoconf
+* automake
+* autoconf
* libtool
* ncurses-devel
* groff
@@ -109,10 +110,10 @@ packages installed:
If you're building from git, you also need the following:
* docutils
-* python-sphinx (optional, if you want the HTML docs built)
+* python-sphinx (optional, if you want to build the documentation)
-Configuring and compiling
--------------------------
+Compiling Varnish
+-----------------
Next, configuration: The configuration will need the dependencies
above satisfied. Once that is taken care of::
@@ -133,7 +134,7 @@ tea while it runs, it takes some minutes::
Don't worry if a single or two tests fail, some of the tests are a
bit too timing sensitive (Please tell us which so we can fix it) but
-if a lot of them fails, and in particular if the ``b00000.vtc`` test
+if a lot of them fails, and in particular if the ``b00000.vtc`` test
fails, something is horribly wrong, and you will get nowhere without
figuring out what.
@@ -146,6 +147,6 @@ And finally, the true test of a brave heart::
Varnish will now be installed in /usr/local. The varnishd binary is in
/usr/local/sbin/varnishd and its default configuration will be
-/usr/local/etc/varnish/default.vcl.
+/usr/local/etc/varnish/default.vcl.
-You can now proceed to the :ref:`tutorial-index`.
+You can now proceed to the :ref:`tutorial-index`.
diff --git a/doc/sphinx/installation/prerequisites.rst b/doc/sphinx/installation/prerequisites.rst
index ad92ee0..736bcd8 100644
--- a/doc/sphinx/installation/prerequisites.rst
+++ b/doc/sphinx/installation/prerequisites.rst
@@ -4,6 +4,7 @@ Prerequisites
In order for you to install Varnish you must have the following:
+ * A recent, preferably server grade, computer.
* A fairly modern and 64 bit version of either
- Linux
- FreeBSD
diff --git a/doc/sphinx/users-guide/command-line.rst b/doc/sphinx/users-guide/command-line.rst
index 65dec6a..dc25087 100644
--- a/doc/sphinx/users-guide/command-line.rst
+++ b/doc/sphinx/users-guide/command-line.rst
@@ -62,7 +62,7 @@ If you go with -f, you can start with a VCL file containing just::
which is exactly what -b does.
-In both cases the default VCL code is appended.
+In both cases the built-in VCL code is appended.
Other options
^^^^^^^^^^^^^
@@ -74,9 +74,9 @@ By default Varnish will use 100 megabytes of malloc(3) storage
for caching objects, if you want to cache more than that, you
should look at the '-s' argument.
-If you run a really big site, you may want to tune the size of
-the tread-pools and other parameters with the '-p' argument,
-but we generally advice not to do that, unless you need to.
+If you run a really big site, you may want to tune the number of
+worker threads and other parameters with the '-p' argument,
+but we generally advice not to do that unless you need to.
Before you go into production, you may also want to re-visit the
chapter
diff --git a/doc/sphinx/users-guide/intro.rst b/doc/sphinx/users-guide/intro.rst
index 18b4a1d..6a67fc5 100644
--- a/doc/sphinx/users-guide/intro.rst
+++ b/doc/sphinx/users-guide/intro.rst
@@ -48,10 +48,10 @@ each and every HTTP request which comes in.
Because the VCL is compiled to C code, and the C code is compiled
to machine instructions, even very complex VCL programs execute in
-a a few microseconds, without impacting performance at all.
+a few microseconds, without impacting performance at all.
And don't fret if you are not really a programmer, VCL is very
-simple to do simpel things with::
+simple to do simple things with::
sub vcl_recv {
# Remove the cookie header to enable caching
@@ -73,7 +73,7 @@ Varnish uses a piece of shared memory to report its activity and
status. For each HTTP request, a number of very detailed records will
be appended to the log segment in this shared memory. Other processes
can subscribe to log-records, filter them, and format them, for
-instance as NCSA style log records.
+instance as Apache/NCSA style log records.
Another segment in shared memory is used for statistics counters,
this allows real-time, down to microsecond resolution monitoring
diff --git a/doc/sphinx/users-guide/run_cli.rst b/doc/sphinx/users-guide/run_cli.rst
index a5e97e1..b534971 100644
--- a/doc/sphinx/users-guide/run_cli.rst
+++ b/doc/sphinx/users-guide/run_cli.rst
@@ -14,7 +14,7 @@ same machine as varnishd is running::
If you want to run varnishadm from a remote system, you can do it
two ways.
-You can ssh into the varnishd computer and run varnishadm::
+You can SSH into the varnishd computer and run varnishadm::
ssh $http_front_end varnishadm help
@@ -27,7 +27,7 @@ And then on the remote system run varnishadm::
varnishadm -T $http_front_end -S /etc/copy_of_varnish_secret help
-but as you can see, ssh is much more convenient.
+but as you can see, SSH is much more convenient.
If you run varnishadm without arguments, it will read CLI commands from
stdin, if you give it arguments, it will treat those as the single
@@ -36,7 +36,7 @@ CLI command to execute.
The CLI always returns a status code to tell how it went: '200'
means OK, anything else means there were some kind of trouble.
-Varnishadm will exit with status 1 and print the status code on
+varnishadm will exit with status 1 and print the status code on
standard error if it is not 200.
What can you do with the CLI
@@ -86,9 +86,8 @@ to the previous VCL program again::
varnish> vcl.use old_name
The switch is instantaneous, all new requests will start using the
-VCL you activated right away, but for consistency, the requests
-currently being processed, complete using whatever VCL they started
-with.
+VCL you activated right away. The requests currently being processed complete
+using whatever VCL they started with.
It is good idea to design an emergency-VCL before you need it,
and always have it loaded, so you can switch to it with a single
@@ -120,9 +119,10 @@ a HTTP request asks for it.
Banning stuff is much cheaper than restarting Varnish to get rid
of wronly cached content.
-In addition to handling such special occations, banning can be used
-in many creative ways to keep the cache up to date, more about
-that in: (XXX: xref)
+.. In addition to handling such special occations, banning can be used
+.. in many creative ways to keep the cache up to date, more about
+.. that in: (TODO: xref)
+
Change parameters
^^^^^^^^^^^^^^^^^
@@ -136,7 +136,7 @@ but they can also be examined and changed on the fly from the CLI::
Default is off
Prefer IPv6 address when connecting to backends
which have both IPv4 and IPv6 addresses.
-
+
varnish> param.set prefer_ipv6 true
200
diff --git a/doc/sphinx/users-guide/storage-backends.rst b/doc/sphinx/users-guide/storage-backends.rst
index 6f0fe9b..b12dba0 100644
--- a/doc/sphinx/users-guide/storage-backends.rst
+++ b/doc/sphinx/users-guide/storage-backends.rst
@@ -19,10 +19,11 @@ malloc
syntax: malloc[,size]
Malloc is a memory based backend. Each object will be allocated from
-memory. If your system runs low on memory swap will be used. Be aware
-that the size limitation only limits the actual storage and that
-approximately 1k of memory per object will be used for various
-internal structures.
+memory. If your system runs low on memory swap will be used.
+
+Be aware that the size limitation only limits the actual storage and that
+approximately 1k of memory per object will be used for various internal
+structures.
The size parameter specifies the maximum amount of memory varnishd
will allocate. The size is assumed to be in bytes, unless followed by
@@ -36,19 +37,19 @@ one of the following suffixes:
T, t The size is expressed in tebibytes.
-The default size is unlimited.
+The default size is unlimited.
-Mallocs performance is bound by memory speed so it is very fast. If
+malloc's performance is bound by memory speed so it is very fast. If
the dataset is bigger than what can fit in memory performance will
-depend on the operating system and how well it doesn paging.
+depend on the operating system and how well it does paging.
file
~~~~
syntax: file[,path[,size[,granularity]]]
-The file backend stores objects in memory backed by a file on disk
-with mmap.
+The file backend stores objects in memory backed by an unlinked file on disk
+with mmap.
The path parameter specifies either the path to the backing file or
the path to a directory in which varnishd will create the backing
@@ -84,8 +85,8 @@ allocation. All allocations are rounded up to this size. The
is assumed to be in bytes, unless followed by one of the
suffixes described for size except for %.
-The default size is the VM page size. The size should be reduced if
-you have many small objects.
+The default granularity is the VM page size. The size should be reduced if you
+have many small objects.
File performance is typically limited by the write speed of the
device, and depending on use, the seek time.
@@ -127,10 +128,11 @@ and can make previously banned objects reappear.
Transient Storage
-----------------
-
+
If you name any of your storage backend "Transient" it will be
used for transient (short lived) objects. By default Varnish
would use an unlimited malloc backend for this.
Varnish will consider an object short lived if the TTL is below the
parameter "shortlived".
+
diff --git a/doc/sphinx/users-guide/vcl-intro.rst b/doc/sphinx/users-guide/vcl-intro.rst
index bc90411..095896c 100644
--- a/doc/sphinx/users-guide/vcl-intro.rst
+++ b/doc/sphinx/users-guide/vcl-intro.rst
@@ -21,7 +21,7 @@ Varnish will execute the built in VCL code. You will see this VCL
code commented out in default.vcl.
99% of all the changes you'll need to do will be done in two of these
-subroutines. *vcl_recv* and *vcl_fetch*.
+subroutines. *vcl_recv* and *vcl_backend_response*.
.. _users-guide-vcl_fetch_actions:
diff --git a/doc/sphinx/users-guide/vcl.rst b/doc/sphinx/users-guide/vcl.rst
index 0e56c3a..defe566 100644
--- a/doc/sphinx/users-guide/vcl.rst
+++ b/doc/sphinx/users-guide/vcl.rst
@@ -4,12 +4,11 @@ VCL - Varnish Configuration Language
------------------------------------
This section is about getting Varnish to do what you want to
-your HTTP traffic, using the Varnish Configuration Language.
+your HTTP traffic, using the Varnish Configuration Language (VCL).
Varnish has a great configuration system. Most other systems use
configuration directives, where you basically turn on and off lots of
-switches. Varnish uses a domain specific language called Varnish
-Configuration Language, or VCL for short.
+switches. Varnish uses a domain specific language called VCL for this.
Every inbound request flows through Varnish and you can influence how
the request is being handled by altering the VCL code. You can direct
@@ -26,8 +25,8 @@ are executed at different times. One is executed when we get the
request, another when files are fetched from the backend server.
If you don't call an action in your subroutine and it reaches the end
-Varnish will execute some built in VCL code. You will see this VCL
-code commented out in default.vcl that ships with Varnish Cache.
+Varnish will execute some built-in VCL code. You will see this VCL
+code commented out in builtin.vcl that ships with Varnish Cache.
.. _users-guide-vcl_fetch_actions:
@@ -45,4 +44,4 @@ code commented out in default.vcl that ships with Varnish Cache.
vcl-examples
websockets
devicedetection
-
+
More information about the varnish-commit
mailing list