$OpenBSD: patch-ctm_ctm_rmail_ctm_rmail_1,v 1.3 2010/04/03 19:39:50 naddy Exp $
--- ctm/ctm_rmail/ctm_rmail.1.orig	Wed May  1 01:01:45 1996
+++ ctm/ctm_rmail/ctm_rmail.1	Sat Apr  3 21:36:51 2010
@@ -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
@@ -92,8 +38,10 @@ error diagnostics and informational messages (other th
 are time stamped and written to the file
 .Em log .
 .It Fl p Ar piecedir
-Collect pieces of deltas in this directory.  Each piece corresponds to a
-single mail message.  Pieces are removed when complete deltas are built.
+Collect pieces of deltas in this directory.
+Each piece corresponds to a
+single mail message.
+Pieces are removed when complete deltas are built.
 If this flag is not given, no input files will be read, but completed
 deltas may still be applied with
 .Xr ctm
@@ -101,30 +49,32 @@ if the
 .Fl b
 flag is given.
 .It Fl d Ar deltadir
-Collect completed deltas in this directory.  Deltas are built from one or
+Collect completed deltas in this directory.
+Deltas are built from one or
 more pieces when all pieces are present.
 .It Fl b Ar basedir
-Apply any completed deltas to this source tree.  If this flag is not given,
-deltas will be stored, but not applied.  The user may then apply the deltas
+Apply any completed deltas to this source tree.
+If this flag is not given,
+deltas will be stored, but not applied.
+The user may then apply the deltas
 manually, or by using
 .Nm ctm_rmail
 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,12 +111,17 @@ 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
 .Em stdin ,
-if there are none) are scanned for delta pieces.  Multiple delta pieces
+if there are none) are scanned for delta pieces.
+Multiple delta pieces
 can be read from a single file, so an entire maildrop can be scanned
 and processed with a single command.
 .Pp
@@ -176,7 +131,8 @@ multiple times concurrently (with different input file
 as might happen when
 .Xr sendmail
 .nh
-is delivering mail asynchronously.  This is because locking is used to
+is delivering mail asynchronously.
+This is because locking is used to
 keep things orderly.
 .Sh FILE FORMAT
 Following are the important parts of an actual (very small) delta piece:
@@ -196,7 +152,8 @@ 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,19 +174,8 @@ 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
@@ -252,9 +198,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
@@ -267,9 +213,49 @@ To apply all the deltas collected, and delete those ap
 .Bd -literal -offset indent
 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,37 +288,33 @@ 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.
+.El
 .\" 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
-your regular maildrop, not back to the sender).  In short, failure to
+your regular maildrop, not back to the sender).
+In short, failure to
 apply a completed delta with
 .Xr ctm
 is not considered an error important enough to bounce the mail, and
 .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
@@ -348,21 +330,28 @@ will report:
 ctm_rmail: message contains no delta
 .Ed
 .sp \n(Ppu
-and return an exit status of 1.  You can use this to redirect wayward messages
+and return an exit status of 1.
+You can use this to redirect wayward messages
 back into your real mailbox if your mail filter goes wonky.
 .Pp
 These messages go to
 .Em stderr
 or to the log file.  Messages from
 .Xr ctm
-turn up here too.  Error messages should be self explanatory.
+turn up here too.
+Error messages should be self explanatory.
 .\" 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.
+.\"
