


HYPERMAIL(1)                                         HYPERMAIL(1)


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 mail-
       box  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 applica-
       ble): 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



                          June 24, 2000                         1





HYPERMAIL(1)                                         HYPERMAIL(1)


       in this fashion: 0000.html, 0001.html, 0002.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 look-
              ing 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 look-
              ing 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

       -V     This shows the version information for the executing  Hypermail.
              Once displayed, Hypermail exits without doing any processing.

       -u     This  option tells Hypermail to add message(s) to the end of the



                          June 24, 2000                         2





HYPERMAIL(1)                                         HYPERMAIL(1)


              existing HTML file archive and integrate them into it  by  links
              and  cross-references.  All archive index files will be regener-
              ated 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 reason-
              ably when given mailboxes containing multiple messages.
               When using the -u option, don't send any messages  that  Hyper-
              mail  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 mes-
              sages and avoid the -u option.

       -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 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  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  upper-
       case.  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



                          June 24, 2000                         3





HYPERMAIL(1)                                         HYPERMAIL(1)


       defaults, from environment variables, from command-line  options,  from
       the configuration file.

       See hmrc.5 for more information on configuration file usage.

       Below  is a list of variables that Hypermail understands.  Boolean num-
       bers 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_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: infor-
              mation 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 pas-
              sages 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.



                          June 24, 2000                         4





HYPERMAIL(1)                                         HYPERMAIL(1)


       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.

       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 arti-
              cle that is being replied  to.   If  defined  as  NONE  ,  email
              addresses  will not be converted to links in articles.  A possi-
              ble 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 fea-
              ture is turned off.





                          June 24, 2000                         5





HYPERMAIL(1)                                         HYPERMAIL(1)


       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  direc-
              tory 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 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 Hyper-
              mail 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 enter-
              ing the archive.  Valid types are date, thread, author, and sub-
              ject.

       HM_HMAIL submission-address
              This is the email address used to send a new message to a hyper-
              mail archive.  "NONE" means don't use it.  Since this is differ-
              ent 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  format-
              ting  statements  that  you wish to included at the top of every



                          June 24, 2000                         6





HYPERMAIL(1)                                         HYPERMAIL(1)


              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  format-
              ting 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  format-
              ting  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  format-
              ting 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 sepa-
              rated 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





                          June 24, 2000                         7





HYPERMAIL(1)                                         HYPERMAIL(1)


       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.





                          June 24, 2000                         8





HYPERMAIL(1)                                         HYPERMAIL(1)


       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 dae-
       mon, 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  <gru-
       ber@intraspect.com>  for  Enterprise  Integration Technologies (EIT) in
       Common Lisp.  It was later rewritten in C  by  Kevin  Hughes  <kev@kev-
       com.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.hypermail.org/


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  con-
       tributions  to  the  hypermail development.  This list is far from com-
       plete ...

       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>



                          June 24, 2000                         9





HYPERMAIL(1)                                         HYPERMAIL(1)


       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                        10


