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. The resource file also allows you to affect MHonArc behavior that cannot be specified by environment variables, or command-line options.

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.

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 File Elements

The following list of elements contain no textual content so no end tag is required:

MBOX
Treat filename arguments as mailbox files.
MH
Treat filename arguments as MH mail folders.
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 index page.
NOSORT
List messages in the index page in the order they are processed.
REVERSE
List messages in reverse chronological order if date sorting is being done, or list messages in reverse processing order if no date sorting is being done.
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.
       
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 Settings to help you understand how the elements are used):

DBFILE
The name of the MHonArc database file. The default is ".mhonarc.db". You should not override the default name unless absolutely necessary, and you are confident about what you are doing.
DOCURL
URL to use for MHonArc documentation. The default is "http://www.oac.uci.edu/indiv/ehood/mhonarc.doc.html".
EXCS
Each line of the EXCS element specifies a mail header field to exclude in the converted HTML output. Each line is treated as a Perl regular expression (NOTE: the regular expression is already anchored to the begining of the line). MHonArc has a default list of fields to exclude from mail headers (see Example (EXCS)). 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 is discarded along with any other lists specified from previous EXCS elements; and only header fields specified in the EXCS element are excluded (see Example (EXCS 2)).

FIELDORDER
Each line of the FIELDORDER element is the exact case-insensitive name of a message header field. The order the fields are listed is the order they will appear in the filtered message. The special field value "-extra-" represents all fields not explicitly specified in the FIELDORDER element and not excluded by the EXCS element. Extra fields are listed in sorted order. See Example (FIELDORDER) for the default value of the FIELDORDER used by MHonArc.

FIELDSTYLES
Each line in the FIELDSTYLES element defines HTML elements to wrap around the field text in mail headers (e.g. "To: field text", "From: field text"). The format of each line is "field_name:html_element". This specifies to wrap html_element around the text associated with field_name. If html_element is empty, then the field text is not wrapped in any element. MHonArc defines a special field_name called "-default-". This is default HTML element to wrap field text in if no explicit specific element is defined for the label.

field_name must be the exact name of a header field name, but character case is ignored.

See Example (FIELDSTYLES) for the default formatting rules used by MHonArc.

See also LABELSTYLES.

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 the Icons section on usage of this element.
INDEXBL
The single line value of the INDEXBL element represents the label text to use for the "Index" button link at the top of filtered messages. Any HTML markup is allowed as long as it is legal within the anchor element. See Example (INDEXBL) for usage of an icon as the Index link. The default value of INDEXBL is "[Index]".

INDEXFL
The single line value of the INDEXFL element represents the text to use before the verbose name "Index" link in the footer of filtered messages. Normal text should be used for this element since the text will appear in an HTML LI element inside a UL. Unlike INDEXBL, the text is not wrapped in an anchor. The default value of INDEXFL is "Index".

IDXFNAME
The name of the index file. The default is "maillist.html".
LABELSTYLES
Each line in the LABELSTYLES element defines HTML elements to wrap around labels in mail headers (e.g. "To:", "From:"). The format of each line is "field_name:html_element". This specifies to wrap html_element around field_name. If html_element is empty, then the label is not wrapped in any element. MHonArc defines a special field_name called "-default-". This is default HTML element to wrap a label in if no explicit specific element is defined for the label.

field_name must be the exact name of a header field name, but character case is ignored.

See Example (LABELSTYLES) for the default formatting rules used by MHonArc.

See also FIELDSTYLES.

LISTBEGIN
See LISTBEGIN in Index Page Customization for usage of this element.
LITEMPLATE
See LITEMPLATE in Index Page Customization for usage of this element.
LISTEND
See LISTEND in Index Page Customization for usage of this element.
MAILTOURL
URL to use for e-mail address hyperlinks. If the URL contains the string, "$TO$", the string will be replaced with e-mail address being hyperlinked. MHonArc will use the following URL by default: mailto:$TO$

MIMEFILTERS
See MIMEFILTERS in Specifying Filters for usage of this element.
MSGSEP
Perl regular expression that represents the message separator for mailbox files. The default expression is "^From ".
NEXTBL
The single line value of the NEXTBL element represents the label text to use for the "Next" button link at the top of filtered messages. Any HTML markup is allowed as long as it is legal within the anchor element. See Example (NEXTBL) for usage of an icon for the Next link. The default value of NEXTBL is "[Next]".

NEXTFL
The single line value of the NEXTFL element represents the text to use before the verbose subject "Next" link in the footer of filtered messages. Normal text should be used for this element since the text will appear in an HTML LI element inside a UL. Unlike NEXTBL, the text is not wrapped in an anchor. The default value of NEXTFL is "Next".

PERLINC
Each line represents a path to search when requiring MIME filters. See Specifying Filters in MIME for the use of this element.
PREVBL
The single line value of the PREVBL element represents the label text to use for the "Prev" button link at the top of filtered messages. Any HTML markup is allowed as long as it is legal within the anchor element. See Example (PREVBL) for usage of an icon for the Prev link. The default value of PREVBL is "[Prev]".

PREVFL
The single line value of the PREVFL element represents the text to use before the verbose subject "Prev" link in the footer of filtered messages. Normal text should be used for this element since the text will appear in an HTML LI element inside a UL. Unlike PREVBL, the text is not wrapped in an anchor. The default value of PREVFL is "Prev".

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 (see Example (TIMEZONES)). 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.

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 index page. The default is "Mail Index".
UMASK
Sets the umask for the MHonArc process. The value is treated as an octal number.
       

