--- doc/rdiff.1	2002/01/25 21:25:34	1.1
+++ doc/rdiff.1	2006/02/21 12:21:52	1.2
@@ -1,6 +1,6 @@
 .\"
 .\" librsync -- dynamic caching and delta update in HTTP
-.\" $Id: rdiff.1,v 1.1 2002/01/25 21:25:34 bje Exp $
+.\" $Id: rdiff.1,v 1.2 2006/02/21 12:21:52 abo Exp $
 .\" 
 .\" Copyright (C) 2000 by Martin Pool <mbp@humbug.org.au>
 .\" 
@@ -18,7 +18,7 @@
 .\" License along with this program; if not, write to the Free Software
 .\" Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 .\"
-.TH rdiff 1 "$Date: 2002/01/25 21:25:34 $" 
+.TH rdiff 1 "$Date: 2006/02/21 12:21:52 $" 
 .SH NAME
 rdiff \- compute and apply signature-based file differences
 .SH SYNOPSYS
@@ -29,10 +29,17 @@
 .PP
 \fBrdiff\fP [\fIoptions\fP] \fBpatch\fP \fIbasis-file delta-file new-file\fP
 .fi
+.SH USAGE
+You can use \fBrdiff\fP to update files, much like \fBrsync\fP does.
+However, unlike \fBrsync\fP, \fBrdiff\fP puts you in control.  There
+are three steps to updating a file: \fBsignature\fP, \fBdelta\fP, and
+\fBpatch\fP.
 .SH DESCRIPTION
 In every case where a filename must be specified, \- may be used
 instead to mean either standard input or standard output as
-appropriate.
+appropriate.  Be aware that if you do this, you'll need to terminate your
+\fIoptions\fP with \-\- or \fBrdiff\fP will think you are passing it
+an empty option.
 .SH "RETURN VALUE"
 0 for successful completion, 1 for environmental problems (file not
 found, invalid options, IO error, etc), 2 for a corrupt file and 3 for
