List Keyword Reference for LISTSERV 17.5

Digest= No 

Digest= Yes,where | Same[,frequency]

 Digest= Yes,where | Same[,frequency] [,when][,Size(maxsize)][,BOTTOM_BANNER]

-- For LISTSERV 16.5 and later:

Digest= Yes,where | Same[,frequency] [,when[,when2]][,Size(maxsize)][,BOTTOM_BANNER]

---

This keyword controls the automatic digest and index function, allowing subscribers who do not have the time to read large numbers of messages as they arrive to subscribe to a digested or indexed version of the list. The list owner decides whether digests are available or not, the frequency at which they are issued and the day of week/month and/or time of day when the digest/index should be distributed.[1]

What are Digests and Indexes?

Digests are larger messages containing all the postings made by list subscribers over a certain period of time. Unlike real-world digests, LISTSERV digests are automatically generated and not edited; what you see is exactly what was posted to the list. The only difference is that you get all the messages for a given day, week or month in a single batch. This is mostly useful if you are just "listening in" to the list and prefer to read the postings at your leisure. Digests are kept separately from list archives and can be made available for mailing lists which do not archive postings (i.e. which run with "Notebook= No").

Digests are available in several variants:  Plain text, MIME, and HTML.  The specific variant is selectable by the subscriber.

Indexes, on the other hand, only provide a few lines of information for each posting: date and time, number of lines, name and address of poster, subject. The actual text is not included. You select just the messages you are interested in, and order them from the server. This is useful for mailing lists where most messages really don't interest you at all, or as an alternative to SET NOMAIL: when you come back from vacations, you can quickly order the messages you are most interested in. Note that, since indexes are not useful without the ability to order a copy of the messages you do want to read, they are not made available unless the list is archived and digests are enabled.

Indexes are available in plain-text and in HTML.  The latter provides the subscriber with the same listing of messages as the plain-text index but also contains hyperlinks for each message which can be clicked to read the message directly from the server archives, rather than having to "order" them from the server via email as is the case with plain-text indexes.

Users sign up for digest delivery rather than immediate delivery with 'SET listname DIGests', while indexes are selected with 'SET listname INDex'. These two options are alternatives to MAIL and NOMAIL. When switching around between these delivery options, users will observe the following behavior (digests will be assumed to be daily for the sake of clarity):

• When switching to NOMAIL: delivery stops immediately. The day's digest is not sent, as the user is assumed to desire immediate termination of traffic from the list.  However, it should be noted that any mail that was already processed and placed into the outbound spool for the user's address prior to the receipt of the SET NOMAIL command will still be delivered.
• When switching from any option to DIGEST or INDEX: mail delivery stops immediately, and the first index or digest may contain some items the user has already seen (if switching from MAIL to DIGEST/INDEX). This is because the digests and indexes are global to the list - they are the same for everyone, just like regular issues of newspapers.
• When switching from DIGEST or INDEX to NODIGEST or NOINDEX, the current, unfinished digest or index is immediately mailed to the user. New messages are delivered normally, as they arrive. Thus, a "trick" to get a copy of the current digest is to switch to NODIGEST and then back to DIGEST. You can send both commands in the same mail message to make sure they are executed together.
  
  Note that if no new messages have been posted to the mailing list since the last regular digest was generated, then this trick will not work, as the new digest would not yet contain any messages in that situation.

The list owner controls the availability and frequency of digests through the  "Digest=" list header keyword, which defaults to "Digest= No" for lists without an archive and "Digest= Yes,Same,Daily" for archived lists. 

We have already noted that it is not necessary for the list to be archived to provide digests and indexes.  However, if digests and indexes are made available for a list that does not have archives, the Digest= keyword should be specified with a "where" parameter pointing to somewhere other than LISTSERV's A disk or directory.  If your normal practice is to store list archives under a directory scheme such as C:\LISTS\listname (Windows) or /home/listserv/lists/listname (unix), then for consistency it would make sense to create a directory under that scheme for your non-archived list and point the Digest= "where" parameter to that directory.

Please note carefully that LISTSERV will not create the directory for you; either it must pre-exist, or an administrator with access to the server filesystem will have to create it using standard operating system methods.  If the directory does not exist, LISTSERV will throw an error when processing mail for the list in question, and the list will be held until the error condition is remedied, after which the list may be freed with the FREE listname command.

The basic syntax of the keyword is either "Digest= No" to disable digests and indexes entirely, or "Digest= Yes,where,frequency,when,maxsize" when digests and indexes are enabled. 

The "where" parameter

The second parameter is either a disk or directory specification, as with the "Notebook=" keyword, or "Same", which means that the digest will be stored in the same location you have specified for Notebook=.  

This parameter may be changed only by the LISTSERV maintainer. A list owner is allowed to change "Digest= No" to "Digest= Yes,Same....", but any other specification for the digest file location will cause an error.

