Many fixes, primarily documentation

git-svn-id: file:///home/lennart/svn/public/syrep/trunk@32 07ea20a6-d2c5-0310-9e02-9ef735347d72
author: Lennart Poettering <lennart@poettering.net> 2003-09-07 23:11:37 +0000
committer: Lennart Poettering <lennart@poettering.net> 2003-09-07 23:11:37 +0000
commit: 17fac7f2c92df794b88648a95bea6796621dbe83 (patch)
tree: f50baaf521f683a24e3de98141643863fab74af1 /doc
parent: 411862e81940e9eaea542ae1c4a04cca5e5b88a3 (diff)
5 files changed, 269 insertions, 5 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 023a636..59432f6 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -16,4 +16,20 @@
 # along with syrep; if not, write to the Free Software Foundation,
 # Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
 
-EXTRA_DIST = todo.txt package.txt usage-intro.txt
+noinst_DATA = README.html README
+EXTRA_DIST = $(noinst_DATA) style.css README.html.in todo.txt package.txt usage-intro.txt
+
+MAINTAINERCLEANFILES = README README.html
+CLEANFILES =
+
+if USE_LYNX
+README: README.html
+	lynx --dump $^ | sed 's,file://localhost/.*/doc/README.html,README,' > $@
+
+CLEANFILES += README
+endif
+
+tidy: README.html
+	tidy -e < README.html
+
+.PHONY: tidy
diff --git a/doc/README b/doc/README
deleted file mode 100644
index 1f7ff7e..0000000
--- a/doc/README
+++ /dev/null
@@ -1 +0,0 @@
-No README yet
diff --git a/doc/README.html.in b/doc/README.html.in
new file mode 100644
index 0000000..f0a038c
--- /dev/null
+++ b/doc/README.html.in
@@ -0,0 +1,218 @@
+<?xml version="1.0" encoding="iso-8895-15"?> <!-- -*-html-helper-*- -->
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+
+<head>
+<title>syrep @PACKAGE_VERSION@</title>
+<link rel="stylesheet" type="text/css" href="style.css" />
+</head>
+
+<body>
+<h1><a name="top">syrep @PACKAGE_VERSION@</a></h1>
+
+<p><i>Copyright 2003 Lennart Poettering &lt;@PACKAGE_BUGREPORT@&gt;</i></p>
+
+<ul class="toc">
+    <li><a href="#license">License</a></li>
+    <li><a href="#news">News</a></li>
+    <li><a href="#overview">Overview</a></li>
+    <li><a href="#status">Status</a></li>
+    <li><a href="#documentation">Documentation</a></li>
+    <li><a href="#requirements">Requirements</a></li>
+    <li><a href="#installation">Installation</a></li>
+    <li><a href="#acks">Acknowledgements</a></li>
+    <li><a href="#download">Download</a></li>
+</ul>
+
+<h2><a name="license">License</a></h2>
+
+<p>This program is free software; you can redistribute it and/or
+modify it under the terms of the GNU General Public License as
+published by the Free Software Foundation; either version 2 of the
+License, or (at your option) any later version.</p>
+
+<p>This program is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+General Public License for more details.</p>
+
+<p>You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.</p>
+
+<h2><a name="news">News</a></h2>
+
+<div class="news-date">Mon Sep 8 2003: </div> <p class="news-text"><a
+href="@PACKAGE_URL@syrep-0.1.tar.gz">Version
+0.1</a> released.</p>
+
+<h2><a name="overview">Overview</a></h2>
+
+<p><tt>syrep</tt> is a generic file repository synchronization tool. It may be
+used to synchronize large file hierarchies bidirectionally by
+exchanging patch files. <tt>Syrep</tt> is truely peer-to-peer, no central
+servers are involved. Synchronizations between more than two
+repositories are supported. The patch files may be transferred via
+offline media, e.g. removable hard disks or compact discs.</p>
+
+<p>Files are tracked by their message digests, currently MD5. The
+following file operations are tracked in the snapshot files: creation,
+deletion, modification, creation of new hard or symbolic links,
+renaming. (The latter is nothing more than a new hard link and removal
+of the old file). <tt>syrep</tt> doesn't distuinguish between soft and
+hard links. In fact even copies of files are treated as the
+same. Currently, <tt>syrep</tt> doesn't synchronize file attributes like
+access modes or modification times.</p>
+
+<p><tt>Syrep</tt> was written to facilitate the synchronization of two
+large digital music repositories without direct network
+connection. Patch files of several gigabytes are common in
+this situation.</p>
+
+<p><tt>Syrep</tt> is able to cope with 64 bit file sizes. (LFS)</p>
+
+<p><tt>Syrep</tt> is optimized for speed. It may make use of a message digest
+cache to accelerate the calculation of digests of a whole directory
+hierarchy.</p>
+
+<h2><a name="status">Status</a></h2>
+
+<p>Version @PACKAGE_VERSION@ is more or less stable and fulfills its purpose.</p>
+  
+<h2><a name="documentation">Documentation</a></h2>
+
+<p>Have a look on the man page <a href="@PACKAGE_URL@syrep.1.xml"><tt>syrep(1)</tt></a>. (A XSLT capable browser is required)</p>
+
+<h3>Method of operation</h3>
+
+<p><tt>Syrep</tt>'s operation relies on "snapshots" of a file
+repository. A snapshot contains information about all files existent
+in the hierarchy combined with a limited history log of file
+operations. Snapshots may be compared, files missing or deleted on one
+of both sides may be detected this way. Based on this knowledge patch
+files containing all missing files may be created and merged.</p>
+
+<p>To keep the file operation log in a sensible state it is crucial to
+update the snapshot frequently, probably by adding a new <tt>cron</tt>
+job.</p>
+
+<h3>Example usage</h3>
+
+<p>Fred and Karl want to synchronize their digital music libraries by
+exchanging an USB hard disk with patch files. As first step, both
+initialize their repositories for usage with <tt>syrep</tt>:</p>
+
+<pre>fred$ syrep -zp --update ~/mp3/
+...
+karl$ syrep -zp --update ~/mp3/</pre>
+
+<p>Depending on the size of the repositories this takes a lot of time,
+since a message digest is calculated for every file. Since exact
+tracking of all file operations on the repository is crucial for
+effetive synchronization, they both use the time passing to add a new
+entry to their <tt>crontab</tt>:</p>
+
+<pre>1 3 * * * syrep -z --update ~/mp3/</pre>
+
+<p>When the snapshot creation finished, they send the newly created
+patch files <tt>~/mp3/.syrep/curent.syrep</tt> to each other. As these
+snapshots are only about 400K of size for a 80GB repository they do
+that via email:</p>
+
+<pre>fred$ mutt -a ~/mp3/.syrep/current.syrep -s "The current snapshot of fred" karl
+...
+karl$ mutt -a ~/mp3/.syrep/current.syrep -s "The current snapshot of karl" fred</pre>
+
+<p>When the mails arrive they both detach the snapshot and create a
+patch on their USB harddisk containing all local files not existing on
+the other siede:</p>
+
+<pre>fred$ mount /mnt/usb
+fred$ syrep -p -o /mnt/usb/patch-for-karl --makepatch ~/mp3/ ~/karls-current.syrep
+fred$ umount /mnt/usb
+...
+karl$ mount /mnt/usb
+karl$ syrep -p -o /mnt/usb/patch-for-fred --makepatch ~/mp3/ ~/freds-current.syrep
+karl$ umount /mnt/usb
+</pre>
+
+<p>As next step they exchange their harddisks. Back at home they merge the newly acquired patch into their own repository:</p>
+
+<pre>fred$ mount /mnt/usb
+fred$ syrep -pT --merge /mnt/usb/patch-for-fred ~/mp3/
+fred$ umount /mnt/usb
+...
+karl$ mount /mnt/usb
+karl$ syrep -pT --merge /mnt/usb/patch-for-karl ~/mp3/
+karl$ umount /mnt/usb
+</pre>
+
+<p>At this moment both have the same file hierarchy. To update the
+local snapshot log with the newly merged files they both should run
+<tt>--update</tt> now. This update run should be much quicker since
+the message digests of all unchanged files are read from a message
+cache created and update each time <tt>--update</tt> runs:</p>
+
+<pre>fred$ syrep -zp --update ~/mp3/
+...
+karl$ syrep -zp --update ~/mp3/</pre>
+
+<p>Some time later Fred got plenty of new music files, while Karl
+didn't change anything on his repository. Thus, Fred is able to use
+the old snapshot he recieved from Karl to generate a new patch for
+him. He does it exactly the same way he did the last time, see
+above.</p>
+
+<p>And now, several iterations of the story described above
+follow.</p>
+
+<p>That's the end of the story.</p>
+
+<p>OK, not quite. Sometimes a conflict happens, e.g. at the same time both created a
+file <tt>foo.mp3</tt> with different contents. When
+this happens the local copy is always copied into the patch and the
+user may decide during merge which file version he wants to have
+locally. Because of that merging is an interactive task and cannot be
+automated completely.</p>
+
+<p>There is no need that the synchronization operations happen in such
+a "symmetric" way as described above.</p>
+
+<h2><a name="requirements">Requirements</a></h2>
+
+<p><tt>syrep</tt> requires installed development versions of <tt><a href="http://www.gzip.org/zlib/">zlib</a></tt> and <tt><a href="http://www.sleepycat.com/">Berkeley DB</a></tt>.</p>
+
+<p><tt>syrep</tt> was developed and tested on Debian GNU/Linux
+"testing" from September 2003, it should work on most other Linux
+distributions and may be POSIX implementations since it uses GNU
+autoconf for source code configuration.</p>
+
+<p>Some support for for big endian architectures is included, however, it is incomplete. You're welcome to send me patches.</p>
+
+<h2><a name="installation">Installation</a></h2>
+
+<p>As this package is made with the GNU autotools you should run
+<tt>./configure</tt> inside the distribution directory for configuring
+the source tree. After that you should run <tt>make</tt> for
+compilation and <tt>make install</tt> (as root) for installation of
+<tt>syrep</tt>.</p>
+
+<h2><a name="acks">Acknowledgements</a></h2>
+
+<p>This software includes an implementation of the MD5 algorithm by
+L. Peter Deutsch. Thanks to him for this.</p>
+
+<h2><a name="download">Download</a></h2>
+
+<p>The newest release is always available from <a href="@PACKAGE_URL@">@PACKAGE_URL@</a></p>
+
+<p>The current release is <a href="@PACKAGE_URL@syrep-@PACKAGE_VERSION@.tar.gz">@PACKAGE_VERSION@</a></p>
+
+<hr/>
+
+<address>Lennart Poettering &lt;@PACKAGE_BUGREPORT@&gt;, Sep 2003</address>
+
+<div><i>$Id$</i></div>
+
+</body>
+</html>
diff --git a/doc/style.css b/doc/style.css
new file mode 100644
index 0000000..110f73c
--- /dev/null
+++ b/doc/style.css
@@ -0,0 +1,31 @@
+/* $Id$ */
+
+/***
+  This file is part of syrep.
+
+  syrep is free software; you can redistribute it and/or modify it under
+  the terms of the GNU General Public License as published by the Free
+  Software Foundation; either version 2 of the License, or (at your
+  option) any later version.
+
+  syrep is distributed in the hope that it will be useful, but WITHOUT
+  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+  FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+  for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with syrep; if not, write to the Free Software Foundation,
+  Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. 
+***/
+
+body { color: black; background-color: white; margin: 0.5cm; } 
+a:link, a:visited { color: #900000; }       
+p { margin-left: 0.5cm; margin-right: 0.5cm; }
+div.news-date { margin-left: 0.5cm; font-size: 80%; color: #4f0000; } 
+p.news-text { margin-left: 1cm; }
+ul { margin-left: .5cm; }
+ol { margin-left: .5cm; }
+h1 { color: #00009F; }
+h2 { color: #00009F; }
+h3 { color: #00004F; margin-left: 0.5cm; }
+pre { margin-left: .5cm; background-color: #f0f0f0; padding: 0.4cm;}
diff --git a/doc/todo.txt b/doc/todo.txt
index 1faad6c..9870198 100644
--- a/doc/todo.txt
+++ b/doc/todo.txt
@@ -19,9 +19,9 @@ pre-0.1:
 - fix makepatch to not include already existing files  DONE
 - better usage info on --help                          DONE
 - autoconf                                             DONE
-
-- documentation/man pages
-- testing
+- syrep doesn't fail on on broken snapshot             DONE
+- documentation/man pages                              DONE
+- testing                                              DONE
 
 post-0.1:
 - continue merge on copy failure
author	Lennart Poettering <lennart@poettering.net>	2003-09-07 23:11:37 +0000
committer	Lennart Poettering <lennart@poettering.net>	2003-09-07 23:11:37 +0000
commit	17fac7f2c92df794b88648a95bea6796621dbe83 (patch)
tree	f50baaf521f683a24e3de98141643863fab74af1 /doc
parent	411862e81940e9eaea542ae1c4a04cca5e5b88a3 (diff)