hypermail.1

.TH HYPERMAIL 1 "June 24, 2000"
.SH NAME
hypermail \- convert mail archives in UNIX box format to HTML pages
.SH SYNOPSIS
.BR"hypermail "[\-AgiMptTuvVxX1 ]
.RB [ \-m
.IR"mailbox"]
.RB [ \-d
.IR"directory"]
.RB [ \-l
.IR"label"]
.RB [ \-L
.IR"language"]
.RB [ \-a
.IR"URL"]
.RB [ \-b
.IR"URL"]
.RB [ \-c
.IR"file"]
.RB [ \-n
.IR"listaddress"]
.RB [ \-o
.IR"keyword=value"]
.RB [ \-s
.IR"htmlsuffix"]
.RB [ \-0
.IR"number"]
.RB [ "mailbox" ]
.SH DESCRIPTION
.Bhypermail
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.
.LP
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.
.LP
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 
.Bmailto:
URLs, or links to a CGI mail program. 
.LP
To complement each set of HTML messages, four
.Iindexfiles
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:
.TP
.Bdate.html
The index of articles sorted by the date they were received by the mail daemon.
.TP
.Bthread.html
The index of articles sorted by thread first, then the date they were received.
.TP
.Bsubject.html
The index of articles sorted by subject. Any
.B"Re:"
prefixes in front of subjects will have been stripped out.
.TP
.Bauthor.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.
.LP
One of the index files will be called
.Bindex.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:
.B0000.html,0001.html,0002.html,
etc.
.SH OPTIONS
.TP
.BI\-a " URL"
This option includes a link labelled
.B"Othermailarchives"
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.
.TP
.BI\-A
Use this to maintain a parallel mbox archive. The file
name defaults to mbox in the directory specified by -d or dir.
.TP
.BI\-b " URL"
This option includes a link labelled
.B"Aboutthisarchive"
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.
.TP
.BI\-c " file"
This option specifies a configuration file to read settings from. By default, Hypermail will look for a file called
.B.hmrc
in the user's home directory.
.TP
.BI\-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
.B\-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. 
.TP
.B\-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.
.TP
.B\-i
Reads in articles from standard input.
.TP
.BI\-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.
.TP
.BI\-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
.TP
.BI\-m " mailbox"
Specifies the mailbox to read articles in from. By default, Hypermail will look for a file called
.Bmbox.
.TP
.B\-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. 
.TP
.BI\-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.
.TP
.BI\-o " keyword=value"
This is a means of setting any variable that can be specified in a config
file.
.TP
.B\-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.
.TP
.B\-shtmlsuffix
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.
.TP
.B\-t
 This will tell Hypermail to generate an
index menu at the top and bottom of each page in a table format.
.TP
.B\-T
This will tell Hypermail to generate 
a message index Subject/Author/Date listings using a table format.
.TP
.B\-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. 
.TP
.B\-v
This shows a the variables and their values that Hypermail will use when.
.TP
.B\-V
This shows the version information for the executing Hypermail.
Once displayed, Hypermail exits without doing any processing.
.TP
.B\-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.
.TP
.B\-X
Use this to let hypermail write an XML archive overview file in each
directory. The filename is archive_overview.haof.
.TP
.B\-0number
 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.
.TP
.B\-1
 Use this to specify there is only one message in the input.
