Description of the changes for release 1.8a of LISTSERV
-------------------------------------------------------
Copyright L-Soft international, 1993
December 7th, 1993
(...)
- New template processor that lets list owners customize administrative
messages without intervention by the LISTSERV maintainer. Formerly this
was not possible without a LISTSERV modification that would jeopardize
the security of all users on the LISTSERV host, even when the list
owner could be trusted. Customers who decided to trade this risk for
added functionality can now enjoy direct support for cutomized messages
without exposing their users in any way.
(...)
***************************************************
* Usability/Security: New mail template processor *
***************************************************
Release 1.8a introduces a new system for the generation of administrative
mail messages, such as the messages sent to users as they subscribe to a
list or are requested to confirm their subscription. This new system is
easier to use, can be placed under direct list owner control, and will
work without change under the new environments LISTSERV is being ported
to, as it no longer relies on the REXX interpreter for expression
evaluation via the INTERPRET statement. Unfortunately, this means that it
was not possible to maintain compatibility with the old system, which
allowed arbitrary REXX expressions and statements.
Both the old and the new systems are based on a collection of "forms" or
"templates", each of which corresponds to a particular administrative
event, such as a subscriber requesting to be added to a mailing list. The
templates are gathered together and stored as a single disk file, called
listname.MAILFORM with the old system and listname.MAILTPL with the new
system. When LISTSERV needs to use a particular template, it first looks
in the file called listname.MAILTPL, if there is one. If the file is not
present or if that particular template is not found in the file, it then
searches a "language template" file (as specified by the "Language=" list
header keyword), and finally examines the default template file, called
DEFAULT.MAILTPL. To customize a particular administrative message, one
simply orders a copy of DEFAULT.MAILTPL, extracts and modifies the
template of interest, and stores the resulting file as listname.MAILTPL.
It is not necessary to carry over the templates that need not be changed,
and in fact it is not advisable to do so as your list would not benefit
from improvements to these other messages in future versions.
There is no change in this general structure; only the name of the
template files and their format has changed. When you upgrade to version
1.8a, LISTSERV no longer examines the old MAILFORM files and all your
list will revert to the standard messages. The individual MAILFORM files
are not erased, however, except for the $DEFAULT MAILFORM file with all
the system defaults. If you are using customized MAILFORM files, it is
advisable to prepare the new MAILTPL files before the upgrade to 1.8a and
place them on LISTSERV's A-disk (they will have no effect on 1.7f of
course). Once the migration is over and the templates are converted to
your satisfaction, you should erase the old MAILFORM files to avoid
future confusion.
The main advantages and end-user benefits of the new system are:
- The single quote character no longer has any special role or 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 template 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.8a, any list owner with write access to a filelist can create
customized mail templates for his lists.
- 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, which
makes them easier to identify than with the old quote-parity system.
List header keywords can be queried in a simpler way than formerly
possible; for instance,
&KWD(NOTEBOOK,3)
replaces
'Word(LSVKEYWD(listname,"NOTEBOOK"),3)'
********************************
* Format of the template files *
********************************
Each template starts with an form name and subject line, such as:
>>> EXAMPLE1 This is the subject line
The template starts with the line containing the form name and subject,
and ends with the next line starting with '>>>', or at the end of the
file. There is no ':END' line like in the old MAILFORM files. The form
names are exactly the same as with the old system. 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 starting with an & sign are substituted, then
lines are joined together to form a paragraph, which is finally formatted
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
no longer joins lines to form a paragraph, but simply writes one line of
text to the message for each line read from the template. This makes it
possible to include tables or a text-mode logo, but can create seriously
imbalanced text if substitutions are used. For instance, a typical &WHOM
substitution can range from a dozen characters to 60 or more, even though
it 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, in English
&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, along
with 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
need not 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 in the default templates
and list owners should not worry about it.
In addition, many templates have their own specific substitutions,
meaningful only in their specific context. For instance, a message
informing a user that he was removed from a mailing list may have an
&INVOKER substitution for the address of the person who issued 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 writes 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,
as in "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. You can resume formatting with .FO ON.
.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, if this is more appropriate.
.CC OFF Removes all "cc:" message recipients, if any. You can also
add message recipients by specifying a series of e-mail
addresses after the .CC statement, as in .CC [log in to unmask]
PC mail users should note that in this context "cc:" is a
RFC822 term that stands for "carbon copy". RFC822 messages
may have "cc:" recipients in addition to their "primary"
recipients. There is no real technical difference between
the two, the "cc:" indicator just denotes a message that is
being sent for your information. Some administrative
messages sent to list owners are copied to the user for
their information, and vice-versa; this behaviour can be
disabled by adding a .CC OFF statement to the template.
.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 in the template.
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".
.DD ddname Copies the contents of the specified DD into the message.
This is meaningful only if a DD has been set up by LISTSERV
for this purpose. As a rule of thumb, you should either
leave these statements unchanged or remove them.
.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 in the console log.
|
