Improve manpage.

1 files changed, 90 insertions, 137 deletions

diff --git a/doc/vmod-dbrw.3 b/doc/vmod-dbrw.3
index 9b6d9f5..9496270 100644
--- a/doc/vmod-dbrw.3
+++ b/doc/vmod-dbrw.3
@@ -13,138 +13,37 @@
 .\"
 .\" You should have received a copy of the GNU General Public License
 .\" along with vmod-dbrw.  If not, see <http://www.gnu.org/licenses/>.
-.TH VMOD_DBRW 1 "July 26, 2013" "VMOD_DBRW" "User Reference"
+.TH VMOD_DBRW 1 "July 27, 2013" "VMOD_DBRW" "User Reference"
 .SH NAME
 vmod-dbrw \- Database-driven rewrite rules for Varnish Cache
 .SH SYNOPSIS
-.sp
-.nf
-import dbrw;
-
-sub vcl_init {
-    dbrw.config("\fIDBTYPE\fR", "\fIPARAMS\fR", "\fIQUERY\fR");
-}
-
-sub vcl_recv {
-    set req.http.\fIXHEADER\fR = dbrw.rewrite(\fIARGS\fR);
-    if (req.http.\fIXHEADER\fR) {
-        error(750, "Redirect");
-    }
-}
-
-sub vcl_error {
-    if (obj.status == 750) {
-        set obj.http.Location = req.http.\fIXHEADER\fR;
-        set obj.status = 301;
-        return (deliver);
-    }
-}
-.fi
+.B import dbrw;
+.br
+.BI "VOID dbrw.config(STRING " dbtype ", STRING " params ", STRING " query ");"
+.br
+.BI "STRING dbrw.rewrite(STRING " args ");"
 .SH DESCRIPTION
 .B Vmod-dbrw
 is a Varnish Cache module implementing database-driven rewrite procedures.
 Its intended use is for web sites that need an exceedingly big number
 of redirect and/or rewrite rules.
 .PP
-Upon startup, the \fBconfig\fR function should be called.  This call
-configures the module and supplies it the information necessary for
-accessing the database and interpreting the data obtained from it.
+The \fBconfig\fR function should be called upon startup, in \fBsub
+vcl_init\fR.  It configures the module and supplies it the information
+necessary for accessing the database and interpreting the data
+obtained from it.
 .PP
-Two database types are supported: \fBMySQL\fR or \fBPostgreSQL\fR.
-The first argument \fBconfig\fR instructs the module which type to
-use.
+The \fIdbtype\fR argument specifies the database type to use.
+Valid values are \fBmysql\fR (for \fBMySQL\fR) and \fBpgsql\fR (for
+\fBPostgreSQL\fR).
 .PP
 .B Vmod-dbrw
 does not impose any requirements on the structure of the database,
 therefore the connection arguments and access credentials may vary
 depending on the flavor of the database used.  This information is
