[4.0] 22dcc15 Updated to running.rst in users guide

Lasse Karstensen lkarsten at varnish-software.com
Tue Apr 1 15:09:51 CEST 2014


commit 22dcc15faf1aa41c90eeee64c06d25cb25a55cd6
Author: benc <benc at redpill-linpro.com>
Date:   Fri Mar 14 13:51:03 2014 +0100

    Updated to running.rst in users guide

diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst
index dde63a6..830149a 100644
--- a/doc/sphinx/index.rst
+++ b/doc/sphinx/index.rst
@@ -18,19 +18,18 @@ Welcome to the Varnish documentation!
 Introduction
 ------------
 
-Varnish is a state of the art web accelerator. It has its mission in front of a
-web server and cache content.
+Varnish Cache is a web application accelerator also known as a caching HTTP reverse proxy. You install it in front of any server that speaks HTTP and configure it to cache the contents. Varnish Cache is really, really fast. It typically speeds up delivery with a factor of 300 - 1000x, depending on your architecture. 
+It has its mission in front of a
+web server and cache content and it makes your web site go faster.
 
-It makes your web site go faster.
-
-We suggest you start by reading the installation guide
-:ref:`install-index`. Once you have Varnish up and running go through
+To get started with Varnish-Cache we recommend that you read the installation guide
+:ref:`install-index`. Once you have Varnish up and running we recommend that you go through
 our tutorial - :ref:`tutorial-index`, and finally the :ref:`users_guide_index`.
 
-If you need to look up how a specific Varnish tool works, the
-:ref:`reference-index` can help you out. Changes from previous versions are in
-the :ref:`whats-new-index` chapter. In closing we have :ref:`phk`, a collection
-of blog posts related to Varnish and HTTP.
+If you need to find out how to use a specific Varnish tool, the
+:ref:`reference-index` contains detailed documentation over the tools. Changes from previous versions are located in
+the :ref:`whats-new-index` chapter. In closing, we have :ref:`phk`, a collection
+of blog posts from Poul-Henning Kamp related to Varnish and HTTP.
 
 
 
diff --git a/doc/sphinx/installation/bugs.rst b/doc/sphinx/installation/bugs.rst
index 98c0e19..dd71cc8 100644
--- a/doc/sphinx/installation/bugs.rst
+++ b/doc/sphinx/installation/bugs.rst
@@ -13,14 +13,17 @@ So if you run into a bug, it is important that you spend a little bit
 of time collecting the right information, to help us fix the bug.
 
 The most valuable information you can give us, is **always** how
-to trigger and reproduce the problem.  If you can tell us that, we
-rarely need anything else to solve it.  The caveat being, that we
+to trigger and reproduce the problem. If you can tell us that, we
+rarely need anything else to solve it.The caveat being, that we
 do not have a way to simulate high levels of real-life web-traffic,
 so telling us to "have 10.000 clients hit at once" does not really
 allow us to reproduce.
 
-Roughly we have three clases of bugs with Varnish, and the information
-we need to debug them depends on the kind of bug.
+To report a bug please follow the suggested procedure described in the "Trouble Tickets" 
+section of the documentation (above).
+
+Roughly we categorize bugs in to three kinds of bugs (described below) with Varnish. The information
+we need to debug them depends on what kind of bug we are facing.
 
 Varnish crashes
 ===============
@@ -32,11 +35,11 @@ does all the work, and the manager hangs around to resurrect it if it
 crashes.
 
 Therefore, the first thing to do if you see a Varnish crash, is to examine
