[master] 93c5e39 header style consistency
Per Buer
perbu at varnish-cache.org
Thu Mar 7 10:36:33 CET 2013
commit 93c5e395e3c95cd7aee0fe679ef2b0913e978d35
Author: Per Buer <perbu at varnish-software.com>
Date: Thu Mar 7 10:34:52 2013 +0100
header style consistency
diff --git a/doc/sphinx/include/vcl-syntax.rst b/doc/sphinx/include/vcl-syntax.rst
deleted file mode 100644
index 441aa06..0000000
--- a/doc/sphinx/include/vcl-syntax.rst
+++ /dev/null
@@ -1,65 +0,0 @@
-VCL SYNTAX
-==========
-
-The VCL syntax is very simple, and deliberately similar to C and Perl.
-Blocks are delimited by curly braces, statements end with semicolons,
-and comments may be written as in C, C++ or Perl according to your own
-preferences.
-
-In addition to the C-like assignment (=), comparison (==, !=) and
-boolean (!, && and \|\|) operators, VCL supports both regular
-expression and ACL matching using the ~ and the !~ operators.
-
-Basic strings are enclosed in " ... ", and may not contain newlines.
-
-Long strings are enclosed in {" ... "}. They may contain any
-character including ", newline and other control characters except
-for the NUL (0x00) character.
-
-Unlike C and Perl, the backslash (\) character has no special meaning
-in strings in VCL, so it can be freely used in regular expressions
-without doubling.
-
-Strings are concatenated using the '+' operator.
-
-Assignments are introduced with the *set* keyword. There are no
-user-defined variables; values can only be assigned to variables
-attached to backend, request or document objects. Most of these are
-typed, and the values assigned to them must have a compatible unit
-suffix.
-
-You can use the *set* keyword to arbitrary HTTP headers. You can
-remove headers with the *remove* or *unset* keywords, which are
-synonym.
-
-You can use the *rollback* keyword to revert any changes to req at
-any time.
-
-The *synthetic* keyword is used to produce a synthetic response
-body in vcl_error. It takes a single string as argument.
-
-You can force a crash of the client process with the *panic* keyword.
-*panic* takes a string as argument.
-
-The ``return(action)`` keyword terminates the subroutine. *action* can be,
-depending on context one of
-
-* deliver
-* error
-* fetch
-* hash
-* hit_for_pass
-* lookup
-* ok
-* pass
-* pipe
-* restart
-
-Please see the list of subroutines to see what return actions are
-available where.
-
-VCL has if tests, but no loops.
-
-The contents of another VCL file may be inserted at any point in the
-code by using the *include* keyword followed by the name of the other
-file as a quoted string.
diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst
index 1cc29c6..b3f734b 100644
--- a/doc/sphinx/index.rst
+++ b/doc/sphinx/index.rst
@@ -1,6 +1,21 @@
.. Varnish documentation master file, created by
sphinx-quickstart on Tue Apr 20 13:02:15 2010.
+.. We use the following header indicators
+
+.. For titles:
+
+.. H1
+.. %%%%%
+.. Title
+.. %%%%%
+
+.. H2 - H5
+.. ======================
+.. ----------------------
+.. ~~~~~~~~~~~~~~~~~~~~~~
+.. ......................
+
Welcome to Varnish's documentation!
===================================
diff --git a/doc/sphinx/installation/index.rst b/doc/sphinx/installation/index.rst
index 15b61eb..b1e0a23 100644
--- a/doc/sphinx/installation/index.rst
+++ b/doc/sphinx/installation/index.rst
@@ -15,7 +15,6 @@ move traffic.
install.rst
help.rst
bugs.rst
- upgrade.rst
platformnotes.rst
diff --git a/doc/sphinx/installation/install.rst b/doc/sphinx/installation/install.rst
index 4a836ff..cf7501f 100644
--- a/doc/sphinx/installation/install.rst
+++ b/doc/sphinx/installation/install.rst
@@ -11,14 +11,14 @@ are 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
being:
FreeBSD
-~~~~~~~
+-------
From source:
``cd /usr/ports/varnish && make install clean``
@@ -26,7 +26,7 @@ Binary package:
``pkg_add -r varnish``
CentOS/RedHat
-~~~~~~~~~~~~~
+-------------
We try to keep the latest version available as prebuilt RPMs (el5) on
`repo.varnish-cache.org <http://repo.varnish-cache.org/>`. See the
@@ -42,7 +42,7 @@ the latest version there is Varnish 2.0.6.
EPEL6 should have Varnish 2.1 available once it releases.
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
@@ -53,7 +53,7 @@ instructions for `Debian
<http://www.varnish-cache.org/installation/ubuntu>`.
Other systems
-~~~~~~~~~~~~~
+-------------
You are probably best of compiling your own code. See `Compiling
Varnish from source`_.
@@ -82,7 +82,7 @@ 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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------------
In order to build Varnish from source you need a number of packages
installed. On a Debian or Ubuntu system these are:
@@ -97,7 +97,7 @@ installed. On a Debian or Ubuntu system these are:
* pkg-config
Build dependencies on Red Hat / CentOS
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------------
To build Varnish on a Red Hat or CentOS system you need the following
packages installed:
@@ -111,7 +111,7 @@ packages installed:
* pkgconfig
Configuring and compiling
-~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------
Next, configuration: The configuration will need the dependencies
above satisfied. Once that is taken care of::
@@ -137,7 +137,7 @@ fails, something is horribly wrong, and you will get nowhere without
figuring out what.
Installing
-~~~~~~~~~~
+----------
And finally, the true test of a brave heart::
diff --git a/doc/sphinx/installation/prerequisites.rst b/doc/sphinx/installation/prerequisites.rst
index f42c37a..3508c1e 100644
--- a/doc/sphinx/installation/prerequisites.rst
+++ b/doc/sphinx/installation/prerequisites.rst
@@ -7,7 +7,7 @@ In order for you to install Varnish you must have the following:
* A fairly modern and 64 bit version of either
- Linux
- FreeBSD
- - Solaris
+ - Solaris (x86 only)
* root access to said system
@@ -19,4 +19,5 @@ time, said to work on:
* OS X
* NetBSD
* OpenBSD
+ * Windows with Cygwin
diff --git a/doc/sphinx/installation/upgrade.rst b/doc/sphinx/installation/upgrade.rst
deleted file mode 100644
index 93446ea..0000000
--- a/doc/sphinx/installation/upgrade.rst
+++ /dev/null
@@ -1,172 +0,0 @@
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-Upgrading from Varnish 2.1 to 3.0
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-This is a compilation of items you need to pay attention to when upgrading from Varnish 2.1 to 3.0
-
-Changes to VCL
-==============
-
-In most cases you need to update your VCL since there has been some changes to the syntax.
-
-string concatenation operator
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-String concatenation did not have an operator previously, but this has now been changed to ``+``.
-
-no more %-escapes in strings
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-To simplify strings, the %-encoding has been removed. If you need non-printable characters, you need to use inline C.
-
-``log`` moved to the std vmod
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-``log`` has moved to the std vmod::
-
- log "log something";
-
-becomes::
-
- import std;
- std.log("log something");
-
-You only need to import std once.
-
-purges are now called bans
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-``purge()`` and ``purge_url()`` are now respectively ``ban()`` and ``ban_url()``, so you should replace all occurences::
-
- purge("req.url = " req.url);
-
-becomes::
-
- ban("req.url = " + req.url);
-
-``purge`` does not take any arguments anymore, but can be used in vcl_hit or vcl_miss to purge the item from the cache, where you would reduce ttl to 0 in Varnish 2.1::
-
- sub vcl_hit {
- if (req.request == "PURGE") {
- set obj.ttl = 0s;
- error 200 "Purged.";
- }
- }
-
-becomes::
-
- sub vcl_hit {
- if (req.request == "PURGE") {
- purge;
- error 200 "Purged.";
- }
- }
-
-``beresp.cacheable`` and ``obj.cacheable`` are gone
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-``beresp.cacheable`` is gone, and can be replaced with ``beresp.ttl > 0s``. Similarly ``obj.cacheable`` can be replaced with ``obj.ttl > 0s``.
-
-returns are now done with the ``return()`` function
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-``pass``, ``pipe``, ``lookup``, ``deliver``, ``fetch``, ``hash``, ``pipe`` and ``restart`` are no longer keywords, but arguments to ``return()``, so::
-
- sub vcl_pass {
- pass;
- }
-
-becomes::
-
- sub vcl_pass {
- return(pass);
- }
-
-
-``req.hash`` is replaced with ``hash_data()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You no longer append to the hash with ``+=``, so::
-
- set req.hash += req.url;
-
-becomes::
-
- hash_data(req.url);
-
-``esi`` is replaced with ``beresp.do_esi``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You no longer enable ESI with ``esi``, so::
-
- esi;
-
-in ``vcl_fetch`` becomes::
-
- set beresp.do_esi = true;
-
-``pass`` in ``vcl_fetch`` renamed to ``hit_for_pass``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The difference in behaviour of ``pass`` in ``vcl_recv`` and
-``vcl_fetch`` confused people, so to make it clearer that they are
-different, you must now do ``return(hit_for_pass)`` when doing a pass
-in ``vcl_fetch``.
-
-Changes to runtime parameters
-=============================
-
-Deleted parameters
-~~~~~~~~~~~~~~~~~~
-
-``cache_vbe_conns`` and ``err_ttl`` has been removed.
-
-New parameters
-~~~~~~~~~~~~~~
-
-The following parameters have been added, see man varnishd for reference:
-
-* ``default_keep``
-* ``expiry_sleep``
-* ``fetch_maxchunksize``
-* ``gzip_level``
-* ``gzip_memlevel``
-* ``gzip_stack_buffer``
-* ``gzip_tmp_space``
-* ``gzip_window``
-* ``http_gzip_support``
-* ``http_req_hdr_len``
-* ``http_req_size``
-* ``http_resp_hdr_len``
-* ``http_resp_size``
-* ``shortlived``
-* ``thread_pool_workspace``
-* ``vcc_err_unref``
-* ``vcl_dir``
-* ``vmod_dir``
-
-Changed default values
-~~~~~~~~~~~~~~~~~~~~~~
-
-The following parameters have new defaults:
-
-* ``ban_lurker_sleep`` changed from 0 to 0.01 seconds, enabling the ban lurker by default.
-* ``connect_timeout`` changed from 0.4 to 0.7 seconds.
-* ``log_hashstring`` changed from off to on.
-* ``send_timeout`` changed from 600 to 60 seconds.
-* ``thread_pool_add_delay`` changed from 20 to 2 ms.
-
-Changed parameter names
-~~~~~~~~~~~~~~~~~~~~~~~
-
-The following parameters have new names:
-
-* ``http_headers`` has been renamed to ``http_max_hdr``.
-* ``max_esi_includes`` has been renamed to ``max_esi_depth``.
-* ``overflow_max`` has been renamed to ``queue_max``.
-* ``purge_dups`` has been renamed to ``ban_dups``.
-
-Changes to behaviour
-====================
-
-Varnish will return an error when headers are too large instead of just ignoring them. If the limits are too low, Varnish will return HTTP 413. You can change the limits by increasing http_req_hdr_len and http_req_size.
-
-thread_pool_max is now per thread pool, while it was a total across all pools in 2.1. If you had this set in 2.1, you should adjust it for 3.0.
More information about the varnish-commit
mailing list