Chapter 31

Hypermail and Generic Bulletin Board Environments


CONTENTS


Hypermail is a software package available from Enterprise Integration Technologies (EIT). The C version of Hypermail was written by Kevin Hughes (kevinh@eit.com). Information about Hypermail can be obtained at the EIT Web site: http://www.eit.com/goodies/software/hypermail/hypermail.html.

A Web site that needs a generic bulletin board environment can download Hypermail from EIT and install it on just about any UNIX server.

Hypermail is a set of C source code files that, when built, create a Hypermail program that processes messages posted via HTML forms. The messages are converted into HTML files and stored in a message spool area on the Web server within the document root of the Web server.

What Is Hypermail?

Hypermail is an application written in C for the UNIX environment. It is a collection of C programs and configuration files that allow the Webmaster to customize the execution of Hypermail.

There is a great HTML page on the Web that contains very specific information about Hypermail. That page is located at http://www.eit.com/goodies/software/hypermail/hypermail.html. See Figure 31.1.

Figure 31.1 : A view of the home page for Hypermail at EIT's Web site. This is the main location for authoritative information about the Hypermail package.

Hypermail is an application that supports a Web-based bulletin board environment. It accepts new messages via e-mail and creates HTML files for each message in the environment. Hypermail processes each new message so that messages appear threaded.

For example, if a reply is made to an existing message, Hypermail inserts the HTML file into the subject-index page to show the relationship between the two articles (see Fig. 31.2).

Figure 31.2 : A sample of the subject-index page for a Hypermail environment. Notice the indentation of a follow-up for an article in the same thread as the parent article.

How Hypermail Works

Hypermail receives input (messages posted by users) and converts them into HTML files located in the document root of the Web server. Hypermail also creates a subject-index page for all the articles that have been posted to the forum.

Note
As you recall from Chapter 30, "Developing Web-based Bulletin Boards," there are four basic pages to all Web-based bulletin board environments:
  • Article subject-index page
  • Article page
  • Respond/new article HTML form page
  • The acknowledgement page accepting new posts/replies (optional)
Hypermail creates these same four types of pages.

A forum is all of the messages for a particular group of threads. A thread is a flow of discussion on the same or similar topic. A forum is collection of threads that are all accessible within the same environment. Environment refers to the Hypermail forum.

The Pages Made by Hypermail

The Hypermail forum created by the Hypermail application generates a new-article, subject-index page whenever a new article is posted to the forum. In addition to a subject-index page, Hypermail creates an author and date index of the same articles. In other words, it's possible to view the articles sorted by subject (alphanumerically), date, or author name.

The index pages made by Hypermail are named subject.html for the subject-index page and author.html for the index page sorted by author's name. The index page where each article is listed in sorted order by date is called date.html. The default index page is the list sorted by subject.

When Hypermail builds an article page, it creates an HTML file in a predefined spool area within the document root. For example, when the Hypermail environment is created, the articles can occupy space in /usr/local/etc/httpd/htdocs/testForum/ if the document root of the Web is /usr/local/etc/httpd/htdocs and the name of the forum is testForum.

The names of each HTML file for each article are four-digit cardinal numbers. For example, 0000.html is a valid file name for an article in the forum. If we use the same document root specified above, the path to that article in the file system is

/usr/local/etc/httpd/htdocs/testForum/0000.html

The URL to that article would be /testForum/0000.html.

As new articles are posted to the forum, the name of the last article is incremented from the previous, smaller-number article. The index files subject, date, author, and index.html (the default) are all re-created to reflect the change in articles in the spool.

When new articles are posted or replies to existing articles are made, an HTML form is used to collect the information from the user. Upon collecting that information, the Web server can acknowledge the user with a special acknowledgement page or pull up the default index page for the user.

The acknowledgement page is optional because the Hypermail application can be set up so that the resulting page from submitting a new message or reply can be a transition between the HTML form accepting the new message and the subject- or author-, date-, etc., index page.

In the bulletin board example from Chapter 30, we didn't use an acknowledgement page because it seemed to put an unnecessary page in the sequence of the forum environment.

