[master] ac9a479 Renovate varnishd's usage message, and don't emit it until asked for it.
Poul-Henning Kamp
phk at FreeBSD.org
Tue Feb 28 11:19:05 CET 2017
commit ac9a4790d2acd04af8c8582db1b878b48149ab75
Author: Poul-Henning Kamp <phk at FreeBSD.org>
Date: Tue Feb 28 10:16:33 2017 +0000
Renovate varnishd's usage message, and don't emit it until asked for it.
Instead of alphabetical, sort the options by category.
Pull -x out of the shadows, despite the RST markup, the output
satisfies "instruction at the point of need".
diff --git a/bin/varnishd/Makefile.phk b/bin/varnishd/Makefile.phk
index 28d8e85..f018d00 100644
--- a/bin/varnishd/Makefile.phk
+++ b/bin/varnishd/Makefile.phk
@@ -126,7 +126,7 @@ include $(TOPDIR)/Makefile.inc.phk
$(PARST): $(PROGNAME)
-ls -l $(PARST) $(PROGNAME)
mkdir -p $(TOPDIR)/doc/sphinx/include
- ./varnishd -x dumprstparam > $(PARST)
+ ./varnishd -x parameter > $(PARST)
#
# Turn the builtin.vcl file into a C-string we can include in the program.
diff --git a/bin/varnishd/common/common.h b/bin/varnishd/common/common.h
index 27da283..0c302c2 100644
--- a/bin/varnishd/common/common.h
+++ b/bin/varnishd/common/common.h
@@ -66,6 +66,7 @@ void MCH_Fd_Inherit(int fd, const char *what);
#define ARGV_ERR(...) \
do { \
fprintf(stderr, "Error: " __VA_ARGS__); \
+ fprintf(stderr, "(-? gives usage)\n"); \
exit(2); \
} while (0)
diff --git a/bin/varnishd/mgt/mgt_main.c b/bin/varnishd/mgt/mgt_main.c
index e0c77ff..1eadebf 100644
--- a/bin/varnishd/mgt/mgt_main.c
+++ b/bin/varnishd/mgt/mgt_main.c
@@ -74,66 +74,80 @@ int optreset; // Some has it, some doesn't. Cheaper than auto*
/*--------------------------------------------------------------------*/
-static void
+static void
usage(void)
{
-#define FMT " %-28s # %s\n"
-
- fprintf(stderr, "usage: varnishd [options]\n");
- fprintf(stderr, FMT, "-a address[:port][,proto]",
- "HTTP listen address and port (default: *:80)");
- fprintf(stderr, FMT, "", " address: defaults to loopback");
- fprintf(stderr, FMT, "", " port: port or service (default: 80)");
- fprintf(stderr, FMT, "", " proto: HTTP/1 (default), PROXY");
- fprintf(stderr, FMT, "-b address[:port]", "backend address and port");
- fprintf(stderr, FMT, "", " address: hostname or IP");
- fprintf(stderr, FMT, "", " port: port or service (default: 80)");
- fprintf(stderr, FMT, "-C", "print VCL code compiled to C language");
- fprintf(stderr, FMT, "-d", "debug");
- fprintf(stderr, FMT, "-F", "Run in foreground");
- fprintf(stderr, FMT, "-f file", "VCL script");
- fprintf(stderr, FMT, "-h kind[,hashoptions]", "Hash specification");
- fprintf(stderr, FMT, "", " -h critbit [default]");
- fprintf(stderr, FMT, "", " -h simple_list");
- fprintf(stderr, FMT, "", " -h classic");
- fprintf(stderr, FMT, "", " -h classic,<buckets>");
- fprintf(stderr, FMT, "-i identity", "Identity of varnish instance");
- fprintf(stderr, FMT, "-I file", "Initialization CLI commands");
- fprintf(stderr, FMT, "-j jail[,jailoptions]", "Jail specification");
+#define FMT " %-28s # %s\n"
+
+ printf( "Usage: varnishd [options]\n");
+
+ printf("\nBasic options:\n");
+
+ printf(FMT, "-a address[:port][,proto]",
+ "HTTP listen address and port");
+ printf(FMT, "", "Can be specified multiple times.");
+ printf(FMT, "", " default: \":80,HTTP/1\"");
+ printf(FMT, "-b address[:port]", "Backend address and port");
+ printf(FMT, "", " default: \":80\"");
+ printf(FMT, "-f vclfile", "VCL program");
+ printf(FMT, "", "Can be specified multiple times.");
+ printf(FMT, "-n dir", "Working directory");
+
+ printf("\n-b can be used only once, and not together with -f\n");
+
+ printf("\nDocumentation options:\n");
+ printf(FMT, "-?", "Prints this usage message");
+ printf(FMT, "-x parameter", "Parameter documentation");
+ printf(FMT, "-x vsl", "VSL record documentation");
+ printf(FMT, "-x cli", "CLI command documentation");
+ printf(FMT, "-x builtin", "Builtin VCL program");
+
+ printf("\nOperations options:\n");
+
+ printf(FMT, "-F", "Run in foreground");
+ printf(FMT, "-T address[:port]", "CLI address");
+ printf(FMT, "", "Can be specified multiple times.");
+ printf(FMT, "-M address:port", "Reverse CLI destination");
+ printf(FMT, "", "Can be specified multiple times.");
+ printf(FMT, "-P file", "PID file");
+ printf(FMT, "-i identity", "Identity of varnish instance");
+ printf(FMT, "-I clifile", "Initialization CLI commands");
+
+ printf("\nTuning options:\n");
+
+ printf(FMT, "-t TTL", "Default TTL");
+ printf(FMT, "-p param=value", "set parameter");
+ printf(FMT, "", "Can be specified multiple times.");
+
+ printf(FMT, "-s [name=]kind[,options]", "Storage specification");
+ printf(FMT, "", "Can be specified multiple times.");
+ printf(FMT, "", " -s malloc");
+ printf(FMT, "", " -s file");
+
+ printf(FMT, "-l vsl[,vsm]", "Size of shared memory file");
+ printf(FMT, "", " vsl: space for VSL records [80m]");
+ printf(FMT, "", " vsm: space for stats counters [1m]");
+
+ printf("\nSecurity options:\n");
+
+ printf(FMT, "-r param[,param...]", "Set parameters read-only from CLI");
+ printf(FMT, "", "Can be specified multiple times.");
+ printf(FMT, "-S secret-file", "Secret file for CLI authentication");
+ printf(FMT, "-j jail[,options]", "Jail specification");
#ifdef HAVE_SETPPRIV
- fprintf(stderr, FMT, "", " -j solaris");
+ printf(FMT, "", " -j solaris");
#endif
- fprintf(stderr, FMT, "", " -j unix[,user=<user>][,ccgroup=<group>]");
- fprintf(stderr, FMT, "", " -j none");
- fprintf(stderr, FMT, "-l vsl[,vsm]", "Size of shared memory file");
- fprintf(stderr, FMT, "", " vsl: space for VSL records [80m]");
- fprintf(stderr, FMT, "", " vsm: space for stats counters [1m]");
- fprintf(stderr, FMT, "-M address:port", "Reverse CLI destination");
- fprintf(stderr, FMT, "-n dir", "varnishd working directory");
- fprintf(stderr, FMT, "-P file", "PID file");
- fprintf(stderr, FMT, "-p param=value", "set parameter");
- fprintf(stderr, FMT,
- "-r param[,param...]", "make parameter read-only");
- fprintf(stderr, FMT, "-S secret-file",
- "Secret file for CLI authentication");
- fprintf(stderr, FMT,
- "-s [name=]kind[,options]", "Backend storage specification");
- fprintf(stderr, FMT, "", " -s malloc[,<size>]");
- fprintf(stderr, FMT, "", " -s file,<dir_or_file>");
- fprintf(stderr, FMT, "", " -s file,<dir_or_file>,<size>");
- fprintf(stderr, FMT, "",
- " -s file,<dir_or_file>,<size>,<granularity>");
- fprintf(stderr, FMT, "",
- " -s file,<dir_or_file>,<size>,<granularity>,<advice>");
- fprintf(stderr, FMT, "", " -s persistent (experimental)");
- fprintf(stderr, FMT, "-T address:port",
- "Telnet listen address and port");
- fprintf(stderr, FMT, "-t TTL", "Default TTL");
- fprintf(stderr, FMT, "-V", "version");
- fprintf(stderr, FMT, "-W waiter", "Waiter implementation");
-#define WAITER(nm) fprintf(stderr, FMT, "", " -W " #nm);
-#include "tbl/waiters.h"
- exit(1);
+ printf(FMT, "", " -j unix");
+ printf(FMT, "", " -j none");
+
+ printf("\nAdvanced/Dev/Debug options:\n");
+
+ printf(FMT, "-d", "debug mode");
+ printf(FMT, "", "Stay in forground, CLI on stdin.");
+ printf(FMT, "-C", "Output VCL code compiled to C language");
+ printf(FMT, "-V", "version");
+ printf(FMT, "-h kind[,options]", "Hash specification");
+ printf(FMT, "-W waiter", "Waiter implementation");
}
/*--------------------------------------------------------------------*/
@@ -323,13 +337,13 @@ mgt_initialize(struct cli *cli)
static void
mgt_x_arg(const char *x_arg)
{
- if (!strcmp(x_arg, "dumprstparam"))
+ if (!strcmp(x_arg, "parameter"))
MCF_DumpRstParam();
- else if (!strcmp(x_arg, "dumprstvsl"))
+ else if (!strcmp(x_arg, "vsl"))
mgt_DumpRstVsl();
- else if (!strcmp(x_arg, "dumprstcli"))
+ else if (!strcmp(x_arg, "cli"))
mgt_DumpRstCli();
- else if (!strcmp(x_arg, "dumpbuiltin"))
+ else if (!strcmp(x_arg, "builtin"))
mgt_DumpBuiltin();
else
ARGV_ERR("Invalid -x argument\n");
@@ -485,9 +499,6 @@ main(int argc, char * const *argv)
o = getopt(argc, argv, opt_spec);
switch (o) {
- case '?':
- usage();
- exit(1);
case 'x':
if (argc != 3)
ARGV_ERR("Too many arguments for -x\n");
@@ -507,8 +518,16 @@ main(int argc, char * const *argv)
do {
switch (o) {
case '?':
- usage();
- exit(1);
+ if (optopt == '?') {
+ usage();
+ exit(1);
+ }
+ ARGV_ERR("Option '%c' unknown.\n",
+ optopt);
+ case 'V':
+ case 'x':
+ ARGV_ERR("-%c must be the first argument\n", o);
+ break;
case 'b':
b_arg = optarg;
break;
@@ -527,10 +546,6 @@ main(int argc, char * const *argv)
case 'j':
j_arg = optarg;
break;
- case 'V':
- case 'x':
- ARGV_ERR("-%c must be the first argument\n", o);
- break;
default:
break;
}
@@ -600,7 +615,6 @@ main(int argc, char * const *argv)
case 'd':
case 'F':
case 'j':
- case 'x':
/* Handled in first pass */
break;
case 'a':
@@ -676,10 +690,8 @@ main(int argc, char * const *argv)
break;
case 'p':
p = strchr(optarg, '=');
- if (p == NULL) {
- usage();
- exit(2);
- }
+ if (p == NULL)
+ ARGV_ERR("\t-p lacks '='\n");
AN(p);
*p++ = '\0';
MCF_ParamSet(cli, optarg, p);
diff --git a/bin/varnishd/mgt/mgt_param.c b/bin/varnishd/mgt/mgt_param.c
index f10d312..e74cc57 100644
--- a/bin/varnishd/mgt/mgt_param.c
+++ b/bin/varnishd/mgt/mgt_param.c
@@ -552,7 +552,7 @@ MCF_DumpRstParam(void)
int j;
printf("\n.. The following is the autogenerated "
- "output from varnishd -x dumprstparam\n\n");
+ "output from varnishd -x parameter\n\n");
VTAILQ_FOREACH(pl, &phead, list) {
pp = pl->spec;
printf(".. _ref_param_%s:\n\n", pp->name);
diff --git a/bin/varnishd/mgt/mgt_util.c b/bin/varnishd/mgt/mgt_util.c
index 4c59a9e..9e63ef7 100644
--- a/bin/varnishd/mgt/mgt_util.c
+++ b/bin/varnishd/mgt/mgt_util.c
@@ -66,7 +66,7 @@ mgt_DumpRstVsl(void)
printf(
"\n.. The following is autogenerated output from "
- "varnishd -x dumprstvsl\n\n");
+ "varnishd -x vsl\n\n");
#define SLTM(tag, flags, sdesc, ldesc) mgt_sltm(#tag, sdesc, ldesc);
#include "tbl/vsl_tags.h"
diff --git a/bin/varnishtest/tests/a00009.vtc b/bin/varnishtest/tests/a00009.vtc
index 12daa47..ca0f299 100644
--- a/bin/varnishtest/tests/a00009.vtc
+++ b/bin/varnishtest/tests/a00009.vtc
@@ -15,10 +15,10 @@ shell -err -expect {Unknown jail method "xyz"} "varnishd -jxyz -f '' "
shell -err -expect {-x must be the first argument} "varnishd -d -x foo "
shell -err -expect {Too many arguments for -x} "varnishd -x foo bar"
shell -err -expect {Invalid -x argument} "varnishd -x foo "
-shell "varnishd -x dumprstparam > ${tmpdir}/_.param"
-shell "varnishd -x dumprstvsl > ${tmpdir}/_.vsl"
-shell "varnishd -x dumprstcli > ${tmpdir}/_.cli"
-shell "varnishd -x dumpbuiltin > ${tmpdir}/_.builtin"
+shell "varnishd -x parameter > ${tmpdir}/_.param"
+shell "varnishd -x vsl > ${tmpdir}/_.vsl"
+shell "varnishd -x cli > ${tmpdir}/_.cli"
+shell "varnishd -x builtin > ${tmpdir}/_.builtin"
shell -err -expect {-V must be the first argument} "varnishd -d -V foo "
shell -err -expect {Too many arguments for -V} "varnishd -V -V"
@@ -31,10 +31,10 @@ shell -err -expect {-C needs either -b <backend> or -f <vcl_file>} \
"varnishd -C "
shell -err -expect {-d makes no sense with -C} "varnishd -C -b 127.0.0.1:80 -d "
shell -err -expect {-F makes no sense with -C} "varnishd -C -b 127.0.0.1:80 -F "
-shell -err -expect {usage: varnishd [options]} "varnishd -? "
+shell -err -expect {Usage: varnishd [options]} "varnishd -? "
shell -err -expect {Invalid backslash sequence} {varnishd -l 'xyz\kk,xyz\foo' -f '' }
shell -err -expect {Invalid backslash sequence} {varnishd -l 'ab\8cd' -f '' }
-shell -err -expect {usage: varnishd [options]} "varnishd -A "
+shell -err -expect {Option 'A' unknown.} "varnishd -A "
shell -err -expect {Cannot open -S file} {
varnishd -S ${tmpdir}/nonexistent -n ${tmpdir}/v0 -f ''
}
diff --git a/doc/sphinx/Makefile.am b/doc/sphinx/Makefile.am
index 6968535..255ce4e 100644
--- a/doc/sphinx/Makefile.am
+++ b/doc/sphinx/Makefile.am
@@ -126,11 +126,11 @@ distclean-local:
rm -rf $(BUILDDIR)
include/cli.rst: $(top_builddir)/bin/varnishd/varnishd
- $(top_builddir)/bin/varnishd/varnishd -x dumprstcli > $@
+ $(top_builddir)/bin/varnishd/varnishd -x cli > $@
BUILT_SOURCES = include/cli.rst
include/params.rst: $(top_builddir)/bin/varnishd/varnishd
- $(top_builddir)/bin/varnishd/varnishd -x dumprstparam > $@
+ $(top_builddir)/bin/varnishd/varnishd -x parameter > $@
BUILT_SOURCES += include/params.rst
include/counters.rst: $(top_builddir)/bin/varnishstat/vsc2rst
diff --git a/doc/sphinx/Makefile.phk b/doc/sphinx/Makefile.phk
index f04a711..ba77075 100644
--- a/doc/sphinx/Makefile.phk
+++ b/doc/sphinx/Makefile.phk
@@ -201,7 +201,7 @@ distclean-local:
# XXX: here be dragons
include/params.rst: ../../bin/varnishd/varnishd
- ../../bin/varnishd/varnishd -x dumprstparam > $@
+ ../../bin/varnishd/varnishd -x parameter > $@
# only sphinx needs the opt2rst stuff anyway
More information about the varnish-commit
mailing list