From 305a48cb21b295985f4c0ed3f8ef6600e401fb43 Mon Sep 17 00:00:00 2001 From: Andre Noll Date: Wed, 8 May 2024 01:54:50 +0200 Subject: [PATCH] Kill INSTALL. Move the installation instructions to index.html.m4 and the configuration bits to the new examples section of the man page. Streamline the installation instructions and recommend to install the debian package of lopsub. --- INSTALL | 94 --------------------------------------------------- Makefile | 5 +-- dss.suite.m4 | 61 +++++++++++++++++++++++++++++++++ index.html.m4 | 54 +++++++++++------------------ 4 files changed, 81 insertions(+), 133 deletions(-) delete mode 100644 INSTALL diff --git a/INSTALL b/INSTALL deleted file mode 100644 index 09d8505..0000000 --- a/INSTALL +++ /dev/null @@ -1,94 +0,0 @@ -dss is known to compile on Linux, FreeBSD and NetBSD. However, it is -run-tested only on Linux. - -Note that [lopsub](http://people.tuebingen.mpg.de/maan/lopsub) -is required to compile dss. - -Type - - make - -in the dss source directory to build the dss executable and the man -page. If lopsub is installed in a non-standard path, you may need to -run `make` as follows: - - make CPPFLAGS=-I$HOME/lopsub/include LDFLAGS=-L$HOME/lopsub/lib - -Then type - - sudo make install - -to install in /usr/local, or - - make install PREFIX=/somewhere/else - -to install in /somewhere/else. - -Also make sure that [rsync](https://rsync.samba.org/) is installed on -your system. Version 2.6.1 or newer is required. - -Examples: ---------- - -Suppose you'd like to create snapshots of the existing directory - - /foo/bar - -in the directory - - /baz/qux. - -Create the config file - - ~/.dssrc - -that contains the values for the source and the destination directories -as follows: - - echo 'source-dir "/foo/bar"' > ~/.dssrc - echo 'dest-dir "/baz/qux"' >> ~/.dssrc - -Then execute the commands - - mkdir /baz/qux - dss run - -In order to print the list of all snapshots created so far, use - - dss ls - -Yes, it's really that easy. - -The second example involves a slightly more sophisticated config file. -It instructs dss to exclude everything which matches at least one -pattern of the given exclude file, prevents rsync from crossing file -system boundaries and increases the number of snapshots. - - source-dir "/foo/bar" - dest-dir "/baz/qux" - # exclude files matching patterns in /etc/dss.exclude - rsync-option "--exclude-from=/etc/dss.exclude" - # don't cross filesystem boundaries - rsync-option "--one-file-system" - # maintain 2^6 - 1 = 63 snapshots - num-intervals "6" - -The /etc/dss.exclude file could look like this (see rsync(1) for -more examples) - - - - /proc - - /**/tmp/ - -Note that dss supports many more features and config options such -as taking snapshots from remote hosts and several hooks that are -executed on certain events, for example whenever a snapshot was -created successfully. Try - - dss -h - -for an overview of all supported command line options or - - dss --detailed-help - -for the full help text. diff --git a/Makefile b/Makefile index 2db46b2..f06f80c 100644 --- a/Makefile +++ b/Makefile @@ -162,7 +162,7 @@ README: index.html.in: index.html.m4 $(call SAY, M4 $<) $(M4) $< > $@ -index.html: index.html.in INSTALL NEWS +index.html: index.html.in NEWS $(call SAY, MD $@) sed -e '/@README@/,$$d' index.html.in > $@ printf '

%s

\n' "$(DESCRIPTION1)" >> $@ @@ -170,8 +170,5 @@ index.html: index.html.in INSTALL NEWS printf '

%s

\n' "$(DESCRIPTION3)" >> $@ sed -e '1,/@README@/d' -e '/@NEWS@/,$$d' index.html.in >> $@ markdown NEWS >> $@ - sed -e '1,/@NEWS@/d' -e '/@INSTALL@/,$$d' index.html.in >> $@ - markdown INSTALL >> $@ - sed -e '1,/@INSTALL@/d' -e '/@MAN_PAGE@/,$$d' index.html.in >> $@ -include Makefile.local diff --git a/dss.suite.m4 b/dss.suite.m4 index 227b0b5..fff9e2b 100644 --- a/dss.suite.m4 +++ b/dss.suite.m4 @@ -544,6 +544,67 @@ caption = Subcommands detected and terminates with exit code 1. [/description] +[section examples] + + Suppose you'd like to create snapshots of the existing directory + .I /foo/bar + in the directory + .IR /baz/qux . + Create the config file + .I ~/.dssrc + containing + the values for the source and the destination directories + as follows: + + .RS 6 + .EX + echo 'source-dir "/foo/bar"' > ~/.dssrc + echo 'dest-dir "/baz/qux"' >> ~/.dssrc + .EE + .RE + + Then execute the commands + + .RS 6 + .EX + mkdir /baz/qux + dss run + .EE + .RE + + To print the list of all snapshots created so far, run + .IR dss\~ls . + + The second example involves a slightly more sophisticated config + file. It instructs dss to exclude everything which matches at least + one pattern of the given exclude file, prevents rsync from crossing + file system boundaries and increases the number of snapshots. + + .RS 6 + .EX + source-dir "/foo/bar" + dest-dir "/baz/qux" + # exclude files matching patterns in /etc/dss.exclude + rsync-option \-\-exclude\-from=/etc/dss.exclude + # don't cross filesystem boundaries + rsync-option \-\-one\-file\-system + # maintain 2^6 - 1 = 63 snapshots + num-intervals "6" + .EE + .RE + + The + .I /etc/dss.exclude + file could look like this (see rsync(1) for more examples) + + .RS 6 + .EX + - /proc + - /**/tmp/ + .EE + .RE +[/section] + [section copyright] Written by AUTHOR() .br diff --git a/index.html.m4 b/index.html.m4 index 91b7411..4b23c81 100644 --- a/index.html.m4 +++ b/index.html.m4 @@ -20,50 +20,33 @@ dnl SPDX-License-Identifier: GPL-2.0 -
- - [NEWS] - [INSTALL] - [Resources] - + [Installation] + [Resources] + [News]
-
-

- README -

-
- @README@ -
+

Installation

-
-

- NEWS -

-
+

To install the dependencies, run apt-get install gcc rsync + liblopsub-dev m4.

- @NEWS@ +

To download the source code, run git clone + CLONE_URL(), or grab a current tarball from the gitweb page and unpack it.

-
+

To build the PACKAGE() executable and the man page, enter the + PACKAGE() source directory and type make. To install + both files run sudo make install.

-
-

- INSTALL -

-
+

Try dss -h for an overview of all supported command + line options, dss --detailed-help for the long help text, + or man dss to see the man page which contains example + configurations.

-

To download the source code, run git clone CLONE_URL() , - or grab a current tarball from the gitweb - page and unpack it.

- - @INSTALL@ - -
- -

Resources

+

Resources

+

News

+ @NEWS@ - -- 2.39.5