From LO-Wiki
[edit] Creating and Editing LISTSERV's Mail and Web Templates
Note for the 14.3 Release and Following Because the changes to the mail templates from earlier versions of LISTSERV to LISTSERV 14.3 and following are so extensive, it may be useful for the reader to also refer to the completely new, comprehensive
template modulewhich is available on the L-Soft web site. In addition, due to significant changes in LISTSERV's web interface templates in the same version frame, we would refer the reader who wishes to customize his list's web appearance to the comprehensive online help, wizards and tutorials available in the Template Management area of LISTSERV's Web Administration Interface.
[edit] What LISTSERV uses templates for
Templates are used to generate some of the mail LISTSERV sends to users in response to commands it receives. Among these are the "You are now subscribed . . ." message, the message sent to users when LISTSERV cannot find a subscription for them in a specified list, and others. Note that certain administrative mail (for instance, the response to the STATS and RELEASE commands) is hard-coded into LISTSERV and cannot be changed. Other templates are used to generate the HTML code used by the web archive and administration interfaces. A word about nomenclature: When we talk about "templates" we are talking about "files that contain one or more template forms", in other words, files like DEFAULT MAILTPL or DEFAULT WWWTPL. A "template form" is an individual section of a template which begins with a title line (three ">" symbols followed by a space, the name of the template form, and (optionally) a short description of the template, which for some template forms is also used as the subject of the mail LISTSERV constructs with the template form), followed by one or more lines of copy and/or imbedded commands, and ends at the next title line or the end of the file, whichever is reached first. A template may contain one or more template forms.
[edit] The default template files and how to get cop
ies LISTSERV stores its default mail template forms in a file called DEFAULT.MAILTPL, which can be requested by list owners from LISTSERV with the GET command, just like any other file. Note that DEFAULT MAILTPL contains some (but not all) of the web interface template forms. LISTSERV stores the rest of its default web interface template forms in a file called DEFAULT WWWTPL, which can be retrieved in a manner identical to that for DEFAULT MAILTPL. Under 1.8d and following, all template forms may be edited using the web administration interface described in chapter 11. Edited template forms are placed in template files that will not be overwritten by software upgrades.
[edit] Mail template format and embedded formatting commands
Each individual template form starts with a form name and subject line, such as: >>> EXAMPLE1 This is the subject line Please note carefully the following instructions for the form name and subject line:- The template form 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.
- The subject line may contain substitutions (such as "&LISTNAME: &WHOM requested to join").
- Ensure that there is a blank space (ASCII 0x20) between '>>>' and the name of the form, or LISTSERV will not recognize the form.
- Also note that the names of the template forms must be typed in UPPER CASE.
| &DATE | Long-style date (04 Jan 1998) |
| &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 Internet-only or BITNET-only servers, this will display LISTSERV's only e-mail address. For servers with both Internet and BITNET connectivity, it will say "LISTSERV@hostname (or LISTSERV@nodeid.BITNET)". |
| &MYSELF | LISTSERV's address, in the form LISTSERV@XYZ.EDU or, if no Internet hostname is available, LISTSERV@XYZVM1.BITNET. |
| &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). Please note however that &WHOM and &INVOKER are not always available in every template. |
| &RELEASE | LISTSERV's release number (e.g., "1.8d"). |
| &OSTYPE | The operating system under which LISTSERV is running, e.g., VM/VMS/unix/Windows. |
| &OSNAME | The full operating system name including the version number, e.g., "VM/ESA 1.2.3", "Windows NT 3.51", "Linux 2.0.27", "SunOS 5.4", etc. |
| &HARDWARE | The type of machine LISTSERV is running on, e.g., "Pentium (128M)". |
| &LISTNAME | Either the short or long name of the list based on the value of "List-Address=" and/or its system default. By default the long ("List-ID=") name is used if present. |
| &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. |
| &LITE | (1.8c and following) Has the value 1 when running the LISTSERV Lite product, and 0 otherwise. This variable can be used to write generic templates that account for the differences between the two products. |
| &ISODATE | (1.8c and following) Returns today's date in ISO format, i.e., yyyy-mm-dd. |
| &DAYSEQ(n) | (1.8c and following) Used to create FAQ templates with rotating topics. May also be used to create bottom banners with rotating text (e.g., for lists with multiple commercial sponsors who get "ad space" in the banner on a rotating basis). |
| Traditional: | For more information, please send mail to &EMAIL or call &PHONE. |
| HTML: | For more information, please send mail to &EMAIL; or call &PHONE;. |
| .* | 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 or .FO RAGGed. (.FO RAGGed requires LISTSERV 1.8e-2002a or later, that is, build date of 31 October 2002 or later) |
| .FO RAGGed | Changes right-justified text formatting to left justified text formatting. You can resume right-justified formatting with .FO ON. (.FO RAGGed requires LISTSERV 1.8e-2002a or later, that is, build date of 31 October 2002 or later) |
| .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 JOE@XYZ.EDU. 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 behavior can be disabled by adding a .CC OFF statement to the template. |
| .TO | Replaces the default recipients of a message with the value specified. For instance, if you use the ADDREQ1 template form to send new subscribers a questionnaire, application form or similar material, you will need to add a '.TO &WHOM' instruction to your modified template form, as by default the user will not receive a copy. |
| Cancels the message. LISTSERV stops reading the template form 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 form. | |
| .QU | (Starting with 1.8e) Ends processing of the current template as if you had reached the end, but without cancelling the message. The main purpose is to avoid multi-level nested .BB/.EB conditional blocks (see below) that are hard to keep track of. |
| .IM name | Imbeds (inserts) another template form 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". As noted above, LISTSERV will not pick up an "imbedded" template form from $SITE$.MAILTPL. If you wish to include an "imbedded" template form (e.g., $SIGNUP) in $SITE$.MAILTPL, you must also include the template form that calls it with the .im command. |
| .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. Note that a conditional block must be contained on one physical line and may not wrap, so be careful when sending MAILTPL files back to LISTSERV that you do not accidentally wrap long .BB lines. Starting with LISTSERV 1.8d the operators =* and ^=* are available to perform wildcard matches in conditional blocks. For instance JOHN_DOE@UNIX.EXAMPLE.COM =* J*DOE@*EXAMPLE.COM is a true statement. The wildcard specification is on the right-hand side whereas the actual text (or variable) you are evaluating is on the left. |
| .EB | End conditional block (see .BB). |
| .QU | Stop (, ie, QUit) processing of the current template as if you had reached the end, but without cancelling the message. The main purpose is to avoid multi-level nested .BB/.EB conditional blocks that are hard to keep track of. Available in 1.8e and following. |
| .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. |
| .CS text | Define a (non standard) character set for the template in question, i.e., .CS ISO-8559-7 This setting is ignored if the template does not actually contain special characters (for instance, if the template is written in 7-bit ASCII). Otherwise the appropriate headers are created for the message in question when it is sent out, i.e., Content-Type: text/plain; charset=ISO-8859-7 Content-Transfer-Encoding: quoted-printable |
| .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. |
| .ASIS text | Tells LISTSERV to leave the text immediately following the .ASIS directive alone, ie, don't convert "<" and ">" characters into HTML < and > when creating pages. This is specifically for use in HTML templates where it is important not to convert parts of a URL reference. For instance, .ASIS Click <a href="http://some.host.com/some-doc.html">here</a>. As with the .CE directive, the text you intend to affect with the .ASIS directive must not wrap. The .ASIS directive will only work on text it finds on the same physical line into which it is coded. |
[edit] 8-bit characters in templates
Starting with 1.8d, if you include 8-bit characters (e.g., accented or national language characters) in templates, LISTSERV will automatically encode the templates on-the-fly in MIME quoted-printable encoding. While there is no guarantee that every mail program will be able to properly display 8-bit characters, those mail programs that understand MIME quoted-printable encoding should have no trouble doing so.
[edit] Creating and editing a <listname>.MAILTPL file for a list
Please note that list-level mail templates are not available in LISTSERV Lite. Make a copy of DEFAULT.MAILTPL on your local machine and name it listname.MAILTPL.[#footnote_anchor-6 6] Keep the original DEFAULT.MAILTPL around in case you make a mistake and need to start over. At this point, you could theoretically store the listname.MAILTPL back on the LISTSERV host. However, without making any changes that would be somewhat pointless. At the very least you should edit the INFO template form before storing the template. Note also that you need only store the sections of the template that you have changed. For instance, if you edit the INFO template form but leave the rest of the template untouched, you can delete the rest of the template and store the INFO template form alone as listname.MAILTPL. The benefit to this approach is that any administrative changes to the rest of the default template are automatically applicable to your list as soon as they are made, rather than requiring that you edit your mail template individually to reflect such changes. L-Soft recommends that this approach be followed as the default. Under LISTSERV 1.8d and following it is not necessary to do the GET and PUT; you can edit individual template forms by using the web administration interface (described in chapter 11) instead.
[edit] The INFO
template form The first section of DEFAULT.MAILTPL is called the INFO template form, and it is LISTSERV's response to the command INFO listname. By default, it contains the following: >>> INFO Information about the &LISTNAME list There is no information file for the &LISTNAME list. Here is a copy of the list "header", which usually contains a short description of the purpose of the list, although its main purpose is to define various list configuration options, also called "keywords". If you have any question about the &LISTNAME list, write to the list owners at the generic address: .ce &LISTNAME-Request@&MYHOST .dd &LISTHDR[edit] 9.1. The default contents of the INFO template form of DEFAULT.MAILTPL.
Note the replaceable parameters &LISTNAME and &MYHOST. Don't change &MYHOST; LISTSERV replaces it with the correct value for the name of the host site. &LISTNAME automatically inserts the name of the list. It's probably best to use &LISTNAME to refer to the list throughout the document rather than to replace it with something like "MYLIST-L". This ensures that the template form will be consistent with the default and will be simpler to debug should a problem arise. Also, in the event the name of the list changes, it will be unnecessary to edit the template form (although it would have to be renamed to match the new name of the list, of course). Should it be desirable to replace the default INFO template form with information about the list, it is probably best to remove the .dd &LISTHDR line. This line instructs LISTSERV to read in the header of the list and add it to the response in lieu of any other data about the list. Many list owners add descriptive comment lines to their list headers, thus this default. Here is a minimally-edited sample INFO template form for a list called MONKEYS:[#footnote_anchor-7 7] >>> INFO Information about the &LISTNAME list &LISTNAME is an open, unmoderated discussion list featuring monkeys. Things such as how to care for a pet monkey, monkey diseases, monkey lore, endangered species of monkeys, and monkey psychology are likely to be discussed. The list is NOT intended for discussion of Darwinism and/or theories of evolution. If you have any question about the &LISTNAME list, write to the list owners at the generic address: .ce &LISTNAME-Request@&MYHOST[edit] 9.2. Sample edited INFO template form.
[edit] Other useful template
forms Traditionally, message templates have contained the text of "long" administrative messages, such as messages informing subscribers that they have been removed from a mailing list. These notices were sent unconditionally, as a separate message. Since version 1.8b, the template processor has supported "linear" messages, which are sent as a normal command reply and allow the list owner to modify the replies from selected commands, and "optional" messages, which are only sent if a template for this action has been specifically provided by the list owner. In a linear message, most special instructions are ignored. This is because the contents of the template form are just a few lines out of a larger message that is being prepared by LISTSERV to contain the reply to the user's command(s). For instance, you do not have any control over the "Reply-To:" field of the message, because the message in question is shared with other commands and, in fact, may not be a mail message at all but an interactive message to the user's terminal, a GUI request, etc. Generally speaking, with a linear message you are providing the TEXT of the reply to be shown to the user, but you do not have any control over the methods used for delivering this information. Here is a list of all of the template forms (other than INFO, described above) available in DEFAULT.MAILTPL, in the order in which they appear and with a short description for each. Linear and optional template forms are noted where applicable.
[edit] MOVE1
Usually active only for peered lists. This message is sent to the subscriber when the list owner or LISTSERV maintainer changes which peer the subscriber receives his or her mail from.[edit] SIGNOFF1
a notification to the list owner that someone has unsubscribed from the list. Whether or not the list owner receives this notification is controlled by the "Notify=" list header keyword.[edit] SIGNOFF2
this message is sent to any user who attempts to unsubscribe from a list to which he or she is not subscribed under the userid from which the unsubscribe command has been sent. For instance, joe@unix1.somehost.com may be subscribed to list MYLIST-L. If his Pine client is set so that his mail comes from his root domain (e.g., joe@somehost.com), he will get this message if he tries to unsubscribe from MYLIST-L.[edit] DELETE1
the message sent when a list owner or the LISTSERV maintainer deletes a user from a list. You can suppress the sending of this message by prepending "QUIET" to your "DELETE" command.</h4>AUTODEL1</h4> this is the message that is sent to users who are deleted by the delivery error monitor. You can customize it to fit your needs, or suppress it for your list by simply redefining it in the 'listname.MAILTPL' and using the .QQ instruction: >>> AUTODEL1. This message is not wanted for our list .QQ Note that L-Soft does not generally recommend suppressing this message, as it may indicate a serious problem for the deleted subscriber. ADD1: the message sent when a list owner or a LISTSERV maintainer manually adds a subscriber to a list.
[edit] ADD2
the message sent to the list owner(s) when someone subscribes to their list. As with SIGNOFF1, whether or not the list owner(s) receive this message is controlled by the "Notify=" list header keyword.[edit] ADDREQ1
this message is sent to the list owner when a user requests to join a list with "Subscription= By_owner". Only the list owner is sent a copy of the ADDREQ1 message. If you use this template form to send new subscribers a questionnaire, application form or similar material, you will need to add a '.TO &WHOM' instruction to your modified template form, as by default the user does not receive a copy. SETINFO: the message sent to the subscriber when the list owner or LISTSERV maintainer changes their personal subscription options. Can be suppressed by the invoker with the use of the "QUIET" command modifier. CHANGE1: the message sent when a list owner or LISTSERV maintainer uses the CHANGE command to change a subcriber's address. ADDMOD2: the message sent to the subscriber when the list owner or LISTSERV maintainer changes the subscriber's "real name" field in the SIGNUP database. ADDPW1: the message sent to the user when a LISTSERV maintainer adds a personal password for that user. List owners should not change this template form. ADDPW2: an informational message sent to the LISTSERV maintainer when a user adds or changes his password, but only if an LSV$PW exit has been enabled to do so. Most installations will never use this template form, but it should not be deleted from DEFAULT.MAILTPL in any case. List owners should not change this template form. ADDPW3: an information message sent to the LISTSERV maintainer when a user tries to add or change his password, but only if an LSV$PW exit has been enabled to do so. Most installations will never use this template form, but it should not be deleted from DEFAULT.MAILTPL in any case. List owners should not change this template form. DELPW: the message sent to the user when a LISTSERV maintainer deletes that user's personal password. List owners should not change this template form. RENEW1: this message is sent to subscribers whose subscriptions are due for renewal (see the Renewal= list header keyword for more information). RENEW2: this message is sent to subscribers who did not renew their subscriptions within the grace period after being notified that their subscription was due for renewal. SIGNUP1: the basic "Your subscription request has been accepted" message. $SIGNUP: a template form included with SIGNUP1 and ADD1 (assuming that SIGNUP1 and ADD1 templates include an ".im $SIGNUP" line, which by default they do) which gives the subscriber a basic outline of how to use the list, how various options are set, and where to get more information on using LISTSERV. You can use this template in lieu of a WELCOME file for your list if you don't want two messages to go to the user at subscription time. SUB_CLOSED (linear): this is the message that is sent to a subscriber attempting to join a list with "Subscription= Closed". The default is "Sorry, the &LISTNAME list is closed. Contact the list owner (&OWNER) for more information." SUB_OWNER (linear): this message is sent to a subscriber attempting to join a list with "Subscription= By_owner". The default is "Your request to join the &LISTNAME list has been forwarded to the list owner for approval. If you have any question about the list, you can reach the list owner at &OWNER." Because this is a linear template form (see above), it is not the best place to put long questionnaires, application forms, terms and conditions, or other material that the subscriber should be required to review prior to joining the list. See the "Tips" section below. POST_EDITOR (linear): this is the message LISTSERV sends to people attempting to post to the list, if it is moderated. The default is "Your &MESSAGE has been submitted to the moderator of the &LISTNAME list: &MBX(&MODERATOR)." REQACK1: this message is sent automatically in reply to any message sent to the xxx-request address. The message acknowledges receipt, explains the difference between the LISTSERV and xxx-request addresses, and contains instructions for joining and leaving the list. To suppress this message for your list, simply redefine it in the 'listname.MAILTPL' and use the .QQ instruction: >>> REQACK1 This message is not wanted for our list .QQ- REQNAK1: (1.8e and following): this message is sent automatically in reply to any message sent to the special ALL-REQUEST address by a user who is not authorized to post to that address.
- BAD_ATTACHMENT (linear): If a posting to a list contains an attachment of a type not allowed by the "Attachments=" setting for the list, this template form is sent back to the poster.
- DIST_VIRUS (linear, 1.8e): Assuming that the anti-virus feature introduced in 1.8e is enabled, if LISTSERV detects a virus in a DISTRIBUTE job, the message is returned to sender along with this template text.
- SIZELIM_EXCEEDED (linear, 1.8e): This template form is used if a posting to a list exceeds the limit set by the Sizelim= list header keyword.
- TOP_BANNER_HTML, BOTTOM_BANNER_HTML (optional, 1.8e and following): When these template forms are present, they will be used "as is" for HTML message parts. If absent, the regular banner is used for HTML, probably with less than 100% satisfaction.
- CONTENT_FILTER (optional, 1.8e and following): When present, provides LISTSERV with a ruleset for message content filtering that can be configured at the list level. See chapter 2.16, above, for more information on how to use content filtering.
[edit] Tips for using templates
Many list owners require prospective subscribers to fill in a little questionnaire before being added to the list, or to explicitly state that they have read the list charter and agree to follow all rules or be removed from the list. The most convenient method, for both list owner and subscriber, is to have the SUBSCRIBE command return a copy of the questionnaire (or list charter, etc), and not forward the request to the owner. The user answers the questions and returns them directly to the list owner, who then adds the subscriber manually. Naturally, it is more convenient for the user if this information arrives in a separate message, with a 'Reply-To:' field pointing to the list owner's address. Thus, you should not use the SUB_OWNER template form for this purpose, because it is a linear template form and does not give you any control over the 'Reply-To:' field. The SUB_OWNER template form could be modified to read "A copy of the list charter is being sent to you, please read it carefully and follow the instructions to confirm your acceptance of our terms and conditions." The list charter would then be sent separately, through the ADDREQ1 template form. You would use the .RE OWNERS command to instruct LISTSERV to point the 'Reply-To:' field to the list owners, and .TO &WHOM to change the destination from list owner to subscriber. If you want to receive a copy of the message, you can use .TO &WHOM cc: xxx@yyy. When writing template forms, it is a good idea to use substitutions (&XXXX) for information which may change in the future. In particular, it is not uncommon for lists to have to be moved from one host to another, and this will be a lot easier if the template forms use substitutions for the list address and list host. The &LISTADDR substitution translates the full address of the list (XYZ-L@XYZ.COM), whereas &LISTNAME is just the name (XYZ-L). For references to the server and host, use &MYHOST for the Internet hostname, &MYSELF for the server address (normally LISTSERV@&MYHOST), and &OWNER for the xxx-request mailbox address. These substitutions are "universal" and can be used in all template forms. For instance, if you decide to make a bottom banner with instructions for leaving the list, the text could read: "To leave the list, send a SIGNOFF &LISTNAME command to &MYSELF or, if you experience difficulties, write to &OWNER."
[edit] Storing the <listname>.MAILTPL file on the host machine
The procedure differs slightly on VM systems, but the following will work for unix, VMS and Windows systems: 1. Get a copy of DEFAULT.MAILTPL and edit it. 2. Be sure that you have defined a "personal password" to LISTSERV with the PW ADD command before you PUT the template file. If you have done this but can't remember the password, send a PW RESET command to LISTSERV, then a new PW ADD command. . 3. Send the file to LISTSERV with a PUT listname MAILTPL PW=XXXXXXXX command at the top of the file, just as if you were storing the list itself. Replace XXXXXXXX with your personal password. The variation for VM systems is that the LISTSERV maintainer will have to create a fileid for the file before you can PUT it on the server. Contact the LISTSERV maintainer before trying to store your template file.
[edit] Other template files: DIGEST-H and INDEX-H
Two other template files that are available pertain to the automatic digestification feature. You may create and store files called listname DIGEST-H and listname INDEX-H. These files define custom digest headers and custom index headers, respectively. The DIGEST-H and INDEX-H files are plain text files, like the WELCOME and FAREWELL files, and the instructions for storing them on the server are identical. Note that, as with the WELCOME and FAREWELL files, you cannot use the template formatting commands and replaceable parameters discussed above. A typical DIGEST-H or INDEX-H file for a list called MYLIST might contain: The MYLIST list is sponsored by ABig Corporation. See http://www.abig.com for information on ABig Corporation's products.
[edit] Typical contents of a DIGEST-H or INDEX-H file.
The contents of DIGEST-H and INDEX-H are appended to the digest or index, respectively, immediately following the list of topics. For instance, Date: Tue, 11 Jun 2001 11:52:41 -0500 From: Automatic digest processor <LISTSERV@MYHOST.COM> Reply-To: My test list <MYLIST@MYHOST.COM> To: Recipients of MYLIST digests <MYLIST@MYHOST.COM> Subject: MYLIST Digest - 10 Jun 2001 to 11 Jun 2001 There is one message totalling 10 lines in this issue. Topics in this issue: 1. Testing 125...3 sir! The MYLIST list is sponsored by ABig Corporation. See http://www.abig.com for information on ABig Corporation's products.
Sample DIGEST output for a list with a DIGEST-H file. The INDEX-H output would be similar, following the list of postings.
(Note that you can't add a digest or index "footer" because anything after the end of the digest text is supposed to be discarded.)
[edit] Templates and template forms for the WWW
interface The following describes the available template files and their respective template forms for the WWW archive and administration interface. L-Soft does not advise modifying these templates unless you know exactly what you are doing. If you modify the templates it is strongly recommended that you keep copies of the originals in a safe location for fall-back.
[edit] Forms contained in DEFAULT MAILTPL
Note that, although these template forms are available in DEFAULT MAILTPL (and thus theoretically available for list owners to modify), individual list owners cannot tamper with them. If the LISTSERV maintainer desires to change the "look" of the site, it is preferable to create a file called www_archive.mailtpl (see the Site Manager's Operations Manual, chapter 5.4.5 and below) rather than to edit the forms in DEFAULT MAILTPL, since DEFAULT MAILTPL will be overwritten during a software upgrade. WWW_ARCHIVE_INDEX: The basic INDEX.HTML page for the WWW archive interface. While this template form is available in DEFAULT MAILTPL, it cannot be changed by list owners. WWW_ARCHIVE_USER_FORMS: Tells LISTSERV which additional "user" forms to format for the list. WWW_ARCHIVE_TRAILER: The page trailer file included by the WWW interface's CGI script. When this template is included in a listname.MAILTPL file it controls ONLY the trailer for the listname.html main index page. See WWW_LIST_TRAILER, below. WWW_ARCHIVE_HEADER: The page header file included by the WWW interface's CGI script. When this template is included in a listname.MAILTPL file it controls ONLY the trailer for the listname.html main index page. See WWW_LIST_HEADER, below. $WWW_IMAGES_URLDEF: Default URLs for standard images, do not change $WWW_IMAGES_URL: URLs for standard images. If these images are stored in non-standard locations you put the URLs for those locations here. Otherwise LISTSERV uses the defaults in $WWW_IMAGES_URLDEF . $WWW_ARCHIVE_HEADER: Contains the header text for the WWW archive interface, e.g., what prints at the top of the page. This template form is included by default in the WWW_ARCHIVE_HEADER template form. $WWW_ARCHIVE_TRAILER: Contains trailer text for the WWW archive interface, e.g., what prints at the bottom of the page. This template form is included by default in the WWW_ARCHIVE_TRAILER template form. XHTML_LISTSERV_REPLY_TRAILER: Contains a trailer used for HTML digests (technically a mail template rather than an HTML template) DIRECTORY: Template directory for X-GETTPL (overrides only). You probably do not want to change this template form unless advised to do so by L-Soft. WWW_ARCHIVE_DIRECTORY: Template directory for X-GETTPL (WWW_ARCHIVE only). You probably should not change this template form unless advised to do so by L-Soft. WWW_LIST_HEADER: A second-level header file that can be defined by the list owner for all pages other than the main listname.html page (see WWW_ARCHIVE_HEADER for the main page). If defined, this header appears after the WWW_ARCHIVE_HEADER and before the rest of the page's content on all pages below listname.html. WWW_LIST_TRAILER: A second-level trailer file that can be defined by the list owner for all pages other than the main listname.html page (see WWW_ARCHIVE_TRAILER for the main page). If defined, this trailer appears before the WWW_ARCHIVE_TRAILER and after the rest of the page's content on all pages below listname.html. The following will help clarify the page placement of WWW_LIST_HEADER and WWW_LIST_TRAILER when they are defined in listname.mailtpl: WWW_ARCHIVE_HEADER WWW_LIST_HEADER [page content] WWW_LIST_TRAILER WWW_ARCHIVE_TRAILER Except as noted for the main list archive page (listname.html), list owners may not override WWW_ARCHIVE_HEADER or WWW_ARCHIVE_TRAILER as they are defined on a site-wide basis.
[edit] The site.mailtpl file
Rather than changing DEFAULT MAILTPL to customize your site's "look", it is recommended that the LISTSERV maintainer(s) place modified templates from DEFAULT MAILTPL in a file called site.mailtpl , which must be located in the same directory as DEFAULT MAILTPL and which will not be overwritten by a software update. (List owners cannot change this file but some of its templates may be overridden in a listname.mailtpl file.) It should be noted that in LISTSERV version 14.2 and earlier, the site.mailtpl file was called www_archive.mailtpl. In any upgrade from LISTSERV 14.2 or earlier to LISTSERV 14.3 or later, an existing www_archive.mailtpl file will be automatically copied to site.mailtpl and renamed to www_archive.oldtpl (with a few caveats as noted in the LISTSERV 14.3 release notes).
[edit] The default.wwwtpl file
The DEFAULT WWWPTL file contains the default templates for the parts of the WWW archive interface that are not defined in DEFAULT MAILTPL. This file should not be edited, as DEFAULT WWWTPL will be overwritten by a software update. Any site-wide emendations should be made in SITE WWWTPL (editable by LISTSERV maintainers only; see the next section) and list-level emendations should be made in listname WWWTPL. Both of these files can be edited via the web administration interface (see chapter 11). When editing these templates please note two fundamental differences between them and the templates in DEFAULT MAILTPL:- Any substitution variable that you use (for instance, &LISTNAME) must be escaped with a "+" symbol between the ampersand and the name of the variable, thus: &+LISTNAME . (Note that, as with the regular mail template forms, not all substitution variables are available in every HTML template form.)
- Any dot-formatting command you use (for instance, .CC , .BB , etc.) must have a "+" symbol rather than the dot, thus: +CC+BB
[edit] The site.wwwtpl file (optional)
If desired, the LISTSERV maintainer(s) can override the default.wwwtpl file by providing a customized site.wwwtpl file in the same directory. This will prevent site-wide definitions being overwritten in an upgrade (i.e., when default.wwwtpl will normally be overwritten). The site.wwwtpl file takes precedence over default.wwwtpl but (for list-level templates only) will itself be overridden by definitions in any listname.wwwtpl files you have installed.
[edit] National language template files (idiom.mailtpl) (optional)
National language templates can be written and used with LISTSERV (L-Soft does not provide them). The use of such templates is governed by two settings: Site-wide: The DEFAULT_LANGUAGE= site configuration variable allows the LISTSERV maintainer to set the site-wide national language template for use by all lists on the server. By default this variable is unset and DEFAULT MAILTPL is used. List-level: The Language= list header keyword can be used to specify a national language template to be used for a particular list, for instance a Spanish-language list on an otherwise English-language server. The language template must already be present on the server in order for the list owner to be able to specify it in this keyword setting. Since national language templates can be created only by the LISTSERV maintainer(s), further information on creating them can be found in the Site Manger's Operations Manual.
[edit] Template precedence
For template forms found in DEFAULT MAILTPL, the following precedence is used when LISTSERV searches for a given template form: listname MAILTPL idiom MAILTPL SITE MAILTPL[#footnote_anchor-8 8] DEFAULT MAILTPL That is to say, if LISTSERV needs a copy of the ADD1 mail template form, it will look first in the listname.mailtpl file for the list in question. If no such file exists, or if ADD1 is not present inlistname.mailtpl, LISTSERV will look in idiom.MAILTPL (if Language= or DEFAULT_LANGUAGE= is set to idiom). Again, if the ADD1 form is not present in idiom.mailtpl, or if idiom.mailtpl does not exist, LISTSERV will then look in default.mailtpl (www_archive.mailtpl is skipped because ADD1 is not a web template form) and pull out the default ADD1 template form. For template forms found in DEFAULT WWWTPL the precedence is: listname WWWTPL idiom WWWTPL SITE MAILTPL DEFAULT WWWTPL The same sequence of events applies as for the MAILTPL files, except that SITE MAILTPL is never skipped (all template forms in the WWWTPL files are web forms).
[edit] Using the DAYSEQ(n) function
The DAYSEQ(n) function is quite powerful. This function allows the list owner to code template forms (such as the PROBE1 or BOTTOM_BANNER messages) that change or "rotate" automatically. The DAYSEQ(n) function is invoked in a .BB - .EB conditional block, and n corresponds to the number of days in the rotation period, i.e., to the number of variations that you want to make to the text of the message. &DAYSEQ(n) returns a number from 1 to n which increases by 1 every day, with no special regard for weekends. That is, if the rotation period is to last for a week, you code DAYSEQ(7). If the rotation period is 15 days, you code DAYSEQ(15). Two examples follow:
[edit] Rotating bottom banner
To create a rotating bottom banner, follow this example. A list has three commercial sponsors, each of whom are provided with an advertisement every three days. (Note that this doesn't take weekends into account; in this example, if company A is featured in the banner on Monday, it will be featured again on Thursday and then again on Sunday. However, in the following week it will be featured on Wednesday, Saturday, and Tuesday, so it will actually get rather good coverage.) Our BOTTOM_BANNER template form would look like this: >>> BOTTOM_BANNER .BB &DAYSEQ(3) = 1 Today's copy of the &LISTNAME newsletter has been brought to you by Company A. .EB .BB &DAYSEQ(3) = 2 Today's copy of the &LISTNAME newsletter has been brought to you by Company B. .EB .BB &DAYSEQ(3) = 3 Today's copy of the &LISTNAME newsletter has been brought to you by Company C. .EB (Naturally you can feel free to be more florid with your prose :) If a company needs to get a higher percentage of "air" time than another, you can simply assign it more than one of the possible n values of &DAYSEQ(n). For instance, if you have two companies but one should get twice as many days of "air" time, you might code something like this: >>> BOTTOM_BANNER .BB (&DAYSEQ(3) = 1) OR (&DAYSEQ(3) = 3) Today's copy of the &LISTNAME newsletter has been brought to you by Company A. .EB .BB &DAYSEQ(3) = 2 Today's copy of the &LISTNAME newsletter has been brought to you by Company B. .EB This would cause Company A's message to appear on days 1 and 3 of the rotation period and Company B's message to appear on day 2 only.
[edit] Rotating FAQ via the PROBE1 template and "Renewal= xx-Daily"
Subscription renewal can be coded with daily granularity (however, please note that it is and remains inadvisable to use renewal intervals of less than a week). If you further code subscription probing into the "Renewal=" keyword with the ",Probe" parameter, you open up the possibility of turning the standard PROBE1 template form into a periodic FAQ. Here's how: We'll assume to start that you will code "Renewal= 15-Daily,Probe" in your list header. (You can experiment with other numbers, but since we have two messages and will be using &DAYSEQ(2), we need an odd renewal period.) We'll also assume that you want to send two versions of your FAQ each month; the first, a complete FAQ document, and the second, an abbreviated "reminder" version that just contains information about how to sign off, how to post to the list, and so forth. The basic algorithm is therefore: When &DAYSEQ(2) = 1, send the full FAQ. When &DAYSEQ(2) = 2, as it will 15 days later, send the abbreviated FAQ. Your PROBE1 template form would thus look like this: >>> PROBE1 Periodic FAQ posting for &LISTNAME &WEEKDAY, &DATE &TIME .BB &DAYSEQ(2) = 1 This is the complete FAQ for &LISTNAME. Please read it and keep a copy for future reference. A FAQ document for &LISTNAME is distributed every 15 days, the full FAQ alternating with a shorter "reminder" FAQ. <body of the full FAQ document> .EB .BB &DAYSEQ(2) = 2 This is the abbreviated FAQ for &LISTNAME. Please read it and keep a copy for future reference. A FAQ document for &LISTNAME is distributed every 15 days, the full FAQ alternating with a shorter "reminder" FAQ. <body of the abbreviated FAQ document> .EB
[edit] Calculating the value for DAYSEQ()
When you first start using a rotating banner with the &DAYSEQ variable, the &DAYSEQ(n)= 1 period begins based on the number of days elapsed since a baseline. On VM (and in REXX generally) you can calculate today's value easily with: /* */ say Date('B') + 1 If you do not have access to a REXX interpreter, Date('B') is described as "the number of complete days (that is, not including the current day) since and including the base date, 1 Jan 0001, in the format 'dddddd' (no leading zeros or blanks)."[#footnote_anchor-9 9] It also is equal to the C language expression time(0)/86400 + 719162 or, for OpenVMS users, to the Smithsonian base date plus 678575. For example, for Friday 21 May 1999, the value of Date('B') is 729895. This value increases by one every day at midnight.
[edit] Serving up custom web pages for your list
This feature is not available in LISTSERV Lite. Originally in order to serve up custom or special web pages for a list it was necessary to construct those pages as HTML files and place them either into the /archives directory or link them from somewhere else. This was sometimes impossible for list owners who had no administrative access to the server's web directories or who had no other place from which to serve web pages. In 1.8d and later it is possible to add ad-hoc web page templates by creating new (non-standard) template forms and enabling their display by setting a special variable value, SHOWTPL_ALLOWED, in the template form. For instance, one could set up a page with special administrative information, the list charter, netiquette information, or the like, and serve it and maintain it directly from the LISTSERV web template interface without need for any other access to the server.
[edit] A practical example: ADMIN_POST
The author used to serve up an administrative posting via FTP back in the days when his lists lived on a server that had FTP access to the archive notebooks. When FTP access to the server was cut off due to security concerns, he had to find another way to serve the information via the web. Here is how it was done: First, log into the web administration interface. Choose the list for which you will be making a new page and click the "Templates" button to enter the mail and web template editing area. Since the template you will be creating is a web template, click the "Switch to WWW templates" button to change modes. Hopefully everything between the two lines of asterisks below will be changed in a future version... ******************************************************************************************************* Currently there is no simple method to create a new (ie previously non-existent) template form from the web interface. The workaround is to open one of the existing template forms and add the template delimiter line at the bottom, then save the existing template form. For instance, we'll choose the first template form that presents itself, A1-DEF. Open this template by clicking on the "Edit form" button. If this template has not been changed from its default (and it probably will not have been), it will look like this: +* You should now set these options using the layout customization
+* screen, except for the special F and S options, which are much too
+* advanced for the layout screen and must still be set in this template.
+IM LAYOUT-data-wrapper
+SE D &+LYT_DVIEW_D;
+SE FP &+LYT_DVIEW_FP;
+SE H &+LYT_DVIEW_H;
+SE O &+LYT_DVIEW_O;
+SE T &+LYT_DVIEW_T;
At the bottom of this form, directly after the +SE T &+LYT_DVIEW_T; line, type >>> ADMIN_POST Administrative information page (Be sure that there is a space between ">>>" and "ADMIN_POST". This is required.) Next, click on the "Update template" button and the template will update. You will see the message at the top of the page: The A1-DEF form has been successfully stored in the LISTNAME template library. (LISTNAME of course will be the name of the list you are working with.) Next, back out of the preceding pages and return to the main web template editing page, and reload that page. In the drop-down list box you will see a new line that says (*) Administrative information page [ADMIN_POST] You now have one final cleanup action to take before you edit the new template form. Go back into the A1-DEF form editing screen (you'll note that it also has a "(*)" next to it, indicating that it has been modified). You'll note when you go into the editing screen that it says at the top, This form is defined in the LISTNAME template. Clear the text out of the edit box, and also clear the "Description:" text box (this is important, otherwise you will leave a blank A1-DEF template form in the list's template library, and that is not good). Update the template again. The interface will again tell you that The A1-DEF form has been successfully stored in the LISTNAME template library. In actuality what has happened is you have removed the copy of A1-DEF that was placed into listname.WWWTPL when you saved the modifed copy that contained the template form delimiter line for your ADMIN_POST template form. If you back out to the template management page again you will see that the "(*)" indicator is no longer present at the start of the A1-DEF line. Now you can open the ADMIN_POST template form and edit it. Next, choose the "(*) Administrative information page [ADMIN_POST]" line, and click the "Edit form" button. You will be presented with an editing page with a blank text box into which you can place your HTML code for the page. The first thing you need to do, however, is to enable the template form so that it can be served by LISTSERV's web interface. This is done by placing the following line at the very top of the template form: +SE SHOWTPL_ALLOWED 1 Following this line you can start adding your HTML. However note carefully that you cannot override the default headers and footers that have already been defined by other template forms in the library. You can start with a <title></title> block but it will be followed by the pre-defined header and then by your HTML. The URL for the page you are defining in this example is then http://your_server_hostname/path_to_wa?SHOWTPL=ADMIN_POST&L=LISTNAME (the parameters for 'wa' are case-sensitive and must be sent in upper case). For instance, the author's version of the ADMIN_POST template form can be viewed at
[1] (The following example assumes that you have the 1.8e web administration interface installed. New template forms cannot be created this way in previous versions.)First, log into the web administration interface. Choose the list for which you will be making a new page and click the "Templates" button to enter the mail and web template editing area. Since the template you will be creating is a web template, click the "Switch to WWW templates" button to change modes.Next, type the name of the new template form into the box provided, and click "Create". A page entitled "Edit List Template" will come up, with the command responseThe ADMIN_POST form has been successfully stored in the TEST template library.In the "Description:" box, type a description of the template, for example, "Administrative information page".In the large text box provided for the template text, first type the following line:+SE SHOWTPL_ALLOWED 1This line tells LISTSERV that it is allowed to serve the page on the web. If the line is not found, the template will not be available.Following this line you can start adding your HTML. However note carefully that you cannot override the default headers and footers that have already been defined by other template forms in the library. You can start with a <title></title> block but it will be followed by the pre-defined header and then by your HTML.After adding your HTML, click "Update", and the template form will be stored. The URL for the page you are defining in this example will be http://your_server_hostname/path_to_wa?SHOWTPL=ADMIN_POST&L=listname (the parameters for 'wa' ''are case-sensitive and must be sent in upper case). For instance, the author's version of the ADMIN_POST template form can be viewed at
[2] Documented Restriction: For LISTSERV 1.8d (or LISTSERV 1.8e running with the 1.8d web interface) there is no simple method to create a new (ie previously non-existent) template form from the web interface. If you are not comfortable with the GET and PUT
method of updating list-level template forms, a web-based workaround is to open one of the existing template forms and add the template delimiter line at the bottom, then save the existing template form. For instance, we'll choose the first template form that presents itself, A1-DEF. Open this template by clicking on the "Edit form" button. If this template has not been changed from its default (and it probably will not have been), it will look like this:+* You should now set these options using the layout customization+* screen, except for the special F and S options, which are much too+* advanced for the layout screen and must still be set in this template.+IM LAYOUT-data-wrapper+SE D &+LYT_DVIEW_D;+SE FP &+LYT_DVIEW_FP;+SE H &+LYT_DVIEW_H;+SE O &+LYT_DVIEW_O;+SE T &+LYT_DVIEW_T;At the bottom of this form, directly after the +SE T &+LYT_DVIEW_T; line, type>>> ADMIN_POST Administrative information page(Be sure that there is a space between ">>>" and "ADMIN_POST". This is required.) Next, click on the "Update template" button and the template will update. You will see the message at the top of the page:The A1-DEF form has been successfully stored in the LISTNAME template library.(LISTNAME of course will be the name of the list you are working with.)Next, back out of the preceding pages and return to the main web template editing page, and reload that page. In the drop-down list box you will see a new line that says(*) Administrative information page [ADMIN_POST]You now have one final cleanup action to take before you edit the new template form. Go back into the A1-DEF form editing screen (you'll note that it also has a "(*)" next to it, indicating that it has been modified). You'll note when you go into the editing screen that it says at the top, This form is defined in the LISTNAME template.Clear the text out of the edit box, and also clear the "Description:" text box (this is important, otherwise you will leave a blank A1-DEF template form in the list's template library, and that is not good). Update the template again. The interface will again tell you thatThe A1-DEF form has been successfully stored in the LISTNAME template library.In actuality what has happened is you have removed the copy of A1-DEF that was placed into listname.WWWTPL when you saved the modifed copy that contained the template form delimiter line for your ADMIN_POST template form. If you back out to the template management page again you will see that the "(*)" indicator is no longer present at the start of the A1-DEF line. Now you can open the ADMIN_POST template form and edit it.