Where Hypermail Is Used

Hypermail is used in situations where a bulk forum environment is needed. Hypermail is a low-maintence bulletin board environment.

Users can post articles and follow up on articles in the forum as long as the index files generated in response don't grow too large. Since the index files are text (with few graphical elements, if any), the index files can grow quite large without endangering the speed of the forum.

Note
The Hypermail forum is so low-maintence that the Webmaster might easily forget about the forum and let the index file grow much too large. Take note of this when delegating responsibility for maintaining the Hypermail forum.

Hypermail is used in situations where the participants in the forum might not neces-sarily want to engage in the Web interface to the forum to contribute. In other words, Hypermail is a unique Web-based bulletin board environment because the contributors to the environment do not necessarily have to be using a Web interface to add their messages.

The basic design of Hypermail is to use e-mail as a delivery agent to add new messages to the spool of articles in the Hypermail forum. Messages added to the Hypermail forum are literally e-mailed to the forum.

Where Hypermail is used depends on where Hypermail can be used. For example, when e-mail aliasing is possible, then Hypermail can be used. But this can't just be any aliasing. Messages processed by Hypermail are received by e-mail through an alias that is a pipe.

E-Mail Aliasing

Since we need to use aliasing to enable Hypermail, let's review how e-mail aliases can be constructed in UNIX. As mentioned, Hypermail specifically uses an alias that is a pipe to another program.

For example, the aliases on a UNIX system might be defined in a plain text file /etc/mail/aliases (or /usr/lib/aliases).

The plain text file is formatted as follows:

An example of an alias file is shown in Listing 31.1.


Listing 31.1  aliases.txt-A Sample UNIX E-Mail Alias File

# this is a comment in the alias file
# here's an example of a plain alias
skydivers:  bill@some.place.com, ted@some.place.com, 
            steve@some.place.else.org


# here's an example of an alias to a pipe
test-pipe: "| /usr/local/bin/myProgram"

The difference between the alias for skydivers and for test-pipe is that mail sent to skydivers goes to the three recipients: bill, ted, and steve. Mail sent to test-pipe is handled very differently.

The function of sendmail is to deliver mail. In the context of Hypermail, the mail is piped through the Hypermail program as standard input (stdin). Here's how it is handled:

The mail sent to any alias (or any e-mail address) is a stream of bytes that are read by the sendmail program. If the recipients of the e-mail are other valid e-mail addresses, then the sendmail program channels the messages to the appropriate mailbox files for those users if the addresses are local, or it sends the e-mail over the network to the machine on which that remote e-mail address exists.

Because this chapter is not about sendmail, the internals of sendmail are not important here. The nutshell version of sendmail is that data accepted by sendmail is channeled to its proper destination. That destination is an e-mail address. Sendmail is the elec-tronic version of the postal system except there are no stamps to affix or ZIP codes to remember.

The function of Hypermail is to accept the message as e-mail, parse it, and, depending on the options given to Hypermail, process it into the proper forum indexes. Then Hypermail creates the hypertext version of the message body among the other messages collected by Hypermail.

How to Install and Use Hypermail

Hypermail can be "ftp'd" from the EIT Web site. The distribution comes as a compressed tar file. You need an ANSI C compiler to build Hypermail on your system.

The package is fairly simple to build and install. In fact, it's too simple; the software is easy to compile and easy to customize. Under "How to Modify Hypermail" later in this chapter, we show you exactly how do to that. First, this section shows you how to build and install Hypermail the way it was intended to run.

Caution
Hypermail is obtained from the FTP site at EIT. Commercial use is granted if you get necessary permission and instructions from EIT. Be sure you consult the Web site at EIT for more information.

You install Hypermail by unpacking the source files and running the UNIX make program over the source files. When the package is compiled, you install it in the Web site. The following section goes into the details of unpacking and compiling the source code.

Getting Hypermail and Installing It

Hypermail is a package of C programs and C source code that builds a library (cgilib.a). The first step in putting this package together is getting the source distribution from EIT.

The URL to get the source code to Hypermail is as follows (see Fig. 31.3):