-your syslogs to see if it has happened before.  (One site is rumoured
+your syslogs to see if it has happened before. (One site is rumoured
 to have had Varnish restarting every 10 minutes and *still* provide better
 service than their CMS system.)
 
-When it crashes, if at all possible, Varnish will spew out a crash dump
+When it crashes, which is highly unlikely to begin with, Varnish will spew out a crash dump
 that looks something like::
 
 	Child (32619) died signal=6 (core dumped)
@@ -62,7 +65,7 @@ If you can get that information to us, we are usually able to
 see exactly where things went haywire, and that speeds up bugfixing
 a lot.
 
-There will be a lot more information than this, and before sending
+There will be a lot more information in the crash dump besides this, and before sending
 it all to us, you should obscure any sensitive/secret
 data/cookies/passwords/ip# etc.  Please make sure to keep context
 when you do so, ie: do not change all the IP# to "X.X.X.X", but
@@ -73,7 +76,7 @@ The most important line is the "Panic Message", which comes in two
 general forms:
 
 "Missing errorhandling code in ..."
-	This is a place where we can conceive ending up, and have not
+	This is a situation where we can conceive Varnish ending up, which we have not
 	(yet) written the padded-box error handling code for.
 
 	The most likely cause here, is that you need a larger workspace
@@ -84,11 +87,11 @@ general forms:
 
 "Assert error in ..."
 	This is something bad that should never happen, and a bug
-	report is almost certainly in order.  As always, if in doubt
+	report is almost certainly in order. As always, if in doubt
 	ask us on IRC before opening the ticket.
 
 In your syslog it may all be joined into one single line, but if you
-can reproduce the crash, do so while running varnishd manually:
+can reproduce the crash, do so while running `varnishd` manually:
 
 	``varnishd -d <your other arguments> |& tee /tmp/_catch_bug``
 
@@ -105,7 +108,7 @@ kill the process and send us an email saying "Varnish hung, I
 restarted it" which gives us only about 1.01 bit of usable debug
 information to work with.
 
-What we need here is all the information can you squeeze out of
+What we need here is all the information you can squeeze out of
 your operating system **before** you kill the Varnish process.
 
 One of the most valuable bits of information, is if all Varnish'
@@ -115,18 +118,21 @@ furiously on some futile condition.
 Commands like ``top -H`` or ``ps -Haxlw`` or ``ps -efH`` should be
 able to figure that out.
 
+.. XXX:Maybe a short description of what valuable information the various commands above generates? /benc 
+
+
 If one or more threads are spinning, use ``strace`` or ``ktrace`` or ``truss``
 (or whatever else your OS provides) to get a trace of which system calls
-the Varnish process issues.  Be aware that this may generate a lot
-of very repetitive data, usually one second worth is more than enough.
+the Varnish process issues. Be aware that this may generate a lot
+of very repetitive data, usually one second worth of data is more than enough.
 
 Also, run ``varnishlog`` for a second, and collect the output
 for us, and if ``varnishstat`` shows any activity, capture that also.
 
 When you have done this, kill the Varnish *child* process, and let
 the *master* process restart it.  Remember to tell us if that does
-or does not work.  If it does not, kill all Varnish processes, and
-start from scratch.  If that does not work either, tell us, that
+or does not work. If it does not, kill all Varnish processes, and
+start from scratch. If that does not work either, tell us, that
 means that we have wedged your kernel.
 
 
@@ -139,10 +145,12 @@ what is wrong about what Varnish does.
 
 Be aware, that often Varnish does exactly what you asked it to, rather
 than what you intended it to do. If it sounds like a bug that would
-have tripped up everybody else, take a moment to read though your
-VCL and see if it really does what you think.
+have tripped up everybody else, take a moment to read through your
+VCL and see if it really does what you think it does.
 
 You can also try setting the ``vcl_trace`` parameter, that will generate log
 records with like and character number for each statement executed in your VCL
 program.
 
+.. XXX:Example of the command perhaps? benc
+
diff --git a/doc/sphinx/installation/help.rst b/doc/sphinx/installation/help.rst
index aaea9ec..946e921 100644
--- a/doc/sphinx/installation/help.rst
+++ b/doc/sphinx/installation/help.rst
@@ -1,15 +1,14 @@
-%%%%%%%%%%%%%%%%%%
-Getting hold of us
-%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%
+Getting help
+%%%%%%%%%%%%
 
 Getting hold of the gang behind Varnish is pretty straight forward,
-we try to help as much as time permits and have tried to streamline
+we try to help out as much as time permits and have tried to streamline
 this process as much as possible.
 
 But before you grab hold of us, spend a moment composing your thoughts and
-formulate your question. There is nothing as pointless as simply telling
-us "Varnish does not work for me" with no further information to give
-any clue to why.
+formulate your question. From our perspective there is nothing as pointless as simply telling
+us "Varnish does not work for me" with no further information. This does not give us any relevant information to use when trying to figure out whats wrong. 
 
 And before you even do that, do a couple of searches to see if your
 question is already answered, if it has been, you will get your answer
@@ -20,7 +19,7 @@ IRC Channel
 
 The most immediate way to get hold of us is to join our IRC channel:
 
-	``#varnish on server irc.linpro.no``
+	`#varnish on server irc.linpro.no`
 
 The main timezone of the channel is Europe work hours.
 
@@ -32,27 +31,27 @@ If the channel is all quiet, try again some time later, we do have lives,
 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 don't paste random links unless they are
+the occasional intrusion from the real world into our flow, we try and keep
+it mostly on topic, and please don't paste random links unless they are
 *really* spectacular and intelligent.
 
 Mailing Lists
 =============
 
-Getting on or off our mailing lists happens through Mailman_.
+Subscribing or unsubscribing to our mailing lists is handled through our 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
+If you are going to use Varnish, subscribing to our `varnish-announce`
+mailing list is 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
-reminded about new releases, bad bugs or security holes.
+reminded about new releases, bugs or potential (security) vulnerabilities.
 
 
-The ``varnish-misc`` mailing list is for general banter, questions,
+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 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
+and potentially learn some smart tricks.  This is also a good place to ask for help
+with more complex issues, that may require file-chunks, references to files and/or long
 explanations.
 
 Make sure to pick a good subject line, and if the subject of the
@@ -61,26 +60,29 @@ 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
+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
 those people.
 
+We also maintain a community wiki_ for Varnish, there you will find information on planned events, meetings, current backlog, troube tickets ,  and links to resources and documentation. 
+
 .. XXX: we should introduce the wiki (if we care about it) before
 .. we start referring to it (below). Make a wiki chapter?
 
-
 Trouble Tickets
 ===============
 
 Please do not open a trouble ticket, unless you have spotted an actual
 bug in Varnish.  Ask on IRC first if you are in doubt.
 
-The reason for this policy, is to avoid the bugs being drowned in a
-pile of sensible suggestions for future enhancements and call for help
-from people who forget to check back if they get it and so on.
+The reason for this policy, is to avoid bugs being drowned in a
+pile of other `issues`, feature suggestions for future releases, and double postings of calls for help
+from people who forgot to check back on already opened Tickets. 
 
-We track suggestions and ideas in our `"Shopping-List" wiki page`_, and user
+.. XXX: Not sure what you want with the last sentence above. benc
+
+We instead track suggestions and feature ideas in our `"Shopping-List" wiki page`_, and through user
 support via email and IRC.
 
 Commercial Support
@@ -90,6 +92,8 @@ The following companies offer commercial Varnish support, and are listed
 here for your convenience.  If you want your company listed here, drop
 an email to phk at FreeBSD.org.
 
+.. XXX: Should we perhaps enhance this to explain Varnish Plus? benc
+
 	Varnish Software
 	sales at varnish-software.com
 
@@ -97,3 +101,4 @@ an email to phk at FreeBSD.org.
 .. _mailman: http://lists.varnish-cache.org/mailman/listinfo
 .. _pastebin: http://gist.github.com/
 .. _"Shopping-List" wiki page: http://varnish-cache.org/wiki/PostTwoShoppingList
+.. _wiki: https://www.varnish-cache.org/trac   
diff --git a/doc/sphinx/installation/index.rst b/doc/sphinx/installation/index.rst
index 7952958..03e60b8 100644
--- a/doc/sphinx/installation/index.rst
+++ b/doc/sphinx/installation/index.rst
@@ -4,11 +4,8 @@
 Varnish Installation
 %%%%%%%%%%%%%%%%%%%%
 
-This document explains how to get Varnish onto your system, where
-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.
+This section covers installation prerequisites, a step-by-step installation procedure, how and where
+to get help, and how to report bugs. It also contains a set of platform specific notes to aid you when installing Varnish on certain platforms.
 
 .. XXX: rewrite the last paragraph.
 
diff --git a/doc/sphinx/installation/install.rst b/doc/sphinx/installation/install.rst
index a32eb68..348b6ef 100644
--- a/doc/sphinx/installation/install.rst
+++ b/doc/sphinx/installation/install.rst
@@ -6,15 +6,15 @@ Installing Varnish
 With open source software, you can choose to install binary packages
 or compile it yourself from source code. To install a package or compile
 from source is a matter of personal taste. If you don't know which
-method to choose, read the whole document and choose the method you
-are most comfortable with.
+method to choose, we recommend that you read this whole section and then choose the method you
+feel most comfortable with.
 
 
 Source or packages?
 -------------------
 
 Installing Varnish on most relevant operating systems can usually
-be done with with the systems package manager, typical examples
+be done with with the specific systems package manager, typical examples
 being:
 
 FreeBSD
@@ -38,13 +38,13 @@ Varnish is included in the `EPEL
 incompatible syntax changes in newer versions of Varnish, only older
 versions are available.
 
-We recommend that you install the latest version from our repository.
+We therefore recommend that you install the latest version directly from our repository, as described above.
 
 Debian/Ubuntu
 -------------
 
 Varnish is distributed with both Debian and Ubuntu. In order to get
-Varnish up and running type `sudo apt-get install varnish`. Please
+Varnish up and running type ``sudo apt-get install varnish``. Please
 note that this might not be the latest version of Varnish.  If you
 need a later version of Varnish, please follow the online installation
 instructions for `Debian
@@ -59,16 +59,16 @@ If there are no binary packages available for your system, or if you
 want to compile Varnish from source for other reasons, follow these
 steps:
 
-We recommend downloading a release tarball, which you can find on
+Download the appropriate release tarball, which you can find on
 `repo.varnish-cache.org/source <http://repo.varnish-cache.org/source/>`_.
 
 Alternatively, if you want to hack on Varnish, you should clone our
 git repository by doing.
 
-      git clone git://git.varnish-cache.org/varnish-cache
+      ``git clone git://git.varnish-cache.org/varnish-cache``
 
 Please note that a git checkout will need some more build-dependencies
-than listed below, in particular the Python Docutils and Sphinx.
+than listed below, in particular the `Python Docutis` and `Sphinx`.
 
 Build dependencies on Debian / Ubuntu
 --------------------------------------
@@ -76,21 +76,21 @@ Build dependencies on Debian / Ubuntu
 In order to build Varnish from source you need a number of packages
 installed. On a Debian or Ubuntu system these are:
 
-* autotools-dev
-* automake1.11
-* libtool
-* autoconf
-* libncurses-dev
-* groff-base
-* libpcre3-dev
-* pkg-config
-* make
-* libedit-dev
+* `autotools-dev`
+* `automake1.1`
+* `libtool`
+* `autoconf`
+* `libncurses-dev`
+* `groff-base`
+* `libpcre3-dev`
+* `pkg-config`
+* `make`
+* `libedit-dev`
 
 If you're building from git, you also need the following:
 
-* python-docutils
-* python-sphinx (optional, if you want to build the documentation)
+* `python-docutils`
+* `python-sphinx` (optional, if you want to build the documentation)
 
 Build dependencies on RedHat / CentOS
 --------------------------------------
@@ -98,19 +98,19 @@ Build dependencies on RedHat / CentOS
 To build Varnish on a RedHat or CentOS system you need the following
 packages installed:
 
-* automake
-* autoconf
-* libtool
-* ncurses-devel
-* groff
-* pcre-devel
-* pkgconfig
-* libedit-devel
+* `automake`
+* `autoconf`
+* `libtool`
+* `ncurses-devel`
+* `groff`
+* `pcre-devel`
+* `pkgconfig`
+* `libedit-devel`
 
 If you're building from git, you also need the following:
 
-* docutils
-* python-sphinx (optional, if you want to build the documentation)
+* `docutils`
+* `python-sphinx` (optional, if you want to build the documentation)
 
 Compiling Varnish
 -----------------
@@ -123,18 +123,17 @@ taken care of::
 	sh configure
 	make
 
-The ``configure`` script takes some arguments, but more likely than
-not you can forget about that for now, almost everything in Varnish
-are run time parameters.
+The `configure` script takes some arguments, but more likely than
+not you can forget about that for now, almost everything in Varnish can be tweaked with run time parameters.
 
 Before you install, you may want to run the test suite, make a cup of
-tea while it runs, it takes some minutes::
+tea while it runs, it usually takes a couple of minutes::
 
 	make check
 
-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
+Don't worry if one or two tests fail, some of the tests are a
+bit too timing sensitive (Please tell us which so we can fix them.) but
+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.
 
@@ -145,9 +144,9 @@ And finally, the true test of a brave heart::
 
 	sudo make install
 
-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.
+Varnish will now be installed in `/usr/loca``l. The ``varnishd` binary is in
+`/usr/local/sbin/varnishd` and its default configuration will be
+`/usr/local/etc/varnish/default.vcl`.
 
-You can now proceed to the :ref:`tutorial-index`.
+After succesful installation you are ready to proceed to the :ref:`tutorial-index`.
 
diff --git a/doc/sphinx/installation/platformnotes.rst b/doc/sphinx/installation/platformnotes.rst
index a7d3fb4..7f11eaa 100644
--- a/doc/sphinx/installation/platformnotes.rst
+++ b/doc/sphinx/installation/platformnotes.rst
@@ -31,7 +31,7 @@ performance.
 If you are running on 64bit OpenVZ (or Parallels VPS), you must reduce
 the maximum stack size before starting Varnish.
 
-The default allocates to much memory per thread, which will make Varnish fail
+The default allocates too much memory per thread, which will make Varnish fail
 as soon as the number of threads (traffic) increases.
 
 Reduce the maximum stack size by running::
@@ -44,13 +44,13 @@ TCP keep-alive configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 On some Solaris, FreeBSD and OS X systems, Varnish is not able to set the TCP
-keep-alive values per socket, and therefor the tcp_keepalive_* Varnish runtime
-parameters are not available. On these platforms it can be benefitial to tune
+keep-alive values per socket, and therefore the *tcp_keepalive_* Varnish runtime
+parameters are not available. On these platforms it can be beneficial to tune
 the system wide values for these in order to more reliably detect remote close
 for sessions spending long time on waitinglists. This will help free up
 resources faster.
 
-Systems to not support TCP keep-alive values per socket include:
+Systems that does not support TCP keep-alive values per socket include:
 
 - Solaris releases prior to version 11
 - FreeBSD releases prior to version 9.1
@@ -59,9 +59,11 @@ Systems to not support TCP keep-alive values per socket include:
 On platforms with the necessary socket options the defaults are set
 to:
 
-- tcp_keepalive_time = 600 seconds
-- tcp_keepalive_probes = 5
-- tcp_keepalive_intvl = 5 seconds
+- `tcp_keepalive_time` = 600 seconds
+- `tcp_keepalive_probes` = 5
+- `tcp_keepalive_intvl` = 5 seconds
 
 Note that Varnish will only apply these run-time parameters so long as
 they are less than the system default value.
+
+.. XXX:Maybe a sample-command of using/setting/changing these values? benc
diff --git a/doc/sphinx/installation/prerequisites.rst b/doc/sphinx/installation/prerequisites.rst
index 736bcd8..7ef0bd7 100644
--- a/doc/sphinx/installation/prerequisites.rst
+++ b/doc/sphinx/installation/prerequisites.rst
@@ -7,18 +7,17 @@ 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
-    - Solaris (x86 only)
-  * root access to said system.
+    - FreeBSD, or
+    - Solaris (x86 only).
+  * Root access.
 
 
-Varnish can be installed on other UNIX systems as well, but it is not
-tested particularly well on these platforms. Varnish is, from time to
+Varnish can be installed on other UNIX systems as well, but it is not extensively or systematically tested by us on other systems than the above. Varnish is, from time to
 time, said to work on:
 
-  * 32 bit versions of the before-mentioned systems.
-  * OS X
-  * NetBSD
-  * OpenBSD
-  * Windows with Cygwin
+  * 32 bit versions of the before-mentioned systems,
+  * OS X,
+  * NetBSD,
+  * OpenBSD, and
+  * Windows with Cygwin.
 
diff --git a/doc/sphinx/tutorial/backend_servers.rst b/doc/sphinx/tutorial/backend_servers.rst
index 476d325..1c9ab65 100644
--- a/doc/sphinx/tutorial/backend_servers.rst
+++ b/doc/sphinx/tutorial/backend_servers.rst
@@ -3,14 +3,14 @@
 Backend servers
 ---------------
 
-Varnish has a concept of "backend" or "origin" servers. A backend
-server is the server providing the content Varnish will accelerate.
+Varnish has a concept of `backend` or `origin` servers. A backend
+server is the server providing the content Varnish will accelerate via the cache.
 
 Our first task is to tell Varnish where it can find its content. Start
 your favorite text editor and open the Varnish default configuration
 file. If you installed from source this is
-/usr/local/etc/varnish/default.vcl, if you installed from a package it
-is probably /etc/varnish/default.vcl.
+`/usr/local/etc/varnish/default.vcl`, if you installed from a package it
+is probably `/etc/varnish/default.vcl`.
 
 If you've been following the tutorial there is probably a section of
 the configuration that looks like this:::
@@ -41,11 +41,16 @@ localhost, port 8080.::
   }
 
 
