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

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

doc/sphinx/reference/vsl.rst

 .. _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

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)

lib/libvarnishapi/vsl2rst.c

+/*-
+ * Copyright (c) 2011-2013 Varnish Software AS
+ * All rights reserved.
+ *
+ * Author: Martin Blix Grydeland <martin@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);
+}

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