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 462aba79c1eb02ab47cb880a679a1e2e8e94f97c..6311395b9879e431c42f5809500655593df264dd 100644 (file)
--- 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 fff9e2bc1a93b23d8e21c306f0c46ecfe8fa16a1..26e7a44b8beef5b0f16b739b403d9b4dd6cf82ce 100644 (file)
--- 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