-Varnish can have several backends defined and can you can even join
+Varnish can have several backends defined and can even join
 several backends together into clusters of backends for load balancing
 purposes, having Varnish pick one backend based on different
 algorithms. 
 
 A lot of the power of Varnish Cache comes from it's design, which
-might not be what you are expecting. Next, let's have a look at some of
-them.
+might not be what you are expecting.
+
+.. XXX:What am I expecting? benc
+
+Next, let's have a look at some of what makes Varnish unique and what you can do with it.
+
+
diff --git a/doc/sphinx/tutorial/index.rst b/doc/sphinx/tutorial/index.rst
index c540f8e..44008e7 100644
--- a/doc/sphinx/tutorial/index.rst
+++ b/doc/sphinx/tutorial/index.rst
@@ -4,12 +4,12 @@
 The Varnish Tutorial
 %%%%%%%%%%%%%%%%%%%%
 
-This documents the basic concept. What is Varnish and how does it
-work? How can I get it up and running. Most likely you would want to
-continue with the users guide (:ref:`users-guide-index`) afterwards.
+This section covers the Varnish basics in a tutorial form. It will cover what Varnish is and how it
+works. It also covers how to get Varnish up and running. After this section you probably would want to
+continue with the users guide (:ref:`users-guide-index`).
 
 If you're reading this on the web note the "Next topic" and "Previous
