Documented ctm_dequeue and the new feature of ctm_smail that goes with it.

Expanded the ctm_rmail example usage section.

usr.sbin/ctm/ctm_rmail/Makefile

@@ -1,6 +1,6 @@
 PROG=           ctm_rmail
 SRCS=           ctm_rmail.c error.c
 CFLAGS+=        -Wall
-MLINKS+=	ctm_rmail.1 ctm_smail.1
+MLINKS+=	ctm_rmail.1 ctm_smail.1 ctm_dequeue.1
 
 .include <bsd.prog.mk>

usr.sbin/ctm/ctm_rmail/ctm_rmail.1

@@ -18,8 +18,13 @@ deltas via mail
 .Op Fl l Ar log
 .Op Fl m Ar maxmsgsize
 .Op Fl c Ar maxctmsize
+.Op Fl q Ar queue-dir
 .Ar ctm-delta
 .Ar mail-alias
+.Nm ctm_dequeue
+.Op Fl l Ar log
+.Op Fl n Ar numchunks
+.Ar queue-dir
 .Nm ctm_rmail
 .Op Fl Dfuv
 .Op Fl l Ar log
@@ -31,7 +36,8 @@ deltas via mail
 In conjuction with the
 .Xr ctm 1
 command,
-.Nm ctm_smail
+.Nm ctm_smail ,
+.Nm ctm_dequeue
 and
 .Nm ctm_rmail
 are used to distribute changes to a source tree via email.
@@ -39,7 +45,8 @@ are used to distribute changes to a source tree via email.
 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.
+pieces, encodes them as mail messages and sends them to the mailing list
+(optionally queued to spread the mail load).
 Each recipient uses
 .Nm ctm_rmail
 (either manually or automatically) to decode and reassemble the delta, and
@@ -73,6 +80,13 @@ 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.
+.It Fl q Ar queue-dir
+Instead of mailing the delta pieces now, store them in the given directory
+to be mailed later using
+.Nm ctm_dequeue .
+This feature allows the mailing of large deltas to be spread out over
+hours or even days to limit the impact on recipients with limited network
+bandwidth or small mail spool areas.
 .El
 .Pp
 .Ar ctm-delta
@@ -83,6 +97,42 @@ The mail messages are sent using
 .Xr sendmail 8 .
 .Pp
 Command line arguments for
+.Nm ctm_dequeue :
+.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 n Ar numchunks
+Limit the number of mail messages that
+.Nm ctm_dequeue
+will send per run.  By default,
+.Nm ctm_dequeue
+will send one mail message per run.
+.El
+.Pp
+.Ar queuedir
+is the directory containing the mail messages stored by
+.Nm ctm_smail .
+Up to
+.Ar numchunks
+mail messages will be sent in each run.  The recipient mailing list is already
+encoded in the queued files.
+.Pp
+It is safe to run
+.Nm ctm_dequeue
+while
+.Nm ctm_smail
+is adding entries to the queue, or even to run
+.Nm ctm_smail
+multiple times concurrently, but a separate queue directory should be used
+for each tree being distributed.  This is because entries are served in
+alphabetical order, and one tree will be unfairly serviced before any others,
+based on the delta names, not delta creation times.
+.Pp
+Command line arguments for
 .Nm ctm_rmail :
 .Bl -tag -width indent
 .It Fl l Ar log
@@ -121,10 +171,9 @@ 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 +210,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 +249,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
@@ -267,6 +320,45 @@ 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
 .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
+on the (non-FreeBSD) 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,
@@ -302,17 +394,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
+.Nm ctm_smail ,
+.Nm ctm_dequeue
 and
 .Nm ctm_rmail
 return exit status 0 for success, and 1 for various failures.
@@ -333,6 +429,17 @@ will report messages like:
 ctm_smail: src-cur.0250.gz 1/2 sent to src-guys
 .Ed
 .Pp
+or, if queueing,
+.Bd -literal -offset indent
+ctm_smail: src-cur.0250.gz 1/2 queued for src-guys
+.Ed
+.Pp
+.Nm ctm_dequeue
+will report messages like:
+.Bd -literal -offset indent
+ctm_dequeue: src-cur.0250.gz 1/2 sent
+.Ed
+.Pp
 .Nm ctm_rmail
 will report messages like:
 .Bd -literal -offset indent
@@ -364,5 +471,9 @@ turn up here too.  Error messages should be self explanatory.
 .\" .Sh STANDARDS
 .\" .Sh HISTORY
 .Sh AUTHOR
-Stephen McKay <syssgm@devetir.qld.gov.au>
+Stephen McKay <mckay@FreeBSD.org>
 .\" .Sh BUGS
+.\" Gosh!  No bugs here!
+.\" This message brought to you by the Coalition for More Humour in Man Pages.
+.\"
+.\" $Id$