This sections shows how to customize the appearance of messages when converted to HTML.
MHonArc allows you to completely override the begining markup of the message
pages. 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
markup used, or have other needs that require control on the beginning markup,
you can set the MSGPGBEGIN
resource file element.
MSGPGBEGIN
The MSGPGBEGIN
resource file element has the default value:
<MSGPGBEGIN> <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> <HTML> <HEAD> <TITLE>$SUBJECTNA:72$</TITLE> <LINK REV="made" HREF="mailto:$FROMADDR$"> </HEAD> <BODY> </MSGPGBEGIN>
The following variables may be used in the MSGPGBEGIN
element:
$DATE$
-- Message date.
$DDMMYY$
-- Message date in dd/mm/yy format.
$DOCURL$
-- URL to documentation.
$FROM$
-- Contents of From field of message.
$FROMADDR$
-- E-mail address contained in From field of message.
$FROMNAME$
-- "English" name contained in From field of message.
$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.
$MMDDYY$
-- Message date in mm/dd/yy format.
$MSGID$
-- Message ID of message.
$MSGNUM$
-- Number assigned to message by MHonArc.
$NUMOFIDXMSG$
-- Number of message listed.
$NUMOFMSG$
-- Number of messages in the archive.
$OUTDIR$
-- Pathname of archive.
$PROG$
-- Program name.
$SUBJECTNA$
-- Message subject text.
$TIDXFNAME$
-- Filename of thread index page.
$TIDXTITLE$
-- Title of thread index page.
$VERSION$
-- Program version.
$YYMMDD$
-- Message date in yy/mm/dd format.
The ending markup of messages can be controlled by the MSGPGEND
resource file
element.
MSGPGEND
The MSGPGEND
resource element may be used to define the ending markup of the
message pages. The default value is the following:
<MSGPGEND> </BODY> </HTML> </MSGPGEND>
The resource variables allowed are the same as for MSGPGBEGIN
.
The MSGHEAD
resource represents HTML text that should be inserted at the very
beginning of each converted message. The MSGFOOT
resource represents HTML
text that should be appended to the end of each converted message. The default
value for both resources is empty. The following variables may be used in the
MSGHEAD
and MSGFOOT
content:
$DATE$
-- Message date.
$DDMMYY$
-- Message date in dd/mm/yy format.
$DOCURL$
-- URL to documentation.
$FROM$
-- Contents of From field of message.
$FROMADDR$
-- E-mail address contained in From field of message.
$FROMNAME$
-- "English" name contained in From field of message.
$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.
$MMDDYY$
-- Message date in mm/dd/yy format.
$MSGID$
-- Message ID of message.
$MSGNUM$
-- Number assigned to message by MHonArc.
$OUTDIR$
-- Pathname of archive.
$PROG$
-- Program name.
$SUBJECTNA$
-- Message subject text.
$TIDXFNAME$
-- Filename of thread index page.
$TIDXTITLE$
-- Title of thread index page.
$VERSION$
-- Program version.
$YYMMDD$
-- Message date in yy/mm/dd format.
MHonArc gives you the ability to control the layout of the navigational links for
each message page. Navigational links include links to previous and next
messages, link to main index, link to thread index, etc. The layout of the
navigational links are controlled by two resource file elements: TOPLINKS
and
BOTLINKS.
TOPLINKS
The TOPLINKS
resource element defines the layout of the navigational links at the
top of each message page. The markup defined, will appear after the MSGHEAD
data and before the filtered message data.
The default value for TOPLINKS
is the following:
<TOPLINKS> <HR> $PREVBUTTON$$NEXTBUTTON$<A HREF="$IDXFNAME$#$MSGNUM$">[Index]</A><A HREF="$TIDXFNAME$#$MSGNUM$">[Thread]</A> </TOPLINKS>
If no thread index is specified, then the thread link markup is removed. The following variables are available:
$DATE$
-- Message date.
$DDMMYY$
-- Message date in dd/mm/yy format.
$DOCURL$
-- URL to documentation.
$FROM$
-- Contents of From field of message.
$FROMADDR$
-- E-mail address contained in From field of message.
$FROMNAME$
-- "English" name contained in From field of message.
$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.
$MMDDYY$
-- Message date in mm/dd/yy format.
$MSGID$
-- Message ID of message.
$MSGNUM$
-- Number assigned to message by MHonArc.
$NEXTBUTTON$
-- Next button markup. See Conditional Links for more
information.
$NEXTFROM$
-- Contenst of From field of the next message according to
the list order of the main index.
$NEXTFROMADDR$
-- E-mail address contained in From field of the next
message according to the list order of the main index.
$NEXTFROMNAME$
-- English" name contained in From field of the next
message according to the list order of the main index.
$NEXTLINK$
-- Next link markup. See Conditional Links for more
information.
$NEXTMSG$
-- Filename of next message according to the list order of the
main index.
$NEXTMSGNUM$
-- Number assigned to next message according to the list
order of the main index.
$NEXTSUBJECT$
-- Subject of next message according to the list order of
the main index.
$NUMOFIDXMSG$
-- Number of message listed.
$NUMOFMSG$
-- Number of messages in the archive.
$PREVBUTTON$
-- Previous button markup. See Conditional Links for
more information.
$PREVFROM$
-- Contenst of From field of the previous message according
to the list order of the main index.
$PREVFROMADDR$
-- E-mail address contained in From field of the
previous message according to the list order of the main index.
$PREVFROMNAME$
-- English" name contained in From field of the
previous message according to the list order of the main index.
$PREVLINK$
-- Previous link markup. See Conditional Links for more
information.
$PREVMSG$
-- Filename of previous message according to the list order of
the main index.
$PREVMSGNUM$
-- Number assigned to previous message according to the
list order of the main index.
$PREVSUBJECT$
-- Subject of previous message according to the list order
of the main index.
$PROG$
-- Program name.
$SUBJECTNA$
-- Message subject text.
$TIDXFNAME$
-- Filename of thread index page.
$TIDXTITLE$
-- Title of thread index page.
$VERSION$
-- Program version.
$YYMMDD$
-- Message date in yy/mm/dd format.
BOTLINKS
The BOTLINKS
resource element defines the layout of the navigational links at the
bottom of each message page. The markup defined, will appear after the filtered
message data and any thread links, and before the MSGFOOT
data.
The default value for BOTLINKS
is the following:
<BOTLINKS> <HR> <UL> $PREVLINK$ $NEXTLINK$ <LI>Index(es): <UL> <LI><A HREF="$IDXFNAME$#$MSGNUM$"><STRONG>Main</STRONG></A></LI> <LI><A HREF="$TIDXFNAME$#$MSGNUM$"><STRONG>Thread</STRONG></A></LI> </BOTLINKS>
If no thread index is specified, then the thread link markup is removed. The
variables available for BOTLINKS
are the same as for TOPLINKS
.
Since the state of some navigational links can change due the position of the message in the archive (eg. first and last messages), special resources exist that allows you to control the markup of some of the links based upon if the link is valid or not for a given message.
The resource elements for defining the conditional links are the following:
PREVBUTTON
, NEXTBUTTON
, PREVLINK
, and NEXTLINK
, and their inactive
counterparts, PREVBUTTONIA
, NEXTBUTTONIA
, PREVLINKIA
, and NEXTLINKIA
.
The appropriate value of these elements (ie. if it is active, or inactive) are
represented by the $PREVBUTTON$
, $NEXTBUTTON$
, $PREVLINK$
, and
$NEXTLINK$
resource file variables, respectively, which may be used in other
resource elements' contents (TOPLINKS
and BOTLINKS
in particular).
The defaults values for each conditional link resource is as follows:
PREVBUTTON
<PREVBUTTON> <A HREF="$PREVMSG$">[Prev]</A> </PREVBUTTON>
NEXTBUTTON
<NEXTBUTTON> <A HREF="$NEXTMSG$">[Next]</A> </NEXTBUTTON>
PREVLINK
<PREVLINK> <LI>Prev: <STRONG><A HREF="$PREVMSG$">$PREVSUBJECT$</A></STRONG></LI> </PREVLINK>
NEXTLINK
<NEXTLINK> <LI>Next: <STRONG><A HREF="$NEXTMSG$">$NEXTSUBJECT$</A></STRONG></LI> </NEXTLINK>
All the "IA
" elements default to empty content.
The last newline for the PREVBUTTON
, NEXTBUTTON
, PREVBUTTONIA
,
and NEXTBUTTONIA
elements is ignored by MHonArc. This allows a
"tight" grouping of button links; ie. no space between buttons. If you
desire to have a newline in the content, just insert a trailing blank line at
the end of the element's content.
You should note that there is a correlation between the value of the conditional
links elements and the contents of the TOPLINKS
and BOTLINKS
elements.
The following variables may be used within the conditional link elements.
$NEXTFROM$
-- Contenst of From field of the next message according to
the list order of the main index.
$NEXTFROMADDR$
-- E-mail address contained in From field of the next
message according to the list order of the main index.
$NEXTFROMNAME$
-- English" name contained in From field of the next
message according to the list order of the main index.
$NEXTMSG$
-- Filename of next message according to the list order of the
main index.
$NEXTMSGNUM$
-- Number assigned to next message according to the list
order of the main index.
$NEXTSUBJECT$
-- Subject of next message according to the list order of
the main index.
$PREVFROM$
-- Contenst of From field of the previous message according
to the list order of the main index.
$PREVFROMADDR$
-- E-mail address contained in From field of the
previous message according to the list order of the main index.
$PREVFROMNAME$
-- English" name contained in From field of the
previous message according to the list order of the main index.
$PREVMSG$
-- Filename of previous message according to the list order of
the main index.
$PREVMSGNUM$
-- Number assigned to previous message according to the
list order of the main index.
$PREVSUBJECT$
-- Subject of previous message according to the list order
of the main index.
Never include conditional link variables ($PREVBUTTON$
,
$NEXTBUTTON$
, $PREVLINK$
, and $NEXTLINK$
) in conditional link
element content. This will cause an infinite loop during execution and will
eventually lead to a crash due to a lack of memory.
Defining the format for the actual mail message data is divided into two parts: the message head and the message body. Customizing the message header markup is described in this section, but due to the nature of how messages are processed, the message body format is controlled by the various MIME filters directly (see the section on MIME for further details).
The EXCS
resource allows you to specify what fields should be excluded in the
HTML output.
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).
The default value for EXCS
is the following:
<EXCS> content- errors-to forward lines message-id mime- nntp- originator path precedence received replied return-path status via x- </EXCS>
Any fields you specify for the EXCS
resource 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.
The FIELDORDER
resource allows you to control the order the message header
fields appear in the HTML output.
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.
The following represents the default value of the FIELDORDER
resource:
<FIELDORDER> to subject from date -extra- </FIELDORDER>
The FIELDSTYLES
and LABELSTYLES
resources allow to control how each
message header field is formatted.
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.
The default value of FIELDSTYLES
is the following:
<FIELDSTYLES> -default- </FIELDSTYLES>
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.
The default value of LABELSTYLES
is the following:
<LABELSTYLES> -default-:em </LABELSTYLES>
URL to use for e-mail address hyperlinks in e-mail message header fields. The
following variables are defined for the MAILTOURL
resource:
$FROM$
-- Who the message is from.
$MSGID$
-- Message ID of the message.
$SUBJECT$
-- The subject of the message.
$TO$
-- Destination e-mail address of link.
MHonArc will use the following URL by default: "mailto:$TO$"
.
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.