-topic" on the right side.
+topic" links on the right side of each page.
 
 .. toctree:: :maxdepth: 1
 
diff --git a/doc/sphinx/tutorial/introduction.rst b/doc/sphinx/tutorial/introduction.rst
index 9e6c541..98cfddc 100644
--- a/doc/sphinx/tutorial/introduction.rst
+++ b/doc/sphinx/tutorial/introduction.rst
@@ -3,25 +3,22 @@
 The fundamentals of web proxy caching with Varnish
 --------------------------------------------------
 
-Varnish is a caching HTTP reverse proxy. It receives requests from
-clients and tries to answer them from its cache. If it cannot answer
-the request from its cache it will forward the request to the backend,
-fetch the response, store it and deliver it to the client.
+Varnish is a caching HTTP reverse proxy. It recieves requests from
+clients and tries to answer them from the cache. If Varnish cannot answer
+the request from the cache it will forward the request to the backend,
+fetch the response, store it in the cache and deliver it to the client.
 
 When Varnish has a cached response ready it is typically delivered in
 a matter of microseconds, several orders of magnitude faster than your
-typical application server, so you want to make sure to have it answer
-as many of the requests as possible.
+typical backend server, so you want to make sure to have Varnish answer
+as many of the requests as possible directly from the cache.
 
 Varnish decides whether it can store the content or not based on the
 response it gets back from the backend. The backend can instruct
 Varnish to cache the content with the HTTP response header
