Release 1.8a will introduce a new system for the generation of
administrative mail, such as messages sent to users as they subscribe to
a list or are requested to confirm their subscription. This replaces
LSVIMAIL and the MAILFORM files. Unfortunately it was not possible to
maintain compatibility with the old system, as it was based on the use of
REXX INTERPRET statements whereas the new code must work on operating
systems where REXX is not standard. This means that customized messages
will have to be converted to the new format, and to facilitate this
process the documentation for the new mail template processor is being
released now. In addition, the new set of default templates is available
from LISTSERV@SEARN under the name DEFAULT MAILTPL (note that
LISTSERV@SEARN still runs 1.7f and uses the old MAILFORM system). Version
1.7f will ignore any 'listname MAILTPL' file it finds on its A-disk, so
you can already prepare the new format customized messages for your lists
and make them available on LISTSERV's A-disk. You should keep the old
MAILFORM files until the upgrade to 1.8a, at which point they should be
erased to avoid future confusion.
The advantages and end-user benefits of the new system are:
- The single quote character no longer has any special meaning.
Previously, single quotes had to be doubled in expressions such as
"you're about to", or a REXX error would result. This was the single
largest source of mailform errors and confusions.
- Because the new mail template processor is a closed environment, list
owners can be given direct access to the templates for their lists
without jeopardizing system security. The individual MTPLATE files can be
maintained in the same fashion as the WELCOME and FAREWELL message files,
without any intervention by the LISTSERV administrator. List owners do
not have to worry about their LISTSERV administrator's willingness to
install and update customized mailforms for them, and the LISTSERV
administrator is relieved from this clerical duty. With version 1.8, any
list owner with write access to a filelist can create customized mail
templates for his list.
- Since the REXX interpreter is no longer used, templates written in the
new format will be directly compatible with the future VMS and Windows NT
versions of LISTSERV that L-Soft is working on.
- The text and format of most administrative messages has been updated
and reworded for easier comprehension by non-technical users. A more
restricted vocabulary has been used for the benefit of non-native
speakers.
- Substitutions are now introduced by the ampersand (&) character, and
easier to identify than with the old quote parity system. List header
keywords can be queried in a simpler way than previously:
&KWD(NOTEBOOK,3) vs 'Word(LSVKEYWD(listname,"NOTEBOOK"),3)' to query the
frequency of archives, for instance.
The procedure for customizing mail templates is very similar, in concept,
to that used with 1.7 mailforms. You must first obtain a copy of the
master template file which contains all the default templates. This file
is now called DEFAULT MAILTPL and available from any LISTSERV running
version 1.8 (anyone can obtain a copy, as it does not contain any
confidential information). The next step is to identify and locate the
templates you want to modify, and extract them into a file called
'listname MAILTPL' - the list template file. It is important to extract
the individual templates into a separate file rather than just edit the
whole file and send it back under the new name, because changes to the
software may require certain templates to be modified. If you store an
unmodified template you did not want to change into the list template
file, the version you have stored will be used forever. If new
information is added to the template in a future version, your list will
not benefit from it; if an incompatible change is required, you will have
to waste time updating your list template file to reflect that change.
Either way, you will waste time in the long run, and of course you will
be wasting disk space.
Each template starts with an internal code and subject line, such as:
>>> EXAMPLE1 This is the subject line for the message
The template starts with the line containing the code and subject, and
ends with the next '>>>' line or at the end of the file. There is no
':END' line like in the MAILFORM files. The code names are exactly the
same as with the old mailforms. As before, the subject line may contain
substitutions (such as "&LISTNAME: &WHOM requested to join").
The template contains text and, optionally, formatting/editing commands,
which start with a period in column 1. All other lines are treated as
normal text: sequences started with an & sign are substituted, then lines
are joined together to form a paragraph which is formatted much like with
any non-WYSIWYG text processor. You can suspend formatting with .FO OFF
and resume it with .FO ON; when formatting is suspended, LISTSERV simply
writes one line of text to the message for each line read from the
template, which makes it possible to include tables or a text-mode logo,
but can create seriously imbalanced text if substitutions are used, as
the typical &WHOM (target address) substitution can be just a dozen
characters or then 60, but only takes up 5 characters on your screen when
you enter it.
The following substitutions are always available:
&DATE Long-style date (29 Jul 1993)
&TIME hh:mm:ss
&WEEKDAY Three-letter day of the week
&MYNAMES The substitution you will use most of the time when you
need to refer to LISTSERV. For BITNET-only or Internet-only
servers, this will display LISTSERV's only e-mail address.
For servers with both BITNET and Internet connectivity, it
will say "[log in to unmask] (or LISTSERV@hostname)".
&MYSELF LISTSERV's address, in the form [log in to unmask] or, if no
Internet hostname is available, [log in to unmask]
&MYNODE LISTSERV's BITNET nodeid, without the '.BITNET', or its
Internet hostname if no NJE address is available.
&MYHOST LISTSERV's Internet hostname or, if none is available, its
NJE address (with '.BITNET').
&MBX(addr) Looks up the specified address in LISTSERV's signup file
and displays "name <addr>" if a name is available, or just
the original address otherwise. This is typically used to
give the name of the command originator or target in
addition to his e-mail address: &MBX(&WHOM) or
&MBX(&INVOKER).
The following substitutions are also available for templates related to
mailing lists:
&LISTNAME Short (CMS) name of the list.
&TITLE Title of the list, or empty string.
&KWD(kwd) Value of the specified keyword for the list. You do not
need to specify the name of the list - it is implicit. You
do not need to put quotes around the keyword names either,
although quotes will be accepted if present. Optionally,
you can specify a second numeric argument to extract just
one of the terms of a list header keyword; for instance, if
the list header contains "Notebook= Yes,L1,Monthly,
Private", &KWD(NOTEBOOK,4) has the value "Private". A third
argument, also optional, specifies the default value for
the keyword in case it was not initialized. It is meant to
be used for conditional formatting and list owners need not
worry about it.
In addition, many templates have their own specific substitutions which
are meaningful only in their specific context. For instance, a message
informing a user that he was removed from a mailing list may have a
&INVOKER substitution for the address of the person who sent the DELETE
command. This is not meaningful for a template informing a user that he
must confirm his subscription to a list within 10 days, so it is not
generally available. If you attempt to use a substitution which is not
available, the template processor write an error message to the mail
message it is generating, but sends it anyway, in the hope that the
recipient will be able to figure out the meaning of the message in spite
of the error. If you need to include a sentence with an ampersand
character, you will have to double it to bypass the substitution process:
Thelma && Louise.
Any line starting with a period in column 1 is processed as a formatting
command. Note that neither substitutions nor formatting commands are case
sensitive. Here is a list of the formatting commands list owners may need
to use:
.* Comment: anything on this line is simply ignored. This is
useful for recording changes to template files when there
are multiple owners. Just add a comment line with the date
and your initials every time you make a change, for the
benefit of the other owners.
.FO OFF Turns off formatting: one template line = one line in the
final message. .FO ON resumes formatting.
.CE text Centers the text you specify (just the text you typed on
the same line as the .CE command). This can be useful to
highlight the syntax of a command.
.RE OWNERS Adds a 'Reply-To:' field pointing to the list owners in the
header of the generated message. Use this command when you
think users are likely to want to reply with a question.
You can also use .RE POSTMASTER to direct replies to the
LISTSERV administrator.
.QQ Cancels the message. LISTSERV stops reading the template
and does not send anything. This is useful if you want to
completely remove a particular message; note however that
this can be confusing with certain commands, as LISTSERV
may say "Notification is being sent to the list owners"
when in fact nothing will be sent because of the .QQ
command.
A number of more advanced commands are available to list owners with more
sophisticated needs and some programming experience. If you encounter one
of these commands in a template, you will probably want to leave it
alone.
.IM name Imbeds (inserts) another template at this point in the
message. This is used to avoid duplicating large pieces of
text which are mostly identical, such as the templates for
"you have been added to list X by Y" and "your subscription
to list X has been accepted".
.BB cond Begin conditional block. The boolean expression following
the keyword is evaluated and, if false, all the text
between the .BB and .EB delimiters is skipped. Conditional
blocks nest to an arbitrary depth. The expression evaluator
is recursive but not very sophisticated; the restriction
you are most likely to encounter is that all
sub-expressions have to be enclosed in parentheses if you
are using boolean operators. That is, ".BB &X = 3" is valid
but ".BB &X = 3 and &Y = 4" is not. String literals do not
require quoting unless they contain blanks, but quotes are
accepted if supplied. Comparison operators are = <> ^= IN
and NOT IN (the last two look for a word in a
blank-separated list of options, such as a keyword value).
These operators are not case-sensitive; == and ^== are
available when case must be respected. Boolean operators
are AND and OR.
.SE var text Defines or redefines a substitution variable. This is
convenient for storing temporary (text) expression results
which need to be used several times. Even standard
variables such as &LISTNAME can be redefined - at your own
risk. You must enclose the text expression in single quotes
if you want leading or trailing blanks.
.TY text Types one line of text on the LISTSERV console log. This
can be useful to the LISTSERV maintainer for debugging, and
also to record information to the log.
Eric
|