Figure 31.3 : This is the page from the EIT site where you can get Hypermail. There is a subsequent page where you agree to a license and can download the package directly through the browser.

http://www.eit.com/goodies/software/hypermail/hypermail.html#6

Find an appropriate place to unpack the software. A good place is in the server root of the Web. The contents are "out of reach"' of the document root of the Web and the files are close by for installing into the cgi-bin directory.

Let's say the server root is /var/Web:

unix% cd /var/web

Now unpack the source code:

unix% tar xf hypermail.tar

The files to check and configure are in the Hypermail directory, so cd into that directory:

unix% cd hypermail

Check these files:

The file that probably needs the most checking is config.h. The flags that are set there determine how the application works. There are also some flags for setting path information specific to your Web server.

The hypermail.h and config.h files (see Listing 31.2) have comments that describe each flag in detail. Look over those files carefully.


Listing 31.2  config.h-The User Configurable C Header File for Hypermail

/*
** Configuration file for Hypermail (C version)
** Kevin Hughes, kevinh@eit.com
** 8/1/94
**
** Copyright (C) 1994, Enterprise Integration Technologies Corp.           
** All Rights Reserved.
*/

/* User-definable options are below */

#ifndef MBOX
#define MBOX "mbox"
#endif

/* Define MBOX as "NONE" to read from standard input.
*/

#ifndef ARCHIVES
#define ARCHIVES ".."
#endif

/* This should be a URL of some type. Define ARCHIVES as "NONE" to omit
** a link to other archives.
*/

#ifndef ABOUT
#define ABOUT "NONE"
#endif

/* This should be a URL of some type. Define ABOUT as "NONE" to omit
** a link to archive information.
*/

#ifndef REVERSE
#define REVERSE 0
#endif

/* Define as 0 if you want latest message on the bottom for date and
** thread indexes. Else define as 1 to put recent articles on top.
*/

#ifndef SHOWHEADERS
#define SHOWHEADERS 0
#endif

/* Define as 0 if you want to hide mail headers in articles.
** Else define as 1.
*/

#ifndef SHOWHTML
#define SHOWHTML 1
#endif

/* Define as 0 if you want articles to be shown in a proportional font.
** Else define as 1.
*/

#ifndef SHOWBR
#define SHOWBR
#endif

/* Define if you want article lines to end with the <br> tag.
** Else uncomment to have non-quoted lines word-wrap. Only takes effect
** if SHOWHTML is defined.
*/

#ifndef IQUOTES
#define IQUOTES
#endif

/* Define if you want quoted lines to be shown in italics. Only
** take effect if SHOWHTML is defined.
*/

#ifndef SHOWHR
/* #define SHOWHR */
#endif

/* Define if you want horizontal rules before and after articles.
*/

#ifndef LABEL
#define LABEL "NONE"
#endif

/* Define as the default title you want to call your archives.
** Define as "NONE" to use the name of the input mailbox.
*/

#ifndef DIR
#define DIR "NONE"
#endif

/* This is the default directory that new files are put into and
** that existing files are read from. If defined as "NONE", this
** will be the name of the input mailbox.
*/

#ifndef OVERWRITE
#define OVERWRITE 0
#endif

/* Define as 0 to always overwrite existing files. Define as 1 to
** only write files that are new.
*/

#ifndef INCREMENT
#define INCREMENT 0
#endif

/* Define as 1 to read in one article only and update existing archives.
** Define as 0 for normal operation.
*/

#ifndef PROGRESS
#define PROGRESS 0
#endif

/* Define as 1 to show progress as Hypermail works. Define as 0 for silent
** operation.
*/

#ifndef DIRMODE
#define DIRMODE 0777
#endif

/* Define as the permissions mode to change any created directories to.
** This must be an octal number.
*/

#ifndef FILEMODE
#define FILEMODE 0666
#endif

/* Define as the permissions mode to change any created HTML files to.
** This must be an octal number.
*/

#ifndef THRDLEVELS
#define THRDLEVELS 2
#endif

/* Define as the number of thread level indents to show in the thread
** index file. The normal value is 2.
*/