-Cache-Control. There are a few other conditions where Varnish will not
-cache, the most common one being cookies. Since cookies is a good
-indication that a web object is personalised, Varnish will with its
-default configuration, not cache it.
-
-This behaviour and most other behaviour can be changed using policies
+`Cache-Control`. There are a few conditions where Varnish will not
+cache, the most common one being the use of cookies. Since cookies indicates a client-specific web object, Varnish will by default not cache it. 
+This behaviour as most of Varnish functionality can be changed using policies
 written in the Varnish Configuration Language. See the Users Guide
 for more information on how to do that.
 
@@ -34,6 +31,8 @@ turning performance into a non-issue. You get to focus on how your web
 application work and you can allow yourself, to some degree, to care
 less about performance and scalability.
 
+.. XXX:Not totally sure what the last sentence above means. benc
+
 Flexibility
 ~~~~~~~~~~~
 
@@ -77,3 +76,5 @@ information and signup.  There is also a web forum on the same site.
 
 Now that you have a vague idea on what Varnish Cache is, let see if we
 can get it up and running.
+
+.. XXX:The above three paragraphs are repetetive this is already handled in previos chapters. The only new information is Governing Board which could be moved to the introduction and the paragraphs scrapped. benc
diff --git a/doc/sphinx/tutorial/peculiarities.rst b/doc/sphinx/tutorial/peculiarities.rst
index af12eff..45f2f25 100644
--- a/doc/sphinx/tutorial/peculiarities.rst
+++ b/doc/sphinx/tutorial/peculiarities.rst
@@ -3,16 +3,19 @@ Peculiarities
 -------------
 
 There are a couple of things that are different with Varnish Cache, as
