$OpenBSD: patch-ctm_ctm_rmail_ctm_rmail_1,v 1.2 2007/10/31 23:14:46 ajacoutot Exp $
--- ctm/ctm_rmail/ctm_rmail.1.orig	Wed May  1 01:01:45 1996
+++ ctm/ctm_rmail/ctm_rmail.1	Wed Oct 31 23:12:21 2007
@@ -6,20 +6,12 @@
 .\" Author: Stephen McKay
 .\"
 .Dd January 24, 1995
-.Dt CTM_MAIL 1
+.Dt CTM_RMAIL 1
 .Os
 .Sh NAME
-.Nm ctm_smail, ctm_rmail
-.Nd send and receive
-.Nm ctm
-deltas via mail
+.Nm ctm_rmail
+.Nd send and receive ctm deltas via mail
 .Sh SYNOPSIS
-.Nm ctm_smail
-.Op Fl l Ar log
-.Op Fl m Ar maxmsgsize
-.Op Fl c Ar maxctmsize
-.Ar ctm-delta
-.Ar mail-alias
 .Nm ctm_rmail
 .Op Fl Dfuv
 .Op Fl l Ar log
@@ -28,61 +20,15 @@ deltas via mail
 .Op Fl b Ar basedir
 .Op Ar
 .Sh DESCRIPTION
-In conjuction with the
-.Xr ctm 1
-command,
-.Nm ctm_smail
-and
+The
 .Nm ctm_rmail
-are used to distribute changes to a source tree via email.
-.Nm ctm_smail
-is given a compressed
-.Xr ctm
-delta, and a mailing list to send it to.  It splits the delta into manageable
-pieces, encodes them as mail messages and sends them to the mailing list.
-Each recipient uses
-.Nm ctm_rmail
+program is used
 (either manually or automatically) to decode and reassemble the delta, and
 optionally call
 .Xr ctm
 to apply it to the source tree.
-At the moment,
-several source trees are distributed, and by several sites.  These include
-the FreeBSD-current source and CVS trees, distributed by
-.Li freefall.FreeBSD.org .
 .Pp
 Command line arguments for
-.Nm ctm_smail :
-.Bl -tag -width indent
-.It Fl l Ar log
-Instead of appearing on
-.Em stderr ,
-error diagnostics and informational messages (other than command line errors)
-are time stamped and written to the file
-.Em log .
-.It Fl m Ar maxmsgsize
-Limit the maximum size mail message that
-.Nm ctm_smail
-is allowed to send.  It is approximate since mail headers and other niceties
-are not counted in this limit.  If not specified, it will default to 64000
-bytes, leaving room for 1535 bytes of headers before the rumoured 64k mail
-limit.
-.It Fl c Ar maxctmsize
-Limit the maximum size delta that will be sent.  Deltas bigger that this
-limit will cause an apology mail message to be sent to the mailing list.
-This is to prevent massive changes overwhelming users' mail boxes.  Note that
-this is the size before encoding.  Encoding causes a 4/3 size increase before
-mail headers are added.  If not specified, there is no limit.
-.El
-.Pp
-.Ar ctm-delta
-is the delta to be sent, and
-.Ar mail-alias
-is the mailing list to send the delta to.
-The mail messages are sent using
-.Xr sendmail 8 .
-.Pp
-Command line arguments for
 .Nm ctm_rmail :
 .Bl -tag -width indent
 .It Fl l Ar log
@@ -112,19 +58,18 @@ without the
 .Fl p
 flag.
 Deltas will not be applied if they do not match the
-.Li .ctm_status
+.Pa .ctm_status
 file in
 .Ar basedir
 (or if
-.Li .ctm_status
+.Pa .ctm_status
 does not exist).
 .It Fl D
 Delete deltas after successful application by
 .Xr ctm .
-It is probably a good idea to avoid this flag (and keep all the deltas)
-as one of the possible future enhancements to
+It is probably a good idea to avoid this flag (and keep all the deltas) as
 .Xr ctm
-is the ability to recover small groups of files from a full set of deltas.
+has the ability to recover small groups of files from a full set of deltas.
 .It Fl f
 Fork and execute in the background while applying deltas with
 .Xr ctm .
@@ -161,7 +106,11 @@ Pass the
 flag to the
 .Xr ctm
 command when applying the complete deltas, causing a more informative
