[master] d0cd96d20 Generate documentation of the varnishd -n option

[Nils Goroll]

commit d0cd96d20a04c839f29dfd433ed039441de19419
Author: Nils Goroll <nils.goroll at uplex.de>
Date:   Fri May 24 11:14:22 2024 +0200

    Generate documentation of the varnishd -n option
    
    with greetings from the rabbit-hole opened by #4105

diff --git a/bin/varnishd/mgt/mgt_main.c b/bin/varnishd/mgt/mgt_main.c
index dc2bce56b..6df16b285 100644
--- a/bin/varnishd/mgt/mgt_main.c
+++ b/bin/varnishd/mgt/mgt_main.c
@@ -79,6 +79,19 @@ static const char opt_spec[] = "?a:b:CdE:f:Fh:i:I:j:l:M:n:P:p:r:S:s:T:t:VW:x:";
 
 /*--------------------------------------------------------------------*/
 
+// Basic options documentation with compile time dependencies
+static void
+mgt_DumpOptions(void)
+{
+	printf(".. _opt_n:\n\n");
+	printf("-n workdir\n\n");
+	printf("  Runtime directory for the shared memory, "
+	       "compiled VCLs etc.\n\n");
+	printf("  In performance critical applications, this directory "
+	       "should be on a RAM backed filesystem.\n\n");
+	VIN_DumpDefaults();
+}
+
 static void
 usage(void)
 {
@@ -121,6 +134,7 @@ usage(void)
 	printf(FMT, "-x cli", "CLI command documentation");
 	printf(FMT, "-x builtin", "Builtin VCL program");
 	printf(FMT, "-x optstring", "List of getopt options");
+	printf(FMT, "-x options", "Dynamic options documentation");
 
 	printf("\nOperations options:\n");
 
@@ -359,6 +373,8 @@ mgt_x_arg(const char *x_arg)
 		mgt_DumpBuiltin();
 	else if (!strcmp(x_arg, "optstring"))
 		(void)printf("%s\n", opt_spec);
+	else if (!strcmp(x_arg, "options"))
+		mgt_DumpOptions();
 	else
 		ARGV_ERR("Invalid -x argument\n");
 }
diff --git a/doc/sphinx/Makefile.am b/doc/sphinx/Makefile.am
index b5d34fb8d..9ceb63456 100644
--- a/doc/sphinx/Makefile.am
+++ b/doc/sphinx/Makefile.am
@@ -85,6 +85,11 @@ include/params.rst: $(top_builddir)/bin/varnishd/varnishd
 	mv -f ${@}_ ${@}
 BUILT_SOURCES += include/params.rst
 
+include/options.rst: $(top_builddir)/bin/varnishd/varnishd
+	$(top_builddir)/bin/varnishd/varnishd -x options > ${@}_
+	mv -f ${@}_ ${@}
+BUILT_SOURCES += include/options.rst
+
 include/counters.rst:
 	ln -s $(abs_top_builddir)/lib/libvsc/counters.rst $@
 BUILT_SOURCES += include/counters.rst
diff --git a/doc/sphinx/reference/varnishd.rst b/doc/sphinx/reference/varnishd.rst
index 3f7dfcb1b..7db93dcf2 100644
--- a/doc/sphinx/reference/varnishd.rst
+++ b/doc/sphinx/reference/varnishd.rst
@@ -142,19 +142,7 @@ Basic options
   could later be accessed remotely, starting `varnishd` requires
   local privileges.
 
-.. _opt_n:
-
--n workdir
-
-  Runtime directory for the shared memory, compiled VCLs etc.
-
-  In performance critical applications, this directory should be
-  on a RAM backed filesystem.
-
-  Relative paths will be appended to `/var/run/` (NB: Binary packages
-  of Varnish may have adjusted this to the platform.)
-
-  The default value is `/var/run/varnishd` (NB: as above.)
+.. include:: ../include/options.rst
 
 Documentation options
 ---------------------
diff --git a/include/vin.h b/include/vin.h
index e7dc3eb8d..2d63cf6c0 100644
--- a/include/vin.h
+++ b/include/vin.h
@@ -33,6 +33,7 @@
 #ifndef VIN_H_INCLUDED
 #define VIN_H_INCLUDED
 
-/* This function lives in both libvarnish and libvarnishapi */
+/* These functions live in both libvarnish and libvarnishapi */
 char *VIN_n_Arg(const char *n_arg);
+void VIN_DumpDefaults(void);
 #endif
diff --git a/lib/libvarnish/vin.c b/lib/libvarnish/vin.c
index 89f132f4e..9e1028f34 100644
--- a/lib/libvarnish/vin.c
+++ b/lib/libvarnish/vin.c
@@ -42,6 +42,7 @@
 #include "vin.h"
 #include "vsb.h"
 
+#define VARNISH_DEFAULT_REL_NAME "varnishd"
 char *
 VIN_n_Arg(const char *n_arg)
 {
@@ -52,7 +53,7 @@ VIN_n_Arg(const char *n_arg)
 	AN(vsb);
 	if (n_arg == NULL || n_arg[0] == '\0') {
 		VSB_cat(vsb, VARNISH_STATE_DIR);
-		VSB_cat(vsb, "/varnishd");
+		VSB_cat(vsb, "/" VARNISH_DEFAULT_REL_NAME);
 	} else if (n_arg[0] == '/') {
 		VSB_cat(vsb, n_arg);
 	} else {
@@ -66,3 +67,13 @@ VIN_n_Arg(const char *n_arg)
 	VSB_destroy(&vsb);
 	return (retval);
 }
+
+void
+VIN_DumpDefaults(void)
+{
+	printf("  Relative paths will be appended to ``%s``.\n\n",
+	       VARNISH_STATE_DIR);
+	printf("  The default value is ``%s``.\n\n",
+	       VARNISH_STATE_DIR "/" VARNISH_DEFAULT_REL_NAME);
+	printf("  Note: These defaults may be distribution specific.\n\n");
+}
diff --git a/man/Makefile.am b/man/Makefile.am
index 560ec8d55..436d7d255 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -78,7 +78,8 @@ varnishadm.1: $(top_builddir)/doc/sphinx/reference/varnishadm.rst
 
 varnishd.1: \
 	$(top_builddir)/doc/sphinx/reference/varnishd.rst \
-	$(top_builddir)/doc/sphinx/include/params.rst
+	$(top_builddir)/doc/sphinx/include/params.rst \
+	$(top_builddir)/doc/sphinx/include/options.rst
 	$(BUILD_MAN) $(top_builddir)/doc/sphinx/reference/varnishd.rst $@
 
 varnishncsa.1: \