List2Web Version 3 User Guide

28 January 1998

Hethmon Brothers
Developers of Internet Software
www.hethmon.com
2305 Chukar Road
Knoxville, Tennessee 37923
423.690.8990

1. Introduction

List2Web is a set of REXX scripts designed to accept email messages
and convert them into formatted output for web pages. Messages are
sorted by year, month, and day for easy access. Messages are saved
as HTML pages with embedded links and MIME attachments unencoded and
presented as links also.

An active list to look at is located at 

   http://w3.hethmon.com/inetmail/

The web pages are based on template pages included with this package
and are customizable on a per list basis. Special comment markers
are in each template page to let List2Web know where to insert the
updated information.

1.1 Uses

List2Web is designed to echo a mailing list to a series of web
pages. It's not restricted to this however, it can and will echo
any message sent to it. Possible uses could include keeping a
web accessible listing of your own personal email or email to
a technical support account.

1.2 Relationship to Inet.Mail

List2Web was designed to work with the local process delivery
option of Inet.Mail. Inet.Mail has the ability to start a local
process upon receipt of email for a particular username. List2Web
accepts the parameters Inet.Mail furnishes and processes the
messages based on them.

Given the correct parameters (explained below), List2Web could
work on any email system capable of running a REXX script. Hethmon
Brothers will render technical assistance for this on a time
permitting basis. Our main priority is to our customers of Inet.Mail.

2. Setup

2.1 Location

List2Web may be installed in any location by simply unzipping the
List2Web archive. All of the basic files are contained in the
distribution. Once a location for the base files is decided upon,
you must either add an environment variable to your config.sys
file and reboot, or modify the List2Web.cmd file to reflect it's
location.

The environment variable to use is L2W_CF. To set it add a line
like this to your config.sys file:

 SET L2W_CF=d:\list2web

Given that "d:\list2web" is your installed location.

Alternately, you may modify the List2Web.cmd file by locating the
lines:

/* Set L2wLocation to a value to override the environment
 * variable or to not use it.
 */
/* L2wLocation = 'd:\inetmail\l2w\Ver3' */
L2wLocation = ''

These lines should start at line 32 of the file. Modify the
last line to reflect your installed location. You should be
familar with REXX if you are going to modify the file. The
location should be contained within the single quote characters
as per the example shown on the next to last line.

List2Web needs this information in order to locate the correct
configuration file to use.

One other restriction on the List2Web location is that it must
be installed on a partition which supports long filenames. For
OS/2, this means a HPFS partition. Your TMP directory must also
be located on a HPFS partition. If your TMP directory is not
on a HPFS partition, you may set the environment variable
STEWARD_TMP to point to a temporary directory on a HPFS partition.

2.2 Ancillary Files

If you are not using List2Web with Inet.Mail, then you will need
the ancillary file set of REXX scripts. List2Web uses several
small REXX scripts for various file operations. These are installed
by default with Inet.Mail. The files may be retrieved from:

 ftp://ftp.hethmon.com/hethmon/pub/scripts/list2web-ancillary.zip

These files must be located in a directory on your PATH statement.
The PATH statement controls which directories OS/2 searches for
programs to execute automatically.

2.3 Configuration Files

For each list (or email id) which List2Web is to handle, you will
need to create a configuration file. A sample configuration file
is the file "list2web-ver3.cf". To set up a list, copy this file
to a file named after your email id to echo. Given the email
id "mylist-l2w@hethmon.com", your filename to use would be
"mylist-l2w@hethmon.com.cf". Inet.Mail passes the username to the 
local process in this form with full domain information. This file 
must be located in the directory pointed to by your environment 
variable (or REXX script modification).

Once copied, you must edit the configuration file to reflect
the values for your list. The settings to edit are:

 LogDir
 Webstem
 UseMsgDate
 DayTemplate
 MonthTemplate
 YearTemplate
 MsgTemplate

2.3.1 LogDir

This setting tells List2Web where to store log files. By default, 
List2Web keeps a running log of its activities. You may turn this
off by setting the "Log" variable in List2Web to FALSE.

2.3.2 Webstem

This setting tells List2Web where to actually create the html
files for the list messages. It starts in this directory and
creates a directory for each year the list operates such as
1997, 1998, and so on. In each of the year directories, a file
called index.html is created. You must manually link to these
files with your regular webpages. All links in the index.html
file are relative links so that the entire directory/page
structure may be moved.

This directory must be on a partition which supports long
filenames, ie HPFS. The html files generated by List2Web utilize
long names.

2.3.3 UseMsgDate

This setting decides whether List2Web uses the current machine time
or the Date header from the mail message to index the message. Under
most circumstances, it is recommended that you use the default setting
of TRUE so that List2Web uses the Date header from the message. However
if you are echoing a mailing list which does not normalize the Date
header so that messages do not arrive in chronological order, you
may wish to set it to FALSE and use your local machine clock time.