-supplied in the \fIPARAMS\fR argument, which is a list of parameter
-assignments separated with semicolons.
-.PP
-Once configured, the \fBrewrite\fR function can be called in the
-appropriate place of the Varnish configuration file.  Its argument
-\fIARGS\fR is a list of variable assignments separated with
-semicolons, similarly to the \fIPARAMS\fR argument described above.
-Each assignment has the form \fINAME\fB=\fIVALUE\fR.  When called
-the function expands the \fBSQL\fR query, supplied with the \fIQUERY\fR
-argument to the \fBconfig\fR call, by replacing each \fB$\fINAME\fR
-construct (a \fBvariable reference\fR) with the corresponding
-\fIVALUE\fR from its argument.  Similarly to the shell syntax, the
-variable reference can be written as \fB${\fINAME\fB}\fR.  This latter
-form can be used in contexts where the variable name is immediately
-followed by another letter, to prevent it from being counted as a part
-of the name.
-.PP
-The expanded query is then sent to the database server.  The handling
-of the return value depends on the number of fields it contains.
-.SS Strict matches
-If the returned set consists of one or two columns, only the
-first tuple is used and the value of its first column is returned.
-The second column (if present) is ignored.
-.SS Regexp matches
-Otherwise, if the returned set consists of three or four columns, the
-columns are interpreted as follows: \fBresult\fR, \fBregexp\fR,
-\fBvalue\fR and optional \fBflags\fR.  For each returned tuple, the
-\fBvalue\fR column undergoes variable expansion, using the same
-algorithm as when preparing the query, and the resulting string is
-matched with the \fBregexp\fR column, which is treated as an extended
-\fBPOSIX\fR regular expression.  If the match occurs, the \fBresult\fR
-column is expanded by replacing \fBbackreferences\fR.  Each occurrence
-of \fB$\fIDIGIT\fR (where \fIDIGIT\fR stands for a decimal digit from
-\fB0\fR through \fB9\fR) is replaced with the contents of the
-\fIDIGIT\fR's parenthesized subexpression in \fBregexp\fR.  For
-compatibility with the traditional usage, the \fB\\\fIDIGIT\fR
-notation is also allowed.  The resulting value is returned.
-.PP
-Optional \fBflags\fR column is a comma-separated list of flags that
-modify regular expression handling.  The following flags are defined:
-.TP
-.BR NC " or " nocase
-Treat \fBregexp\fR as case-insensitive.
-.TP
-.B case
-Treat \fBregexp\fR as case-sensitive (default).
-.TP
-.BR QSA " or " qsappend
-Treat the resulting value as URL; append any query string from the
-original \fBvalue\fR to it.
-.TP
-.BR QSD " or " qsdiscard
-Treat the resulting value as URL; discard any query string attached to
-the original \fBvalue\fR.
-.TP
-\fBredirect=\fICODE\fR or \fBR=\fICODE\fR
-On success, set the \fBX\-VMOD\-DBRW\-Status\fR header to \fICODE\fR,
-which must be a valid HTTP status code. 
-.PP
-If \fBregexp\fR or \fBvalue\fR is NULL, the tuple is handled as
-described in
-.BR "Strict matches" .
-.PP
-If \fBflags\fR is NULL, it is ignored.
-.SH FUNCTIONS
-.SS config
-.TP
-.B Prototype
-config(STRING \fIDBTYPE\fR, STRING \fIPARAMS\fR, STRING \fIQUERY\fR)
-.TP
-.B Return value
-VOID
-.TP
-.B Description
-This function configures the module and supplies the data necessary to
-connect and use the database.
-.TP
-.B Arguments
-.RS 4
-.TP
-.I DBTYPE
-Type of the database.  Valid values are \fBmysql\fR (for \fBMySQL\fR)
-and \fBpgsql\fR (for \fBPostgreSQL\fR).
-.TP
-.I PARAMS
-Database connection parameters.  This is a list of
-\fINAME\fB=\fIVALUE\fR assignments separated with semicolons.  The
+supplied in the \fIparams\fR argument, which is a list of
+\fINAME\fB=\fIVALUE\fR assignments separated with semicolons.
+The
 \fIVALUE\fR can be any sequence of characters, excepting white space
 and semicolon.  If any of these have to appear in it, they must either
 be escaped by prepending them with a backslash, or entire \fIVALUE\fR
@@ -169,7 +68,6 @@ enclosed in a pair of (single or double) quotes.  The following
 Any other character following a backslash is output verbatim.
 .sp
 The valid parameters are:
-.RS 8
 .TP
 \fBdebug\fR=\fIN\fR
 Set debugging level.  \fIN\fR is a decimal number.
@@ -208,30 +106,71 @@ Database user name.
 .TP
 \fBpassword\fR=\fISTRING\fR
 Password to access the database.
-.RE
+.PP
+Once configured, the \fBrewrite\fR function can be called in the
+appropriate place of the Varnish configuration file.  Its argument
+\fIargs\fR is a list of variable assignments separated with
+semicolons, similarly to the \fIparams\fR argument described above.
+Each assignment has the form \fINAME\fB=\fIVALUE\fR.  When called
+the function expands the \fBSQL\fR query, supplied with the \fIquery\fR
+argument to the \fBconfig\fR call, by replacing each \fB$\fINAME\fR
+construct (a \fBvariable reference\fR) with the corresponding
+\fIVALUE\fR from its argument.  Similarly to the shell syntax, the
+variable reference can be written as \fB${\fINAME\fB}\fR.  This latter
+form can be used in contexts where the variable name is immediately
+followed by another letter, to prevent it from being counted as a part
+of the name.
+.PP
+The expanded query is then sent to the database server.  The handling
+of the return value depends on the number of fields it contains.
+.SS Strict matches
+If the returned set consists of one or two columns, only the
+first tuple is used and the value of its first column is returned.
+The second column (if present) is ignored.
+.SS Regexp matches
+Otherwise, if the returned set consists of three or four columns, the
+columns are interpreted as follows: \fBresult\fR, \fBregexp\fR,
+\fBvalue\fR and optional \fBflags\fR.  For each returned tuple, the
+\fBvalue\fR column undergoes variable expansion, using the same
+algorithm as when preparing the query, and the resulting string is
+matched with the \fBregexp\fR column, which is treated as an extended
+\fBPOSIX\fR regular expression.  If the match occurs, the \fBresult\fR
+column is expanded by replacing \fBbackreferences\fR.  Each occurrence
+of \fB$\fIDIGIT\fR (where \fIDIGIT\fR stands for a decimal digit from
+\fB0\fR through \fB9\fR) is replaced with the contents of the
+\fIDIGIT\fR's parenthesized subexpression in \fBregexp\fR.  For
+compatibility with the traditional usage, the \fB\\\fIDIGIT\fR
+notation is also allowed.  The resulting value is returned.
+.PP
+Optional \fBflags\fR column is a comma-separated list of flags that
+modify regular expression handling.  The following flags are defined:
 .TP
-.I QUERY
-\fBSQL\fR query to use.  It can contain variable references in the
+.BR NC " or " nocase
+Trea