[master] e2161bc Add skeleton vtc manpage

[Guillaume Quintard]

commit e2161bcfe37ec75fcc0c6a9ceef6124770415864
Author: Guillaume Quintard <guillaume at varnish-software.com>
Date:   Mon May 30 16:16:57 2016 +0200

    Add skeleton vtc manpage

diff --git a/doc/sphinx/reference/index.rst b/doc/sphinx/reference/index.rst
index 603d1a0..917fe60 100644
--- a/doc/sphinx/reference/index.rst
+++ b/doc/sphinx/reference/index.rst
@@ -26,6 +26,7 @@ The Varnish Reference Manual
 	varnish-counters.rst
 	vsl.rst
 	vsl-query.rst
+	vtc.rst
 
 .. todo::
 	The programs:
diff --git a/doc/sphinx/reference/vtc.rst b/doc/sphinx/reference/vtc.rst
new file mode 100644
index 0000000..443015b
--- /dev/null
+++ b/doc/sphinx/reference/vtc.rst
@@ -0,0 +1,76 @@
+.. role:: ref(emphasis)
+
+.. _vtc(7):
+
+===
+VTC
+===
+
+------------------------
+Varnish Test Case Syntax
+------------------------
+
+:Manual section: 7
+
+OVERVIEW
+========
+
+This document describes the syntax used by Varnish Test Cases files (.vtc).
+A vtc file describe a scenario with different scripted HTTP-talking entities,
+and generally one or more Varnish instances to test.
+
+PARSING
+=======
+
+A vtc file will be read word after word, with very little tokenization, meaning
+a syntax error won't be detected until the test actually reach the relevant
+action in the test.
+
+A parsing error will most of the time result in an assert being triggered. If
+this happens, please refer yourself to the related source file and line
+number. However, this guide should help you avoid the most common mistakes.
+
+Words and strings
+~~~~~~~~~~~~~~~~~
+
+The parser splits words by detecting whitespace characters and a string is a
+word, or a series of words on the same line enclosed by double-quotes ("..."),
+or, for multi-line strings, enclosed in curly brackets ({...}).
+
+Comments
+~~~~~~~~
+
+The leading whitespaces of lines are ignored. Empty lines (or ones consisting
+only of whitespaces) are ignored too, as are the lines starting with "#" that
+are comments.
+
+Lines and commands
+~~~~~~~~~~~~~~~~~~
+
+Test files take at most one command per line, with the first word of the line
+being the command and the following ones being its arguments. To continue over
+to a new line without breaking the argument string, you can escape the newline
+character (\n) with a backslash (\).
+
+SYNTAX
+======
+
+.. include:: ../include/vtc-syntax.rst
+
+HISTORY
+=======
+
+This document has been written by Guillaume Quintard.
+
+SEE ALSO
+========
+
+* :ref:`varnishtest(1)`
+
+COPYRIGHT
+=========
+
+This document is licensed under the same licence as Varnish
+itself. See LICENCE for details.
+
+* Copyright (c) 2006-2016 Varnish Software AS
diff --git a/doc/sphinx/vtc-syntax.awk b/doc/sphinx/vtc-syntax.awk
new file mode 100644
index 0000000..ef67591
--- /dev/null
+++ b/doc/sphinx/vtc-syntax.awk
@@ -0,0 +1,41 @@
+# end of paragraph if we hit '*/'
+$0 ~ "*/" {
+	p = 0;
+}
+
+# if in paragraph and no section is announced,
+# concatenate
+p && $0 !~ "[ /]* SECTION: " {
+	cl[section] = cl[section]  gensub(/ \* ?/, "", "1", $0) "\n";
+}
+
+# section announcement
+$0 ~ "[ /]* SECTION: " {
+	section = $3;
+	sl[len++] = section;
+	tl[section] = gensub(/[\t ]*\/?\* SECTION: [^ ]+ +/, "", "1", $0);
+	p = 1;
+}
+
+# sort sections, underline titles, print
+END {
+	asort(sl);
+	for (i in sl) {
+		section = sl[i]
+		print(tl[section]);
+		a = section
+		c = gsub(/\./, "", a);
+		if (c == 0)
+			r = "=";
+		else if (c == 1)
+			r = "*"
+		else if (c == 2)
+			r = "+"
+		else if (c == 3)
+			r = "-"
+		else
+			r = "."
+		print(gensub(/./, r, "g", tl[section]));
+		print(cl[section]);
+	}
+}
diff --git a/doc/sphinx/vtc-syntax.vtc b/doc/sphinx/vtc-syntax.vtc
deleted file mode 100644
index ef67591..0000000
--- a/doc/sphinx/vtc-syntax.vtc
+++ /dev/null
@@ -1,41 +0,0 @@
-# end of paragraph if we hit '*/'
-$0 ~ "*/" {
-	p = 0;
-}
-
-# if in paragraph and no section is announced,
-# concatenate
-p && $0 !~ "[ /]* SECTION: " {
-	cl[section] = cl[section]  gensub(/ \* ?/, "", "1", $0) "\n";
-}
-
-# section announcement
-$0 ~ "[ /]* SECTION: " {
-	section = $3;
-	sl[len++] = section;
-	tl[section] = gensub(/[\t ]*\/?\* SECTION: [^ ]+ +/, "", "1", $0);
-	p = 1;
-}
-
-# sort sections, underline titles, print
-END {
-	asort(sl);
-	for (i in sl) {
-		section = sl[i]
-		print(tl[section]);
-		a = section
-		c = gsub(/\./, "", a);
-		if (c == 0)
-			r = "=";
-		else if (c == 1)
-			r = "*"
-		else if (c == 2)
-			r = "+"
-		else if (c == 3)
-			r = "-"
-		else
-			r = "."
-		print(gensub(/./, r, "g", tl[section]));
-		print(cl[section]);
-	}
-}
diff --git a/man/Makefile.am b/man/Makefile.am
index adb76c2..f27934b 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -13,6 +13,7 @@ dist_man_MANS = \
 	varnishncsa.1 \
 	varnishstat.1 \
 	varnishtest.1 \
+	vtc.7 \
 	varnishtop.1 \
 	vmod_directors.3 \
 	vmod_std.3
@@ -66,6 +67,9 @@ varnishstat.1: $(top_srcdir)/doc/sphinx/reference/varnishstat.rst \
 varnishtest.1: $(top_srcdir)/doc/sphinx/reference/varnishtest.rst
 	${RST2MAN} $(RST2ANY_FLAGS) $(top_srcdir)/doc/sphinx/reference/varnishtest.rst $@
 
+vtc.7: $(top_srcdir)/doc/sphinx/reference/vtc.rst
+	${RST2MAN} $(RST2ANY_FLAGS) $(top_srcdir)/doc/sphinx/reference/vtc.rst $@
+
 varnishtop.1: \
 	$(top_srcdir)/doc/sphinx/reference/varnishtop.rst \
 	$(top_builddir)/doc/sphinx/include/varnishtop_options.rst \