MHonArc supports the ability to read in a resource file to control the behavior of MHonArc. The resource file allows you to specify most of the resources set by environment variables and command-line options, and it allows you to specify other resources to control MHonArc's behavior.
The resource file is specified by the M2H_RCFILE
environment variable or the
-rcfile
command-line option. The command-line option overrides the
environment variable if both are defined.
MHonArc will store the information specified in the resource file in the database for the archive. Therefore, it is unnecessary to respecify the resource file duing archive updates unless changes are required from the current settings.
Resources are set in the file by using elements similiar in style to HTML/SGML markup. However, MHonArc uses simpler parsing rules for the resource file than standard SGML:
Any line that is not a recognized element open tag, and the line is not contained within an element, is ignored. This implies that regular text can be put anywhere outside of recognized elements for commenting purposes.
NOTE: You should use SGML comment declarations (<!--
... -->
) when
commenting a resource file. This will eliminate possible conflict with later
versions of MHonArc if more stricter parsing rules are adopted.
The opening tag of an element must occur by itself on a single line. Whitespace is allowed before the the open tag.
No comments are allowed inside elements because the text will be treated as element content.
Each element must be closed with a </
element_name>
tag on its own
line unless explicitly stated otherwise in the Resource Elements section.
Whitespace is allowed before the close tag.
Some elements can take an optional attribute called "Override
". This
tells MHonArc that the contents of the element will completely override
the default behavior of MHonArc, and previous instances of the element.
Example: "<EXCS Override>
". If "Override
" is not specified, then the
contents of the element augment the current setting.
Element names are case-insensitive.
Elements can occur in any order in the resource file.
Some resource element contents may contain variables. Variables get expanded to strings at run-time.
Variable expansion will only take place in resource elements that are intended to have variables as part of their content. If an element is not meant to have variables, the variable text will be taken literally as part of the element content.
The syntax of the variables to use in resource elements is as follows:
$
VARIABLE[:
[N][U
]]$
The items in []'s are optional. Definition of each part:
$
The $
character represents the beginning, and ending, of the variable.
This is the the actual name of the variable. All variable names must be uppercase.
:
[N][U
] (optional)
This defines a maximum length of the replacement string for the variable.
The option "U
" denotes that the replacement string should be treated as
part of a URL string. This can be useful when the variable may contain
special characters, and the variable is used withing a URL.
No whitespace is allowed between the opening $
and closing $
. If an unrecognized
variable is encountered, it gets replaced with an empty string. If a literal "$
" is
needed, use "$$
".
The MAILTOURL
resource has different rules for variable expansion. If a
variable does not exactly match the set of variables available for the
MAILTOURL
, the variable text will be taken literally as part of the element
content. Therefore, a single "$
" can be used to represent a "$
" character.
Also, variables in the MAILTOURL
should NOT have ":
NU" modifier. This
will prevent the variables from be recognized. MHonArc will
automatically treat the replacement value as a part of a URL string.
Here are some examples of legal variable usage:
$SUBJECT$
$FROMNAME$
$SUBJECT:50$
$SUBJECTNA:60U$
$FROMADDR:U$
Each resource element will define what variables are defined for it.
The following are complete listings of all the resource elements defined by MHonArc. Many element descriptions will reference to other sections of the documentation on the exact usage of the element.
The following list of elements contain no textual content. Therefore, no end tag is required:
NODOC
Do not put link to documentation on main index page.
NOMAILTO
Do not convert e-mail addresses in mail headers to mailto hyperlinks.
NONEWS
Do not convert newsgroups in the Newsgroups:
mail header field to news
hyperlinks.
NOREVERSE
Do not perform a reverse listing of the mail messages in the main index page.
NOSORT
List messages in the index page in the order they are processed.
NOTHREAD
Do not create thread index.
NOTREVERSE
List threads in the thread index with oldest thread first.
NOTSUBSORT
Do not sort thread by subject in thread index page.
REVERSE
List messages in reverse listing order for the main index page.
SORT
List messages in the index page in chronological order.
SUBSORT
Sort messages by subject. Subject sorting is case-insensitive, and begining "Re:
",
"A
", "An
", and "The
" words are ignored.
THREAD
Create thread index. This is the default.
TREVERSE
List threads in the thread index with newest thread first.
TSUBSORT
Sort thread by subject in thread index page.
The following list of elements contain textual content, therefore, each element must be explicitly closed with an element end tag (examples are given in Example Resource File):
BOTLINKS
Markup for defining the various hyperlinks at the bottom of converted messages. See Navigational Links of Message Customization for usage of this element.
DBFILE
Use name for the name of MHonArc database file. The default is ".mhonarc.db
"
(or "MHONARC.DB
" under MS-DOS).
You should not override the default name unless absolutely necessary, and you are confident about what you are doing.
DOCURL
URL to MHonArc documentation. The default is
"http://www.oac.uci.edu/indiv/ehood/mhonarc.html
".
EXCS
Set of message header fields to exclude from messages. See Excluding Fields of Message Customization for usage of this element.
FIELDORDER
The order the message header fields appear in messages. See Field Order of Message Customization for usage of this element.
FIELDSTYLES
The format specification for message header field values. See Field Formatting of Message Customization for usage of this element.
FOOTER
File to include at the end of the index page. See Include Files in Index Page Customization for more information about the footer file.
HEADER
File to include at the beginning of the index page. See Include Files in Index Page Customization for more information about the header file.
ICONS
The ICONS
element is used to specify the icons that represent the different
content-types of messages. See Icons in Index Page Customization for usage of this
element.
IDXFNAME
The name of the index file. The default is "maillist.html
".
LABELSTYLES
The format specification for message header field labels. See Field Formatting in Message Customization for usage of this element.
LISTBEGIN
Markup for beginning the main index list. See Listing Layout in Index Page Customization for usage of this element.
LITEMPLATE
Markup for an entry in the main index list. See Listing Layout in Index Page Customization for usage of this element.
LISTEND
Markup for terminating the main index list. See Listing Layout in Index Page Customization for usage of this element.
MAILTOURL
Url to use for e-mail hyperlinks. See E-mail Links in Message Customization for usage of this element.
MIMEARGS
Arguments to MIME filters. See Specifying Filters in MIME for usage of this element.
MIMEFILTERS
Routines for filtering messages. See Specifying Filters in MIME for usage of this element.
MSGFOOT
Footer text for converted messages. See Header and Footer in Message Customization for usage of this element.
MSGHEAD
Header text for converted messages. See Header and Footer in Message Customization for usage of this element.
MSGSEP
Perl regular expression that represents the message separator for mailbox files. The
default expression is "^From
".
OTHERINDEXES
List of resource files (one per line) defining other index pages to generate when creating, or updating, an archive.
It is very important that each resource file specified defines the IDXFNAME
(or the TIDXFNAME
and THREAD
elements for a thread index) to prevent
overwriting of the default index pages.
MHonArc will only store the name of the resource files listed in the database. Therefore, for any subsequent updates the archive, the extra index resource files must exist inorder to generate the extra index pages.
Since MHonArc will look in the archive location for resource files specified
with relative pathnames, you can keep the other index resource files in the
same location as the archive, and just specify the filenames for the
OTHERINDEXES
element in the main resource file.
When create resource files for extra indexes, make sure to explicitly set all resources desired since some resource settings may no longer be set to the defaults due to database settings, or from a previously read resource file. Ie. MHonArc does not reset to the default settings when reading in the other resource files.
PERLINC
Each line represents a path to search when requiring MIME filters. See Specifying Filters in MIME for the use of this element.
TFOOT
Markup that appears after the thread index listing. See Listing Layout in Thread Index Customization for usage of this element.
THEAD
Markup that appears before the thread index listing. See Listing Layout in Thread Index Customization for usage of this element.
TIDXFNAME
The name of the thread index file. The default is "threads.html
".
TIMEZONES
Each line of the TIMEZONES
element defines a timezone acronym and its hour
offset from UTC/GMT (Universal Coordinate Time). The format of each line is
"timezone_acronym:
hour_offset". Examples of timezone acronyms are:
UTC
, PDT
, EST
. The hour offset is should be positive for timezones West of UTC,
and negative for time zones East of UTC.
MHonArc has a default list of timezone acronyms defined with hour offsets.
Therefore, the list given in the resource file will augment the default list, unless the
"Override
" attribute is specified. If "Override
" is specified, the default list,
along with any other lists specified in previous TIMEZONES
elements, are
discarded, and only the timezone acronyms specified in the TIMEZONES
element
will be used.
The following is the default value for TIMEZONES
:
<TIMEZONES> UTC:0 GMT:0 AST:4 ADT:3 EST:5 EDT:4 CST:6 CDT:5 MST:7 MDT:6 PST:8 PDT:7 </TIMEZONES>
Most of the time, the date used by MHonArc uses a hour offset instead of a timezone acronym. However, mail messages may contain timezone acronyms in received/sent dates and MHonArc must be told what the hour offset from UTC the timezone acronym represents in order to properly sort messages by date.
TITLE
Title for the main index page. The default is "Mail Index".
TLEVELS
The maximum number of nested lists for the thread index. The default is 3.
TLITXT
Markup for an entry in the thread index list. See Listing Layout in Thread Index Customization for usage of this element.
TOPLINKS
Markup for defining the various hyperlinks at the top of converted messages. See Navigational Links in Message Customization for usage of this element.
TTITLE
Title for the thread index page. The default is "Mail Thread Index".
UMASK
Sets the umask for the MHonArc process. The value is treated as an octal number. The resource is only applicable on Unix systems.
<!-- MHonArc resource file --> <SORT> <TITLE> MHonArc test </TITLE> <TTITLE> MHonArc test </TTITLE> <!--=== Index Page Customizations =========================================--> <!-- Have LISTBEGIN contain last updated information --> <LISTBEGIN> <address> Last updated: $LOCALDATE$<br> $NUMOFMSG$ messages in chronological order<br> </address> <ul> <li><a href="$TIDXFNAME$">Thread Index</a></li> </ul> <p> Listing format is the following: <p> <ul><li> <strong>Subject</strong> (# of follow-ups) <em>From</em><br> </ul> <p> <hr> <ul> </LISTBEGIN> <!-- A compact listing template --> <LITEMPLATE> <li> <strong>$SUBJECT:40$</strong> ($NUMFOLUP$) <em>$FROMNAME$</em><br> </LITEMPLATE> <LISTEND> </ul> <p> <hr> <strong> <a href="http://foo.org/">Home</a> </strong> <p> </LISTEND> <!--=== Thread Index Page Customizations ==================================--> <THEAD> <address> Thread index<br> Last updated: $LOCALDATE$<br> $NUMOFMSG$ messages<br> </address> <ul> <li><a href="$IDXFNAME$">Main Index</a></li> </ul> <hr> </THEAD> <!--=== Message Customizations ============================================--> <EXCS override> apparently errors-to followup forward lines message-id mime- nntp- originator path precedence received replied return-path status via x- </EXCS> <LABELSTYLES> -default- subject:strong from:strong to:strong </LABELSTYLES> <FIELDSTYLES> -default- subject:strong from:strong to:strong keywords:em newsgroups:strong </FIELDSTYLES> <MSGHEAD> <address> MHonArc test archive </address> </MSGHEAD> <MSGFOOT> <strong> <a href="http://foo.org/">Home</a> | <a href="$IDXFNAME$">Main Index</a> | <a href="$TIDXFNAME$">Thread Index</a> </strong> </MSGFOOT> <!--=== Icons =============================================================--> <ICONS> application/octet-stream:http://foo.org/icons/binary.xbm application/postscript:http://foo.org/icons/postscript.xbm audio/basic:http://foo.org/icons/sound.xbm image/gif:http://foo.org/icons/image.xbm image/jpeg:http://foo.org/icons/image.xbm image/tiff:http://foo.org/icons/image.xbm multipart/alternative:http://foo.org/icons/alternative.xbm multipart/digest:http://foo.org/icons/text.xbm multipart/mixed:http://foo.org/icons/mixed.xbm multipart/parallel:http://foo.org/icons/mixed.xbm text/richtext:http://foo.org/icons/mixed.xbm text/html:http://foo.org/icons/mixed.xbm text/plain:http://foo.org/icons/text.xbm unknown:http://foo.org/icons/unknown.doc.xbm video/mpeg:http://foo.org/icons/movie.xbm video/quicktime:http://foo.org/icons/movie.xbm </ICONS>
Elements can be duplicated. The following elements augment previous instances of themselves:
EXCS
(can specify Override
attribute)
FIELDSTYLES
ICONS
(can specify Override
attribute)
LABELSTYLES
MIMEFILTERS
(can specify Override
attribute)
PERLINC
(can specify Override
attribute)
TIMEZONES
(can specify Override
attribute)
The Override
attribute will discard previous settings of the element.
If duplicate instances of other elements exist, the last instance takes precedence.
If an element only accepts a single line of content, then the last line is used for the element's content.
If elements have conflicting resource settings (eg. NOSORT
and SORT
), the
last element defined takes precedence.
Resource file settings override environment variables.
Command-line options override any settings in the resource file.
If you want to do an exact match of a field in the EXCS
element, append a
'$
' after the field name.