HYPERMAIL(1) HYPERMAIL(1)
August 15, 1998 - Version 2.0b3
NAME
hypermail - convert mail archives in UNIX box format to HTML pages
SYNOPSIS
hypermail [-ipuvVx] [-m mailbox] [-d directory] [-l label] [-a URL] [-b
URL] [-c file]
DESCRIPTION
hypermail is a program that takes a file of mail messages in UNIX
mailbox format and generates a set of cross-referenced HTML documents.
Each file that is created represents a separate message in the mail
archive and contains links to other articles, so that the entire
archive can be browsed in a number of ways by following links.
Archives generated by Hypermail can be incrementally updated, and
Hypermail is set by default to only update archives when changes are
detected. Each HTML file that is generated for a message contains
(where applicable): the subject of the article, the name and email
address of the sender, the date the article was sent, links to the
next and previous messages in the archive, a link to the message the
article is in reply to, and a link to the message next in the current
thread. In addition, Hypermail will convert references in each
message to email addresses and URLs to hyperlinks so they can be
selected. Email addresses will be converted to mailto: URLs, or links
to a CGI mail program. 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:
date.html
The index of articles sorted by the date they were received by
the mail daemon.
thread.html
The index of articles sorted by thread first, then the date they
were received.
subject.html
The index of articles sorted by subject. Any Re: prefixes in
front of subjects will have been stripped out.
author.html
is 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. One of the index files will be
called index.html and is the default index that users can go to
when entering the archive. In the specified directory, articles
will be read out in the order that they were read from a mailbox
or standard input. Filenames start at zero and increase in this
fashion: 0000.html, 0001.html, 0002.html, etc.
- 1 - Formatted: April 27, 2024
HYPERMAIL(1) HYPERMAIL(1)
August 15, 1998 - Version 2.0b3
OPTIONS
-a URL
This option includes a link labelled Other mail archives in the
index pages to the specified URL. This way users who are looking
at the Hypermail archive have the opportunity to go to pointers
to other mail archives. By default, this is a link to the parent
directory which holds the archive files.
-b URL
This option includes a link labelled About this archive in the
index pages to the specified URL. This way users who are looking
at the Hypermail archive have the opportunity to go to
information about the archive.
-c file
This option specifies a configuration file to read settings from.
By default, Hypermail will look for a file called .hmrc in the
user's home directory.
-d directory
Specifies the directory to put the HTML files and index files
that are created. 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 input mailbox or will create one if needed.
-i Reads in articles from standard input.
-l label
This 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.
-m mailbox
Specifies the mailbox to read articles in from. By default,
Hypermail will look for a file called mbox.
-n submission-address
This is the list's submission address. In this manner people will
be able to submit new messages to the list the hypermail archive
serves.
-p This 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.
-v This shows a the variables and their values that Hypermail will
use when
- 2 - Formatted: April 27, 2024
HYPERMAIL(1) HYPERMAIL(1)
August 15, 1998 - Version 2.0b3
-V This shows the version information for the executing Hypermail.
Once displayed, Hypermail exits without doing any processing.
-u This updates 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.
-x This 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.
GENERAL EXECUTION NOTES Note: 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. Note: The -i and -m options cannot be used
together. Only archives in UNIX mailbox format can be read in -
mailboxes of this kind are usually appended RFC 822-compliant articles
separated by lines such as "\nFrom person@site Mon Jan 10 12:34:56
1994". Note: If the mailbox that is being read from is an archive
that new messages are always being added to, don't use the -u or -x
options. Hypermail will then read in all the messages given it but
will only write new messages that have been appended to the mailbox.
Note: If the -u option is used and articles are read in 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.
CONFIGURATION OPTIONS The following settings can be read in as
environment variables or from the specified configuration file.
Environment settings are in uppercase. For instance, in the C shell,
variables can be set as:
setenv HM_MBOX /home/john/my_mailbox setenv HM_FILEMODE 0600
In the configuration file, blank lines and lines beginning with a hash
mark (#) are ignored. Variables must be in lowercase and separated by
values with an equals (=) sign, such as:
set hm_mbox = /home/john/my_mailbox set hm_filemode = 0600
Settings are read in this order: from the program's hard-wired
internal defaults, from environment variables, from command-line
options, from the configuration file. See hmrc.4 for more information
on configuration file usage. Below is a list of variables that
Hypermail understands. Boolean numbers can have the value of 0 or 1.
HM_CONFIGFILE filename
This is the default configuration file to read settings in from.
This can only be specified as an environment variable. If the
first character is "~", Hypermail will look for the file under
- 3 - Formatted: April 27, 2024
HYPERMAIL(1) HYPERMAIL(1)
August 15, 1998 - Version 2.0b3
the current user's home directory.
HM_MBOX filename
This is the default mailbox to read messages in from. Define this
with a value of NONE to read from standard input as the default.
HM_ARCHIVES URL
This will create a link in the archived index pages labelled
Other mail archives to the specified URL. Define as NONE to omit
such a link.
HM_ABOUT URL
This will create a link in the archived index pages labelled
About this archive to the specified URL. Define as NONE to omit
such a link.
HM_USETABLE boolean_number
Defining this causes Hypermail to generate an index menu in HTML
table format at the top and bottom of each page.
HM_REVERSE boolean_number
Defining this variable as 1 will 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.
HM_SHOWHEADERS boolean_number
Define this as 1
to 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.
HM_SHOWHTML boolean_number
Define as 1 to show the articles in a proportionally-spaced font
rather than a fixed-width (monospace) font.
HM_SHOWBR boolean_number
Define as 1 to place <br> tags at the end of article lines.
Otherwise, all non-quoted article lines will word wrap. This only
takes effect if HM_SHOWHTML is defined.
HM_IQUOTES boolean_number
Define as 1 to italicize quoted lines.
HM_SHOWHR boolean_number
Define as 1 to place horizontal rules before and after articles.
HM_SHOW_MSG_LINKS boolean_number
Define as 1 to put the individual message links at the top of the
individual message pages. Define as 0 to produce pages without
the Next, Previous, Reply, In reply to, etc. links.
- 4 - Formatted: April 27, 2024
HYPERMAIL(1) HYPERMAIL(1)
August 15, 1998 - Version 2.0b3
HM_EURODATE boolean_number
Define as 1 to display article received dates with days before
months instead of months before days.
HM_SHOWREPLIES boolean_number
Define as 1 to show all replies to a message as links in article
files.
HM_MAILTO address
The address of the contact point that is put in the HTML header
line
<LINK REV=made HREF=mailto:MAILTO>
The <LINK...> header can be disabled by default by setting
HM_MAILTO to "NONE".
HM_MAILCOMMAND command
This specifies the mail command to use when converting email
addresses to links. The variables $TO, $SUBJECT, and $ID can be
used in constructing the command string. $TO represents the
address to send mail to, $SUBJECT represents the subject that is
being replied to, and $ID represents the message ID of the
article that is being replied to. If defined as NONE , 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.
HM_DOMAINADDR domainname
Set this to the domainname you want added to a mail address
appearing in the RFC822 field which lack a hostname. When the
list resides on the same host as the user sending the message, it
is often not required of the MTA to domain-ize these addresses
for delivery. In such cases, Hypermail will add the DOMAINADDR
to the email address. If defined as NONE , this feature is turned
off.
HM_LABEL label name
Define this as the default label to put in archives.
HM_DIR directory
This is the default directory that Hypermail will look for when
creating and updating archives. If defined as NONE the directory
will have the same name as the input mailbox.
HM_DIRMODE octal_number
This is an octal number that new directories are set to when they
are created. If the archives will be made publically available,
it's a good idea to define this as 0755. If files will be updated
incrementally with sendmail, this will have to be 0777.
- 5 - Formatted: April 27, 2024
HYPERMAIL(1) HYPERMAIL(1)
August 15, 1998 - Version 2.0b3
HM_FILEMODE octal_number
This is an octal number that new files are set to when they are
created. If the archives will be made publically available, it's
a good idea to define this as 0644.
HM_OVERWRITE boolean_number
Define as 1 to make Hypermail overwrite existing archives by
default.
HM_INCREMENT boolean_number
Define as 1 to read one article only and append it to existing
archives by default.
HM_PROGRESS boolean_number
Define as 1 or as 2 to always show a progress report as Hypermail
works. Defined as 2 shows more information about the attachment
files created. This is written to stdout.
HM_THRDLEVELS number
This specifies the number of thread levels to outline in the
thread index. For instance, if HM_THRDLEVELS is 2, replies to
messages will be indented once in the index, but replies to
replies, etc., will only be indented once as well.
HM_DEFAULTINDEX type
This specifies the default index that users can view when
entering the archive. Valid types are date, thread, author, and
subject.
HM_BODY <BODY>
This is the <BODY> line to use when generating the HTML pages.
Define as "NONE" to use the builtin <BODY> line by default.
HM_HMAIL submission-address
This is the email address used to send a new message to a
hypermail archive. "NONE" means don't use it. Since this is
different for each hypermail archive, you should probably leave
it set to "NONE" here, and let it be specified at runtime by
command-line parameters in the list specific configfile.
HM_IHTMLHEADERFILE path
Define path as the path to a file containing valid HTML
formatting statements that you wish to included at the top of
every index page. Hypermail will print this file as the header of
the index so make sure it contains <HTML>, <HEAD>, <BODY> and
other statements that suit your local customized needs.
HM_IHTMLFOOTERFILE path
Define path as the path to a file containing valid HTML
formatting statements that you wish to included at the bottom of
every index page. Hypermail will print this file as the trailer
- 6 - Formatted: April 27, 2024
HYPERMAIL(1) HYPERMAIL(1)
August 15, 1998 - Version 2.0b3
of the index so make sure it contains at a minimum a </BODY> and
</HTML> statement.
HM_MHTMLHEADERFILE path
Define path as the path to a file containing valid HTML
formatting statements that you wish to included at the top of
every message page. Hypermail will print this file as the header
of the message so make sure it contains <HTML>, <HEAD>, <BODY>
and other statements that suit your local customized needs.
HM_MHTMLFOOTERFILE path
Define path as the path to a file containing valid HTML
formatting statements that you wish to included at the bottom of
every message page. Hypermail will print this file as the trailer
of the message so make sure it contains at a minimum a </BODY>
and </HTML> statement.
HM_SHOW_HEADERS list of headers to display
Define the list of headers to be displayed if the variable
HM_SHOWHEADERS is set to 1 (ON). This is a comma or space
separated all on a single line such as
hm_show_headers = From,Subject,Date,Message-ID
or they can be listed individually or any combination of.
hm_show_headers = From
hm_show_headers = Subject
hm_show_headers = Date
hm_show_headers = Message-ID
HM_INLINE_TYPES image data types to inline
This is the list of MIME types that you want inlined as opposed to
simply linked into the message. They can be listed individually on
multiple lines or comma or space separated on a single line.
hm_inline_types = image/gif image/jpeg
or
hm_inline_types = image/gif hm_inline_types = image/jpeg
HM_IGNORE_TYPES indicate attachment types to ignore
This is the list of MIME attachment types that you do not want to do
anything with. They are quietly ignored. They can be listed individually
on multiple lines or comma or space separated on a single line.
hm_ignore_types = text/x-vcard application/x-msdownload
or
hm_ignore_types = text/x-vcard
hm_ignore_types = application/x-msdownload
- 7 - Formatted: April 27, 2024
HYPERMAIL(1) HYPERMAIL(1)
August 15, 1998 - Version 2.0b3
BUGS
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. Forwarded messages with bad
headers may be incorrectly handled.
AUTHORS
Hypermail was originally designed and developed by Tom Gruber
<gruber@intraspect.com> for Enterprise Integration Technologies (EIT)
in Common Lisp. It was later rewritten in C by Kevin Hughes
<kev@kevcom.com> while at EIT. Kevin passed on-going development and
support for Hypermail to Kent Landfield <kent@landfield.com>. The
latest documentation can be found at
http://www.landfield.com/hypermail/
CREDITS
I'd like to thank the members of the Hypermail Development list for
their continued encouragement, ideas, bug fixes and participation.
Additionally, following people should be noted for their work and
contributions to the hypermail development. This list is far from
complete ...
Bob Crispen <bob.crispen@boeing.com>
Darci Chapman <minerva@phix.com>
Byron C. Darrah <bdarr@sse.FU.HAC.COM>
Dave Kopper <dave@birman.com>
Daniel Stenberg <Daniel.Stenberg@sth.frontec.se>
I.Ioannou <roryt@hol.gr>
Elliot Lee <sopwith@redhat.com>
Martin Schulze <joey@infodrom.north.de>
Jay Soffian <jay@cimedia.com>
Jared Reisinger <feety@hhhh.org>
Peter C. McCluskey <pcm@rahul.net>
Roy T. Fielding <fielding@kiwi.ics.uci.edu>
Roy Tennant <rtennant@library.berkeley.edu>
.rm]B
- 8 - Formatted: April 27, 2024
