[4.0] 70b1004 Run-through of the first chapter in the docs

Lasse Karstensen lkarsten at varnish-software.com
Thu Mar 13 10:24:30 CET 2014 

commit 70b1004ce4adbc52f5c872972cba9738862c9114
Author: Lasse Karstensen <lkarsten at varnish-software.com>
Date:   Tue Mar 4 14:43:37 2014 +0100

    Run-through of the first chapter in the docs
    
    I'm happy with the first chapter for 4.0 release.

diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst
index e83d1dc..dde63a6 100644
--- a/doc/sphinx/index.rst
+++ b/doc/sphinx/index.rst
@@ -15,12 +15,24 @@
 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. It makes your web site go faster.
+web server and cache content.
+
+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
-our tutorial - :ref:`tutorial-index`.
+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.
+
+
 
 .. toctree::
    :maxdepth: 1
diff --git a/doc/sphinx/installation/bugs.rst b/doc/sphinx/installation/bugs.rst
index 16f0c51..98c0e19 100644
--- a/doc/sphinx/installation/bugs.rst
+++ b/doc/sphinx/installation/bugs.rst
@@ -28,11 +28,11 @@ 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 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.)
 
@@ -138,11 +138,11 @@ transactions recorded with ``varnishlog`` and your explanation of
 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, so it sounds like a bug that would
+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.
 
-You can also try setting the ``vcl_trace`` parameter, that will
-generate log records with like and char number for each statement
-executed in your VCL program.
+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.
 
diff --git a/doc/sphinx/installation/help.rst b/doc/sphinx/installation/help.rst
index 4fb8362..aaea9ec 100644
--- a/doc/sphinx/installation/help.rst
+++ b/doc/sphinx/installation/help.rst
@@ -7,7 +7,7 @@ we try to help 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
+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.
 
@@ -18,15 +18,15 @@ much faster that way.
 IRC Channel
 ===========
 
-The most immediate way to get hold of us, is to join our IRC channel:
+The most immediate way to get hold of us is to join our IRC channel:
 
 	``#varnish on server irc.linpro.no``
 
-The main timezone of the channel is Europe+America.
+The main timezone of the channel is Europe work hours.
 
 If you can explain your problem in a few clear sentences, without too
 much copy&paste, IRC is a good way to try to get help. If you do need
-to paste log files, VCL and so on, please use a pastebin_.
+to paste log files, VCL and so on, please use a pastebin_ service.
 
 If the channel is all quiet, try again some time later, we do have lives,
 families and jobs to deal with also.
@@ -39,7 +39,7 @@ it mostly on topic, and don't paste random links unless they are
 Mailing Lists
 =============
 
-Getting on or off our mailing lists 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
@@ -66,6 +66,10 @@ 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.
 
+.. XXX: we should introduce the wiki (if we care about it) before
+.. we start referring to it (below). Make a wiki chapter?
+
+
 Trouble Tickets
 ===============
 
@@ -90,6 +94,6 @@ an email to phk at FreeBSD.org.
 	sales at varnish-software.com
 
 
-.. _Mailman: http://lists.varnish-cache.org/mailman/listinfo
+.. _mailman: http://lists.varnish-cache.org/mailman/listinfo
 .. _pastebin: http://gist.github.com/
 .. _"Shopping-List" wiki page: http://varnish-cache.org/wiki/PostTwoShoppingList
diff --git a/doc/sphinx/installation/index.rst b/doc/sphinx/installation/index.rst
index 60d43e0..0b0c665 100644
--- a/doc/sphinx/installation/index.rst
+++ b/doc/sphinx/installation/index.rst
@@ -5,10 +5,13 @@ 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
+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.
 
+.. XXX: rewrite the last paragraph.
+
 .. toctree::
 
 	prerequisites.rst
diff --git a/doc/sphinx/installation/install.rst b/doc/sphinx/installation/install.rst
index 45c5e4e..a32eb68 100644
--- a/doc/sphinx/installation/install.rst
+++ b/doc/sphinx/installation/install.rst
@@ -4,7 +4,7 @@ Installing Varnish
 ==================
 
 With open source software, you can choose to install binary packages
-or compile stuff from source-code. To install a package or compile
+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.
@@ -29,7 +29,7 @@ CentOS/RedHat
 -------------
 
 We try to keep the latest version available as prebuilt RPMs (el5 and el6)
-on `repo.varnish-cache.org <http://repo.varnish-cache.org/>`_.  See the
+on `repo.varnish-cache.org <http://repo.varnish-cache.org/>`_.  See the online
 `RedHat installation instructions
 <http://www.varnish-cache.org/installation/redhat>`_ for more information.
 
@@ -46,7 +46,7 @@ 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
 note that this might not be the latest version of Varnish.  If you
-need a later version of Varnish, please follow the installation
+need a later version of Varnish, please follow the online installation
 instructions for `Debian
 <http://www.varnish-cache.org/installation/debian>`_ or `Ubuntu
 <http://www.varnish-cache.org/installation/ubuntu>`_.
@@ -92,10 +92,10 @@ If you're building from git, you also need the following:
 * python-docutils
 * python-sphinx (optional, if you want to build the documentation)
 
-Build dependencies on Red Hat / CentOS
+Build dependencies on RedHat / CentOS
 --------------------------------------
 
-To build Varnish on a Red Hat or CentOS system you need the following
+To build Varnish on a RedHat or CentOS system you need the following
 packages installed:
 
 * automake
@@ -115,8 +115,8 @@ If you're building from git, you also need the following:
 Compiling Varnish
 -----------------
 
-Next, configuration: The configuration will need the dependencies
-above satisfied. Once that is taken care of::
+The configuration will need the dependencies above satisfied. Once that is
+taken care of::
 
 	cd varnish-cache
 	sh autogen.sh
@@ -124,7 +124,7 @@ above satisfied. Once that is taken care of::
 	make
 
 The ``configure`` script takes some arguments, but more likely than
-not, you can forget about that for now, almost everything in Varnish
+not you can forget about that for now, almost everything in Varnish
 are run time parameters.
 
 Before you install, you may want to run the test suite, make a cup of
@@ -143,10 +143,11 @@ Installing
 
 And finally, the true test of a brave heart::
 
-	make install
+	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.
 
 You can now proceed to the :ref:`tutorial-index`.
+
diff --git a/doc/sphinx/installation/platformnotes.rst b/doc/sphinx/installation/platformnotes.rst
index bacc57e..a7d3fb4 100644
--- a/doc/sphinx/installation/platformnotes.rst
+++ b/doc/sphinx/installation/platformnotes.rst
@@ -2,6 +2,10 @@
 Platform specific notes
 ------------------------
 
+On some platforms it is necessary to adjust the operating system before running
+Varnish on it. The systems and steps known to us are described in this section.
+
+
 Transparent hugepages on Redhat Enterprise Linux 6
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -12,7 +16,8 @@ It is recommended to disable transparent hugepages on affected systems::
 
     $ echo "never" > /sys/kernel/mm/redhat_transparent_hugepage/enabled
 
-On Debian/Ubuntu systems running 3.2 kernels the default value is "madvise" and does not need to changed.
+On Debian/Ubuntu systems running 3.2 kernels the default value is "madvise" and
+does not need to be changed.
 
 
 OpenVZ
@@ -38,12 +43,12 @@ in the Varnish startup script.
 TCP keep-alive configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-On some 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 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.
+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
+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:

More information about the varnish-commit mailing list