[Previous][Next][Contents][FAQ][Bugs][Home]

Resource File

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.

NOTE

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.


Resource Syntax

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:

Resource Variables

Some resource element contents may contain variables. Variables get expanded to strings at run-time.

NOTE

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.

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 "$$".

SPECIAL NOTE

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:

Each resource element will define what variables are defined for it.


Resource Elements

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.

Empty Elements

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.

Non-Empty Elements

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).

NOTE

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.

CAUTION

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.

NOTE

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.


Example Resource File

<!-- 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>


Notes on Resource File


[Previous][Next][Contents][FAQ][Bugs][Home]