Update docs

2 files changed, 31 insertions, 2 deletions

diff --git a/README b/README
index 821de7f..b815aff 100644
--- a/README
+++ b/README
@@ -12,13 +12,13 @@ For accessing complete vmod-variable documentation, see the section
 
 For a list of differences between this module and vmod_var, see
 the section "vmod_variable vs. vmod_var".
 
 * Overview
 
-This module provides extended variable support for VCL scripts.
+This module provides enhanced variable support for VCL scripts.
 It compiles for Varnish versions 3 and 4.
 
 There are two kinds of variables: session-specific, which have the
 lifespan of one HTTP session (connection) and cease to exist when
 it is closed, and global, which are shared between all sessions.
 
diff --git a/src/vmod-variable.3 b/src/vmod-variable.3
index 6e4f8b6..5d5467d 100644
--- a/src/vmod-variable.3
+++ b/src/vmod-variable.3
@@ -18,13 +18,13 @@
 vmod-variable \- variable support for Varnish Cache
 .SH SYNOPSIS
 
 \fBimport variable\fR [\fIPATH\fR]\fB;\fR
 
 .SH DESCRIPTION
-This module provides extended variable support for \fBVCL\fR scripts.
+This module provides enhanced variable support for \fBVCL\fR scripts.
 .PP
 There are two kind of variables: \fIsession-specific\fR and \fIglobal\fR.
 Session-specific variables have a lifespan of one HTTP session and cease to
 exist when it is closed.  Such variables can be of almost any VCL type:
 .BR STRING ,
 .BR INT ,
@@ -40,14 +40,42 @@ patterns.
 .PP
 The \fBqueryset\fR function parses its input as a HTTP query string and
 sets the variables defined in it.
 .PP
 The \fIglobal\fR variables are shared between all threads and sessions.  They
 can hold only string values.
+.SH VMOD_VARIABLE VS. VMOD_VAR
+This module doesn't share any code with \fBvmod_var\fR.  Compared with
+the latter, it provides the following new features:
+.PP
+.nr step 1 1
+.IP \n[step].
+Both Varsnish 3 and 4 are supported;
+.IP \n+[step].
+Variables are stored in hash tables with open addressing, to
+speed up accesses (\fBvmod_var\fR keeps them in singly-linked lists).
+.IP \n+[step].
+Functions for testing existence and types of variables, and for
+unsetting a variable:
+.BR defined() ,
+.BR type_of() ", and"
+.BR unset() .
+.IP \n+[step].
+The \fBregset()\fR and \fBqueryset()\fR functions.
+.IP \n+[step].
+Additional functions for global variables:
+.BR global_clear() ,
+.BR global_defined() ", and"
+.BR global_unset() .
+.PP
+To facilitate transition, \fBvmod_variable\fR uses the same naming
+scheme as \fBvmod_var\fR, so switching to using it in your VCL script
+is as simple as replacing \fBs/var\\./variable./\fR.
 .SH FUNCTIONS
 The function below operate on session-local variables.
+.PP
 .TP
 \fBVOID set(STRING \fIname\fB, STRING \fIvalue\fB)\fR
 Assigns \fIvalue\fR to the string variable \fIname\fR.
 .TP
 \fBSTRING get(STRING \fIname\fB)\fR
 Returns value of the string variable \fIname\fR.  If the variable is not
@@ -144,12 +172,13 @@ Returns type of the variable \fIname\fR.  Available types are:
 \fBVOID unset(STRING \fIname\fB)\fR
 Unsets the variable \fIname\fR.
 .SS Global variables
 .PP
 The functions below operate on global variables.  Global variables can
 be hold only string values.
+.PP
 .TP
 \fBVOID global_set(STRING \fIname\fB, STRING \fIvalue\fB)\fR
 Assigns \fIvalue\fR to the global variable \fIname\fR.
 .TP
 \fBSTRING global_get(STRING \fIname\fB)\fR
 Returns value of the global variable \fIname\fR.  If the variable is not