[master] 1cd1d7a Generate the VSL record tag documentation from the header tables.
Martin Blix Grydeland
martin at varnish-cache.org
Wed Oct 16 14:39:13 CEST 2013
commit 1cd1d7a53ce4deae18bf4bacbf29cd1a7b54ec5c
Author: Martin Blix Grydeland <martin at varnish-software.com>
Date: Wed Oct 16 12:12:51 2013 +0200
Generate the VSL record tag documentation from the header tables.
This patch generates an rst file containing the record tag
documentation from the corresponding header tables.
It also adds a man-page from the vsl.rst document and includes the tag
descriptions.
The old list of tags in varnishlog.rst is removed.
Fixes: #1338
diff --git a/doc/sphinx/reference/varnishlog.rst b/doc/sphinx/reference/varnishlog.rst
index 6021fd4..f4cb33c 100644
--- a/doc/sphinx/reference/varnishlog.rst
+++ b/doc/sphinx/reference/varnishlog.rst
@@ -54,62 +54,6 @@ SIGNALS
Flush any outstanding transactions
-TAGS
-====
-The following log entry tags are currently defined:
-
-* Backend
-* BackendClose
-* BackendOpen
-* BackendReuse
-* BackendXID
-* CLI
-* ClientAddr
-* Debug
-* Error
-* ExpBan
-* ExpKill
-* ExpPick
-* Hit
-* HitPass
-* HttpError
-* HttpGarbage
-* Length
-* ObjHeader
-* ObjLostHeader
-* ObjProtocol
-* ObjRequest
-* ObjResponse
-* ObjStatus
-* ObjURL
-* ReqEnd
-* ReqStart
-* RxHeader
-* RxLostHeader
-* RxProtocol
-* RxRequest
-* RxResponse
-* RxStatus
-* RxURL
-* SessionClose
-* SessionOpen
-* StatAddr
-* StatSess
-* TTL
-* TxHeader
-* TxLostHeader
-* TxProtocol
-* TxRequest
-* TxResponse
-* TxStatus
-* TxURL
-* VCL_acl
-* VCL_call
-* VCL_return
-* VCL_trace
-* WorkThread
-
-
SEE ALSO
========
* varnishd(1)
@@ -117,6 +61,7 @@ SEE ALSO
* varnishncsa(1)
* varnishstat(1)
* varnishtop(1)
+* vsl(7)
* vsl-query(7)
HISTORY
diff --git a/doc/sphinx/reference/vsl.rst b/doc/sphinx/reference/vsl.rst
index e9f2ff3..dbe789d 100644
--- a/doc/sphinx/reference/vsl.rst
+++ b/doc/sphinx/reference/vsl.rst
@@ -1,8 +1,18 @@
.. _reference-vsl:
-=====================
+===
+VSL
+===
+
+---------------------
Shared Memory Logging
-=====================
+---------------------
+
+:Author: Poul-Henning Kamp
+:Author: Martin Blix Grydeland
+:Date: 2013-10-16
+:Version: 1.0
+:Manual section: 7
TTL records
~~~~~~~~~~~
@@ -61,3 +71,10 @@ Examples::
U F E 182 159 80 80 1392
G F E 159 173 80 1304 1314
+
+VSL tags
+~~~~~~~~
+
+Alphabetical list of all the VSL log records with description:
+
+.. include:: ../../../lib/libvarnishapi/vsl-tags.rst
diff --git a/lib/libvarnishapi/Makefile.am b/lib/libvarnishapi/Makefile.am
index 6f36ef6..6316612 100644
--- a/lib/libvarnishapi/Makefile.am
+++ b/lib/libvarnishapi/Makefile.am
@@ -51,16 +51,31 @@ libvarnishapi_la_LDFLAGS += -export-symbols-regex '^V'
endif
EXTRA_DIST = \
- generate.py
+ generate.py \
+ vsl-tags.rst
BUILT_SOURCES = \
vxp_fixed_token.c \
- vxp_tokens.h
+ vxp_tokens.h \
+ vsl-tags.rst
CLEANFILES = \
$(builddir)/vxp_fixed_token.c \
$(builddir)/vxp_tokens.h
+MAINTAINERCLEANFILES = \
+ vsl-tags.rst
+
+noinst_PROGRAMS = vsl2rst
+
+vsl2rst_SOURCES = \
+ vsl2rst.c \
+ $(top_srcdir)/include/tbl/vsl_tags.h \
+ $(top_srcdir)/include/tbl/vsl_tags_http.h
+
+vsl-tags.rst: vsl2rst
+ ./vsl2rst > $@
+
vxp_fixed_token.c vxp_tokens.h: \
$(srcdir)/generate.py
@PYTHON@ $(srcdir)/generate.py $(srcdir) $(top_builddir)
diff --git a/lib/libvarnishapi/vsl2rst.c b/lib/libvarnishapi/vsl2rst.c
new file mode 100644
index 0000000..41ee69c
--- /dev/null
+++ b/lib/libvarnishapi/vsl2rst.c
@@ -0,0 +1,113 @@
+/*-
+ * Copyright (c) 2011-2013 Varnish Software AS
+ * All rights reserved.
+ *
+ * Author: Martin Blix Grydeland <martin at varnish-software.com>
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in the
+ * documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
+ * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+ * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+ * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ *
+ */
+
+#include "config.h"
+
+#include <stdio.h>
+#include <stdint.h>
+#include <stdlib.h>
+#include <string.h>
+#include <assert.h>
+
+#include "vapi/vsl.h"
+
+struct SLT {
+ unsigned tag;
+ const char *name;
+ const char *sdesc;
+ const char *ldesc;
+};
+
+static struct SLT tags[SLT__MAX] = {
+#define SLTM(name, sdesc, ldesc) \
+ [SLT_##name] = { SLT_##name, #name, sdesc, ldesc },
+#include "tbl/vsl_tags.h"
+#undef SLTM
+};
+
+static int
+ptag_cmp(const void *va, const void *vb)
+{
+ const struct SLT *a, *b;
+
+ a = *(const struct SLT * const *)va;
+ b = *(const struct SLT * const *)vb;
+ if (a->name == NULL && b->name != NULL)
+ return (1);
+ else if (a->name != NULL && b->name == NULL)
+ return (-1);
+ else if (a->name == NULL && b->name == NULL)
+ return (0);
+ return (strcmp(a->name, b->name));
+}
+
+static void
+print_tabbed(const char *string, int tabs)
+{
+ int i;
+ const char *c;
+
+ for (c = string; *c; c++) {
+ if (c == string || *(c - 1) == '\n')
+ for (i = 0; i < tabs; i++)
+ printf("\t");
+ printf("%c", *c);
+ }
+}
+
+int
+main(int argc, char *argv[])
+{
+ int i;
+ struct SLT *ptags[SLT__MAX];
+
+ (void)argc;
+ (void)argv;
+
+ for (i = 0; i < SLT__MAX; i++)
+ ptags[i] = &tags[i];
+
+ qsort(&ptags, SLT__MAX, sizeof *ptags, &ptag_cmp);
+
+ for (i = 0; i < SLT__MAX; i++) {
+ if (ptags[i]->name == NULL || !strcmp(ptags[i]->name, ""))
+ continue;
+ printf("* %s", ptags[i]->name);
+ if (ptags[i]->sdesc != NULL && strcmp(ptags[i]->sdesc, ""))
+ printf(" (%s)", ptags[i]->sdesc);
+ printf("\n\n");
+ if (ptags[i]->ldesc != NULL && strcmp(ptags[i]->ldesc, "")) {
+ printf("\t::\n\n");
+ print_tabbed(ptags[i]->ldesc, 2);
+ printf("\n\n");
+ }
+ }
+
+ return (0);
+}
diff --git a/man/Makefile.am b/man/Makefile.am
index cc32a4b..878e7f4 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -8,7 +8,7 @@ vsc2rst_SOURCES = vsc2rst.c \
AM_CPPFLAGS = -I$(top_srcdir)/include
-dist_man_MANS = vcl.7 varnish-cli.7 varnish-counters.7
+dist_man_MANS = vcl.7 varnish-cli.7 varnish-counters.7 vsl.7
MAINTAINERCLEANFILES = $(dist_man_MANS)
vcl.7: $(top_srcdir)/doc/sphinx/reference/vcl.rst \
@@ -42,3 +42,14 @@ varnish-counters.7: $(top_srcdir)/include/tbl/vsc_fields.h
@echo "========================================"
@false
endif
+
+vsl.7: $(top_srcdir)/doc/sphinx/reference/vsl.rst \
+ $(top_srcdir)/lib/libvarnishapi/vsl-tags.rst
+if HAVE_RST2MAN
+ ${RST2MAN} $(top_srcdir)/doc/sphinx/reference/vsl.rst $@
+else
+ @echo "========================================"
+ @echo "You need rst2man installed to make dist"
+ @echo "========================================"
+ @false
+endif
More information about the varnish-commit
mailing list