Teach the remaining programs about --optstring.

Move the description of this feature from user to reference.

bin/varnishadm/varnishadm.c

@@ -423,6 +423,8 @@ n_arg_sock(const char *n_arg, const char *t_arg)
 	return (sock);
 }
 
+#define OPTARG "hn:pS:T:t:"
+
 int
 main(int argc, char * const *argv)
 {
@@ -432,6 +434,10 @@ main(int argc, char * const *argv)
 	const char *t_arg = NULL;
 	int opt, sock;
 
+	if (argc == 2 && !strcmp(argv[1], "--optstring")) {
+		printf(OPTARG "\n");
+		exit(0);
+	}
 	/*
 	 * By default linux::getopt(3) mangles the argv order, such that
 	 *	varnishadm -n bla param.set foo -bar
@@ -440,7 +446,7 @@ main(int argc, char * const *argv)
 	 * The '+' stops that from happening
 	 * See #1496
 	 */
-	while ((opt = getopt(argc, argv, "+hn:pS:T:t:")) != -1) {
+	while ((opt = getopt(argc, argv, "+" OPTARG)) != -1) {
 		switch (opt) {
 		case 'h':
 			/* Usage help */

bin/varnishd/mgt/mgt_main.c

@@ -490,6 +490,11 @@ main(int argc, char * const *argv)
 	struct vsb *vsb;
 	pid_t pid;
 
+	if (argc == 2 && !strcmp(argv[1], "--optstring")) {
+		printf("%s\n", opt_spec);
+		exit(0);
+	}
+
 	heritage.argc = argc;
 	heritage.argv = argv;
 

doc/sphinx/reference/index.rst

@@ -88,12 +88,13 @@ Varnishtest
 	VarnishTest - execute test cases <varnishtest>
 	vmod_vtc.rst
 
-For Developers
---------------
+For Developers & DevOps
+-----------------------
 
 .. toctree::
 	:maxdepth: 1
 
+	Shell tricks <shell_tricks>
 	VMODS - Extensions to VCL <vmod>
 	VSM - Shared memory use <vsm>
 	VDIR - Backends & Directors <directors>

doc/sphinx/reference/shell_tricks.rst

+.. _ref-shell_tricks:
+
+%%%%%%%%%%%%
+Shell Tricks 
+%%%%%%%%%%%%
+
+All the varnish programs can be invoked with the single
+argument ``--optstring`` to request their `getopt()`
+specification, which simplifies wrapper scripts:
+
+.. code-block:: shell
+
+    optstring=$(varnishfoo --optstring)
+
+    while getopts "$optstring" opt
+    do
+        case $opt in
+        n)
+            # handle $OPTARG
+            ;;
+        # handle other options
+        *)
+            # ignore unneeded options
+            ;;
+        esac
+    done
+
+    varnishfoo "$@"
+
+    # do something with the options

doc/sphinx/users-guide/run_cli.rst

@@ -65,7 +65,9 @@ To load new VCL program::
 	varnish> vcl.load some_name some_filename
 
 Loading will read the VCL program from the file, and compile it. If
-the compilation fails, you will get an error messages::
+the compilation fails, you will get an error messages:
+
+.. code-block:: text
 
 	.../mask is not numeric.
 	('input' Line 4 Pos 17)
@@ -105,7 +107,9 @@ But sometimes it is useful to be able to throw things out of cache
 without having an exact list of what to throw out.
 
 Imagine for instance that the company logo changed and now you need
-Varnish to stop serving the old logo out of the cache::
+Varnish to stop serving the old logo out of the cache:
+
+.. code-block:: text
 
 	varnish> ban req.url ~ "logo.*[.]png"
 
@@ -130,7 +134,9 @@ Change parameters
 ^^^^^^^^^^^^^^^^^
 
 Parameters can be set on the command line with the '-p' argument,
-but they can also be examined and changed on the fly from the CLI::
+but they can also be examined and changed on the fly from the CLI:
+
+.. code-block:: text
 
 	varnish> param.show prefer_ipv6
 	200
@@ -169,47 +175,3 @@ always need to start the child process explicitly.
 
 Should the child process die, the master process will automatically
 restart it, but you can disable that with the 'auto_restart' parameter.
-
-The shell, the other CLI
-------------------------
-
-Besides accessing the CLI via its interface or via ``varnishadm`` there
-is the matter of actually running the ``varnishd`` command line, usually
-via a shell. See :ref:`run_security` for security concerns around the
-``varnishd`` command line. See also :ref:`ref_syntax` about the CLI
-syntax and quoting pitfalls when using ``varnishadm``.
-
-The programs shipped with Varnish can expose their *optstring* in order
-to help writing wrapper scripts, in particular to get an opportunity to
-hook a task before a program daemonizes. With the exception of
-``varnishtest`` and ``varnishadm``, you can write Shell wrappers for
-``varnishd`` using the ``-x`` option and other programs using the
-``--optstring`` long option.
-
-This way, when writing a wrapper script you don't need to maintain the
-*optstring* in sync when you only need a subset of the options, usually
-``-n`` or ``-P``::
-
-    optstring=$(varnishd -x optstring)
-
-    while getopts "$optstring" opt
-    do
-        case $opt in
-        n)
-            # handle $OPTARG
-            ;;
-        # handle other options
-        *)
-            # ignore unneeded options
-            ;;
-        esac
-    done
-
-    varnishd "$@"
-
-    # do something with the options
-
-You can for example write a wrapper script that blocks until the shared
-memory is ready or when the child is started if you need that kind of
-synchronization. You can also prevent ``varnishd`` from starting if the
-``-S`` option is inadvertently set to not challenge access to the CLI.

doc/sphinx/users-guide/run_security.rst

@@ -199,7 +199,7 @@ system, but if `varnishd` is not started as root/superuser, this is
 not possible. No, don't ask me why you have to be superuser to
 lower the privilege of a child process...
 
-Inline-C is disabled by default starting with Varnish version 4, so unless
+Inline-C is disabled by default since Varnish version 4, so unless
 you enable it, you don't have to worry about it.
 
 The parameters mentioned above can restrict the loading of VMODs to only