.LP
.SS
GENERAL EXECUTION NOTES
.LP
.BNote:
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.
.LP
.BNote:
The
.B\-i
and
.B\-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".
.LP
.BNote:
If the mailbox that is being read from is an archive that new messages are always being added to, don't use the
.B\-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.
.LP
.SS
CONFIGURATION OPTIONS
.LP
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:
.LP
.PD0
.RS
.BsetenvHM_MBOX"/home/john/my_mailbox"
.LP
.BsetenvHM_FILEMODE0600
.PD
.RE
.LP
In the configuration file, blank lines and lines beginning with a hash mark
.RB ( # )
are ignored. Variables must be in lowercase and separated by values with an equals
.RB ( = )
sign, such as:
.LP
.PD0
.RS
.Bmbox="/home/john/my_mailbox"
.LP
.Bfilemode=0600
.PD
.RE
.LP
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.
.LP
See 
.Bhmrc.4
for more information on configuration file usage.
.LP
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
.B0
or
.B1.
.TP
.BHM_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.
.TP
.BHM_MBOX"filename"
This is the default mailbox to read messages in from. Define this with a value of
.B"NONE"
to read from standard input as the default.
.TP
.BHM_ARCHIVES"URL"
This will create a link in the archived index pages labelled
.I"Othermailarchives"
to the specified URL. Define as
.B"NONE"
to omit such a link.
.TP
.BHM_ABOUT"URL"
This will create a link in the archived index pages labelled
.I"Aboutthisarchive"
to the specified URL. Define as
.B"NONE"
to omit such a link.
.TP
.BHM_REVERSEboolean_number
Defining this variable as
.B1
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.
.TP
.BHM_SHOWHEADERSboolean_number
Define this as
.B1
 to show the article header lines in the archived HTML files. These lines 
typically include the
.BR"To:"," From: "and" Subject:"
information found in most email messages.
.TP
.BHM_SHOWHTML0,1,or2
Define as
.B1
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
.B2
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.
.TP
.BHM_SHOWBRboolean_number
Define as
.B1
to place
.B<br>
tags at the end of article lines. Otherwise, all non-quoted article lines will word wrap. This only takes effect if
.BHM_SHOWHTML
is defined.
.TP
.BHM_IQUOTESboolean_number
Define as
.B1
to italicize quoted lines.
.TP
.BHM_SHOW_MSG_LINKSboolean_number
Define as
.B1
to put the individual message links at the top of the individual
message pages. Define as
.B0
to produce pages without the Next, Previous, Reply, In reply to, etc. links.
.TP
.BHM_EURODATEboolean_number
Define as
.B1
to display article received dates with days before months instead of months before days.
.TP
.BHM_SHOWREPLIESboolean_number
Define as
.B1
to show all replies to a message as links in article files.
.TP
.BHM_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".
.TP
.BHM_MAILCOMMAND"command"
This specifies the mail command to use when converting email addresses to links. The variables
.B$TO,$SUBJECT,
and
.B$ID
can be used in constructing the command string.
.B$TO
represents the address to send mail to,
.B$SUBJECT
represents the subject that is being replied to, and
.B$ID
represents the message ID of the article that is being replied to. If defined as
.B"NONE",
email addresses will not be converted to links in articles. A possible command one could use is
.B"mailto:$TO",
but this could easily be changed to specify a CGI program such as
.B"/cgi-bin/mail?to=$TO".
A CGI mail program is included with the source which can be used for this purpose.
.TP
.BHM_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
.B"NONE",
this feature is turned off.
.TP
.BHM_LABEL"labelname"
Define this as the default label to put in archives. 
.TP
.BHM_DIR"directory"
This is the default directory that Hypermail will look for when creating and updating archives. If defined as
.B"NONE"
the directory will have the same name as the input mailbox.
.TP
.BHM_DIRMODEoctal_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
.B0755. 
If files will be updated incrementally with sendmail, this will have to be
.B0777.
.TP
.BHM_FILEMODEoctal_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
.B0644.
.TP
.BHM_OVERWRITEboolean_number
Define as
.B1
to make Hypermail overwrite existing archives by default. 
.TP
.BHM_INCREMENT0,1,or-1
Define as
.B1
to append all input messages to the end of existing archives.
 Define as
.B0
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
.B-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.
.TP
.BHM_PROGRESSboolean_number
Define as
.B1
or as
.B2
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.
.TP
.BHM_THRDLEVELSnumber
This specifies the number of thread levels to outline in the thread index. For instance, if
.BHM_THRDLEVELS
is
.B2,
replies to messages will be indented once in the index, but replies to replies, etc., will only be indented once as well.
.TP
.BHM_DEFAULTINDEXtype
This specifies the default index that users can view when entering the archive. Valid types are
.B"date,"
.B"thread,"
.B"author,"
and
.B"subject."
.TP
.BI 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.
.TP
.BHM_IHTMLHEADERFILEpath
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 
.B<HTML>,<HEAD>,<BODY> 
and other statements that suit your local customized needs.
.TP
.BHM_IHTMLFOOTERFILEpath
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 
.B</BODY>
and
.B</HTML> 
statement.
.TP
.BHM_MHTMLHEADERFILEpath
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 
.B<HTML>,<HEAD>,<BODY> 
and other statements that suit your local customized needs.
.TP
.BHM_MHTMLFOOTERFILEpath
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 
.B</BODY>
and
.B</HTML> 
statement.
.TP
.BHM_SHOW_HEADERSlistofheaderstodisplay
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. 

.nf
 show_headers = From 
 show_headers = Subject 
 show_headers = Date 
 show_headers = Message-ID 
.nr

As a special case you can use the identifier ``*'' as header to tell
.Bhypermail
to display all header lines.

.TP
.BHM_INLINE_TYPESimagedatatypestoinline
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. 

.nf
 inline_types = image/gif image/jpeg 
 or 
 inline_types = image/gif inline_types = image/jpeg 
.nr
.TP
.BHM_IGNORE_TYPESindicateattachmenttypestoignore
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. 

.nf
 ignore_types = text/x-vcard application/x-msdownload 
 or 
 ignore_types = text/x-vcard 
 ignore_types = application/x-msdownload 
.nr
.TP
.BHM_LINKQUOTESboolean_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).
.TP
.BHM_SEARCHBACKMSGNUMpostiveinteger
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.
.TP
.BHM_LINK_TO_REPLIES"textusedtoindicatelinkstoreplies"
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.
.TP
.BHM_QUOTE_HIDE_THRESHOLDpercent(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.
.TP
.BHM_QUOTE_LINK_STRING"texttoappearinplaceofquotedtext"
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.
.TP
.BHM_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.
.TP
.BHM_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.
.TP
.BHM_THREAD_FILE_DEPTH=0or1
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.

.SH BUGS

.LP
.BSorting:
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.
.LP
Forwarded messages with bad headers may be incorrectly handled.
.LP
.SH AUTHORS
.LP
.BHypermail
was originally designed and developed by Tom Gruber
.RI <gruber@intraspect.com>
for Enterprise Integration Technologies (EIT) in Common Lisp. It was later rewritten in C by Kevin Hughes
.RI <kev@kevcom.com>
while at EIT. Kevin passed on\-going development and support for Hypermail 
to Kent Landfield
.RI <kent@landfield.com>.
.LP
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/
.LP
.SH CREDITS
.LP
.LP
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 ...
.LP
.nf
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>
.nr
.TP