From: Andre Noll <maan@tuebingen.mpg.de>
Date: Thu, 9 May 2024 23:38:45 +0000 (+0200)
Subject: Move snapshot distribution explanation to separate man section.
X-Git-Tag: v1.0.2~4
X-Git-Url: http://git.tue.mpg.de/?a=commitdiff_plain;h=6bc9707d71db7c18b14bd82f33649ebae454c4ab;p=dss.git

Move snapshot distribution explanation to separate man section.

Since the new section contains a table, we have to tell groff to run
the tbl preprocessor to generate the html version of the man page.

We now pass -I image to the groff postprocessor so that
the png image file gets a predictable name. We'd love to
pass --image‐directory=build/ to place the png file in
the build directory, but this also creates html like <img
src="build/image1.png">, which does not work because index.html is
in build/. Change the cwd to the build directory to work around this.
---

diff --git a/Makefile b/Makefile
index 462aba7..6311395 100644
--- a/Makefile
+++ b/Makefile
@@ -45,7 +45,7 @@ B := build
 VERSION := $(shell $(MKDIR_P) $(B) && ./version-gen.sh $(PACKAGE) $(B)/version.c)
 RM := rm -f
 LSG := lopsubgen
-GROFF := groff -m man -Thtml -P -l -P -r
+GROFF := groff -m man -t -Thtml -P -l -P -r -P -I -P image
 GZIP := gzip -cfn9
 GIT := git
 M4 := m4 \
@@ -134,7 +134,8 @@ $(B)/%.1: $(B)/%.suite
 	$(GZIP) < $< > $@
 $(B)/%.1.html: $(B)/%.1
 	$(call SAY, GROFF $<)
-	$(GROFF) $< > $@
+	cd $(B)
+	$(GROFF) ../$< > ../$@
 $(B)/index.html: index.html.m4 Makefile
 	$(call SAY, M4 $@)
 	$(M4) $< > $@
diff --git a/dss.suite.m4 b/dss.suite.m4
index fff9e2b..26e7a44 100644
--- a/dss.suite.m4
+++ b/dss.suite.m4
@@ -170,23 +170,6 @@ caption = Subcommands
 	[option intervals]
 		summary = Fine tuning the number of snapshots per time unit
 		flag ignored
-		[help]
-			Snapshot aging is implemented in terms of intervals. There are two
-			command line options related to intervals: the duration u of a unit
-			interval and the number of unit intervals, denoted n below.
-
-			dss removes snapshots older than n times u and tries to keep 2^(n -
-			k - 1) snapshots in interval k, where the interval number k counts
-			from zero to n - 1, with zero being the most recent unit interval.
-
-			Hence the oldest snapshot will at most be u * n days old (4 days *
-			5 intervals = 20 days, if default values are used). Moreover, there
-			are at most 2^n - 1 snapshots in total (2^5 - 1 = 31 by default). Note
-			that for this to work out your system must be fast enough to create at
-			least 2^(n - 1) snapshots per unit interval (16 snapshots in 4 days =
-			one snapshot in 6 hours), because this is the number of snapshots in
-			interval zero.
-		[/help]
 	[option unit-interval]
 		short_opt = u
 		summary = the duration of a unit interval
@@ -605,6 +588,47 @@ caption = Subcommands
 	.RE
 [/section]
 
+[section snapshot distribution]
+	The age of a snapshot is measured in terms of unit
+	intervals. Given
+	the duration
+	.I u
+	of a unit
+	interval and the number
+	.I n
+	of unit intervals to consider, dss tries to keep
+	.I 2^(n-k-1)
+	snapshots in interval
+	.IR k ,
+	where the interval number
+	.I k
+	counts
+	from zero to
+	.IR n-1 ,
+	with zero being the most recent unit interval. Snapshots older than
+	.I n
+	unit intervals are regarded as outdated and are removed. There are
+	.I 2^n-1
+	snapshots in total.
+
+	For example, with four unit intervals, the 2^4 - 1 = 15 snapshots
+	are distributed as follows.
+
+	.TS
+	allbox;
+	lb r r r r
+	lb r r r r.
+	Interval	3	2	1	0
+	Snapshots	\~\~\~\~*\~\~\~	\~\~*\~\~*\~\~	\~*\~*\~*\~*	********
+	.TE
+
+	Note that for this to work out the system must be fast enough to
+	create at least
+	.I 2^(n-1)
+	snapshots per unit interval because this is the number of snapshots
+	in interval zero.
+[/section]
+
 [section copyright]
 	Written by AUTHOR()
 	.br