#ifndef CONFIGFILE
#define CONFIGFILE "~/.hmrc"
#endif

/* Define as the configuration file to read settings from. ~ as the first
** character represents the current user's home directory. Define as
** "NONE" for no configuration file.
*/

#ifndef DEFAULTINDEX
#define DEFAULTINDEX "thread"
#endif

/* Define as the default main index that users see when the archive
** is first accessed. Possible values are "date", "subject", "author", and
** "thread".
*/

#ifndef EURODATE
/* #define EURODATE */
#endif

/* Define if you want dates in the index files as "DD MM YYYY" instead of
** "MM DD YYYY".
*/

#ifndef SHOWREPLIES
/* #define SHOWREPLIES */
#endif

/* Define if you want links to article replies in messages.
*/

#ifndef MAILCOMMAND
/*
#define MAILCOMMAND "/cgi-bin/mail?to=$TO&replyto=$ID&subject=$SUBJECT"
#define MAILCOMMAND "mailto:$TO"
*/
#endif

/* This is the mail command that email links go to, for instance
** "mailto:$TO" or "/cgi-bin/mail?to=$TO".
**
** In constructing this command, you can specify variables:
**
** $TO : the email address of the person you're sending mail to.
** $ID : the ID of the message you're replying to.
** $SUBJECT: the subject you're replying to.
*/
/* End of user-definable options */

Tip
As with every application you download from the Net, be sure to keep a copy of all the original files before you edit them-for example, cp config.h config-dist.h-so that you know the backup copy is a distribution copy.

Next, check over the makefile. Be sure that the right compiler is specified and any special library directories are set according to the notes in the makefile.

When you go to build Hypermail, there are a few programs to make. One isn't really a program; it's a library that is linked with the Hypermail program. Also, when you build Hypermail, it needs to compile successfully. Hypermail also is dependent on an agent to process the new messages that are sent to the Hypermail program.

The makefile specified in Listing 31.3 shows how the Hypermail application is put together.


Listing 31.3  Makefile-The UNIX Makefile for Building Hypermail

#
# Makefile for Hypermail
# Kevin Hughes, 8/1/94
#

BINDIR= /export/home/jdw/bookweb/bin
# This is where you want hypermail to be installed

MANDIR= /export/home/jdw/bookweb/man/man1
# This is where the man page goes

HTMLDIR= /export/home/jdw/bookweb/htdocs/hypermail
# This is where the HTML documentation goes

CGIDIR= /export/home/jdw/bookweb/cgi-bin/hm
# This is where your CGI programs live

CC= gcc

CFLAGS=  -w

OBJS=          file.o mem.o string.o print.o \
          parse.o struct.o date.o hypermail.o

MAILOBJS=     mail.o libcgi/libcgi.a 

.c.o:
          $(CC) -c $(CFLAGS) $<

all:          hypermail

hypermail:     $(OBJS)
          $(CC) -o hypermail $(CFLAGS) $(OBJS)
          chmod 0755 hypermail
          chmod 0644 hypermail.1
          chmod 0644 hypermail.html
          chmod 0644 hypermail.gif

libcgi/libcgi.a:
          cd libcgi; make all CC="$(CC)" CFLAGS="$(CFLAGS)"

mail:          $(MAILOBJS)
          $(CC) -o mail $(CFLAGS) $(MAILOBJS) -lnsl
          chmod 0755 mail

$(OBJS):     Makefile hypermail.h config.h

install:
          install -cs -m 0755 hypermail $(BINDIR)
          install -c -m 0644 hypermail.1 $(MANDIR)

html.install:
          install -c -m 0644 hypermail.html $(HTMLDIR)
          install -c -m 0644 hypermail.gif $(HTMLDIR)

mail.install:
          install -c -m 0755 mail $(CGIDIR)

install.alpha:
          install -c $(BINDIR) -s -m 0755 hypermail
          install -c $(MANDIR) -m 0644 hypermail.1

html.install.alpha:
          install -c $(HTMLDIR) -m 0644 hypermail.html
          install -c $(HTMLDIR) -m 0644 hypermail.gif

