MHonArc creates an index page with links to all mail messages filtered (unless
processing a single message with the -single
option). MHonArc allows you to
have complete customization over the appearance of the index page by setting
various resource either through environment variables, command-line options, or
the resource file.
By default, the filename of the index page is "maillist.html
". However, a
different name may be specified with the M2H_IDXFNAME
environment variable,
the IDXFNAME
resource element, or the -idxfname
command-line option.
MHonArc allows you to completely override the begining markup of the index
page. I.e. You can control the opening <HTML> tag, the HEAD element contents,
the opening <BODY> tag, etc. Therefore, if you are not satisfied with the default
behavior of how the TITLE resource is used, or have other needs that require
control on the beginning markup, you can set the IDXPGBEGIN
resource file
element.
IDXPGBEGIN
The best way to show how the IDXPGBEGIN
works, the following represents the
default setting MHonArc uses:
<IDXPGBEGIN> <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> <HTML> <HEAD> <TITLE>$IDXTITLE$</TITLE> </HEAD> <BODY> <H1>$IDXTITLE$</H1> </IDXPGBEGIN>
Technically, setting the TITLE resource, via the M2H_TITLE
environment
variable, the TITLE
resource element, or the -title
command-line
option, sets the $IDXTITLE$
resource file variable.
The resource variables allowed in the IDXPGBEGIN
element are the following:
$DOCURL$
-- URL to documentation
$GMTDATE$
-- Current GMT date.
$IDXFNAME$
-- Filename of main index page.
$IDXSIZE$
-- Max number of messages that may be listed in the index.
$IDXTITLE$
-- The title of the index page.
$LOCALDATE$
-- Current local date.
$NUMOFIDXMSG$
-- Number of message listed.
$NUMOFMSG$
-- Number of messages in the archive.
$OUTDIR$
-- Pathname of archive.
$PROG$
-- Program name.
$TIDXFNAME$
-- Filename of thread index page.
$TIDXTITLE$
-- Title of thread index page.
$VERSION$
-- Program version.
See Resource Variables for more information on the usage of variables.
Since MHonArc allows you to control the beginning markup, it makes sense for it to allow you to control the ending markup.
IDXPGEND
The IDXPGEND
resource element may be used to define the ending markup of the
index page. The default value is the following:
<IDXPGEND> </BODY> </HTML> </IDXPGEND>
The resource variables allowed are the same as for IDXPGBEGIN
.
MHonArc allows you to include the contents of files into the index page via the header and footer resources.
The use of include files is discouraged since the LISTBEGIN
and LISTEND
resources can be used to achieve the same results. Also, the support for the
include resource may be removed in future releases.
The header file is specified via the M2H_HEADER
environment variable, the
HEADER
resource element, or the -header
command-line option. The contents of
the header file are inserted above the message listing, and right after the H1
title
element.
Filename should not contain the <HTML>
, <HEAD>
, and <BODY>
tags; these
tags are automatically provided by MHonArc, or defined by the
IDXPGBEGIN
resource file element.
The footer file is specified via the M2H_FOOTER
environment variable, the FOOTER
resource element, or the -footer
command-line option. The contents of the footer
file are inserted after the message listing.
Filename should not contain the </BODY>
, and </HTML>
tags; these tags
are automatically provided by MHonArc, or defined by the IDXPGEND
resource file element.
The header and footer files allow you to incorporate search-forms, hyperlinks to other pages, or any other HTML markup you like.
It is only necessary to specify the header and/or footer files the first time you create an archive. The contents included from the header and/or footer files are preserved in any subsequent additions to the archive. Only respecify the header and/or footer files if you need to make changes to the header/footer contents.
MHonArc lists messages in the order specified by the various sort options.
However, you have complete control on how the message listing are formatted via
the LISTBEGIN
, LITEMPLATE
, and LISTEND
resource elements in the Resource
File. These elements allow you to specify the HTML markup to use in the index
page.
LISTBEGIN
The LISTBEGIN
resource element specifies the text to begin the message list. The
text can be any valid HTML markup. Plus, MHonArc defines the following
variables you may use which get expanded at run-time:
$DOCURL$
-- URL to documentation
$GMTDATE$
-- Current GMT date.
$IDXFNAME$
-- Filename of main index page.
$IDXSIZE$
-- Max number of messages that may be listed in the index.
$IDXTITLE$
-- The title of the index page.
$LOCALDATE$
-- Current local date.
$NUMOFIDXMSG$
-- Number of message listed.
$NUMOFMSG$
-- Number of messages in the archive.
$OUTDIR$
-- Pathname of archive.
$PROG$
-- Program name.
$TIDXFNAME$
-- Filename of thread index page.
$TIDXTITLE$
-- Title of thread index page.
$VERSION$
-- Program version.
MHonArc's LISTBEGIN
default value is the following:
<LISTBEGIN> <UL> <LI><A HREF="$TIDXFNAME$">Thread Index</A></LI> </UL> <HR> <UL> </LISTBEGIN>
If the NOTHREAD resource is set, the following is the default value:
<LISTBEGIN> <HR> <UL> </LISTBEGIN>
LITEMPLATE
The LITEMPLATE
resoure element defines the HTML text to represent each
message list item. You may use the following variables which are expanded at
runtime:
$A_ATTR$
-- The NAME
and HREF
attributes to use in an anchor to link to
the archived message. The NAME
attribute links the messages to the index
page.
$A_HREF$
-- The HREF
attribute to use in an anchor to link to the archived
message.
$A_NAME$
-- The NAME
attributes to use in an anchor for messages to link
to the index page.
$DATE$
-- The date of the message.
$DDMMYY$
-- Message date in dd/mm/yy format.
$ICON$
-- The context-type sensistive icon. See Icons for information.
$ICONURL$
-- The URL to the context-type sensistive icon. See Icons for
information.
$MMDDYY$
-- Message date in mm/dd/yy format.
$NUMFOLUP$
-- Number of follow-ups for the given message.
$FROM$
-- The complete text in the From:
field of the message.
$FROMADDR$
-- The e-mail address in the From:
field of the message.
$FROMNAME$
-- The English name of the person in the From:
field of the
message. If no English name is found, the username specified in the e-mail
address is used.
$MSGNUM$
-- The message numbers assigned to the message by MHonArc.
$ORDNUM$
-- The current listing number of the message.
$SUBJECT$
-- The subject text of the message wrapped in an anchor
element that hyperlinks to the message.
$SUBJECTNA$
-- The subject text of the message without the anchor
element.
$YYMMDD$
-- Message date in yy/mm/dd format.
Do not specify $A_ATTR$
, $A_NAME
, and $SUBJECT$
together in the
LITEMPLATE
element. Since all of these variables contain the NAME
atrribute. Invalid HTML will be created since multiple anchors will have
the same NAME
identifier.
LITEMPLATE
's default value is the following:
<LITEMPLATE> <LI><STRONG>$SUBJECT$</STRONG> <UL><LI><EM>From</EM>: $FROM$</LI></UL> </LI> </LITEMPLATE>
LISTEND
The LISTEND
resource element specifies the text to use to end the message list. The
text can be any valid HTML markup. LISTEND
may contain the same variables as
LISTBEGIN
.
LISTEND
's default value is the following:
<LISTEND> </UL> </LISTEND>
MHonArc supports the ability to insert icons in the index page for each message based on the message's content-type. For example: You can have text/plain messages use a different icon than text/html messages.
To specify the icons for MHonArc to use, you use the ICONS
resource element in
the Resource File. The format of each line in the ICONS
element is as follows:
<content-type>:
<URL for icon>
<content-type> represents a MIME content-type. <URL for icon> is the URL to the
icon. The special content-type called "unknown
" may be defined to specify the
icon to use for non-recognized content-types. If unknown
is not defined, the
text/plain icon is used for unknown content types.
<ICONS> audio/basic:http://foo.org/gifs/gsound.gif image/gif:http://foo.org/gifs/gimage.gif image/jpeg:http://foo.org/gifs/gimage.gif image/tiff:http://foo.org/gifs/ggraphic.gif multipart/alternative:http://foo.org/gifs/gmulti.gif multipart/digest:http://foo.org/gifs/gtext.gif multipart/mixed:http://foo.org/gifs/gdoc2.gif multipart/parallel:http://foo.org/gifs/gdoc.gif text/richtext:http://foo.org/gifs/gdoc.gif text/html:http://foo.org/gifs/gdoc.gif text/plain:http://foo.org/gifs/gletter.gif unknown:http://foo.org/gifs/gunknown.gif video/mpeg:http://foo.org/gifs/gmovie.gif </ICONS>
In order to incorporate icons into the index page, insert the $ICON$
variable into
the LITEMPLATE
resource element.
<litemplate> $ICONURL$<strong>$SUBJECT:40$</strong> ($NUMFOLUP$) <em>$FROMNAME$</em><br> </litemplate>
The $ICON$
variable expands to the IMG
HTML element with the appropriate
URL in the SRC
attribute to the icon. The ALT
attribute of the IMG
element contains
the content-type of the message, surrounded by []
's, for use with text based
browsers.
$ICONURL$
may also be used if you want redefine the format of the IMG
element.
<litemplate> <img src="$ICONURL$" alt="* "><strong>$SUBJECT:40$</strong> ($NUMFOLUP$) <em>$FROMNAME$</em><br> </litemplate>
This example overrides what is normally used in the ALT
attribute.
It may be easier to see how the LISTBEGIN
, LITEMPLATE
, LISTEND
resource
elements work when declared together:
<!-- This represents the default values used by MHonArc --> <LISTBEGIN> <UL> <LI><A HREF="$TIDXFNAME$">Thread Index</A></LI> </UL> <HR> <UL> </LISTBEGIN> <LITEMPLATE> <LI><STRONG>$SUBJECT$</STRONG> <UL><LI><EM>From</EM>: $FROM$</LI></UL> </LI> </LITEMPLATE> <LISTEND> </UL> </LISTEND>
Here's another example that changes the layout into a more compact listing, adds Icons usage, and adds a time stamp information on when the index page was last updated:
<listbegin> <address> Last update: $CURDATE$<br> $NUMOFMSG$ messages<br> </address> <p> <UL> <LI><A HREF="$TIDXFNAME$">Thread Index</A></LI> </UL> <p> Messages listed in chronological order. Listing format is the following: <blockquote> <img src="http://foo.org/gifs/gletter.gif" alt="* "> <strong>Subject</strong> (# of follow-ups) <em>From</em>. </blockquote> <p> <hr> </listbegin> <litemplate> <img src="$ICONURL$" alt="* "><strong>$SUBJECT:40$</strong> ($NUMFOLUP$) <em>$FROMNAME$</em><br> </litemplate> <listend> </listend>