[master] e2161bc Add skeleton vtc manpage
Guillaume Quintard
guillaume at varnish-software.com
Mon Jun 6 11:01:08 CEST 2016
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 \
More information about the varnish-commit
mailing list