mail.install.alpha:
          install -c $(CGIDIR) -m 0755 mail

pure:
           make CFLAGS="-g" $(OBJS)
          purify $(CC) -o hypermail -g $(CFLAGS) $(OBJS)

quant:
           make CFLAGS="-g" $(OBJS)
          quantify $(CC) -o hypermail -g $(CFLAGS) $(OBJS)

clean:
          rm -f ./hypermail ./mail *.o .pure hypermail.pure* *qx *qv
          rm -fr ./archive
          cd libcgi; make clean

To build Hypermail, at the UNIX prompt:

unix% make hypermail

After Hypermail is compiled, you need to build a program called mail that is part of the Hypermail suite. (Not to be confused with the mail program on the UNIX machine.)

unix% make mail

The programs to compile are mail (to be inserted into /cgi-bin) and Hypermail (to be inserted into /usr/local/bin). The default paths for these are set up in the config.h configuration file. Once these programs are compiled, set up a spool directory for new messages.

unix% mkdir DocumentRoot/archive

Now we're ready to begin using Hypermail.

Using Hypermail

To use Hypermail as is, you need to set up an e-mail alias in the aliases file for the server that Hypermail will run.

For example, in Solaris, add the following string to the /etc/mail/aliases file:

test-list:  "|/usr/local/bin/hypermail -I -u -d /archives/test-list -l \"Test List\""

Messages are spooled up in /archives/test-list. That path is symbolically linked (if necessary) to the document root on the Web server. Mail sent to the alias

test-list@that.server.com

is processed by Hypermail and added to the spool directory with the file name ####.html (as described earlier in this chapter).

Hypermail produces a set of index files for all the messages within a particular forum. Figure 31.2, earlier in this chapter, shows an example of the subject index for a forum on VRML at wired.com.

When a message is sent to the forum via e-mail (by sending e-mail to the test-list@that.server.com address, for example), Hypermail inserts the message into the spool.

But a Web interface for adding new messages is possible, too. For example, suppose you want to allow a user to contribute to the forum by using the Web interface instead of having to use an e-mail client program. To do this, you create an HTML form that accepts input to be processed by Hypermail.

Hypermail can only read messages if they are in e-mail format. To fake the use of e-mail and pass a message to Hypermail, the HTML form must accept and formulate a message to make it look like an e-mail message and then pipe it through Hypermail.

See Listing 31.4 for an example of how to write a CGI interface for adding new messages to a Hypermail forum.


Listing 31.4  hypermail.cgi-A Sample CGI Script That Generates a Page to Accept Messages for Hypermail

#!/usr/local/bin/perl

@INC = ('../lib', @INC);
require 'web.pl';

&beginHTML;

$Hypermail = "$ServerRoot/bin/hypermail";
%Form = &getStdin;

$Form{'email'} = 'no-one@noplace.com' unless $Form{'email'};
$Form{'name'}  = 'No Body' unless $Form{'name'};
$Form{'subject'}= 'No Subject' unless $Form{'subject'};
$Form{'body'} = 'No body' unless $Form{'body'};

open(HM, "| $Hypermail -i -u -d $ServerRoot/htdocs/ch32/spool"); 

print HM "From: $Form{'email'} ($Form{'name'})\n",
         "Subject: $Form{'subject'}\n",
         "To: test-list\n",
         "\n\n",
         $Form{'body'},
         "\n";
close HM;
print "Mail Sent<p>\n";

The CGI script in Listing 31.4 actually uses e-mail to send the message through Hypermail, but users don't have to deal with that technicality. As far as they are concerned, e-mail plays no part in how messages get from their keyboards to the forum on the Web. See Figure 31.4 to see how this would look.

Figure 31.4 : The HTML form available from the server can act as a fake e-mail client for sending a message to the Hypermail forum. Users who want to submit a new message just need to enter their name, e-mail address, and the body of their message.