Example Resource Settings

This section gives examples of how to use some of the resource file elements.

Example (DOCURL)

<!--  DOCURL element specifies the URL to use for pointing to 
      MHonArc documentation.  All whitespace is stripped out of the
      line.
  -->
<DOCURL>
http://www.oac.uci.edu/indiv/ehood/mhonarc.doc.html
</DOCURL>

Example (EXCS)

<!--  Each line in the EXCS element is treated as a Perl
      (case-insensitive) regular expression for excluding mail header
      fields from the HTML output.  All whitespace is stripped out of
      each expression.

      "Override" attribute may be specified to clear the default
      exclusion fields.

      The following list represents the default exclusions made by
      MHonArc.
  -->
<EXCS>
content- 
errors-to 
forward 
lines 
message-id 
mime- 
nntp- 
originator 
path 
precedence 
received 
replied 
return-path 
status 
via 
x- 
</EXCS>

Example (EXCS 2)

<!--  This example overrides the default exclusion fields, and requires
      that header fields must EXACTLY match what is listed inorder
      to be excluded (this is done by appending a '$' at the end
      of each field listed.
  -->
<EXCS override>
apparently-to$
apparently-from$
replied$
received$
</EXCS>

Example (FIELDORDER)

<!--  This represents the default values used by MHonarc
  -->
<FIELDORDER>
to
subject
from
date
-extra-
</FIELDORDER>

Example (FIELDSTYLES)

<!--  Each line in the FIELDSTYLES element specifies the exact
      (case-insensitive) name of a mail header field label and what HTML
      element to wrap the field text in.  The label and the element are
      separated by a colon.  Specifying no HTML element for a field will
      cause the field text to appear in regular text.
      
      The special field "-default-" can be defined to tell what fields
      are wrapped in if no explicit style is specified for the field.

      The following reflects the default formatting used by MHonArc.
  -->
<FIELDSTYLES>
-default-
</FIELDSTYLES>

Example (FIELDSTYLES 2)

<!--  Alternate formatting for field text.
  -->
<FIELDSTYLES>
-default-
subject:strong
from:strong
to:strong
keywords:em
</FIELDSTYLES>

Example (FOOTER)

<!--  FOOTER element specifies the file to include at the bottom of the
      index page.
  -->
<FOOTER>
/mnt/ehood/public_html/mail/indexfooter.html
</FOOTER>

Example (HEADER)

<!--  HEADER element specifies the file to include at the beginning of
      the index page.
  -->
<HEADER>
/mnt/ehood/public_html/mail/indexheader.html
</HEADER>

Example (IDXFNAME)

<!--  IDXFNAME element specifies the filename to give the message
      index file.
  -->
<IDXFNAME>
maillist.html
</IDXFNAME>

Example (INDEXBL)

<!--  This shows how you can use an icon for the Index link in messages
  -->
<INDEXBL>
<img src="up.gif" alt="[Index]">
</INDEXBL>

Example (LABELSTYLES)

<!--  Each line in the LABELSTYLES element specifies the exact
      (case-insensitive) name of a mail header field label and what HTML
      element to wrap it in.  The label and the element are separated by
      a colon.  Specifying no HTML element for a label will cause the
      label to appear in regular text.

      The special label "-default-" can be defined to tell what labels
      are wrapped in if no explicit style is specified 

      The following reflects the default formatting used by MHonArc.
  -->
<LABELSTYLES>
-default-:em
</LABELSTYLES>

Example (LABELSTYLES 2)

<!--  Remove the default <EM> tag used on field labels, and apply our
      format to specific labels
  -->
<LABELSTYLES>
-default-
subject:strong
from:strong
to:strong
</LABELSTYLES>

Example(MAILTOURL)

<!--  MAILTOURL element specifies the URL to use for e-mail address
      hyperlinks.  The URL can contain the string `$TO$' embedded in it.
      This will get expanded to the e-mail address the link is for.

      All whitespace is stripped out of the line.
  -->
<MAILTOURL>
mailto:$TO$
</MAILTOURL>

Example (NEXTBL)

<!--  This shows how you can use an icon for the Next link in messages
  -->
<NEXTBL>
<img src="next.gif" alt="[Next]">
</NEXTBL>

Example (PREVBL)

<!--  This shows how you can use an icon for the Prev link in messages
  -->
<PREVBL>
<img src="up.gif" alt="[Prev]">
</PREVBL>

Example (TIMEZONES)

<!--  Time zone acronym definitions.  The TIMEZONES element can be uesd
      to define time zone acronyms and their hour offset from UTC/GMT.
      The acronym and the hour offset are separated by a colon.
      Time zones West of UTC/GMT should have postive hour offsets.
      Time zones East of UTC/GMT should have negative hour offsets.
      "Override" attribute may be specified to clear the default
      time zone acronym definitions.

      The timzones below define what MHonArc recognize by default.
      All timezones are US based.
  -->
<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>

Example (TITLE)

<!--  TITLE element specifies the message index page title.
  -->
<TITLE>
HTML Mail Archive
</TITLE>

       

Notes on Resource File

       

[Prev:Command-Line Options]
[Next:Adding New Messages to an Archive]
[ToC]


MHonArc 1.0.0 -- Resource File