-opposed to other programs. One thing you've already seen - VCL. I'll
-just give you a very quick tour of the other pecularities.
+opposed to other programs. One thing you've already seen - VCL. In this section we provide a very quick tour of other pecularities you need to know about to get the most out of Varnish.
 
 Configuration
 ~~~~~~~~~~~~~
 
 The Varnish Configuration is written in VCL. When Varnish is ran this
 configuration is transformed into C code and then fed into a C
-compiler, loaded and run. So, as opposed to declaring various
-settings, you write polices on how the incoming traffic should be
+compiler, loaded and executed.
+
+.. XXX:Ran sounds strange above, maybe "is running" "is started" "executes"? benc
+
+So, as opposed to switching various
+settings on or off, you write polices on how the incoming traffic should be
 handled.
 
 
@@ -20,8 +23,8 @@ varnishadm
 ~~~~~~~~~~
 
 Varnish Cache has an admin console. You can connect it it through the
-"varnishadm" command. In order to connect the user needs to be able to
-read /etc/varnish/secret in order to authenticate.
+``varnishadm`` command. In order to connect the user needs to be able to
+read `/etc/varnish/secret` in order to authenticate.
 
 Once you've started the console you can do quite a few operations on
 Varnish, like stopping and starting the cache process, load VCL,
@@ -30,11 +33,13 @@ adjust the built in load balancer and invalidate cached content.
 It has a built in command "help" which will give you some hints on
 what it does.
 
+.. XXX:sample of the command here. benc
+
 varnishlog
 ~~~~~~~~~~
 