-output. Note that you need to make your own arrangements to capture it.
+output.  All
+.Xr ctm
+output appears in the
+.Nm ctm_rmail
+log file.
 .El
 .Pp
 The file arguments (or
@@ -196,7 +145,7 @@ CTM_MAIL END 61065
 The subject of the message always begins with
 .Dq ctm-mail
 followed by the name of the delta, which piece this is, and how many total
-pieces there are.  The data is bracketed by
+pieces there are.  The data are bracketed by
 .Dq CTM_MAIL BEGIN
 and
 .Dq CTM_MAIL END
@@ -217,23 +166,12 @@ You can retrieve this delta via ftpmail, or your good 
 .Pp
 You are then on your own!
 .Sh EXAMPLES
-To send delta 32 of
-.Em src-cur
-to a group of wonderful code hackers known to
-.Xr sendmail
-as
-.Em src-guys ,
-limiting the mail size to roughly 60000 bytes, you could use:
-.Bd -literal -offset indent
-ctm_smail -m 60000 /wherever/it/is/src-cur.0032.gz src-guys
-.Ed
-.Pp
 To decode every
-.Nm ctm-mail
+.Xr ctm 1
 message in your mailbox, assemble them into complete deltas, then apply
 any deltas built or lying around, you could use:
 .Bd -literal -offset indent
-ctm_rmail -p ~/pieces -d ~/deltas -b /usr/ctm-src-cur $MAIL
+.Ic ctm_rmail -p ~/pieces -d ~/deltas -b /usr/ctm-src-cur $MAIL
 .Ed
 .Pp
 (Note that no messages are deleted by
@@ -252,9 +190,9 @@ and
 directories and
 .Pa /ctm/log
 file are writable by user
-.Em daemon
+.Dq daemon
 or group
-.Em wheel ) :
+.Dq wheel ) :
 .Bd -literal -offset indent
 receiver-dude: "|ctm_rmail -p /ctm/tmp -d /ctm/deltas -l /ctm/log"
 owner-receiver-dude: real_dude@wherever.you.like
@@ -265,11 +203,50 @@ or wherever else you like.
 .Pp
 To apply all the deltas collected, and delete those applied, you could use:
 .Bd -literal -offset indent
-ctm_rmail -D -d /ctm/deltas -b /ctm/src-cur -l /ctm/apply.log
+.Ic ctm_rmail -D -d /ctm/deltas -b /ctm/src-cur -l /ctm/apply.log
 .Ed
+.Pp
+For maximum flexibility, consider this excerpt from a
+.Xr procmail
+script:
+.Bd -literal -offset indent
+PATH=$HOME/bin:$PATH
+
+:0 w
+* ^Subject: ctm-mail cvs-cur
+| ctm_incoming
+.Ed
+.Pp
+together with the
+shell script
+.Pa ~/bin/ctm_incoming :
+.Bd -literal -offset indent
+#! /bin/sh
+PATH="$HOME/bin:/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin"
+export PATH
+
+cd $HOME/ctm && ctm_rmail -f -p pieces -d deltas -l log -b /ctm
+.Ed
+.Pp
+which will deposit all
+.Xr ctm
+deltas in
+.Pa ~/ctm/deltas ,
+apply them to the tree in
+.Pa /ctm ,
+and drop any failures into your regular mail box.
+Note the
+.Ev PATH
+manipulation in
+.Pa ctm_incoming
+which allows
+.Nm ctm_rmail
+to execute
+.Xr ctm 1
+on the (non-OpenBSD) machine that this example was taken from.
 .Sh SECURITY
 If you automatically take your mail and pass it to a file tree patcher, you
-might think you are handing the keys to your system to the hackers!  Happily,
+might think you are handing the keys to your system to the crackers!  Happily,
 the window for mischief is quite small.
 .Nm ctm_rmail
 is careful to write only to the directories given to it (by not believing any
@@ -302,20 +279,21 @@ must be in your
 .Ev PATH .
 .Sh FILES
 .Bl -tag -width indent
+.It Pa QUEUEDIR/*
+Pieces of deltas encoded as mail messages waiting to be sent to the
+mailing list.
 .It Pa PIECEDIR/*
-Pieces of deltas waiting for the rest.
+Pieces of deltas waiting for the rest to arrive.
 .It Pa DELTADIR/*
 Completed deltas.
 .It Pa BASEDIR/.ctm_status
-File containing name and number of the next delta to be applied to this
+File containing the name and number of the next delta to be applied to this
 source tree.
 .\" This next request is for sections 1, 6, 7 & 8 only
 .\"     (command return values (to shell) and fprintf/stderr type diagnostics)
 .Sh DIAGNOSTICS
-.Nm ctm_smail
-and
 .Nm ctm_rmail
-return exit status 0 for success, and 1 for various failures.
+returns exit status 0 for success, and 1 for various failures.
 .Nm ctm_rmail
 is expected to be called from a mail transfer program, and thus signals
 failure only when the input mail message should be bounced (preferably into
@@ -326,13 +304,6 @@ is not considered an error important enough to bounce 
 .Nm ctm_rmail
 returns an exit status of 0.
 .Pp
-In normal operation,
-.Nm ctm_smail
-will report messages like:
-.Bd -literal -offset indent
-ctm_smail: src-cur.0250.gz 1/2 sent to src-guys
-.Ed
-.Pp
 .Nm ctm_rmail
 will report messages like:
 .Bd -literal -offset indent
@@ -359,10 +330,15 @@ turn up here too.  Error messages should be self expla
 .\" The next request is for sections 2 and 3 error and signal handling only.
 .\" .Sh ERRORS
 .Sh SEE ALSO
-.Xr ctm 1
-(coming soon)
+.Xr ctm 1 ,
+.Xr ctm 5
+.Pp
+.Pa "http://www.openbsd.org/ctm.html"
 .\" .Sh STANDARDS
 .\" .Sh HISTORY
 .Sh AUTHOR
 Stephen McKay <syssgm@devetir.qld.gov.au>
 .\" .Sh BUGS
+.\" Gosh!  No bugs here!
+.\" This message brought to you by the Coalition for More Humour in Man Pages.
+.\"