Steward rewrites the Date header of all messages it processes to its
local time. Other mailing lists will pass the Date header unchanged
and as such the Date header is not a reliable way to determine
the actual chronological order. (This might be done by interpreting
the timezone parameter of a mail message, but given the non-standard
ways of expressing it, List2Web ignores the timezone when interpreting
Date headers.)

2.3.4 DayTemplate

This setting specifies the template file to use for the daily
web pages. This should be a fully path specified filename. The suggested
location for DayTemplate and all template files is the directory
given in the Webstem variable. This way all files related to particular
list are located in a central location. You should copy the 
day-template.html file in the distribution to your specified location
and then modify as needed to reflect your list name. There are
certain comment lines which must remain untouched in the file. They
are clearly marked.

2.3.5 MonthTemplate

This setting specifies the template file to use for the monthly web
pages. Like the DayTemplate, it is a fully path specified filename.
An example, month-template.html, is included and should be used as
your basis.

2.3.6 YearTemplate

This template file serves the same function for the year pages as
the month and day templates. All the same information applies.

2.3.7 MsgTemplate

This template file is used to create the actual message pages. Again
you may modify this file to reflect your list needs.

2.4 Inet.Mail Setup

In Inet.Mail open the Add User notebook and create a user with the
correct username. On the Advanced page, check the local process box
and give the List2Web.cmd script as the process to run. Be sure to
use the fully qualifed pathname for the script.

3. Template Files

The various template files that List2Web uses may be modified
for your use. Care must be taken in not disturbing the comment
lines that List2Web keys on. They may be moved around in the file
and/or additional HTML inserted around them. It is recommend that
you do minimal modifications at first. In all the template files
you will find phrases like "List2Web Mailing List". Change the
"List2Web" to your mailing list name for starters. From there
you can expand your modifications.

4. Updating From A Previous Version

In order to update from a previous version of List2Web, three
additional REXX scripts are included:

 Order.cmd
 WebArchive.cmd
 StewArchive.cmd

The recommended way to update is to create a new directory
structure for the list and reprocess your existing message base.
There are two ways to do this.

4.1 From Steward Archive Files

If you have the archive function turned on for your mailing list,
you can use the StewArchive.cmd file to read the archive files
and create the new web pages. It parses the archive file into the
component messages and creates the web pages based on the message
Date header. You must have UseMsgDate set to TRUE for this to
work (the default setting).

Once you have your base List2Web setup complete, location
setup, template files in place, configuration file modified, you
simply run StewArchive.cmd giving it two arguments. The first
is the listname. This is in the "username@domain.com" form.
The second argument is the Steward archive file to process. It
will not modify the Steward archive file.

If you run the script multiple times on the same file, it will add
the messages to the web pages multiple times. So if a mistake occurs,
delete the entire tree and then run it again.

4.2 From Current Web Pages

If you do not have the Steward archive files, then you may reprocess
the current mail messages in your List2Web page setup. You should 
backup your current files before doing this procedure, it WILL DELETE
the current files as part of the process.

For each Month-Year directory in your current web pages, you will
need to repeat this procedure.

 A. Backup your current files.
 B. Run the order.cmd script giving it a wildcard specification
    for the files to process. Example: order *.txt
    This will read each of the message files in the directory and
    rename them based on the Date header in the message. This is
    important to establish the correct chronological order of the
    messages.
 C. Run the WebArchive.cmd script giving it 2 parameters. The first
    is the listname in the "username@domain.com" form. The second
    is a wildcard specification for the files to process. The order.cmd
    script creates output files with the *.msg extension, so you
    would give it *.msg as the second parameter. This creates your
    web pages. You must have the UseMsgDate setting set to TRUE
    for the dates to be correct.

This procedure will work for any group of plain text mail message
files if they are complete with all headers.

5. Support

Support for this product is supplied by Hethmon Brothers. You may
contact us via email at "support@hethmon.com". This product is also
discussed on the Inet.Mail product mailing list. On this list, we
answer questions and other users of the product do also. To subscribe
to this list, send an email message to "inetmail-request@hethmon.com".
In the body of the message put the command "subscribe" (without the
quotes).

You may also consult our support web pages at:

  http://www.hethmon.com/support.html

6. Acknowledgements

This product makes use of the freely available debase64.cmd
script by James L. Dean. Copies of the package are available from
Hethmon Brothers on request and from other OS/2 software repositories
such as the OS/2 SuperSite (http://www.os2ss.com) and 
Hobbes Archive (http://hobbes.nmsu.edu). The debase64.cmd script
was modified for use with List2Web from the original. Changes
are denoted in the debase64.cmd file.