-Varnish does not log to disk. Instead it logs to a bit of memory. It
-is like a stream of logs. At any time you'll be able to connect to the
+Varnish does not log to disk. Instead it logs to a chunk of memory. It
+is actually streaming the logs. At any time you'll be able to connect to the
 stream and see what is going on. Varnish logs quite a bit of
 information. You can have a look at the logstream with the command
 ``varnishlog``.
diff --git a/doc/sphinx/tutorial/putting_varnish_on_port_80.rst b/doc/sphinx/tutorial/putting_varnish_on_port_80.rst
index acef0c6..0fc2ddc 100644
--- a/doc/sphinx/tutorial/putting_varnish_on_port_80.rst
+++ b/doc/sphinx/tutorial/putting_varnish_on_port_80.rst
@@ -9,13 +9,15 @@ First we stop varnish::
 
      # service varnish stop
 
+.. XXX:This renders to a different font than other commands. it should be the double backtick format for the command. benc
+
 Now we need to edit the configuration file that starts Varnish. 
 
 
 Debian/Ubuntu
 ~~~~~~~~~~~~~
 
-On Debian/Ubuntu this is /etc/default/varnish. In the file you'll find
+On Debian/Ubuntu this is `/etc/default/varnish`. In the file you'll find
 some text that looks like this::
 
   DAEMON_OPTS="-a :6081 \
@@ -36,7 +38,7 @@ Red Hat EL / Centos
 ~~~~~~~~~~~~~~~~~~~
 
 On Red Hat EL / Centos
-On Red Hat/Centos it is /etc/sysconfig/varnish
+On Red Hat/Centos it is `/etc/sysconfig/varnish`
 
 
 Restarting Varnish
diff --git a/doc/sphinx/tutorial/starting_varnish.rst b/doc/sphinx/tutorial/starting_varnish.rst
index 58bf574..2896394 100644
--- a/doc/sphinx/tutorial/starting_varnish.rst
+++ b/doc/sphinx/tutorial/starting_varnish.rst
@@ -4,36 +4,35 @@
 Starting Varnish
 ----------------
 
-This tutorial will assume that you are either running Ubuntu, Debian,
+This tutorial will assume that you are running Varnish on Ubuntu, Debian,
 Red Hat Enterprise Linux or Centos. Those of you running on other
 platforms might have to do some mental translation exercises in order
-to follow me. Since you're on a "weird" platform you're probably used
+to follow this. Since you're on a "weird" platform you're probably used
 to it. :-)
 