If you want to send e-mail to Hypermail, you need to know how to write an e-mail message to be read by Hypermail via stdin (-i flag). E-mail needs to have a valid e-mail address in order to arrive someplace. It is possible in UNIX to create an e-mail alias (a fake e-mail address) that accepts a message and "pipes" it through another program just as if the message was stdin to that program.

For example, an e-mail alias such as

myTest:    "| cat >> /tmp/myTest"

will create an alias on the server so that e-mail sent to myTest@that.host.com will be appended to the file /tmp/myTest.

This is the same as saying

cat >> /tmp/myTest 

from the shell.

So, to actually send e-mail to Hypermail you need an alias to the program Hypermail. Hypermail needs to be "told" that data should be read from stdin, so use the -i flag (command line switch, if you prefer) to tell Hypermail that the data you are getting should be read from stdin. Hypermail -i will accept input via stdin.

The format of the input needs to be in the standard UNIX mailbox format (RFC 822 describes that format in detail). The UNIX mailbox format is

From user@some.place.com Mon May  6 23:12:00 1996
Date: Mon, 6 May 1994 23:12:00 PDT 1996
From: user@some.place.com
To: you@where.you.are.com
Subject: Did you get hypermail running yet?

Let me know so I can try it out

If you could peer into the "stdin pipe" as the data is accepted by sendmail and then channeled through the pipe (the alias is to a pipe to Hypermail), you would see the preceding data verbatim. It would be different mail obviously, but the format would be the same format as the mail that is in your UNIX mailbox now.

The parameters and switches to Hypermail tell Hypermail what to do with this new found message.

-i tells Hypermail to read data via stdin.

Messages stored by Hypermail are kept in a spool area. The spool is the directory or archive directory where the subject index is located. Actually, the spool is where everything content-related for a Hypermail forum is located. The index files and the articles themselves are stored in the spool.

Hypermail needs to know what the path is to that directory so it can open and update the correct files (the index files). It needs to know the path to the spool so it can write new article files there, and so on.

The -d flag tells Hypermail where that path is.

The -u flag tells Hypermail that we do indeed want to update the index files.

When Hypermail creates the subject, author, and date index files it uses other flags to help format the indexes. The title (or label) of the forum is an argument after the -l flag to Hypermail.

The label text appearing after the -l flag is copied verbatim to the top of the index pages and the article pages when they are built by Hypermail.

