NAME
hypermail - convert mail archives in UNIX box format to HTML pages
SYNOPSIS
hypermail [-AgiMptTuvVxX1] [-m mailbox] [-d directory] [-l label] [-L
language] [-a URL] [-b URL] [-c file] [-n listaddress] [-o
keyword=value] [-s htmlsuffix] [-0 number] [mailbox]
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, 00.html, 00.html, etc.
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.
-A Use this to maintain a parallel mbox archive. The file name
defaults to mbox in the directory specified by -d or dir.
-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.
-g Use this to use gdbm to implement a header cache. This will
speed up hypermail, especially if your filesystem is slow. It
will probably not provide any speedup if you use the linkquotes
option.
-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.
-L language
This is a two-letter string specifying the default language to
use, or a longer string specifying a language and locale. Set
this the value of the language table you wish to use when
running and generating archives. See also the iso2022jp and
eurodate config file options.
Current supported languages, with their default locales:
de (de_DE) - German
en (en_US) - English
es (es_ES) - Spanish
fi (fi_FI) - Finnish
fr (fr_FR) - French
el (el) - Greek
gr (el_GR) - Greek
is (is_IS) - Icelandic
no (no_NO) - Norwegian
pl (pl_PL) - Polish
pt (pt_BR) - Brazilian Portuguese
ru (ru_RU) - Russian
sv (sv_SE) - Swedish
-m mailbox
Specifies the mailbox to read articles in from. By default,
Hypermail will look for a file called mbox.
-M This option allows you to use metadata to store the content
type of a MIME attachments and, later on, when a user browses
the attachment, send back this information in the HTTP Content-
Type header. When used, the Content-Type header of a MIME
attachment will be stored in a metadata file.
-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.
-o keyword=value
This is a means of setting any variable that can be specified in
a config file.
-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.
-s htmlsuffix
Use this to specify the html file suffix to be used when
Hypermail generates the html files. This is dependent on local
needs. Do not put a ’.’ in the value. It would result in
"file..html", probably not what you want.
-t This will tell Hypermail to generate an index menu at the top
and bottom of each page in a table format.
-T This will tell Hypermail to generate a message index
Subject/Author/Date listings using a table format.
-u This option tells Hypermail to add message(s) to the end of the
existing HTML file archive and integrate them into it by links
and cross-references. All archive index files will be
regenerated to include the new message.
Hypermail used to require that you only send it one message at
a time when using the -u option, but it should now work
reasonably when given mailboxes containing multiple messages.
When using the -u option, don’t send any messages that
Hypermail has already processed. If you want Hypermail to
recognize that some messages are old messages that shouldn’t be
added to the archive again, send it a mailbox with a complete
set of messages and avoid the -u option.
-v This shows a the variables and their values that Hypermail will
use when.
-V This shows the version information for the executing Hypermail.
Once displayed, Hypermail exits without doing any processing.
-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.
-X Use this to let hypermail write an XML archive overview file in
each directory. The filename is archive_overview.haof.
-0 number
This is a message number that should be deleted from the html
archive. The mbox is not changed.
See the delete_level config file option for more info about
what happens to the message.
-1 Use this to specify there is only one message in the input.
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 RFC2822-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 option. Hypermail
will then read in all the messages given it but will only write new
messages that have been appended to the mailbox.
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:
mbox = /home/john/my_mailbox
filemode = 0600
Settings are read in this order: from the program’s hard-wired internal
defaults, from environment variables, from the configuration file, from
command-line options.
See hmrc.4 for more information on configuration file usage.
Below is a partial list of variables that Hypermail understands. A full
list is available in the file hmrc.html, or you can also look in
setup.c. 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
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_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 0, 1, or 2
Define as 1 to show the articles in a proportionally-spaced font
rather than a fixed-width (monospace) font. Setting this option
to 1 also tells Hypermail to attempt to italicize quoted
passages in articles. Define as 2 for more complex conversion
to html similar to that in txt2html.pl. Showhtml = 2 will
normally produce nicer looking results than showhtml = 1, and
showhtml = 0 will look pretty dull, but 1 and 2 run risks of
altering the appearance in undesired ways.
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_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.
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 RFC2822 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.
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 0, 1, or -1
Define as 1 to append all input messages to the end of existing
archives.
Define as 0 for it to read a mailbox that corresponds to the
entire archive. (See the mbox_shortened option for an exception
to the requirement that it be the entire archive). If there are
any existing html messages, it will figure out which ones at the
end of the mailbox are new, and add only those that haven’t been
converted yet.
Define as -1 to have hypermail figure out whether the input is
entirely new messages to be appended or whether it contains
messages that are already in the archive. A value of -1 cannot
be used with the mbox_shortened option or with the -i command
line option or with mbox = NONE.
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_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
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
show_headers = From,Subject,Date,Message-ID
or they can be listed individually or any combination of.
show_headers = From
show_headers = Subject
show_headers = Date
show_headers = Message-ID
As a special case you can use the identifier ‘‘*’’ as header to
tell hypermail to display all header lines.
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.
inline_types = image/gif image/jpeg
or
inline_types = image/gif 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.
ignore_types = text/x-vcard application/x-msdownload
or
ignore_types = text/x-vcard
ignore_types = application/x-msdownload
HM_LINKQUOTES boolean_number
Set this to On to create fine-grained links from quoted text to
the text where the quote originated. It also improves the
threads index file by more accurately matching messages with
replies. Note that this may be rather cpu intensive (see the
searchbackmsgnum option to alter the performance).
HM_SEARCHBACKMSGNUM postive integer
If the linkquotes option is on and an incremental update is
being done (-u option), this controls the tradeoff between speed
and the reliability of finding the right source for quoted text.
Try to set it to the largest number of messages between a
message and the final direct reply to that message.
HM_LINK_TO_REPLIES text used to indicate links to replies
If the linkquotes option is on, specifying a string here causes
it to generate links from original quoted text the location(s)
in replies which quote them. The string is used to display the
link.
HM_QUOTE_HIDE_THRESHOLD percent (integer)
If the linkquotes option is on, setting this to an integer less
than 100 will cause it to replace quoted text with one-line
links if the percent of lines in the message body (exluding the
signature) consisting of quoted text exceeds the number
indicated by this option.
HM_QUOTE_LINK_STRING text to appear in place of quoted text
If the quote_hide_threshold option is being used, the
quote_link_string will be used if available to display the link
that replaces the quoted text. If no string is specified here,
the first line of each section of quoted text will used.
HM_MONTHLY_INDEX = boolean_number
Set this to On to create additional index files broken up by
month. A summary.html file will provide links to all the monthly
indices.
HM_YEARLY_INDEX = boolean_number
Set this to On to create additional index files broken up by
year. A summary.html file will provide links to all the yearly
indices.
HM_THREAD_FILE_DEPTH = 0 or 1
If nonzero, break the threads index file into multiple files,
with the initial message of each thread in the main index file
along with links to files containing the replies. Setting this
to 1 creates one file for each thread that has replies, and is
recommended for archives with over a few hundred messages.
Setting this greater than 1 will produce multiple levels of
files for each thread whose replies are nested by more than 1
level, but that is rarely useful. This option is currently
disabled if the indextable option is turned on, and probably
needs to be less than thrdlevels.
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 usually be found at
.B http://www.hypermail.org/
but you might also want to check the cvs repository which is the first
place that changes become available:
.B http://cvs.hypermail.org/cgi-bin/cvsweb.cgi/hypermail/docs/
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>
Ashley M. Kirchner <ashley@pcraft.com>
Darci Chapman <minerva@phix.com>
Byron C. Darrah <bdarr@sse.FU.HAC.COM>
Dave Kopper <dave@birman.com>
Daniel Stenberg <Daniel.Stenberg@haxx.nu>
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>
Jose Kahan <jose@w3.org>
Bjarni R. Einarsson <bre@netverjar.is>
Francisco Iacobelli <fiacobelli@ibersis.cl>
Nicolas Noble <pixels@chez.com>
Scott Rose <srose@direct.ca>
Greg Shenaut <greg@bogslab.ucdavis.edu>
W. Tasin <tasin@fhm.edu>
Darryl Lee <lee@darryl.com>
Paul Haldane <Paul.Haldane@newcastle.ac.uk>
Andreas Fuchs <asf@ycom.at>
David D Kilzer <ddkilzer@ti.com>
Tim Witham <twitham@pcocd2.intel.com>
Jyrki Kuoppala <jkp@kaapeli.fi>
Bernhard Reiter <bernhard@climate2.geog.uwm.edu>
Hisashi Gotoh <gotoh@horae.dti.ne.jp>
David Eisner <cradle@glue.umd.edu>
Andy Yoder <ayoder@heisenbug.org>
Peter Karlsson <peter@softwolves.pp.se>
Moritz Willers <Moritz.Willers@ubsw.com>
David Bau <davidbau@hotmail.com>
Brian Kirkby <bkirkby@Concentrico.net>
William King <William.King@dadaboom.com>
June 24, 2000