-I assume you have Varnish Cache installed.
+Make sure you have Varnish succesfully installed (following one of the procedures described in "Installing Varnish" above.
 
-You start Varnish with ``service varnish start``.  This will start
+When properly installed you start Varnish with ``service varnish start``.  This will start
 Varnish if it isn't already running.
 
+.. XXX:What does it do if it is already running? benc
+
 Now you have Varnish running. Let us make sure that it works
 properly. Use your browser to go to http://127.0.0.1:6081/
-(obviously, you should replace the IP address with one on your own
-system). 
-
+(obviously, you should replace the IP address with the IP for the machine that currently runs Varnish. 
 The default configuration will try to forward requests to a web
-service running on the same computer as Varnish was installed at,
-port 8080.
+application running on the same machine as Varnish was installed on. Varnish expects the web application to be exposed over http on port 8080.
 
-If there is no web application being served up there Varnish will
+If there is no web application being served up on that location Varnish will
 issue an error. Varnish Cache is very conservative about telling the
 world what is wrong so whenever something is amiss it will issue the
 same generic "Error 503 Service Unavilable".
 
 You might have a web application running on some other port or some
-other computer. Let's edit the configuration and make it point to
+other machine. Let's edit the configuration and make it point to
 something that actually works.
 
-Fire up your favorite editor and edit /etc/varnish/default.vcl. Most
+Fire up your favorite editor and edit `/etc/varnish/default.vcl`. Most
 of it is commented out but there is some text that is not. It will
 probably look like this::
 
diff --git a/doc/sphinx/users-guide/index.rst b/doc/sphinx/users-guide/index.rst
index 7cd0c25..3d4d831 100644
--- a/doc/sphinx/users-guide/index.rst
+++ b/doc/sphinx/users-guide/index.rst
@@ -15,7 +15,7 @@ The Varnish documentation consists of three main documents:
   looking up specific questions.
 
 After :ref:`users_intro`, this Users Guide is organized in sections
-along the major interfaces to Varnish as a service:
+following the major interfaces to Varnish as a service:
 
 :ref:`users_running` is about getting Varnish configured, with
 respect to storage, sockets, security and how you can control and
@@ -25,12 +25,12 @@ communicate with Varnish once it is running.
 HTTP requests the way you want, what to cache, how to cache it,
 modifying HTTP headers etc. etc.
 
-:ref:`users_report` explains how you can see and monitor what Varnish does,
-from transaction level to aggregate statistics.
+:ref:`users_report` explains how you can monitor what Varnish does,
+from a transactional level to aggregating statistics.
 
 :ref:`users_performance` is about tuning your website with Varnish.
 
-:ref:`users_trouble` is for locating and fixing trouble with Varnish.
+:ref:`users_trouble` is for locating and fixing common issues with Varnish.
 
 .. toctree::
    :maxdepth: 2
diff --git a/doc/sphinx/users-guide/intro.rst b/doc/sphinx/users-guide/intro.rst
index 6a67fc5..8b31b32 100644
--- a/doc/sphinx/users-guide/intro.rst
+++ b/doc/sphinx/users-guide/intro.rst
@@ -3,10 +3,12 @@
 The Big Varnish Picture
 =======================
 
-What is in this package called "Varnish", what are all the different
-bits and pieces named and will you need a hex-wrench for assembly?
+In this section we will cover the questions:
+- What is in this package called "Varnish"?
+- what are all the different bits and pieces named? 
+- Will you need a hex-wrench for assembly?
 
-The two main parts of Varnish are the two processes in the varnishd
+The two main parts of Varnish are the two processes in the `varnishd`
 program. The first process is called "the manager", and its job is to
 talk to you, the administrator, and make the things you ask for
 happen.
@@ -15,12 +17,12 @@ The second process is called "the worker" or just "the child" and
 this is the process which does all the actual work with your HTTP
 traffic.
 
-When you start varnishd, you start the manager process, and once it is
+When you start `varnishd`, you start the manager process, and once it is
 done handling all the command line flags, it will start the child
 process for you. Should the child process die, the manager will start
 it again for you, automatically and right away.
 
-The main reason for this division of labor is security:  The manager
+The main reason for this division of labor is security: The manager
 process will typically run with "root" permissions, in order to
 open TCP socket port 80, but it starts the child process with minimal
 permissions, as a defensive measure.
@@ -39,11 +41,15 @@ or tie it to your CMS.
 
 All this is covered in :ref:`users_running`.
 
-How the child process should deal with the HTTP requests, what to
-cache, which headers to remove etc, is al specified in a small
+Things like, how the child process should deal with the HTTP requests, what to
+cache, which headers to remove etc, is all specified using a small
 programming language called VCL -- Varnish Configuration Language.
 The manager process will compile the VCL program and check it for
-errors, but it is the child process which runs the VCL program, for
+errors,
+
+.. XXX:What does manager do after compile and error-check? Maybe a short description of further handling when no errors as well as when errors? benc
+
+but it is the child process which runs the VCL program, for
 each and every HTTP request which comes in.
 
 Because the VCL is compiled to C code, and the C code is compiled
@@ -69,9 +75,9 @@ can do for your HTTP traffic, there really is no limit.
 
 :ref:`users_vcl` describes VCL and what it can do in great detail.
 
-Varnish uses a piece of shared memory to report its activity and
+Varnish uses a segment of shared memory to report and log its activities 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
+be appended to the log memory segment. Other processes
 can subscribe to log-records, filter them, and format them, for
 instance as Apache/NCSA style log records.
 
@@ -81,24 +87,25 @@ of cache hit-rate, resource usage and specific performance indicating
 metrics.
 
 Varnish comes with a number of tools which reports from shared
-memory, varnishlog, varnishstats, varnishncsa etc, and with a API
+memory, `varnishlog`, `varnishstats`, `varnishncsa` etc, and with an API
 library so you can write your own tools, should you need that.
-writing
 
 :ref:`users_report` explains how all that work.
 
-Presumably the reason why you are interested in Varnish, is that you
+Presumably the reason for your interest in Varnish, is that you
 want your website to work better. There are many aspects of
 performance tuning a website, from relatively simple policy decisions
 about what to cache, to designing a geographically diverse multilevel
 CDNs using ESI and automatic failover.
 
+.. XXX:CDNs or CDN? benc
+
 :ref:`users_performance` will take you through the possibilities
 and facilities Varnish offers.
 
-Finally, Murphys Law must be contended with: Things will go wrong, and
+Finally, Murphys Law must be referenced here: Things will go wrong, and
 more likely than not, they will do so at zero-zero-dark O'clock. Most
-likely during a hurricane, when your phones battery is flat and your
+likely during a hurricane, when your phone battery is flat and your
 wife had prepared a intimate evening to celebrate your anniversary.
 
 Yes, we've all been there, haven't we?



More information about the varnish-commit mailing list