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.