X-Git-Url: https://git.distorted.org.uk/~mdw/ezmlm/blobdiff_plain/5b62e993b0af39700031c2875d7f6654e6a02850..f8beb284087c279acfb30506f5bb32baa4949b44:/ezmlm-get.1

diff --git a/ezmlm-get.1 b/ezmlm-get.1
new file mode 100644
index 0000000..12c4e3b
--- /dev/null
+++ b/ezmlm-get.1
@@ -0,0 +1,464 @@
+.TH ezmlm-get 1
+.SH NAME
+ezmlm-get \- handles mailing list archive retrieval and digests
+.SH SYNOPSIS
+.B ezmlm-get
+[
+.B \-bBcCpPsSvV
+][
+.B \-f
+.I format
+]
+.I dir
+[
+.I digestcode[f]
+]
+.SH OPTIONS
+.TP
+.B \-b
+(Default.)
+Copy administrative information and the request to the bottom of replies.
+This informs the recipient of other commands, and allows some error tracking
+in case the recipient did not originate the request.
+.TP
+.B \-B
+Suppress the normal administrative information and request copy. This may make
+it harder for the recipient to diagnose problems and learn commands.
+.TP
+.B \-c
+(Default.)
+Process and reply to commands (does not affect digests).
+.TP
+.B \-C
+Ignore all commands except digest.
+.TP
+.B \-f \fIformat
+.B ezmlm-get
+will use
+.I format
+as the default format for all returned message collections. The default
+is 'm' for MIME with a header subset (see below). Format specifiers
+send with individual requests override the default set with the
+.B \-f
+switch.
+.TP
+.B \-p
+\-get, \-index, and \-thread commands are available to all users,
+provided other flags are permissive. This overrides normal behavior,
+which is to allow archive retrieval only to moderators, when
+.I dir\fB/public
+does not exist. This is useful to set up non-public lists that still give
+users archive access.
+.TP
+.B \-P
+\-get, \-index, and \-thread commands are available
+only to moderators, even if
+.I dir\fB/public
+exists. The
+.B \-C
+and
+.B \-s
+flags can restrict this further. This is useful for public lists with
+archive retrieval restricted to a subset of users (moderators).
+.TP
+.B \-s
+\-get, \-index, and \-thread requests are processed only if
+.B SENDER
+is a subscriber.
+.TP
+.B \-S
+(Default.)
+Anyone can issue \-get, \-index, and \-thread requests.
+.TP
+.B \-v
+Print version info.
+.TP
+.B \-V
+Print version info.
+.SH DESCRIPTION
+.B ezmlm-get
+handles archive retrieval and optionally makes and sends out
+digests for the mailing list
+stored in
+.IR dir .
+Subscribers of the digest list are stored in
+.IR dir\fB/digest/subscribers/ .
+
+The contents of
+.I dir\fB/headeradd
+are added to the header of outgoing messages.
+
+.B ezmlm-get
+is normally invoked from a
+.B .qmail(7)
+file.
+
+It reads a mail message from its standard input,
+and a mail envelope from the
+.BR SENDER ,
+.BR LOCAL ,
+and
+.BR HOST
+environment variables.
+
+.B ezmlm-get
+uses
+.B LOCAL
+to determine where it is invoked. If
+.B LOCAL
+is the list local name only,
+.B ezmlm-get
+assumes it is run from
+.I dir\fB/editor
+to produce a digest.
+The digest is sent directly to the digest list subscribers.
+
+If
+.B LOCAL
+is empty or undefined,
+.B ezmlm-get
+assumes it is run from the command line or a script. In this case
+it behaves as if run from
+.I dir\fB/editor
+and sends out a digest to the digest subscribers.
+
+Otherwise,
+.B ezmlm-get
+expects
+.B LOCAL
+to be of the form
+.IR list\fB-\fIaction .
+Here
+.I list
+is the first line of
+.IR dir\fB/inlocal
+and
+.I action
+is a request.
+The output is sent to the envelope sender.
+
+.BR ezmlm-get
+checks
+.I action
+for
+.BR dig\.\fIdigestcode ,
+.BR index ,
+.BR thread ,
+and
+.BR get .
+If 
+.I action
+is one of these,
+.B ezmlm-get
+handles the request and sends a reply. If successful, it
+exits 99 (ignore remaining
+.B .qmail(7)
+file entries).
+If
+.I action
+is not one of these,
+.B ezmlm-get
+exits 0 (success) to pass the message on to later handlers,
+such as
+.BR ezmlm-manage(1) .
+
+.B ezmlm-get
+expects
+.B HOST
+to match the first line of
+.IR dir\fB/inhost .
+
+.BR ezmlm-dig\.\fIdigestcode
+returns a digest of messages received since the last digest, unless
+numerical arguments are given.
+.I digestcode
+must be alphanumeric, and match (case-insensitive)
+.I digestcode
+on the
+.B ezmlm-get
+command line. Otherwise, the request will be ignored. This is to restrict
+digest creation. The body of the requesting message up to the first line
+starting with '-' is copied into the
+.I administrivia 
+section of the digest. This is followed by the contents of
+.IR dir\fB/text/digest ,
+if this file exists.
+
+.B Note:
+Anyone who can read your
+.I dir\fB/manager
+file, digest-requesting scripts, or mail log knows the
+.I digestcode
+and can trigger digests.
+
+.B ezmlm-get
+copies
+.I dir\fB/mailinglist
+into a
+.B Mailing-List
+field in its response.
+If the incoming message has a
+.B Mailing-List
+field,
+.B ezmlm-get
+refuses to respond.
+.B ezmlm-get
+also refuses to respond to bounce messages.
+
+If
+.I dir\fB/listid
+exists,
+.B ezmlm-get
+will assume that the format is correct and
+create a ``List-ID:'' header by placing the contents after the
+text ``List-ID: ''. 
+
+If
+.I dir\fB/qmqpservers
+exists,
+.B ezmlm-get will use
+.B qmail-qmqp(1)
+to send digests. Other messages are sent by the normal qmail mechanism.
+
+If
+.I dir\fB/public
+does not exist,
+.B ezmlm-get
+rejects all archive retrieval attempts, unless the
+.B \-p
+command line switch is used.
+
+Archive retrieval actions can be of the form
+.BR action[f] , 
+.BR action[f].\fInum 
+or 
+.BR action[f].\fInum_num2 ,
+where 
+.I num
+is the message number for the action or
+.I num_num2
+the range of message numbers for the action.
+
+.B f
+is an optional format specifier for
+.IR \-get ,
+.IR \-thread ,
+and
+.I \-dig
+requests. It is allowed, but ignored for
+.I \-index
+requests. Currently, the following are allowed:
+
+.TP
+.B r
+rfc1153. This is a ``plain'' non-MIME format for dumb clients.
+.TP
+.B m
+(Default.) MIME
+.I multipart/digest 
+with a subset of ordered headers sorted.
+Currently, the following headers are
+included in the order listed:
+Date:,
+To:,
+From:,
+Reply-To:,
+Cc:,
+MIME-Version:,
+Content-Type:,
+Message-ID:,
+and Keywords:.
+This can be customized with the optional file
+.IR dir\fB/digheaders ,
+which should contain the desired headers up to but not including the colon.
+
+The format is no longer compliant
+with rfc1153, as the rfc1153 format is incompatible with rfc2046, which
+which the format is (should be) compatible.
+.TP
+.B x
+MIXED: This is the same as the default MIME
+format, except that the Content-Type is
+.IR multipart/mixed .
+This helps circumnavigate a Pine bug: when the digest is
+content-transfer-encoded, Pine will refuse to display the initial
+text/plain part of a 
+.I multipart/digest
+message, but display the same part of a
+.I multipart/mixed
+message. Some MUAs for some strange reason treat the two multipart formats
+differently. In some cases, ``x'' works better than ``m''.
+.TP
+.B v
+VIRGIN: This is MIME
+.I multipart/digest 
+with messages returned without any header filtering.
+.TP
+.B n
+NATIVE: This is VIRGIN format without threading, i.e. messages are
+presented in numerical order and the message index is suppressed.
+
+.PP
+For flexibility and backwards compatibility, the '.' separating the action from
+the first argument can be replaced by '\-',
+or omitted.
+Any non-alphanumeric character can separate
+.I num2
+from
+.IR num .
+.PP
+
+If
+.I action
+is
+.IR dig.digestcode ,
+.B ezmlm-get
+returns a digest of the messages received since the last digest, and updates
+the digest issue counter.
+
+If
+.I action
+is
+.IR get ,
+.B ezmlm-get
+sends back message(s)
+.I num
+or
+.I num
+through
+.IR num2 .
+from
+.IR dir\fB/archive/ .
+If
+.I num
+is omitted and
+.I dir\fB/dignum
+does not exist or is 0, the latest HISTGET message (default 30) are
+returned. Otherwise,
+the messages since the latest digest are returned including the last
+message in that digest, so that always at least 1 message is send. If the
+number of messages
+exceeds MAXGET (default 100), only the MAXGET last messages are returned.
+if
+.I num
+is greater than the latest message in the archive _and_
+.I num2
+is specified, the latest messages back to HISTGET before the end of the
+latest digest up to MAXGET messages are returned. This is a good way of
+always getting at least the latest 30 messages without knowing the latest
+message number. A link with such a command could be put into e.g.
+.IR dir\fB/text/sub-ok .
+
+.I num
+and
+.I num2
+are adjusted to make both > 0, and
+.I num2
+>=
+.IR num .
+If either is greater than
+the largest message number processed, it is silently
+set to the largest message number.
+At most 100 messages are
+returned.
+
+If
+.I action
+is
+.BI index ,
+.B ezmlm-get
+sends back the subjects and authors of the message(s)
+.I num
+or
+.IR num
+through
+.I num2
+in sets of 100 from
+.IR dir\fB/archive/ .
+.I num
+and
+.I num2
+are reasonable adjusted as for 'get'. No warnings are
+sent. At most 20 sets of 100 message entries are returned per request. If
+.I num
+is omitted,
+.B ezmlm-get
+returns the last 100-200 message entries, which automatically gives
+information about the last message number.
+
+If
+.I action
+is
+.BI thread ,
+.B ezmlm-get
+sends back the message(s) that have an index subject entry identical to
+that of message
+.I num 
+from
+.IR dir\fB/archive/ .
+
+If
+.I num2
+is given it is ignored. If
+.I num
+is out of range, and error
+message is returned. The message range scanned for the subject is limited
+to 2000 messages before and after the master message, i.e. the
+.BR thread
+argument.
+This limit protects very large archives.
+Most threads are expected to be considerably more short-lived.
+In the unlikely event that there are further messages,
+these can be retrieved by a second request for the 
+highest/lowest message returned in the first request.
+.SH "CHARACTER SETS"
+If
+.I dir\fB/charset
+exists,
+.B ezmlm-get
+will use the character set listed for all messages. Otherwise, the
+default ``us-ascii'' will be used. The character set can be suffixed
+by ``:'' followed by a code. If the code is ``Q'', outgoing messages are 
+sent as ``Quoted-Printable'', if it is ``B'' they are sent ``base64'' encoded.
+Otherwise, text is sent as is.
+.SH "FILES"
+.TP
+.I dir\fB/dignum
+The last message included in the latest normal mode digest.
+.TP
+.I dir\fB/digissue
+The issue number of the latest normal mode digest.
+.TP
+.I dir\fB/text/get-bad
+Returned if a/the message cannot be found.
+.TP
+.I dir\fB/text/digest
+Copied into the
+.I Administrivia
+section of digests after the body of the requesting message.
+.TP
+.I dir\fB/charset
+The character set used for all
+.B ezmlm-get
+messages (see above).
+If not present, the default, ``us-ascii'', is used without encoding.
+.SH BUGS
+The digest format per rfc2046
+should (but is not required to) be multipart/mixed
+with the table-of-contents a text/plain part, and the entire remainder of
+the digest a multipart/digest part. The multipart/digest in turn should 
+contain all the messages. Many
+MUA's fail to split out the individual messages from such a hierarchy, so the
+format used by
+.B ezmlm-get
+is a simple multipart/digest, explicitly typing the table-of-contents
+to text/plain, with the ``x'' format changing the mail content-type to
+multipart/mixed.
+.SH "SEE ALSO"
+ezmlm-make(1),
+ezmlm-manage(1),
+ezmlm-send(1),
+ezmlm(5),
+qmail-command(8),
+qmail-qmqp(1)
+