Add skeleton vtc manpage

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:

doc/sphinx/reference/vtc.rst

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

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 \