README.listtexts

List texts in mlmmj
===================

List texts are stored in listdir/text. They specify the content of various
automatic emails that Mlmmj sends. They are provided in a number of different
languages. The language to use for a list is chosen when you run the
mlmmj-make-ml script and the appropriate files are copied into your
listdir/text directory.

This file documents

- Supported list texts
- List text format
- List text substitutions

Supported list texts
--------------------

The following list texts are supported by mlmmj:

- access
  sent to a poster when their post is denied because of an access rule

- bounce-probe
  sent to a subscriber after an email to them bounced to inform them of the
  bounce and probe when the address is no longer bouncing

- digest
  sent at the start of a digest

- listfaq
  sent in response to an email to listname+faq@domain.tld

- listhelp
  sent in response to an email to listname+help@domain.tld

- listsubs
  sent in response to an email to listname+list@domain.tld from the list owner
  (the formatted list of subscribers is automatically appended to the listtext)

- maxmailsize
  sent to the poster when a mail exceeds the maximum allowed size

- moderation
- moderation-poster
  sent when a message is to be moderated (to the appropriate moderators or to
  the poster)

- notifysub
- notifysub-digest
- notifysub-nomail
- notifyunsub
- notifyunsub-digest
- notifyunsub-nomail
  sent to the list owner when somebody is (un-)subscribed

- notintocc
  sent to the poster when the list address is not found in a To: or CC: header

- sub-confirm
- sub-confirm-digest
- sub-confirm-nomail
  sent to a requester to allow them to confirm a subscription request

- sub-deny-digest
- sub-deny-nomail
  sent when a subscription request is received for the digest or nomail version
  of a list when that version is disabled

- sub-ok
- sub-ok-digest
- sub-ok-nomail
  sent to the new subscriber when a subscription succeeds

- sub-subscribed
  sent to a person sending a subscription request when they are already
  subscribed to the list

- submod-moderator
- submod-requester
  sent when a subscription is to be moderated (to the appropriate moderators
  or to the requester)

- subonlypost
  sent to the poster when they attempt to post to a subonlypost list without
  being subscribed

- unsub-confirm
- unsub-confirm-digest
- unsub-confirm-nomail
  sent to a subscriber to allow them to confirm an unsubscription request

- unsub-notsubscribed
  sent to a person sending an unsubscription request when they are not actually
  subscribed to the list

- unsub-ok
- unsub-ok-digest
- unsub-ok-nomail
  sent to the old subscriber when an unsubscription succeeds

List text format
----------------

They have the following format:

- Headers
- Blank line
- Body

They are expected to be in UTF-8 encoding and have Unix line endings.

The headers should be formatted as they should appear in the mail message. They
will begin the mail message. Header continuation via lines beginning with
linear whitespace is supported.

Following the headers found in the list text, Mlmmj will output the following
default headers, unless the same header is already provided in the list text.

- From:
- To:
- Message-ID:
- Date:
- Subject: mlmmj administrivia
- MIME-Version: 1.0
- Content-Type: text/plain; charset=utf-8
- Content-Transfer-Encoding: 8bit

The Subject: header is treated specially: it may include UTF-8 characters,
which will automatically be escaped using the =?utf-8?q?...?= quoting
mechanism.

List text substitutions
-----------------------

Both headers and body may include the following, which are substituted prior to
sending the message (though note that some of these substitutions are
multi-line substitutions and would not work in a header):

- $bouncenumbers$
  (available only in bounceprobe)
  the formatted list of indexes of messages which may not have been received as
  they bounced

- $confaddr$
  (available only in [un]sub-confirm[-digest|-nomail])
  the address to which to send mail to confirm the (un-)subscription in
  question

- $controlN$
  the contents of the control file named N, with its final newline stripped; N
  represents the name of the file to be found in the list's control
  subdirectory; the name may only include letters and digits

- $digestfirst$
  (available only in digest)
  index of the first message included in a digest

- $digestinterval$
  (available only in digest)
  indexes of the first and last messages included in a digest (e.g. 1-5), or
  just the index if only a single message is included

- $digestissue$
  (available only in digest)
  the issue number of the digest

- $digestlast$
  (available only in digest)
  index of the last message included in a digest

- $digestsubaddr$
  listname+subscribe-digest@domain.tld

- $digestthreads$
  (available only in digest)
  the list of threads included in the digest

- $digestunsubaddr$
  listname+unsubscribe-digest@domain.tld

- $faqaddr$
  listname+faq@domain.tld

- $helpaddr$
  listname+help@domain.tld

- $listaddr$
  listname@domain.tld

- $listgetN$
  listname+get-N@domain.tld
  (the N here is nothing special, so this won't actually work, but is used to
  explain to users how to use the +get functionality)

- $listowner$
  listname+owner@domain.tld

- $listsubaddr$
  listname+subscribe@domain.tld

- $listunsubaddr$
  listname+unsubscribe@domain.tld

- $maxmailsize$
  (available only in maxmailsize)
  the maximum size of mail that Mlmmj will accept

- $moderateaddr$
  (available only in moderation and submod-moderator)
  the address to which to send mail to approve the post or subscription in
  question

- $moderators$
  (available only in moderation, moderation-poster and submod)
  the formatted list of moderators to whom the moderation request has been sent

- $newsub$
  (available only in notifysub, notifysub-digest and notifysub-nomail)
  the address that has been subscribed

- $nomailsubaddr$
  listname+subscribe-nomail@domain.tld

- $nomailunsubaddr$
  listname+unsubscribe-nomail@domain.tld

- $oldsub$
  (available only in notifyunsub, notifyunsub-digest and notifyunsub-nomail)
  the address that has been unsubscribed

- $originalmail$
- $originalmailN$
  the email message being processed (usually a mail being moderated); this must
  appear first on a line, optionally preceded by whitespace: any preceding
  whitespace is prepended to each line of the mail that is included and the
  rest of the line following originalmail$ is ignored; N represents a number,
  which is how many lines of the message (including headers) to include: if
  omitted, 100 will be used, and to include the whole message, use a large
  number like 1000000000.

- $posteraddr$
  (available only in access, notintocc, moderation, moderation-poster and
  subonlypost)
  the from address of the message that was received as determined by Mlmmj

- $random0$
- $random1$
- $random2$
- $random3$
- $random4$
- $random5$
  these are 6 distinct random strings; they allow list texts to be constructed
  that are MIME messages with attachments by using creating boundaries that are
  unlikely to appear in the attached messages

- $subaddr$
  (available only in submod-moderator and [un]sub-confirm[-digest|-nomail])
  the address requested to be (un-)subscribed

- $subject$
  (available only in access, notintocc, moderation, moderation-poster and
  subonlypost)
  the subject line of the message in question

- \uNNNN
  (NNNN are hex digits)
  a Unicode character
  (this is not really appropriate for use in a header, except perhaps the
  Subject: header as Mlmmj does automatic quoting for that header as described
  above)