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