Hypermail is invoked when mail is sent to "myTest@that.host.com." Sendmail writes the message to the pipe specified in the alias file. The message data is expected to be in UNIX mailbox format. By scanning the mail and determining the subject of the message, the sender, and the message header (Message-ID), Hypermail creates a new single article file (####.html) for it in the spool. If the -u flag is set, then the index files are updated with the new information about the article (its author, the date, and the subject of the article). A link is written into the index files for each article pointing to the raw text article file (####.html).

Each article is written (like a CGI sandwich) to a file with HTML tags before and after the message body. The HTML tags decorate the page with the label (-l flag) and show the date and author of the article. Embedded into the article are links to mail to the author of the article, post a follow-up, or make a new article.

In order to reply to a post, you have to be reading an article or the subject index. The mail program that comes with Hypermail is a CGI program that accepts form data and uses sendmail to transfer a message to Hypermail (the default). The mail program that comes with Hypermail also can generate an HTML form for accepting new messages.

To reply to a post, the e-mail address of the author you are replying to will be linked to a CGI script. By default, that CGI script is the mail program that comes with Hypermail. The script will relay a message to the Hypermail alias (from the aliases file) so that the "reply" is treated like another piece of mail. The mail CGI creates an HTML form in which you enter your message. The subject of the message (if it's a reply) will already be filled in for you.

The mail program that comes with Hypermail is used for generating an HTML form to accept replies to messages. It generates HTML and it handles the form data, resending it "via e-mail" to the Hypermail alias until it finally ends up on the index pages as a new article.

This way of using Hypermail is a departure from the classic use of Hypermail. By default, Hypermail is great for accepting e-mail to insert into a Web-based forum. It's easy for someone to send e-mail to an address. Listing 31.4 shows how to build a simple CGI interface that accepts a new message that will be submitted to the forum just like any e-mail message.

How to Modify Hypermail

There are many situations in which the default use of Hypermail won't fit your needs. By this we mean that the function of Hypermail-to display Hypermail routines that generate output-may work. But the "look and feel" of Hypermail is probably not what you want.

Underneath the textual and graphical interface of Hypermail is a good engine for processing messages and creating HTML links to and from messages so they appear to be ordered in some way. On top of that e-mail processing engine is a collection of functions that generate the HTML output for the user.

In the print.c file, we show you how to modify these functions to customize the look and feel of Hypermail for your Web application.

print.c

The print.c file is where the HTML output is generated for Hypermail-where messages are located on the page, how the links are placed for next message and previous message, and routines for how to display the indexes of messages (by subject, author, and date). print.c controls how content generated by Hypermail is displayed.

The print.c file contains functions that create the individual articles in and the index files for the forum.

In print.c, these functions are

hypermail.c

hypermail.c contains the main() function for the Hypermail program. This file doesn't have any specific functions that affect the output as directly as print.c. But if your enhancements to print.c involve a larger scope of work, then you might need to modify hypermail.c.

For instance, in the main() function (hypermail.c), environment variables are detected and data is extracted from them to determine how Hypermail behaves.

You can add a new environment variable for Hypermail to detect that contains a new attribute for changing the display of the pages Hypermail generates.

Suppose you want to change the default background color of the pages Hypermail generates when new messages are submitted. You create an hm_bgcolor environment variable.
If the shell environment that invokes Hypermail has an hm_bgcolor environment variable defined to a non-null string, then that string is added to the <BODY..> tag of the article page.

You need to create a new C string variable to hold this data. So in hypermail.c (the easiest thing to do is make it global), add the following declaration before the main() function is defined:

char hm_bgcolor[MAXLINE];

Then, inside the main() function, after it starts to load from hard-wired defaults, add the following:

if (getenv("HM_BGCOLOR") != NULL)
     strcpy(hm_bgcolor, getenv("HM_BGCOLOR"));

At this point, the bgcolor specified in the environment variable is now in the hm_bgcolor C string. When the display routines in print.c are used, you can reference this data (hm_bgcolor) to build the article (and indexes, if necessary) with the background color you want. And this color is set before Hypermail is invoked; it's not hardwired into Hypermail.

Let's look again at print.c to see where we'd add some C code to handle the new background color. Near line 82 of print.c, (in the writearticles() function), where the <TITLE> tag is written for the new article, you can add the C code:

fprintf(fp, "<BODY %s>\n",   hm_bgcolor == NULL?"":hm_bgcolor);

Since hm_bgcolor is declared in hypermail.c, hm_bgcolor is an external variable to print.c. At the top of the file in print.c, be sure to include the C code:

extern char hm_bgcolor[];

Caution
Remember that Hypermail is not freeware or in the public domain. There are specific licensing issues when you use Hypermail for commercial purposes or modify the source code and reuse the package.
Consult the EIT home page about Hypermail for more information. Hypermail is a very stable program and incorporating it into your Web site is worth the effort to look into the licensing issues.

This chapter describes Hypermail, an application you can use to implement an electronic forum on your Web server without a lot of overhead or customization. The advantages of Hypermail are that it allows users to contribute to a forum in more than one way. They can send messages via e-mail or post them directly from the Web.

In both cases, the messages end up in the master spool of messages. In addition, Hypermail messages are indexed by subject, author, and date, providing an efficient mechanism to access them.

In this chapter, we looked briefly at how you can modify the presentation interface for a Hypermail-based Web forum. We learned how to modify the display routines of Hypermail if nessecary to make the presentation of the Hypermail forum adhere to the existing motif of your Web site.

The next chapter talks about a related application, the classified ad. Like Hypermail, this application enables users to post messages. But the presentation of messages in the classified ad application is for a specific purpose: to be a marketplace of ideas and products.

Both the Web site owner and the general public can participate in populating the Web-based classified ad system. The level is still within your control.

The classified ad application in the next chapter shows a different approach to developing a system of user-generated messages to make the Web site more effective.