A list owner is also allowed to change "Digest= Yes..." to "Digest= No" without the intervention of the LISTSERV maintainer. Note that if the list is not archived ("Notebook= No"), changing "Digest= No" to "Digest= Yes,Same" will cause the digest files to be written to LISTSERV’s A disk (or equivalent specification on the workstation systems).  Since the overhead for a typical digest is small, it is not expected that this will cause any problem for the LISTSERV maintainer.

The "when" parameter

The third parameter is either "Daily" (the default), "Weekly" or "Monthly", and determines how often the digest and index are distributed.  In the following sections we will discuss separately the three different digest/index types and how to configure them.

Setting up Daily Digests

The basic keyword syntax for Daily digests is

Digest= Yes,where,Daily

For instance, 

Digest= Yes,c:\listserv\lists\mylist-l,Daily

or

Digest= Yes,/home/listserv/lists/mylist-l,Daily

which causes the digest to be cut at 00:00 every morning.  There is also an optional "when" parameter allowing the list owner to determine the hour when the digest is cut:

Digest= Yes,where,Daily[,hour]

For instance,

Digest= Yes,c:\listserv\lists\mylist-l,Daily,12

or

Digest= Yes,/home/listserv/lists/mylist-l,Daily,12

which causes the digest to be cut at 12:00 Noon every day.

Setting up Weekly Digests

The basic keyword syntax for Weekly digests is

Digest= Yes,where,Weekly,dayofweek

For instance,

Digest= Yes,c:\listserv\lists\mylist-l,Weekly,Friday

or

Digest= Yes,/home/listserv/lists/mylist-l,Weekly,Friday

which causes the digest to be cut at 00:00 on Friday morning.  

If the dayofweek value is omitted, the digest is cut at 00:00 on Monday morning.

Starting with LISTSERV 16.5, there is also an optional parameter allowing the list owner to determine the hour of the specified day of the week when the digest is cut:

Digest= Yes,where,Weekly,dayofweek[,hour]

For instance,

Digest= Yes,c:\listserv\lists\mylist-l,Weekly,Friday,12

or

Digest= Yes,/home/listserv/lists/mylist-l,Weekly,Friday,12

which causes the digest to be cut at 12:00 Noon on Friday.

Setting up Monthly Digests

The basic keyword syntax for Monthly digests is

Digest= Yes,where,Monthly,dayofmonth

For instance,

Digest= Yes,c:\listserv\lists\mylist-l,Monthly,15

or

Digest= Yes,/home/listserv/lists/mylist-l,Monthly,15

which causes the digest to be cut at 00:00 on the 15th day of each month.  

If the dayofmonth value is omitted, the digest is cut at 00:00 on the first day of the month.

Starting with LISTSERV 16.5, there is also an optional parameter allowing the list owner to determine the hour of the specified day of the month when the digest is cut:

Digest= Yes,where,Monthly,dayofmonth[,hour]

For instance,

Digest= Yes,c:\listserv\lists\mylist-l,Monthly,15,12

or

Digest= Yes,/home/listserv/lists/mylist-l,Monthly,15,12

which causes the digest to be cut at 12:00 Noon on the 15th day of the month.

Digests and Indexes are evaluated and sent only at the top of the hour

When configuring a digest with time values, it is necessary only to provide the "hh" value, but for human-readabilty, LISTSERV will also accept "hh:mm" values in the configuration.  Times are specified using the usual 24-hour clock scale, 00 through 23.  24 is also accepted for "midnight" and is exactly equivalent to "00".

However, LISTSERV will "read" only the "hh" part of an "hh:mm" value when provided as part of a Digest= setting.  This is because LISTSERV evaluates whether or not digests and indexes should be sent only at the top of each hour, and it cuts and sends them only at the top of the hour, regardless of any ":mm" value you may have provided in the keyword setting.  

As an example, coding "Digest= Yes,Same,Daily,14:55" will result in the digest being cut at 2:00 PM (14:00).

Cutting size-based "special issues" 

LISTSERV also provides a method of cutting a "special issue" earlier than the normal digest time if the accumulated messages exceed a specified size.  This involves adding a maxsize setting at the end of the Digest= specification.

Digest= Yes,where,frequency[,when][,Size(maxsize)]

For instance,

Digest= c:\listserv\lists\mylist-l,Daily,12,Size(1M)

The size setting may be specified in several ways:

When the digest grows over the specified limit, LISTSERV will close the digest and send it out, regardless of the "frequency" or "when" settings.  (Note that your digests may run over the limit set in  "Size(maxsize)". This is because LISTSERV will never truncate a message in order to meet the digest size limit. Thus, if you've reached 95,000 lines of your 100,000 line setting and the next message is 1500 lines long, your digest will cut at 100, 500 lines. Digest limits specified in kilobytes or megabytes operate in a similar manner.)

Digest limits exist because most mail servers formerly applied very small limits to inbound mail – for instance, many systems would not accept messages larger than 100 kilobytes, or 1500 or so lines.  Today the default is 10,000 lines, which is over half a megabyte – and this is still tiny compared to some mail system limits, which may exceed 10 to 20 megabytes.  If your list is used to send very large files (such as images), it may be prudent to raise the value of the Size() parameter so that every single post does not cause a "special issue" digest to be cut.

The BOTTOM_BANNER option

The normal behavior of a list with a BOTTOM_BANNER template defined in listname.MAILTPL is to print the contents of the BOTTOM_BANNER mail template near the beginning of the digest, between the list of topics and the first message in the digest, as well as at the bottom of each individual message in the digest. The initial copy of the bottom banner will be suppressed if the special option BOTTOM_BANNER is specified at the end of the Digest= keyword setting. There is not a way to suppress the copies of the banner in the individual messages.

Note that the list's TOP_BANNER (if one is configured) is always included at the top of each message in the digest. Generally, TOP_BANNER contains copyright or other important information that should be included with each message, and therefore it is not suppressed.

Disabling Digests and Indexes for existing lists

The list owner must take special care when disabling digests and indexes for a list, as LISTSERV does not presently have any facility which would allow it to alter subscription options automatically on the basis of changes to the list header. Subscribers who had opted for digests or indexes would continue not to receive mail as it arrives, but would not get the digests or indexes either. The best way to solve this problem is to announce the change far enough in advance so that people can switch back before digests and indexes are suspended.  Alternately, the list owner or LISTSERV maintainer may issue a "QUIET SET listname NODIGEST FOR *@*" command before disabling digests.

L-Soft does not expect this to be a frequent condition. Daily digests and indexes take up very little disk space (which is freed up as soon as the digests and indexes are cut and sent) and there is usually no reason to disable them for a typical list.

Types of Digests and Indexes

By default, LISTSERV will send subscribers their digests or indexes as plaintext messages.  However, both digests and indexes are also available in an HTML format, and a third type of digest known as a "MIME" digest is also available as an option for subscribers.  The subscriber chooses the format either by using the SET command by email, or by changing their subscription options for the list in the LISTSERV web interface (choose the [Subscriptions] menu item at left, then choose the list for which it is desired to modify options).

UTF-8 "plaintext" digests

LISTSERV implements a "plaintext" digest format that will properly display UTF-8-encoded messages in the body of the digest.  Prior to LISTSERV 16.0, the old "plaintext" digest was limited to 7-bit ASCII text, and as such, was only able to display UTF-8 messages as received, that is, in their non-human-readable UUencoded or Base-64-encoded form.

As currently implemented, LISTSERV produces a "plaintext' digest that looks exactly like an RFC1153-compliant digest.  In reality it is a MIME message, and can handle any character set.  For each message in the digest, LISTSERV locates the most pertinent text part, decodes it, and uses that as the text of the message in question.  The format is not formally RFC1153, but it looks as close to RFC1153 as possible while still being useful for non-ASCII messages.

1. All RFC822 headers are '=?' decoded, converted to UTF-8, and output in plain text.
2. All MIME messages are run through LISTSERV's MIME parser and reduced into a plain text part. This is converted to UTF-8 and is the final display "copy".
3. Any attachments and additional material other than the plain-text part are discarded. This includes additional plain-text parts.
4. Step 2 can fail if there is a MIME or encoding error, or if there is simply no plain text data in the message. The error that is thrown is controlled by one of two new mail templates, depending on the error: MSG_DIGEST_FRAGMENT_MIME_ERROR or MSG_DIGEST_FRAGMENT_NO_TEXT, both found in DEFAULT MAILTPL. The content of the appropriate template is then output. Note that these are single-line templates, therefore they are not suitable for a complex explanation of what happened. Any edits to these templates should keep them short and to the point
5. If there is only one HTML part in the message, there is no plain text part and step 2 fails.
6. To make all this possible, the whole digest is charset=UTF-8.

Setting "Misc-Options= OLD_NOMIME_DIGEST" in the list header will force LISTSERV to revert to the original RFC1153 format, if for some reason this is required.  Normally it should not be; however, even if you can guarantee that every posting is 7-bit ASCII text and nothing else, the newer format has the downside of using Unicode.  While this of course is identical to ASCII for pure ASCII input, the message may be marked as Unicode in people's mail clients.

---

[1]LISTSERV digests are collections of messages received for and processed through the list over a specified period of time (usually, but not always, one day) which are pulled together into a single large email and sent at the end of the collection period to users who have chosen to receive only this digest-format email from the list, rather than receive all of the individual messages which are distributed to non-digest subscribers as they are received.  Indexes are similar to digests in that they are distributed at the same time as the digest, but they contain only basic information about each message received during the digest period – message number, sender, date/time stamp, subject line, and length of the message – along with a hyperlink that can be used to pull the message up in LISTSERV's web interface.