Each HTML file that is generated for a message contains (where applicable):
In addition, Hypermail will convert references in each message to email addresses and URLs to hyperlinks so they can be selected. Email addresses can be converted to
mailto: URLs or links to a CGI mail program. Note that not all World-Wide Web browsers support the
mailto: URL yet.
To complement each set of HTML messages, four index files are created which sort the articles by date received, thread, subject, and author. Each entry in these index files are links to the individual articles and provide a bird's-eye view of every archived message.
Hypermail was originally developed and designed by Tom Gruber for Enterprise Integration Technologies (EIT) in Common Lisp. It was later rewritten in C by Kevin Hughes at EIT.
To see what Hypermail can do, take a look at these Hypermail-produced archives:
usage: hypermail -upix [-m "mbox"] [-l "label"] [-d "dir"] [-a "URL"] [-b "URL"] [-c "file"] options: -m : Mail archive to read in -l : What to name the output archive -d : The directory to save HTML files in -a : URL to other archives -b : URL to archive information -c : Configuration file to read in -x : Overwrite previous messages -i : Read messages from standard input -u : Update archive by one article -p : Show progress
Using the flags -z, -h, or -? with Hypermail will display this usage summary.
To tell Hypermail what mailbox to read in, use the -m option. If articles will be sent to Hypermail through standard input, use the -i option. Note that the -m and -i options can't be used together! By default, Hypermail will look for a file called
mbox to read its articles in from.
The -d option specifies the directory to put the HTML files and index files that are created into. If the directory doesn't exist, a new one will be created with the name that is specified. If the -d option isn't used, Hypermail will look for a directory with the same name as the mailbox or will create one if needed.
example 1: hypermail -m "www-talk" -d "/archives/www-talk" example 2: cat "/var/spool/mail/foo" | hypermail -i
www-talkand will save the output in the
/var/spool/mail/foofrom standard input and will save the output in a directory called
archivein the same directory Hypermail was run from.
Note that Hypermail can only read messages in the UNIX mailbox format! Such archives are typically RFC 822 mail messages appended to each other that look similar to this:
From email@example.com Mon Jan 1 00:01:30 1994 Date: Mon, 1 Jan 1994 00:01:15 PDT From: firstname.lastname@example.org To: email@example.com Subject: Hello, world! Hi, everyone, just saying hello! From firstname.lastname@example.org Mon Jan 1 00:02:00 1994 Date: Mon, 1 Jan 1994 00:01:45 PDT ...
The messages are typically separated by lines in this format:
From email@example.com Fri Jul 1 00:18:20 1994
The -c option tells Hypermail to read in settings from a configuration file. By default, the program will attempt to read settings from a file called
.hmrc in the user's home directory if it exists.
In the configuration file, variables are set in the following manner:
set hm_variable = number set hm_variable = "string"The complete set of variables that Hypermail recognizes is described in the Configuration Options section.
Archive Interface Options:
-l, "label", -a "URL", -b "URL"
The -l option tells Hypermail what to call the archive - the name that is specified will be in the title of the index pages so users know what sort of messages are being archived.
The -a option includes a link labelled "Other mail archives" in the index pages to any specified URL. This way users who are looking at the archive have the opportunity to go to pointers to other mail archives. By default, this will be a pointer to the parent directory in which the archive files reside.
The -b option includes a link labelled "About this archive" in the index pages to any specified URL. This way users who are looking at the archive have the opportunity to go to information about the archive.
example: hypermail -l "WWW-Talk Archives" -a "http://foo.com/archives/" -b "http://foo.com/archives/info.html"
In the index files for the archive, the above setting will produce something like this:
(top of page)
(list of indexed articles below)
The -x option tells Hypermail to explicitly overwrite any previous HTML files that may exist. Use this option only when it is desirable to completely rewrite the entire archive.
The -u option tells Hypermail to update the archives by one message only. With this option, only one email message will be read in from a file or standard input. This message will be added to the end of the existing HTML file archive and will be integrated into it by links and cross-references. All archive index files will be regenerated to include the new message.
Important! - If the -u option is used and Hypermail is reading from a mailbox file, Hypermail will assume that the file contains only one article, no matter how many files the mailbox may actually contain. Make sure that Hypermail is given only one article when using this option.
If the mailbox that is being read from is an archive that new messages are always being added to, don't use either of these options. Hypermail will then read in all the messages given it but will only write new messages that have been appended to the mailbox.
example 1: cat "one.letter" | hypermail -i -u -d "/www-talk" example 2: hypermail -i -u -m "one.letter" -d "/www-talk" example 3: hypermail -m "mailbox" -d "/www-talk" -x example 4: hypermail -m "mailbox" -d "/www-talk"
www-talkdirectory. If no archive exists, a new one will be created with the specified letter as the first file of the archive.
mailboxand write over any existing files in the
www-talkdirectory if they exist. If no archive exists, a new one will be created.
mailboxand only write new articles - it will not overwrite any existing archive files.
Note that no matter what options are specified, the index files are always rewritten. The date when Hypermail was last run is included in index pages, so it's easy to tell when the archive was last updated.
The -p option shows a progress report as Hypermail reads in and writes out messages - the number of files that Hypermail is reading and writing and the file names of the directory and files created are shown.
setenv HM_MBOX /home/john/my_mailbox setenv HM_FILEMODE 0600
In the configuration file, variables must be in lowercase and separated by their values with an equals (
=) sign. Blank lines and lines beginning with the
# character are skipped:
set hm_mbox = "/home/john/my_mailbox" set hm_filemode = 0600
Settings are read in this order:
Below is a list of configuration variables that can be defined. Boolean numbers can have the value of 0 or 1.
"NONE"to read from standard input as the default.
"NONE"to omit such a link.
"NONE"to omit such a link.
1will reverse-sort the article entries in the date and thread index files by the date they were received. That is, the most recent messages will appear at the top of the index rather than the other way around.
1to show the article header lines in the archived HTML files. These lines typically include the "To:", "From:", and "Subject:" information found in most email messages.
1this to show the articles in a proportionally-spaced font rather than a fixed-width (monospace) font. Defining this option will also tell Hypermail to attempt to italicize quoted passages in articles.
HM_LABEL "label name"
"NONE", the directory name will be the same name as the mailbox read in.
0755. If files will be updated incrementally with sendmail, this will have to be
0644. If files will be updated incrementally with sendmail, this will have to be
1to make Hypermail overwrite existing archives by default.
1to read one article only and append it to existing archives by default.
1to always show a progress report as Hypermail works.
2, replies to messages will be indented once in the index, but replies to replies, etc., will only be indented once as well.
There are a few
#define options which can only be changed in the source code:
<br>tags will be placed at the end of article lines. Otherwise, all non-quoted article lines will word wrap. This only takes effect if
$TOrepresents the address to send mail to,
$SUBJECTrepresents the subject that is being replied to, and
$IDrepresents the message ID of the article that is being replied to.
MAILCOMMAND is not defined, email addresses will not be converted to links in articles. A possible command one could use is
"mailto:$TO", but this could easily be changed to specify a CGI program such as
"/cgi-bin/mail?to=$TO". A CGI mail program is included with the source which can be used for this purpose.
0002.html, etc. In the same directory:
date.htmlis the index of articles sorted by the date they were received by the system's mail daemon.
thread.htmlis the index of articles sorted by thread first, then the date they were received.
subject.htmlis the index of articles sorted by subject. Any "Re:" prefixes in front of subjects will have been stripped out.
author.htmlis the index of articles sorted by the first word of the author's name. If the author's name can't be determined, their email address will be substituted.
index.htmland is the default index that users can go to when entering the archive.
Sorting: In the date and thread index files, note that these lists are sorted by the date the articles were received by the system's mail daemon, not by the date they were written on. The order of articles in the date index may not necessarily match the order in which the article files are written and linked together. Because of this, it is a good idea to make sure the mailbox is sorted by date with the most recent messages towards the bottom.
Running Hypermail automatically: All that's needed to start archiving email messages is to set up Hypermail to do incremental updates in your
/etc/aliases file. Here's what an entry might look like (the last line is one unbroken line):
# Archived mailing list # firstname.lastname@example.org 1/1/94 list: john, mary, "|/usr/local/bin/hypermail -i -u -d /archives/list -l \"Mailing List Archive\""
After adding the entry, make sure
newaliases is run to update the mail aliases. This entry will run Hypermail and update/create the archive whenever a new message is received. Hypermail also works well as a
cron job. Because
sendmail may run Hypermail as different users (this is a well-known
sendmail bug), you will want to make sure that archive directories and files are made readable and writeable by everyone when they are created. This will ensure that there will be no problems incrementally updating the archive.
Including HTML in messages: One can include formatted HTML in message bodies by enclosing the HTML with the <HTML> tag (in either uppercase or lowercase). This tag must be on a line by itself:
This text will not be parsed... <html> this text will be parsed as HTML. </html> This text will not be parsed...
There is no limit to how often the <HTML> tag can be used in an article.
Hypermail binaries and source are available via FTP from ftp.eit.com in the /pub/web.software/hypermail directory.
Hypermail binaries are available for the following platforms:
The Common Lisp version of Hypermail has had no formal version number and differs in many ways from the current C version. Older documentation and information on this version can be found at http://gummo.stanford.edu/html/hypermail/hypermail.html. The latest documentation of the C version can always be found at http://www.eit.com/software/hypermail/hypermail.html.
Please send any feature requests, bug fixes, and comments on the C version of Hypermail to Kevin Hughes at email@example.com. Requests, fixes, and comments on the Common Lisp version should be sent to Tom Gruber at firstname.lastname@example.org.