From 0a546e35a18999d10077b79240c7c675121af5be Mon Sep 17 00:00:00 2001 From: Earl Hood Date: Fri, 12 Jul 1996 17:46:27 -0500 Subject: [PATCH] MHonArc 1.2.3: (https://www.mhonarc.org/release/MHonArc/tar/MHonArc1.2.3.tar.gz) o Extracted initialization of data structures into mhinit.pl. The file is just required from the main source. o Use q{} instead of qq{} when trying to read database file. Should fix require problem under MS-DOS. o Added comments at beginning of messages. May aid in database recovery techniques. o ';'s are now deleted in filenames in mhexternal.pl (applicable only when "usename" option specified) o Added recognition of '/' when converted e-mail addresses to mailto links in message headers. o Simple fix to mhtxt2022.pl for execution under Perl 5. --- ACKNOWLEDGEMENTS | 39 - ACKNOWLG | 46 + CHANGES | 477 +- README | 160 +- RELEASE_NOTES => RELNOTES | 88 +- bat/README | 19 + bat/mhonarc.bat | 2 + doc/Makefile | 41 +- doc/adding.html | 138 + doc/contacts.html | 68 + doc/details.html | 185 + doc/diagnos.html | 231 + doc/glossary.html | 48 + doc/indexpg.html | 422 ++ doc/install.html | 381 ++ doc/intro.html | 77 + doc/message.html | 510 +++ doc/mhonarc.1 | 3787 ++++++++++++++++ doc/mhonarc.doc.html | 122 - doc/mhonarc.html | 160 + doc/mhonarc.ps | Bin 0 -> 390942 bytes doc/mhonarc.txt | 5021 +++++++++++++-------- doc/mhonarc_adding.doc.html | 196 - doc/mhonarc_clopts.doc.html | 218 - doc/mhonarc_diagnostics.doc.html | 316 -- doc/mhonarc_env.doc.html | 105 - doc/mhonarc_icons.doc.html | 115 - doc/mhonarc_indexpg.doc.html | 387 -- doc/mhonarc_integrity.doc.html | 49 - doc/mhonarc_intro.doc.html | 79 - doc/mhonarc_mime.doc.html | 507 --- doc/mhonarc_notes.doc.html | 57 - doc/mhonarc_qstart.doc.html | 157 - doc/mhonarc_rcfile.doc.html | 664 --- doc/mhonarc_tips.doc.html | 64 - doc/mime.html | 597 +++ doc/mktxt | 27 + doc/overview.html | 529 +++ doc/qstart.html | 192 + doc/rcfile.html | 648 +++ doc/removing.html | 112 + doc/{mhonarc_stamp_t.gif => stamp_t.gif} | Bin doc/thread.html | 225 + examples/deffilters.rc | 2 + examples/{icons.mhrc => icons.rc} | 12 - extras/HtmlMail | 124 + extras/MosaicMail | 148 + extras/README | 18 + icons/DocsLeftArrow.gif | Bin 1289 -> 0 bytes icons/DocsRightArrow.gif | Bin 1273 -> 0 bytes icons/DocsUpArrow.gif | Bin 1292 -> 0 bytes icons/README | 2 - icons/SearchIcon.gif | Bin 279 -> 0 bytes icons/arrow_right.gif | Bin 984 -> 0 bytes icons/back.gif | Bin 279 -> 0 bytes icons/back2.gif | Bin 216 -> 0 bytes icons/binary.gif | Bin 332 -> 0 bytes icons/blueball.gif | Bin 326 -> 0 bytes icons/forward2.gif | Bin 217 -> 0 bytes icons/gaudio.gif | Bin 200 -> 0 bytes icons/gbook.gif | Bin 222 -> 0 bytes icons/gdoc.gif | Bin 184 -> 0 bytes icons/gdoc2.gif | Bin 240 -> 0 bytes icons/gdoc3.gif | Bin 214 -> 0 bytes icons/gdoc4.gif | Bin 212 -> 0 bytes icons/ggraphic.gif | Bin 259 -> 0 bytes icons/ggraphic2.gif | Bin 265 -> 0 bytes icons/ggraphic3.gif | Bin 268 -> 0 bytes icons/gimage.gif | Bin 244 -> 0 bytes icons/gimage2.gif | Bin 279 -> 0 bytes icons/gimage3.gif | Bin 222 -> 0 bytes icons/gletter.gif | Bin 169 -> 0 bytes icons/gmovie.gif | Bin 239 -> 0 bytes icons/gmulti.gif | Bin 196 -> 0 bytes icons/go_next_btn_s.gif | Bin 141 -> 0 bytes icons/go_prev_btn_s.gif | Bin 144 -> 0 bytes icons/go_up_btn.gif | Bin 264 -> 0 bytes icons/go_up_btn_s.gif | Bin 145 -> 0 bytes icons/gsound.gif | Bin 182 -> 0 bytes icons/gtext.gif | Bin 212 -> 0 bytes icons/gtext2.gif | Bin 200 -> 0 bytes icons/gunknown.gif | Bin 185 -> 0 bytes icons/home_btn.gif | Bin 267 -> 0 bytes icons/home_btn_s.gif | Bin 139 -> 0 bytes icons/html.gif | Bin 352 -> 0 bytes icons/image.gif | Bin 357 -> 0 bytes icons/index.gif | Bin 325 -> 0 bytes icons/kevinh/README | 19 - icons/kevinh/binary.xbm | 9 - icons/kevinh/binhex.xbm | 9 - icons/kevinh/compressed.xbm | 9 - icons/kevinh/directory.xbm | 9 - icons/kevinh/ftp.xbm | 9 - icons/kevinh/image.xbm | 9 - icons/kevinh/index.xbm | 9 - icons/kevinh/index2.xbm | 9 - icons/kevinh/movie.xbm | 9 - icons/kevinh/sound.xbm | 9 - icons/kevinh/tar.xbm | 9 - icons/kevinh/telnet.xbm | 9 - icons/kevinh/text.xbm | 9 - icons/kevinh/unknown.doc.xbm | 9 - icons/kevinh/uu.xbm | 9 - icons/la.gif | Bin 1167 -> 0 bytes icons/mailbutton.gif | Bin 1202 -> 0 bytes icons/menu.gif | Bin 408 -> 0 bytes icons/more_btn.gif | Bin 275 -> 0 bytes icons/movie.gif | Bin 321 -> 0 bytes icons/ra.gif | Bin 1166 -> 0 bytes icons/scrollbutton.gif | Bin 1187 -> 0 bytes icons/sound.gif | Bin 364 -> 0 bytes icons/soundbutton.gif | Bin 1343 -> 0 bytes icons/text.gif | Bin 322 -> 0 bytes icons/ua.gif | Bin 1159 -> 0 bytes icons/unknown.gif | Bin 269 -> 0 bytes icons/up2.gif | Bin 231 -> 0 bytes icons/usenet.gif | Bin 342 -> 0 bytes icons/wp_btn.gif | Bin 305 -> 0 bytes install.cfg | 68 + install.me | 226 +- lib/base64.pl | 46 +- lib/mhdb.pl | 163 + lib/mhexternal.pl | 123 +- lib/mhinit.pl | 292 ++ lib/mhtxt2022.pl | 159 + lib/mhtxthtml.pl | 64 +- lib/mhtxtplain.pl | 45 +- lib/mhtxtsetext.pl | 6 +- lib/mhutil.pl | 813 ++++ lib/osinit.pl | 83 + lib/qprint.pl | 31 +- lib/readmail.pl | 468 ++ logo/{mhonarc_s.gif => small.gif} | Bin logo/{mhonarc_st.gif => small_t.gif} | Bin logo/{mhonarc_stamp.gif => stamp.gif} | Bin logo/{mhonarc_stamp_t.gif => stamp_t.gif} | Bin mail2html | 1 - mbox2html | 1 - mhf2html | 1 - mhonarc | 3113 ++++++------- 140 files changed, 16480 insertions(+), 6949 deletions(-) delete mode 100644 ACKNOWLEDGEMENTS create mode 100644 ACKNOWLG rename RELEASE_NOTES => RELNOTES (59%) create mode 100644 bat/README create mode 100644 bat/mhonarc.bat create mode 100644 doc/adding.html create mode 100644 doc/contacts.html create mode 100644 doc/details.html create mode 100644 doc/diagnos.html create mode 100644 doc/glossary.html create mode 100644 doc/indexpg.html create mode 100644 doc/install.html create mode 100644 doc/intro.html create mode 100644 doc/message.html create mode 100644 doc/mhonarc.1 delete mode 100644 doc/mhonarc.doc.html create mode 100644 doc/mhonarc.html create mode 100644 doc/mhonarc.ps delete mode 100644 doc/mhonarc_adding.doc.html delete mode 100644 doc/mhonarc_clopts.doc.html delete mode 100644 doc/mhonarc_diagnostics.doc.html delete mode 100644 doc/mhonarc_env.doc.html delete mode 100644 doc/mhonarc_icons.doc.html delete mode 100644 doc/mhonarc_indexpg.doc.html delete mode 100644 doc/mhonarc_integrity.doc.html delete mode 100644 doc/mhonarc_intro.doc.html delete mode 100644 doc/mhonarc_mime.doc.html delete mode 100644 doc/mhonarc_notes.doc.html delete mode 100644 doc/mhonarc_qstart.doc.html delete mode 100644 doc/mhonarc_rcfile.doc.html delete mode 100644 doc/mhonarc_tips.doc.html create mode 100644 doc/mime.html create mode 100755 doc/mktxt create mode 100644 doc/overview.html create mode 100644 doc/qstart.html create mode 100644 doc/rcfile.html create mode 100644 doc/removing.html rename doc/{mhonarc_stamp_t.gif => stamp_t.gif} (100%) create mode 100644 doc/thread.html rename examples/{icons.mhrc => icons.rc} (82%) create mode 100755 extras/HtmlMail create mode 100755 extras/MosaicMail create mode 100644 extras/README delete mode 100644 icons/DocsLeftArrow.gif delete mode 100644 icons/DocsRightArrow.gif delete mode 100644 icons/DocsUpArrow.gif delete mode 100644 icons/README delete mode 100644 icons/SearchIcon.gif delete mode 100644 icons/arrow_right.gif delete mode 100644 icons/back.gif delete mode 100644 icons/back2.gif delete mode 100644 icons/binary.gif delete mode 100644 icons/blueball.gif delete mode 100644 icons/forward2.gif delete mode 100644 icons/gaudio.gif delete mode 100644 icons/gbook.gif delete mode 100644 icons/gdoc.gif delete mode 100644 icons/gdoc2.gif delete mode 100644 icons/gdoc3.gif delete mode 100644 icons/gdoc4.gif delete mode 100644 icons/ggraphic.gif delete mode 100644 icons/ggraphic2.gif delete mode 100644 icons/ggraphic3.gif delete mode 100644 icons/gimage.gif delete mode 100644 icons/gimage2.gif delete mode 100644 icons/gimage3.gif delete mode 100644 icons/gletter.gif delete mode 100644 icons/gmovie.gif delete mode 100644 icons/gmulti.gif delete mode 100644 icons/go_next_btn_s.gif delete mode 100644 icons/go_prev_btn_s.gif delete mode 100644 icons/go_up_btn.gif delete mode 100644 icons/go_up_btn_s.gif delete mode 100644 icons/gsound.gif delete mode 100644 icons/gtext.gif delete mode 100644 icons/gtext2.gif delete mode 100644 icons/gunknown.gif delete mode 100644 icons/home_btn.gif delete mode 100644 icons/home_btn_s.gif delete mode 100644 icons/html.gif delete mode 100644 icons/image.gif delete mode 100644 icons/index.gif delete mode 100644 icons/kevinh/README delete mode 100644 icons/kevinh/binary.xbm delete mode 100644 icons/kevinh/binhex.xbm delete mode 100644 icons/kevinh/compressed.xbm delete mode 100644 icons/kevinh/directory.xbm delete mode 100644 icons/kevinh/ftp.xbm delete mode 100644 icons/kevinh/image.xbm delete mode 100644 icons/kevinh/index.xbm delete mode 100644 icons/kevinh/index2.xbm delete mode 100644 icons/kevinh/movie.xbm delete mode 100644 icons/kevinh/sound.xbm delete mode 100644 icons/kevinh/tar.xbm delete mode 100644 icons/kevinh/telnet.xbm delete mode 100644 icons/kevinh/text.xbm delete mode 100644 icons/kevinh/unknown.doc.xbm delete mode 100644 icons/kevinh/uu.xbm delete mode 100644 icons/la.gif delete mode 100644 icons/mailbutton.gif delete mode 100644 icons/menu.gif delete mode 100644 icons/more_btn.gif delete mode 100644 icons/movie.gif delete mode 100644 icons/ra.gif delete mode 100644 icons/scrollbutton.gif delete mode 100644 icons/sound.gif delete mode 100644 icons/soundbutton.gif delete mode 100644 icons/text.gif delete mode 100644 icons/ua.gif delete mode 100644 icons/unknown.gif delete mode 100644 icons/up2.gif delete mode 100644 icons/usenet.gif delete mode 100644 icons/wp_btn.gif create mode 100644 install.cfg create mode 100644 lib/mhdb.pl create mode 100644 lib/mhinit.pl create mode 100644 lib/mhtxt2022.pl create mode 100644 lib/mhutil.pl create mode 100644 lib/osinit.pl create mode 100644 lib/readmail.pl rename logo/{mhonarc_s.gif => small.gif} (100%) rename logo/{mhonarc_st.gif => small_t.gif} (100%) rename logo/{mhonarc_stamp.gif => stamp.gif} (100%) rename logo/{mhonarc_stamp_t.gif => stamp_t.gif} (100%) delete mode 120000 mail2html delete mode 120000 mbox2html delete mode 120000 mhf2html diff --git a/ACKNOWLEDGEMENTS b/ACKNOWLEDGEMENTS deleted file mode 100644 index 595b3bc..0000000 --- a/ACKNOWLEDGEMENTS +++ /dev/null @@ -1,39 +0,0 @@ -ACKNOWLEDGEMENTS for MHonArc - ---------------------------------------------------------------------------- -Special thangs go to: - - A. P. Barrett - For developing a base64 library. The library is used to decode - base64 messages by MHonArc. - - Susie Blackstock - For helping me with the documentation. - - Timothy Finin - Whose initial feedback on mbox2html (my first mail->HTML - program) caused the ball rolling on developing a more complete - mail-to-HTML program. - - Ken Harward - For helping me tackle Perl problems and for bouncing ideas - off. - ---------------------------------------------------------------------------- -I'd like to Thank the following people for finding bugs/giving -comments/whatever that effected the functionality of MHonArc (mail2html): - - Daniel L Smith - Daniel R. Kegel - Jaak Vilo - James Everett Ward - Robert M Walker - Tessa Lau - Walt Hobbs - -Sorry for those I left out unintentionally. - -And thanks to Larry Wall for inventing Perl :-) - ---------------------------------------------------------------------------- -Earl Hood, ehood@convex.com diff --git a/ACKNOWLG b/ACKNOWLG new file mode 100644 index 0000000..f21eaf0 --- /dev/null +++ b/ACKNOWLG @@ -0,0 +1,46 @@ +ACKNOWLEDGEMENTS for MHonArc + + + +I would like to thank everyone who has given feedback on MHonArc. +Sorry for not listing everyone, but it has become too hard to keep +track of all the names. However, I'd like to give special thanks to +the following: + + A. P. Barrett + For developing a base64 library. The library has been adapted + to decode base64 messages by MHonArc. + + Susie Blackstock + For helping me with the documentation. Any problems with the + documentation is purely my fault. + + Achim Bohnet + For his help in testing, and contributing to, mhonarc and for + setting up the mhonarc mailing list. + + Roman Czyborra + For his help with the MosaicMail script. + + Timothy Finin + Whose initial feedback on mbox2html (my first mail->HTML + program) caused the ball rolling on developing a more complete + mail-to-HTML program. + + Ken Harward + For helping me tackle Perl problems and for bouncing ideas + off. + + Phyllis Imperatrice + For the initial sketch of the MHonArc logo. + + Steve Pacenka + For his great help in getting MHonArc to run under MS-DOS, and + for his help in trouble-shooting. + + NIIBE Yutaka + For the contribution of a text/plain filter to process + ISO-2022 encoded mail messages (ie. Japanese character set). + +--------------------------------------------------------------------------- +Earl Hood, ehood@isogen.com diff --git a/CHANGES b/CHANGES index d7793d2..417e31a 100644 --- a/CHANGES +++ b/CHANGES @@ -1,18 +1,477 @@ CHANGES for MHonArc -Revision history for MHonArc. + + +Revision history for MHonArc. Changes listed are brief. Consult +the documentation for further information/clarification. MM/DD/YY -=========================================================================== -########################################################################### -=========================================================================== +======================================================================= +####################################################################### +======================================================================= +07/12/96 (1.2.3) + + o Extracted initialization of data structures into mhinit.pl. + The file is just required from the main source. + + o Use q{} instead of qq{} when trying to read database file. + Should fix require problem under MS-DOS. + + o Added comments at beginning + of messages. May aid in database recovery techniques. + + o ';'s are now deleted in filenames in mhexternal.pl + (applicable only when "usename" option specified) + + o Added recognition of '/' when converted e-mail addresses + to mailto links in message headers. + + o Simple fix to mhtxt2022.pl for execution under Perl 5. + +======================================================================= +####################################################################### +======================================================================= +04/18/96 (1.2.2) + + o Increased the speed performance of base64 decoding. Speed + increase is much greater under Perl 4 than Perl 5. + + o Added -time option to print out total CPU execution time. + Mainly used for debugging reasons (like checking on + base64 decoding times). Time information is sent to + standard error. + + o Added M2H_LOCKDELAY envariable and -lockdelay option. + Either can be used to adjust the sleep time between + attempts to lock the archive. + + o Added -force option to override a lock on an archive if + attempts to lock fail. + + o Added image/x-bmp and image/x-pcx to the default supported + MIME types. + + o Ignore "Sv:" at the beginning of subjects when sorting by + subject. "Sv:" is Danish for "Re:". + + o Fixed bug in mhutil.pl where TIDXPGEND actually set + TIDXPGBEG. + + o Dynamically define exclude_field routine after reading + user options. exclude_field is utilized when formatting + a message header in HTML. Defining the routine at run-time + helps reduce the regular expression overhead the old version + of the routine entailed. There should be an increase in + overall execution time. + +======================================================================= +03/22/96 (1.2.1) + + o Added support for x-uuencode content-transfer-encoding. + + o Added -locktries command-line option. + + o Added the resource variable $OUTDIR$. + + o mhexternal.pl filter will use the name parameter string + on the content-type field as the anchor text to the file + if there is no content-description. + + o application/x-patch is recognized and processed by the + text/plain filter (mhtxtplain.pl). + + o Fixed bug in install.me and osinit.pl where setting + $'PROG caused perl to terminate if $'DIRSEP was a backslash + (occured under MS-DOS usage). + + o Fixed bug in install.me in the create_dir routine. + If $DIRSEP was a backslash, the regular expression setting + @a would cause perl to abort with an error. + + o Fixed database bug where the MIMEARGS resource setting + was not being stored. + + o Fixed index listing bug where a reverse listing was not + correct if an index size was specified less than the + current size of the archive. + +======================================================================= +03/01/96 (1.2.0) + + o Rewrote message parser routine so it will work under Perl 5 + for multipart messages. The rewrite also allows some + additional features that are mentioned below. + + o The -mbox and -mh options are no longer required. MHonArc + will automatically determine which mode to operate in + based upon the file arguments. Hence, one can specify + MH folders and mailbox files on the same command-line. + Both options are ignored if specified. + + o An HTML index of an archive contents can be generated to + standard output (-genidx). + + o Message header lines not conforming to RFC 822 are ignored. + (Eg: Those pesky "From " lines should not show up anymore -- + please do not confuse this with the regular "From:" lines; + note the colon vs the space). + + o New resources: + + BOTLINKS - May be used to completely customize + the links at the bottom of messages. + IDXPGBEGIN - Opening markup for main index page. + Allows one to redefine opening HTML + element, HEAD element, TITLE element, + opening BODY element, etc. + IDXPGEND - Closing markup for main index page. + IDXSIZE - Set the maximum number of messages + listed in index. This is different + in MAXSIZE where MAXSIZE will remove + older messages when the MAXSIZE limit + is reached in the archive. + MIMEARGS - Define arguments to filters + MSGPGBEGIN - Opening markup for message pages. + Allows one to redefine opening HTML + element, HEAD element, TITLE element, + opening BODY element, etc. + MSGPGEND - Closing markup for message pages. + NEXTBUTTON - Defines the 'Next' button. + NEXTBUTTONIA - Defines the 'Next' button when it is + inactive. + NEXTLINK - Defines the 'Next' link. + NEXTLINKIA - Defines the 'Next' link when it is + inactive. + NOTSUBSORT - Do not sort threads by subject. + OTHERINDEXES - List other resource files defining + other indexes to create when creating, + or updating, an archive. + PREVBUTTON - Defines the 'Prev' button. + PREVBUTTONIA - Defines the 'Prev' button when it is + inactive. + PREVLINK - Defines the 'Prev' link. + PREVLINKIA - Defines the 'Prev' link when it is + inactive. + TIDXPGBEGIN - Opening markup for thread index page. + Allows one to redefine opening HTML + element, HEAD element, TITLE element, + opening BODY element, etc. + TIDXPGEND - Closing markup for thread index page. + TOPLINKS - May be used to completely customize + the buttons at the top of messages. + TSUBSORT - Sort threads listed by subject. + + o Removed resources: + + INDEXBL, INDEXFL, MBOX, MH, NEXTBL, NEXTFL, PREVBL, + PREVFL, TINDEXBL, TINDEXFL + + Resource were removed because they were no longer applicable + and/or have been superceded by other resources. MHonArc + will still honor old resource settings (where applicable) of + older archives and incorporate them into the new resource + settings. + + o When specifying the resource file, mhonarc will now do + the following to determine its location: + + 1. If its an absolute pathname, mhonarc uses it. + 2. If it is a relative pathname, mhonarc checks for + it relative to the current working directory. + 3. Otherwise, mhonarc checks for it relative to + location of the archive as specified by outdir. + + This resolution will allow you to place resource files with + the archive if desired (can be useful when using the + OTHERINDEXES resource element). + + o Because of the new resources available, many
's are no + longer hard-coded and are controllable by resources.
's + are still used in message pages to separate message data + from mhonarc data. + + o Added resource variables: + (NOTE: Some variables are only valid in certain contexts) + + $DDMMYY$ - Date of message in dd/mm/yy format + $IDXSIZE$ - Max size of index list + $MMDDYY$ - Date of message in mm/dd/yy format + $MSGID$ - Message id + $NEXTBUTTON$ - Next button markup + $NEXTFROM$ - From field of next listed message + $NEXTFROMADDR$ - From e-mail address of next listed message + $NEXTFROMNAME$ - From name of next listed message + $NEXTLINK$ - Next link markup + $NEXTMSGNUM$ - Number of next listed message + $NEXTSUBJECT$ - Subject text of next listed message + $NUMOFIDXMSG$ - Number of messages in index list + $PREVBUTTON$ - Previous button markup + $PREVFROM$ - From field of previous listed message + $PREVFROMADDR$ - From e-mail address of prev listed message + $PREVFROMNAME$ - From name of previous listed message + $PREVLINK$ - Previous link markup + $PREVMSGNUM$ - Number of previous message + $PREVSUBJECT$ - Subject text of previous listed message + $YYMMDD$ - Date of message in yy/mm/dd format + + o Can specify a 'U' with variable length specifier to denote + replacement string is to be used in a URL. Examples: + + $SUBJECTNA:40U$ + $MSGID:U$ + + The 'U' causes the replace text to have special characters + escaped as denoted by the URL spec. NOTE: Specify ":U" + should NOT be used in the MAILTOURL resource; the variables + will automatically be expanded according to the URL spec. + Specifyind ":U" or a length specifier in the MAILTOURL + resource will prevent mhonarc from detecting the variable. + + o New command-line options: + + -genidx - Generate HTML index of archive contents + to stdout. + -idxsize - Maximum number of messages shown in indexes + -notsubsort - Do not sort threads listed by subject. + -savemem - Write message data while processing + -tsubsort - Sort threads listed by subject. + + o The library mhtxt2022.pl has been added that provides + a filter to process ISO-2022 (Japanese) encoded mail messages. + See mhtxt2022.pl on how to hook it in. + + o The mhexternal.pl filter by default ignores any filename + specification in the message for creating derived files. + This avoids name conflicts and security problems. + The "usename" filter option may be used to override this. + + o Mime filters are now called with two additional arguments: + + $converted_data = &function( + $header, *parsed_header_assoc_array, + *message_data, $decoded_flag, + $optional_filter_arguments); + + The $decoded_flag is set to 1 if the *message_data has been + decoded. $optional_filter_arguments contains an optional + argument string as determined by the filter. + + o Mime filters can now be registered for multipart types + and message types. This allows one to override mhonarc's + conversion of these types, and completely replace mhonarc's + message->HTML conversion process. + + o Mime filters should now use $'FieldSep instead of $'X for + accessing parsed message headers. + + o Mime filters can be registered for a base type. Ie. + It is no longer required to explicitly list each possible + subtype if a single filter is to be used for them all. + Example: + + + image/*:myfilter'imagefilter:myfilter.pl + + + Registers "myfilter'filter" for all image data types, + regardless of subtype. However, if an explicit entry + exists for a subtype, then that filter is called. + Example: + + + image/*:myfilter'imagefilter:myfilter.pl + image/gif:myfilter'giffilter:myfilter.pl + + + "myfilter'giffilter" is called for all image/gif data. + "myfilter'imagefilter" is called for all other image data. + + o A new resource, MIMEARGS, may be used to pass optional arguments + to filters to control their behavior. The format of the + argument string is controlled by the various filters. The + arguments can be specified by a specific content-type, or + for the filter routine in general. A content-type argument + will be used over any arguments specified for a filter. + + Example usage: + + + image/gif:inline usename + m2h_external'filter:usename + + + See the documentation for possible arguments to filters. + + o Installation program can now be invoked in batch mode. + + o Thread index properly includes docurl as main index. + -nodocurl will prevent the inclusion as with the main index. + + o Fixed bug in mhtxthtml.pl on properly propogating a base + URL to relative URLs starting with a "/". + + o Fixed bug where single quotes, and backslashed in keys of + associative arrays in the database file were not getting + escaped. + + o Fixed bug where spaces and special characters were not + properly escaped in URL strings: spaces were left as-is, + and special characters were deleted. + + o Removed illegal invocation choices in the Synopsis of the + documentation. + +======================================================================= +04/24/95 (1.1.1) + + o Fixed bug in -scan output where month in date was off by + one. + +======================================================================= +04/21/95 (1.1.0) + + o Made modifications to make MHonArc suitable to run + under MS-DOS without modification. MHonArc will + automatically detect if it is running under Unix or MS-DOS. + + o Added support for a thread index. MHonArc will create a + complimentary index to the main index showing message + threads. + + o Archive messages can be deleted. + + o A listing to stdout of an archives contents can be + generated. + + o Maximum number of messages for an archive can be set. + Older messages (based on sort method) are removed + automatically during add operations. + + o MHonArc will now recognize if you try to add in a message + that already exists in an archive. + + o The -editdx option will now also cause a updating of all + mail messages. Guarantees resource changes to affect all + messages. + + o Added the following resource file elements: + + MSGFOOT -- Footer text for converted messages + MSGHEAD -- Header text for converted messages + NODOC -- Do not put link to documentation + NOTHREAD -- Do not create thread index + TFOOT -- Text at bottom of thread index page + THEAD -- Text at top of thread index page + THREAD -- Create thread index + TLEVELS -- Depth of thread listing + TLITXT -- Template text for entry in thread + index + TIDXFNAME -- Thread index filename + TINDEXBL -- Top button label in messages to + thread index + TINDEXFL -- Verbose label in message to thread + index + TTITLE -- Title of thread index page + + o Added the following command-line options: + + -maxsize -- Maxinum # messages in an archive + -nodoc -- Do not put link to documentation + -nothread -- Do not create thread index + -rmm -- Remove messages from an archive + -scan -- Listing of archive to stdout + -thread -- Create thread index + -tidxfname -- Thread index filename + -tlevels -- Depth of thread listing + -ttitle -- Title of thread index page + + o Added the following environment variables: + + M2H_MAXSIZE -- Maxinum # messages in an archive + M2H_THREAD -- If non-zero, create thread index + M2H_TIDXFNAME -- Thread index filename + M2H_TLEVELS -- Depth of thread listing + M2H_TTITLE -- Title of thread index page + + o Added the following variables for template resources + (applicability of variables vary depending on the resource): + + $DOCURL$ -- URL to documentation + $IDXFNAME$ -- Main index page filename + $IDXTITLE$ -- Main index page title + $NEXTMSG$ -- Next message filename + $PREVMSG$ -- Previous message filename + $PROG$ -- Program name + $TIDXFNAME$ -- Thread index page filename + $TIDXTITLE$ -- Thread index page title + $VERSION$ -- Version number of the program + + o Added $FROM$, $MSGID$, and $SUBJECT$ variables to be used + in the MAILTOURL resource. + + o The string `$$' in template resources will produce a `$' in + the output. + + o Fixed problem with messages (with follow-ups) getting + unnecessarily updated when messages are added to an archive. + + o Only a CR/LF, or LF, pair will terminate a message head. + Before, MHonArc was terminating message heads when + encountering an empty line or a line that only contained + whitespace (which was incorrect behavior). + + o Fixed bug in mhexternal.pl dealing with the `name' parameter + in the content-type field. Surrounding "s or 's were not + being deleted causing filenames with quotes to be written. + + o mhexternal.pl: The head of a pathname in the `name' + parameter in the content-type field is stripped off before + writing the external file. I.e. Only the base filename is + used. + + o Only one
after the H1 subject in messages will appear + if no message header fields are printed. + + o Added recognition of the following content-types in + mhexternal.pl: + + application/mac-binhex40 + + o Added a extras/ directory containing useful programs for + MHonArc. See README in the directory for information on + the programs contained in there. + + o To support -rmm, MIME filters now return an array. The + first array value is the HTML for the message, and any other + array values are filenames of files generated by the + filter. This allows MHonArc to know of any extra files that + must be deleted when a message is removed. + + o Some routines from the main mhonarc source file have been + moved into a separate librarys: readmail.pl, mhdb.pl, + mhutil.pl + + o The default URL to the documentation is now, + + http://www.oac.uci.edu/indiv/ehood/mhonarc.html + + The old URL, + + http://www.oac.uci.edu/indiv/ehood/mhonarc.doc.html + + is still valid. + + o There's probably other stuff, but I cannot remember. + + +======================================================================= 10/01/94 (1.0.0) - o First release -- See RELEASE_NOTES about compatibility issues + o First release -- See RELNOTES about compatibility issues with mail2html. -=========================================================================== -########################################################################### -=========================================================================== -Earl Hood, ehood@convex.com +======================================================================= +####################################################################### +======================================================================= +Earl Hood, ehood@isogen.com diff --git a/README b/README index 9357001..df32d01 100644 --- a/README +++ b/README @@ -23,11 +23,21 @@ ############################################################################## README for MHonArc +v1.2.3 - An Internet mail-to-HTML converter. + --------------------------------------------------------------------------- - Copyright (C) 1994 Earl Hood, ehood@convex.com +Table of Contents: + CONTENTS + DOCUMENTATION + INSTALLATION + MAILING LIST + BUGS/COMMENTS/SUGGESTIONS? + +--------------------------------------------------------------------------- + MHonArc -- Internet mail-to-HTML converter + Copyright (C) 1995,1996 Earl Hood, ehood@isogen.com This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -43,76 +53,133 @@ README for MHonArc along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. --------------------------------------------------------------------------- ---------------------------------------------------------------------------- -CONTENTS of directory: +CONTENTS -ACKNOWLEDGEMENTS Thanks to people +ACKNOWLG Thanks to people CHANGES Revision history of MHonArc COPYING GNU General Public License README The file you are reading -RELEASE_NOTES Release notes for MHonArc (_READ_) +RELNOTES Release notes for MHonArc (please read) +bat/ Batch files for MS-DOS users doc/ Documentation for MHonArc examples/ Example resource files for MHonArc -icons/ A collection of icons to use with MHonArc +extras/ Extra programs for use with MHonArc (See extras/README) +install.cfg Base installation configuration file install.me Installation program for MHonArc lib/ Libraries/MIME filters used by MHonArc logo/ Gifs of the MHonArc logo -mail2html Symbolic link to mhonarc -mbox2html Symbolic link to mhonarc -mhf2html Symbolic link to mhonarc -mhonarc* The MHonArc Perl program +mhonarc* The MHonArc program --------------------------------------------------------------------------- -** PLEASE read the RELEASE_NOTES before running MHonArc. ---------------------------------------------------------------------------- +DOCUMENTATION + +Documentation for MHonArc is located in the doc/ directory. + +html: + The main documentation for MHonArc is in multiple HTML files. Load + mhonarc.html in the doc/ directory into your Web browser to get + started. The HTML is generated from the Frame source via + MifMucker, + . + +postscript: + The postscript file, mhonarc.ps, is available if a hardcopy version + of the documentation is required. Since the cross-references used + are designed for HTML reading (ie they get converted into + hyperlinks), they may not be as useful for hardcopy reading. + The postscript is generated from the Frame source. + +ascii: + A plain text version of the documentation is in the single file + mhonarc.txt. This file is created by converting the HTML files + into ascii. See the Makefile in doc/ for how the conversion is + done. + +manpage: + For Unix users, there is a manpage in doc/ called mhonarc.1. It + is not very fancy. It is automatically generated like the + ascii version. The manpage does not follow the standard manpage + style and is not intended to be printed via troff. + +The installation process does not deal with the manpage or postscript +file. If you want to install them, you must do it manually. The +installation process does allow you to install the HTML and ASCII +documentation in a location of your choice. + --------------------------------------------------------------------------- INSTALLATION -To install MHonArc, run the following command: +This section gives the basic method for installing MHonArc on a Unix or +MS-DOS/Windows system. The documentation (doc/install.html) contains +an installation section with more detailed information. You can also +read the detailed instructions at + + +Brief Instructions + + Interactive Installing: + + Run the following command: + + perl install.me - % perl install.me + The installation program will ask you a series of questions on + where the Perl executable is and where to put MHonArc files. + Just hit to accept the default values listed in ()'s. -The installation process will ask you a series of questions on where -the Perl executable is and where to put MHonArc files. Just hit -to accept the default values listed in ()'s. + Batch Install: -Notes on installation process: + 1. Edit the file 'install.cfg'. + 2. Run the following command: - o The '#!' line in the installed mhonarc program is set to point to - the Perl executable specified in the installation process. + perl install.me install.cfg - o The installed mhonarc program has code added so it will find its - default libraries specified in the installation program. I.e. - The install lib directory is added to mhonarc's search path so it - will find its libraries. + The installation program will output information on what + is being installed and where it is being installed. - o If you specify paths that do not exist, the install.me program - will create the path. +Notes on Installation Program + o The '#!' line in the installed mhonarc program is set to + point to the Perl executable specified in the installation + process (this has no meaning under MS-DOS). -** PLEASE read the RELEASE_NOTES before running MHonArc. + o The installed mhonarc program has code added so it will find + its default libraries specified in the installation program. + I.e. The install lib directory is added to mhonarc's search + path so it will find its libraries. + + o If you specify paths that do not exist, the install.me + program will create the path ONLY if running in interactive + more. If using a configuration file (eg: install.cfg) you + must check that all paths specified exist. + +Bugs in Installation Program + + o In interactive mode, if you change a path after confirmation, + the old specified path will still exist, even if install.me + created it for you. Hence, the author recommends batch install. --------------------------------------------------------------------------- -DOCUMENTATION +MAILING LIST -Documentation for MHonArc is located in the doc/ directory. + A MHonArc mailing list exists to provide a general discussion forum + for users and developers. To subscribe to the mailing list, send + mail to mhonarc-request@rosat.mpe-garching.mpg.de with the single + word "subscribe" (without the quotes) as the message body. -html: - The main documentation for MHonArc is in multiple HTML files. Load - mhonarc.doc.html in the doc/ directory into your Web browser to get - started. + Mail sent to mhonarc@rosat.mpe-garching.mpg.de will be distributed + to all subscribers. -ascii: - A plain text version of the documentation is in the single file - mhonarc.txt. This file is created by converting the HTML files - into ascii. See the Makefile in doc/ for how the conversion is - done. + The WWW archive of the mailing list is located at + --------------------------------------------------------------------------- BUGS/COMMENTS/SUGGESTIONS? - If you have any bugs/comments/suggestions about MHonArc, feel free - to drop me an e-mail message at ehood@convex.com. + If you have any bugs/comments/suggestions about MHonArc, you may + send mail to the proper person(s) listed in the Contacts section of + the documentation, or (the prefered method) you may send mail to + the MHonArc mailing list, mhonarc@rosat.mpe-garching.mpg.de. If it is a bug you are reporting, please include the following in your message: @@ -120,13 +187,14 @@ BUGS/COMMENTS/SUGGESTIONS? o Version of Perl (can be retrievied by "perl -v"). o Version of the program in question. o The exact command-line used to invoke the program. - o Error/diagnostic message from the program. + o Error/diagnostic messages from the program. o Any other information that might prove useful. + Before sending e-mail, make sure the documentation does not already + have an answer to your question/problem. - If you have questions on what MHonarc can, or cannot do, please - read the documnetation first. If the docs do not answer your - question(s), feel free to e-mail me. + The latest information on MHonArc may be obtained at + --------------------------------------------------------------------------- -Earl Hood, ehood@convex.com +Earl Hood, ehood@isogen.com diff --git a/RELEASE_NOTES b/RELNOTES similarity index 59% rename from RELEASE_NOTES rename to RELNOTES index eff1627..b7d505c 100644 --- a/RELEASE_NOTES +++ b/RELNOTES @@ -1,9 +1,10 @@ -RELEASE_NOTES for MHonArc +Release Notes for MHonArc - An Internet mail-to-HTML converter. + --------------------------------------------------------------------------- - Copyright (C) 1994 Earl Hood, ehood@convex.com + MHonArc -- Internet mail-to-HTML converter + Copyright (C) 1995,1996 Earl Hood, ehood@isogen.com This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -19,10 +20,85 @@ RELEASE_NOTES for MHonArc along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. --------------------------------------------------------------------------- + +Version 1.2.3 +------------- + +This version is a minor enhancement, bug fix release. See the CHANGES +files for what was added and fixed. + +No modifications were made that require changes to the documentation +from v1.2.2. The documentation has been left untouched. + +--------------------------------------------------------------------------- + The following are release notes from previous versions of MHonArc. --------------------------------------------------------------------------- -RELEASE NOTES for MHonArc - Please read the release notes before executing MHonArc. +Version 1.2.2 +------------- + +This version is a minor enhancement, bug fix release. See the CHANGES +files for what was added and fixed. + +--------------------------------------------------------------------------- + +Version 1.2.1 +------------- + +This version is a minor enhancement, bug fix release. See the CHANGES +files for what was added and fixed. + + +Version 1.2.0 +------------- + +The CHANGES file contains information on the changes that may affect +1.1.0 archives. Please read it. + + +Version 1.1.0 +------------- + +Database file: + 1.1.0 is able to handle 1.0.x database files. Only additions + have been made between 1.0.x and 1.1.0. + +Threading: + + o If you have a 1.0 archive, you can generate a thread index + for it with the following: + + mhonarc -thread -editidx ... + + NOTE: You will also need to (re)specify the LISTBEGIN + resource so a link to the thread index exists on the main + index page. See the section on _Index Page Customization_ + in the documentation for more information. + + o You can prevent the creation of the thread index by the + following: + + * Set the M2H_THREAD environment variable to 0. + * Specify the NOTHREAD resource file element. + * Use the -nothread option. + + o Remember, the thread index does not replace the main index. + It compliments the main index. If using a custom layout, + resource variables are available to link between the 2 + indexes. + + +The following note is only relevant if you have developed your own +MIME filters for use in MHonArc: + + o MHonArc now treats the return value from MIME filters as + an array. The first value of the array is treated as the + HTML text to use in the message. All other array values are + treated as names of files that the filter may have generated + (eg. mhexternal.pl). MHonArc stores the filenames in the + database. Therefore, MHonArc can delete any extra files + associated with a message if the message is removed via the + -rmm option. Version 1.0.0 @@ -93,4 +169,4 @@ issues with the mail2html 3.1.x program. --------------------------------------------------------------------------- -Earl Hood, ehood@convex.com +Earl Hood, ehood@isogen.com diff --git a/bat/README b/bat/README new file mode 100644 index 0000000..e8944d7 --- /dev/null +++ b/bat/README @@ -0,0 +1,19 @@ +README for MHonArc/bat + +--------------------------------------------------------------------------- +CONTENTS of directory: + +README The file you are reading + +mhonarc.bat Batch file to invoke MHonArc as mhonarc. + +--------------------------------------------------------------------------- +NOTES + +The batch files are for your use if you are running MHonArc under +MS-DOS. Edit the paths in the files to reflect where you have +installed MHonArc via the install.me program. Then copy the batch +files to a location in your executable searc path. + +--------------------------------------------------------------------------- +Earl Hood, ehood@convex.com diff --git a/bat/mhonarc.bat b/bat/mhonarc.bat new file mode 100644 index 0000000..4066373 --- /dev/null +++ b/bat/mhonarc.bat @@ -0,0 +1,2 @@ +@echo off +perl c:/bin/mhonarc %1 %2 %3 %4 %5 %6 %7 %8 %9 diff --git a/doc/Makefile b/doc/Makefile index e47ff91..d8cf761 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,27 +1,32 @@ HTMLDOCS = \ - mhonarc.doc.html \ - mhonarc_intro.doc.html \ - mhonarc_qstart.doc.html \ - mhonarc_env.doc.html \ - mhonarc_clopts.doc.html \ - mhonarc_rcfile.doc.html \ - mhonarc_adding.doc.html \ - mhonarc_mime.doc.html \ - mhonarc_indexpg.doc.html \ - mhonarc_icons.doc.html \ - mhonarc_integrity.doc.html \ - mhonarc_tips.doc.html \ - mhonarc_notes.doc.html \ - mhonarc_diagnostics.doc.html + mhonarc.html \ + intro.html \ + install.html \ + qstart.html \ + overview.html \ + rcfile.html \ + adding.html \ + removing.html \ + indexpg.html \ + message.html \ + mime.html \ + details.html \ + diagnos.html \ + glossary.html \ + contacts.html +TMPFILE = ,mhonarc TEXTDOC = mhonarc.txt +MANPAGE = mhonarc.1 -textdoc: - /bin/rm -f $(TEXTDOC) +$(TEXTDOC): $(HTMLDOCS) mktxt + /bin/rm -f $(TMPFILE) $(TEXTDOC) $(MANPAGE) @for i in $(HTMLDOCS) ;\ do \ echo $$i ;\ - lynx -dump $$i >> mhonarc.txt ;\ + lynx -dump -nolist $$i >> $(TMPFILE) ;\ done - chmod 644 $(TEXTDOC) + perl mktxt < $(TMPFILE) + /bin/rm -f $(TMPFILE) + chmod 644 $(TEXTDOC) $(MANPAGE) diff --git a/doc/adding.html b/doc/adding.html new file mode 100644 index 0000000..8b2aad8 --- /dev/null +++ b/doc/adding.html @@ -0,0 +1,138 @@ + + + +MHonArc v1.2.2 -- Adding Messages + + +[Previous][Next][Contents][FAQ][Bugs][Home] +
+ +

Adding Messages +

+ +

Adding messages to an archive is done via the -add option. If no mailbox/folder +arguments are given, MHonArc assumes that a single message is being added to +the archive via standard input. Otherwise, MHonArc adds the messages contained +in the mail folders specified. +

+
+
NOTE + +

MHonArc will skip any messages that already exist in an archive. If a +message to be added has a message-ID that equals a message-ID of an +archived message, the message is skipped. +

+
+

Examples +

+ +

Adding a mail folder +

+ +

Here is example session adding an mail folder to an existing archive: +

+
% mhonarc -add test/www
+Requiring MIME filter libraries ...
+        mhexternal.pl
+        mhtxthtml.pl
+        mhtxtplain.pl
+        mhtxtsetext.pl
+Adding messages to ./maillist.html
+Reading test/www/ ........................................
+Writing HTML ...
+49 messages
+
+
+ +

.forward +

+ +

MHonArc can be used to add new messages as they are received by using the +".forward" file in your home directory. Here is how I would set up my +.forward file to invoke MHonArc on incoming mail: +

+
\ehood, "|/mnt/ehood/bin/webnewmail #ehood"
+
+
+ +
+
NOTE on .forward entry: + +

The "\ehood" tells sendmail to still deposit the incoming message to my +mail spool file. The "#ehood" Bourne shell comment is needed to insure +the command is unique from another user. Otherwise, sendmail may not +invoke the program for you or the other user. +

+

"webnewmail" is a Perl program that calls MHonArc with the appropriate +arguments. A wrapper program is used instead of calling MHonArc directly to +keep the .forward file simple. Here is the code to the webnewmail program: +

+
#!/usr/local/bin/perl
+
+$cmd = "/mnt/ehood/bin/mhonarc -add -quiet " .
+ "-outdir /mnt/ehood/public_html/newmail";
+open(M2H, "|$cmd");
+print M2H <STDIN>;
+close(M2H);
+
+
+ +

The webnewmail can be modified to check the mail header before calling +MHonArc to perform selective archiving of messages. For example, webnewmail +can check the To: field and only archive messages that come from a specific +mailing list. +

+

Cron +

+ +

This example uses cron(1) to update some mail archives from MH mail folders. +

+

The following entry is in my crontab file: +

+
0 0 * * * webmail
+
+
+ +

webmail is a script executed every night that calls MHonArc to perform the +update: +

+
#! /bin/csh -f
+
+umask 022
+setenv M2H_RCFILE $HOME/.mhonarc.rc
+## WWW messages
+mhonarc -add \
+          -outdir $HOME/public_html/doc/wwwmail \
+          $HOME/mail/www
+folder +www >& /dev/null
+refile first-last +www.ar >& /dev/null    # Archive original messages
+
+## Tools messages
+mhonarc -add \
+          -outdir $HOME/public_html/doc/toolsmail \
+          $HOME/mail/tools $HOME/mail/dtd
+folder +tools >& /dev/null
+refile first-last +tools.ar >& /dev/null  # Archive original messages
+folder +dtd >& /dev/null
+refile first-last +dtd.ar >& /dev/null    # Archive original messages
+
+folder +inbox >& /dev/null                # Set current folder to inbox
+
+
+
+ +

To avoid mail everynight from cron due to output from MHonArc, the -quiet +option can be used for each call to MHonArc, or use the following line in your +crontab file: +

+
0 0 * * * webmail > /dev/null
+
+ +

Standard error is not redirected to /dev/null so mail is still received if errors +occured during MHonArc execution. +

+ +
+[Previous][Next][Contents][FAQ][Bugs][Home] + + diff --git a/doc/contacts.html b/doc/contacts.html new file mode 100644 index 0000000..09c1fac --- /dev/null +++ b/doc/contacts.html @@ -0,0 +1,68 @@ + + + +MHonArc v1.2.2 -- Contacts + + +[Previous][Contents][FAQ][Bugs][Home] +
+ +

Contacts +

+ +
+

Mailing List +

+ +

A mailing list, mhonarc@rosat.mpe-garching.mpg.de, is available to provide a +discussion forum on the usage and development of MHonArc. Appropriate topics +for the list include: usage questions, bug reports, behavioral enhancements, +documentation bugs, and general help. +

+

To subscribe to the mailing list, send mail to +mhonarc-request@rosat.mpe-garching.mpg.de with the command, +

+
subscribe
+
+
+ +

as the message body. +

+

If you send mail mhonarc@rosat.mpe-garching.mpg.de, your message will be +distributed to all subscribers on the list. +

+

The mailing list is archived by Majordomo. You can also use the WWW to access +the archive (with full text search using glimpse) at +<URL:http://www.rosat.mpe-garching.mpg.de/mailing-lists/mhonarc/> +

+
+

People +

+ +
+
Earl Hood
+ehood@isogen.com + +

Main developer of MHonArc. Contact for bug reports, behavioral +enhancements, documentation bugs, and Unix usage issues. +

+
+
Steve Pacenka
+sp17@cornell.edu + +

Contributing developer. Worked on isolating code that would conflict +with MS-DOS. Contact for MS-DOS installation problems or MS-DOS +usage issues. +

+
+
Achim Bohnet
+ach@rosat.mpe-garching.mpg.de + +

Contributing developer. Administrator, and maintainer, of the MHonArc +mailing list. +

+ +
+[Previous][Contents][FAQ][Bugs][Home] + + diff --git a/doc/details.html b/doc/details.html new file mode 100644 index 0000000..44ee035 --- /dev/null +++ b/doc/details.html @@ -0,0 +1,185 @@ + + + +MHonArc v1.2.2 -- Gory Details + + +[Previous][Next][Contents][FAQ][Bugs][Home] +
+ +

Gory Details +

+ +

This sections explain in detail how MHonArc functions. Knowing the material +covered in this section may help you when trouble shooting. +

+
+

OS Detection +

+ +

MHonArc will automatically detect which operating system it is running under. If +the following list of conditions are true, MHonArc assumes it is running under +MS-DOS: +

+
    +
  • The COMSPEC environment variable is defined. +
  • The value of the COMSPEC environment variable is a legal MS-DOS +pathname. +

  • The value of the COMSPEC environment variable is an executable file. +

+

If any of the above conditions is false, MHonArc assumes it is running under Unix. +

+
+
NOTE + +

The previous conditions are used since the conditions will exist if Perl has +been installed on an MS-DOS machine. None of the above conditions exist +when Perl is installed on a Unix system. +

+
+

Processing Steps +

+ +

This section describes the steps MHonArc performs when creating/editting an +archive. Anytime messages are added or deleted or the index page layout is +changed, MHonArc will perform the following steps. +

+
    +

  • Creates a lock file. This insures only one MHonArc process is updating the +archive at any given moment. See Archive Integrity for more information. +

  • Reads the database file. The name, and location, of the database file can be +explicitly specified via the M2H_DBFILE and M2H_OUTDIR environment +variables or the command-line options -dbfile and -outdir. +Otherwise, the current working directory is used. +

    NOTE: The database file must be in the same location as the archive since the +M2H_OUTDIR variable and -outdir option also specify the location of the +archive. +

    The database file contains data to update any mail threads and the +resource settings when MHonArc was last invoked. This allows new +messages to contain the same formatting/resource specifications as +existing messages in the archive without having to re-specify the resources +each time new messages are added. Resources defined in the database file +override the environment variables. +

    NOTE: If no database file is found, MHonArc will create a new archive. +

  • Read the MHonArc resource file, if specified. The resource file will override +any settings contained in the database file. +

  • Read the settings specified on the command-line. Command-line options +override any settings in the database and/or resource file. +

  • Update archive. +

  • Rewrites the index pages to reflect the update. +

  • Writes a new database file containing the new state of the archive and all +(new) resource settings. +

+

Normally, knowing all the previous steps is unnecessary. However, it may be +useful to be aware of them if unexpected behavior, or errors, occur. +

+
+

Archive Integrity +

+ +

MHonArc applies safeguards to try to insure that a mail archive does not get +corrupted due to exceptional circumstances. MHonArc does the following to insure +a mail archive does not get corrupted: +

+
    +

  • MHonArc creates a lock file, ".mhonarc.lck", when creating/updating +an archive. The lock file insures that only one MHonArc process is +modifying an archive at any given moment. The -locktries +command-line option, or the M2H_LOCKTRIES environment variable, +allows you to control how long a given MHonArc process will wait if an +archive is currently locked. If MHonArc can not lock the archive after the +specified number of tries, MHonArc will exit, unless the -force option is +specified. +

  • MHonArc will ignore the following signals once messages are actually +being written to disk: SIGABRT, SIGHUP, SIGINT, SIGQUIT, SIGPIPE, +SIGTERM. Possible archive corruption can still occur if a SIGKILL signal +is received since SIGKILLs are uncatchable. A SIGKILL will also prevent +MHonArc from deleting the lock file. +

+
+

File Formats +

+ +

Database File +

+ +

The MHonArc database file is actual Perl code. MHonArc requires it like any other +Perl library to load in the contents of the database. +

+
+
CAUTION + +

You should never modify the database file by hand. Changing the file by +hand could cause future incorrect/unpredictable behavior when +processing the archive. +

+

Index and Message Files +

+ +

The indexes and message files are legal HTML documents. However, manual +editting of the documents is discouraged. The documents contain special comment +declarations. The comment declarations act as markers which allow MHonArc to +correctly edit the documents when needed. +

+

The comment declarations look like the following: +

+
<!--X-Body-Begin-->
+<!--X-User-Header-->
+<!--X-User-Header-End-->
+<!--X-TopPNI-->
+...
+
+
+ +

Derived Files +

+ +

Derived files are files that are generated by the MIME filters. These files are created +when the data being processed in messages cannot be converted to HTML (eg. +images, postscript, video, binaries). The format of these files depend on the +content-type of the data. +

+
+

Notes +

+ +
    +

  • Here is the explicit order of decreasing precedence when setting +resources/options: +

      +
    • command-line options (highest precedence) +
    • resource file +
    • database file +

    • environment variables (lowest precedence) +

    +

  • Mail thread detection is dependent upon the mail messages containing the +message id(s) of referenced messages. Most mailers reply function will +automatically include the message id of the message being replied to. +

  • All mail message being converted into HTML are stored in memory before +they are written to disk. This can eat up much memory if many mail +messages are being converted. If you are processing multiple +mailboxes/folders and worried about memory, you can try the following: +

      +
    • Invoke MHonArc on each one separately using the -add option. +

    • Or, invoke MHonArc with the -savemem option. +

    +

  • The database file, and the index pages, are completely rewritten evertime +new messages are added. This may cause slight slow-downs when +archives become very large. +

  • When reading MH mail folders, mail message are assumed to have +numeric filenames. +

  • When sorting by date, MHonArc tries to use the date listed in the first +Received field of the message. If no Received field exists, than the Date field +is used. +

  • No distinction is made, in the output, on which messages came from +which mail folder if multiple mail folders are processed. +

  • MHonArc can probably be modified to handle other types of mailers +(which has been done since the original version only supported MH mail +folders). The MSGSEP resource gives flexibility in processing Unix style +mailbox files. +

+ +
+[Previous][Next][Contents][FAQ][Bugs][Home] + + diff --git a/doc/diagnos.html b/doc/diagnos.html new file mode 100644 index 0000000..b1d7a80 --- /dev/null +++ b/doc/diagnos.html @@ -0,0 +1,231 @@ + + + +MHonArc v1.2.2 -- Diagnostics + + +[Previous][Next][Contents][FAQ][Bugs][Home] +
+ +

Diagnostics +

+ +

Three types of messages exist in MHonArc: Informative messages, Warnings, and +Errors. Informative messages give you the current status of MHonArc's execution. +Warnings signify undesired conditions, but are not critical in MHonArc's exection. +Errors signify critical conditions that inhibit MHonArc from finishing its task. +

+

Another set of messages exists that are generated from the Perl interpreter itself. +MHonArc tries its best to catch any conditions that may cause Perl to abnormally +abort, but conditions may arise where this is not possible. +

+

This section describes the various diagnostics MHonArc may produce and +messages Perl may produce. +

+
+

Informative messages +

+ +

Informative messages may be suppressed via the -quiet command-line option. +Only the more important Informative messages are listed here. +

+

Could not process message with given Content-Type: ... +

+ +

MHonArc will output this statement in filtered mail messages for content-types it +is unable to process. See Default Filters in MIME for content-types that MHonArc +supports by default. See Writing Filters for adding new filters into MHonArc. +

+

This is the only Informative message that does not go to standard output, but into +the actual filtered mail message. +

+

No new messages +

+ +

No mail messages exist when performing an add operation to an archive. This can +occur if an empty MH mail folder, or empty mailbox file, is passed to MHonArc. +

+

Requiring MIME filter libraries ... +

+ +

Indicates MHonArc is loading external libraries for filtering mail messages. +MHonArc will output each library it loads. See MIME for more information of filter +libraries. +

+

Trying to lock mail archive ... +

+ +

The statement means that a lock file is in place for the archive you are trying to +update. Normally, an existing lock file implies that another MHonArc process is +currently using the archive, and other MHonArc processes will wait awhile to see +if the archive will be unlocked. +

+

However, there are times when a lock file exists, but no MHonArc process is +modifying the archive. This can occur if MHonArc is abnormally terminated. If you +know that no other MHonArc process is editting the archive you are try to modify, +then manually remove the lock file or use the -force option. +

+

See Archive Integrity for more information. +

+
+

Warnings +

+ +

Warning messages denote some undesired event occurred, but the event is not +severe enough to cause program termination. +

+

Warning: Could not find date for message +

+ +

MHonArc was unable to find a received/sent date for a mail message. With respect +to other mail messages, a message with no received/sent date is first in +chronological order. +

+

Warning: Database (<dbversion>) != program (<prgversion>) version +

+ +

Indicates that the version of MHonArc updating an archive is different from the +version of MHonArc that created the database file. Problems can arise if the +database file changes in format from different version of MHonArc. See the release +notes of the MHonArc distribution if changes in the databse format has effects on +older archives. +

+

Warning: Unable to create <outdir>/<dbfile> +

+ +

Indicates MHonArc was unable to create the database file <dbfile> for the mail +archive created/modified in <outdir>. This message can occur if <outdir> +permissions changed during MHonArc execution, the existing <dbfile> is read-only, +or the file system is full. +

+

This message can be severe because no future add operations can be performed to +the archive. +

+

Warning: Unable to open footer: <footer> +

+ +

MHonArc was unable to open the footer file, <footer>, for inclusion into the index +page. Make sure <footer> exists, and is readable by you. +

+

Warning: Unable to open header: <header> +

+ +

MHonArc was unable to open the header file, <header>, for inclusion into the index +page. Make sure <header> exists, and is readable by you. +

+

Warning: Unable to open <folder> +

+ +

MHonArc was unable to open the specified mail <folder> for reading. Make sure +<folder> exists and is readable (and executable if a directory) by you. +

+

Warning: Unable to open message: <folder>/<message> +

+ +

MHonArc was unable to open the specified MH mail message <folder>/<message> +for reading. Make sure <folder>/<message> exists and is readable by you. +

+

Warning: Unable to open resource file: <file> +

+ +

MHonArc was unable to open the resource file, <file>, for reading. Make sure <file> +exists, and is readable by you. +

+

Warning: Undefined time zone: "<timezone>" +

+ +

MHonArc has found an unrecognized timezone acronym, <timezone>, in a mail +message. You can tell MHonArc about other timezone acronyms, and their hour +offset to UTC, by using the TIMEZONES resource element of the Resource File. +

+

The timezone UTC (or GMT) is used for an undefined timezone acronym +

+
+

Errors +

+ +

Errors denote conditions that cause MHonArc to abort execution. +

+

Some error conditions may cause the MHonArc archive to become corrupted. If the +error occurs when MHonArc is writing files, you may have to recreate the archive +from the original messages. +

+

ERROR: Database read error of <dbfile> +

+ +

An error occured when trying to read an archive's database. The error can occur if +the database file is not readable or the file got corrupted. +

+

ERROR: Unable to create <file> +

+ +

MHonArc was unable to create <file>. This message can occur if the directory being +written to is not writable, a read-only file with the same name exists, or the file +system is full. +

+

ERROR: Unable to create <lockfile> after <#> tries +

+ +

The statement means that a lock file is in place for the archive you are trying to +update. +

+

Sometimes a lock file exists, but no MHonArc process is modifying the archive. This +can occur if MHonArc is abnormally terminated. If you know that no other +MHonArc process is editting the archive you are try to modify, then manually +remove the lock file or use the -force option. +

+

ERROR: Unable to open <file> +

+ +

MHonArc was unable to open <file> for reading. Make sure <file> exists, and is +readable by you. +

+

ERROR: Unable to require newgetopt.pl +

+ +

The newgetopt.pl library is needed for MHonArc to parse the command-line. +newgetopt.pl is part of the standard Perl distribution. Make sure Perl has been +correctly installed at your site. +

+

ERROR: Unable to require timelocal.pl +

+ +

The timelocal.pl library is needed for MHonArc to process dates in messages. +timelocal.pl is part of the standard Perl distribution. Make sure Perl has been +correctly installed at your site. +

+

ERROR: Unable to require <file> +

+ +

This message signifies MHonArc was unable to require the library <file>. Make sure +you properly installed MHonArc via the installation program. If <file> is your own +custom filter, make sure you properly registered it in the Resource File. See also +Specifying Filters and the PERLINC resource element. +

+
+

Perl Messages +

+ +

Generally, if execution is aborted and the following error messages appear, then +you will have to manually delete the lock file since MHonArc will not have the +chance to delete the file. +

+

Can't locate <file> in @INC at <file> line <number>. +

+ +

A library that MHonArc tried to load was not found in the Perl include search +paths. This error usually implies that MHonArc was not installed correctly. Make +sure that MHonArc was installed via the install.me program that is provided in +the MHonArc distribution. +

+

<file> did not return a true value at <file> line <number>. +

+ +

If you are using your own MIME filters with MHonArc, make sure the library files +return 1. +

+ +
+[Previous][Next][Contents][FAQ][Bugs][Home] + + diff --git a/doc/glossary.html b/doc/glossary.html new file mode 100644 index 0000000..6b081cf --- /dev/null +++ b/doc/glossary.html @@ -0,0 +1,48 @@ + + + +MHonArc v1.2.2 -- Glossary + + +[Previous][Next][Contents][FAQ][Bugs][Home] +
+ +

Glossary +

+ +
+
HTML + +

Hypertext Markup Language. HTML is the main document markup +language for the World Wide Web. +

+
+
MIME + +

Multipurpose Internet Mail Extensions. MIME allows the transmission of +non-ASCII data, and mixed content data, in electronic mail messages. +

+
+
MH + +

Message Handler. MH is a free message handling system initially +developed by the RAND Corporation, with subsequent development done +at the University of Califonia: Irvine. +

+
+
Perl + +

Practical Extraction and Report Language. Perl is an interpreted +programming language suited for processing text and generating reports. +

+
+
SGML + +

Standard Generalized Markup Language. SGML is a language for +document representation. +

+ +
+[Previous][Next][Contents][FAQ][Bugs][Home] + + diff --git a/doc/indexpg.html b/doc/indexpg.html new file mode 100644 index 0000000..c344dfe --- /dev/null +++ b/doc/indexpg.html @@ -0,0 +1,422 @@ + + + +MHonArc v1.2.2 -- Index Page Customization + + +[Previous][Next][Contents][FAQ][Bugs][Home] +
+ +

Index Page Customization +

+ +

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

+
+

Filename +

+ +

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

+
+

Beginning Markup +

+ +

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>
+
+
+ +
+
NOTE + +

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

+
+

End Markup +

+ +

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

+
+

Include Files +

+ +

MHonArc allows you to include the contents of files into the index page via the +header and footer resources. +

+
+
NOTE + +

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

+
+
NOTE + +

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

+
+
NOTE + +

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

+
+

Listing Layout +

+ +

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

+

+
+
NOTE + +

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

Icons +

+ +

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

+

Defining Icons +

+ +

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

+

Example +

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

Using Icons +

+ +

In order to incorporate icons into the index page, insert the $ICON$ variable into +the LITEMPLATE resource element. +

+

Example +

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

+

Example +

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

+
+

Examples +

+ +

Example 1 +

+ +

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

Example 2 +

+ +

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>
+
+
+ + +
+[Previous][Next][Contents][FAQ][Bugs][Home] + + diff --git a/doc/install.html b/doc/install.html new file mode 100644 index 0000000..37b9f1b --- /dev/null +++ b/doc/install.html @@ -0,0 +1,381 @@ + + + +MHonArc v1.2.2 -- Installation + + +[Previous][Next][Contents][FAQ][Bugs][Home] +
+ +

Installation +

+ +

This section instructs you on how to install and get MHonArc running on your +machine. The section covers Unix installation and MS-DOS/Windows installation. +

+
+
NOTE + +

For brevity, anything that applies to MS-DOS also applies to Windows. +

+
+

System Requirements +

+ +

MHonArc is written in Perl 4. Therefore, you must have Perl 4 or 5 installed on your +system. If you do not know if Perl is installed on your system, ask your system +administrator. +

+

If Perl is not installed on your system, you can retrieve Perl at +<URL:http://www.cis.ufl.edu/perl/ftp.html>. I recommend version 4.0 +patchlevel 34, or later. MHonArc has not been tested on earlier versions. +

+
+
NOTE + +

MHonArc makes use of the Perl libraries newgetopt.pl and +timelocal.pl. These libraries are part of the normal Perl distribution. +

+
+

Extracting the Distribution File +

+ +

Before extracting the distribution file, you may want copy the distribution file into +scratch directory, and work in there during installation. +

+

Tar/Gzip Distribution +

+ +

You must have gzip and tar installed on your system. If gzip is not installed, you +may obtain gzip at <URL:ftp://prep.ai.mit.edu/pub/gnu>. Tar comes with all +Unix systems. However, MS-DOS users may have to obtain tar. +

+

To extract the file, type the following command at your shell's prompt: +

+
+
Unix + +

zcat MHonArc.tar.gz | tar xvof - +

+
+
MS-DOS + +

gunzip -dv MHonArc.tar.gz
+tar xvf MHonArc.tar +

+

A directory called "MHonArc" should be created. The directory contains all the +files need for installing MHonArc. +

+
+
NOTE + +

The actual name of the distribution file may differ from the example given. +

+

Zip Distribution +

+ +

You must have pkzip or unzip installed on your system. +

+

To extract the file, type the following command at your shell's prompt: +

+

unzip mhonarc.zip
+
+OR
+
+pkunzip -d mhonarc.zip +

+
+
IMPORTANT + +

The directory structure of the zip file must be preserved during extraction +to insure proper installation. +

+

A directory called "MHonArc" should be created. The directory contains all the +files need for installing MHonArc. +

+
+
NOTE + +

The actual name of the distribution file may differ from the example given. +

+
+

Installing the Software +

+ +

Once you have extracted the distribution file, change your current working +directory into the MHonArc directory created during the extraction of the +distribution file. +

+

Example: Assuming you are in the directory you extracted the distribution file in, +you can type the following on your command-line: +

+
+
Unix + +

cd MHonArc +

+
+
MS-DOS + +

cd MHONARC +

+

install.me +

+ +

Contained in the MHonArc directory is a Perl program called "install.me". This +program will perform the tasks required to install MHonArc on you machine. The +install program is capable of running interactively, or in batch. +

+

Interactive Mode +

+ +

To run install.me in interactive mode, type the following at your shell's +prompt: +

+

perl install.me +

+
+
NOTE + +

Make sure you are in the same directory as the install.me program. +

+

The program will then prompt you for the necessary information to install +MHonArc on your system. +

+

Here's an example (Unix) session: +

+
% perl install.me
+MHonArc Installation
+====================
+The installation process will ask you a series of questions on where
+the Perl executable is and where to put MHonArc files.  Just hit <CR>
+to accept the default values listed in ()'s.
+
+If directory path does not exist on your system, the installation
+program will create the path for you.
+
+-----------------------------------------------
+Note:  Make sure all pathnames are absolute.
+-----------------------------------------------
+
+Hit <CR> to continue ...
+Perl executable ("/usr/local/bin/perl")
+-> /usr/bin/perl
+Location to install programs ("/usr/local/bin")
+-> /mnt/ehood/bin
+Location to install libraries ("/usr/local/lib/MHonArc")
+-> /mnt/ehood/lib/MHonArc
+Install documentation ("y")?  y
+Location to install docs ("/usr/local/lib/MHonArc/doc")
+-> /mnt/ehood/lib/MHonArc/doc
+
+You've specified the following:
+        Perl location: /usr/bin/perl
+        Program directory: /mnt/ehood/bin
+        Library directory: /mnt/ehood/lib/MHonArc
+        Doc directory: /mnt/ehood/lib/MHonArc/doc
+Is this correct ("y")?  y
+Installing the following into /mnt/ehood/bin
+        mhonarc
+Installing the following into /mnt/ehood/lib/MHonArc
+        base64.pl
+        mhexternal.pl
+        mhtxthtml.pl
+        mhtxtplain.pl
+        mhtxtsetext.pl
+        qprint.pl
+        readmail.pl
+Installing the following into /mnt/ehood/lib/MHonArc/doc
+        mhonarc.txt
+        ...
+
+
+ +

Batch Mode +

+ +

To run install.me in batch mode, type the following at your shell's prompt: +

+

perl install.me install.cfg +

+
+
NOTE + +

Make sure you are in the same directory as the install.me program. +

+

The install.cfg contains the necessary information for intalling MHonArc on +your system. You will need to edit install.cfg to reflect your installation +requirements. +

+

Here is an example install.cfg: +

+
# Should executables be installed. 0 => NO, non-zero => YES.
+#
+$dobin = 1;
+
+# Should libraries be installed. 0 => NO, non-zero => YES.
+#
+$dolib = 1;
+
+# Should documentation be installed. 0 => NO, non-zero => YES.
+#
+$dodoc = 1;
+
+# Location for executable.  If using ms-dos, use something like
+# 'C:\\BIN'.
+#
+$bindir  = '/usr/local/bin';
+
+# Location for libraries.  If using ms-dos, use something like
+# 'C:\\LIB\\MHONARC'.
+#
+$libdir  = '/usr/local/lib/MHonArc';
+
+# Location for documents.  If using ms-dos, use something like
+# 'C:\\DOC\\MHONARC'.
+#
+$docdir  = '/usr/local/lib/MHonArc/doc';
+
+# Location of perl executable.  If using ms-dos, use something like
+# 'C:\\BIN\\PERL.EXE'.
+#
+$perlprg = '/usr/local/bin/perl';
+
+
+1; # DO NOT DELETE THIS LINE
+
+
+ +

The file is Perl code, and therefore, must follow Perl syntax rules: +

+
    +
  • Anything following a `#' character is ignored. +
  • Strings values need to be enclosed in quotes. +
  • If you need to use a backslash in a string value, it must be escaped with a +backslash. Example: 'C:\\LIB\\MHONARC'. The same applies to the '$' +character. +
  • All statements must end with a semi-colon. +
  • The "1;" line must not be deleted. +
+
+
NOTE + +

You can verify the syntax of the configuration file by invoking "perl -c" +on the file. +

+

After you have successfully executed install.me, MHonArc is ready to use. +

+

MS-DOS Post install.me Note +

+ +

If you would like the ability to run MHonArc like other programs, then create a +batch file that contains something like the following: +

+
@ECHO OFF
+C:\BIN\PERL.EXE C:\BIN\MHONARC %1 %2 %3 %4 %5 %6 %7 %8 %9
+
+
+ +

Of course, you will need to change the paths to Perl and MHonArc to suit your +systems configuration. +

+

Sample batch files are available in the MHonArc distribution. +

+

Notes on install.me +

+ +
    +

  • If you do not know the location of the Perl executable on your system, ask +your system administrator. +

  • All pathnames must be absolute. +

  • If a path does not exist that you specify, the path will be automatically +created if running in interactive mode. In batch mode, all paths specified +must already exist. +

  • During the installation process, the main MHonArc source file is modified +to be aware of the location of the Perl executable and MHonArc's library +files. If you ever need to install MHonArc in a different location, rerun the +install.me program. +

    NOTE: Location of the Perl exectuble is only relevant for Unix systems. +MS-DOS systems do not make use of the "#!" line in scripts. +

  • MHonArc requires the use of timelocal.pl and newgetopt.pl. These +libraries are part of the normal Perl distribution. +

+
+

Tested Environments +

+ +

This section covers software environments MHonArc has worked successfully. +Feedback is welcome about other success, or failure, stories covering MHonArc +usage in other environments. +

+

Perl +

+ +

MHonArc is known to work with the following version of Perl 4, or later: +

+

$RCSfile: perl.c,v $$Revision: 4.0.1.7 $$Date: 92/06/08 +14:50:39 $
+Patch level: 34 +

+

MHonArc is known also to work with Perl 5.001m and Perl 5.002 beta2. +

+
+
NOTE + +

The version numbers are based upon the Unix versions of Perl. DOS +version numbers may differ. +

+

Unix +

+ +

Mail Software +

+ +
    +
  • MH +

  • Elm, Mail, mail, and any other mail software that stores e-mail in UUCP +style mailbox format. UUCP format is where mail messages are separated +by a line beginning with "From " (I.e. the word "From" followed by a +space). You may need to utilize the MSGSEP resource if the message +separator is different from standard mailbox files (eg. MMDF format). +

+

News Software +

+ +

Different news software store messages differently. Messages are either stored in a +format similiar to MH or similiar to a mailbox file: +

+
    +

  • MH style is where the messages are stored in a directory with each post a +separate file, and each file has a numeric filename. +

  • Mailbox style is where messages are stored in a single file. You may need +to utilize the MSGSEP resource if the message separator is different from +standard mailbox files. +

+

MS-DOS +

+ +

Mail/News Software +

+ +

MHonArc has been tested under MS-DOS with message files created by the +following mail and news programs: +

+
    +
  • Eudora +
  • WinVN +
  • Windows Trumpet +

  • NUPop +

+

It also works with individual RFC822 mail messages, but you must run MHonArc +without a batch file if you need to use redirection. For example: +

+

perl c:\bin\mhonarc <one.msg >one.htm
+perl c:\bin\mhonarc -add <one.msg
+ +

+ +
+[Previous][Next][Contents][FAQ][Bugs][Home] + + diff --git a/doc/intro.html b/doc/intro.html new file mode 100644 index 0000000..2b62428 --- /dev/null +++ b/doc/intro.html @@ -0,0 +1,77 @@ + + + +MHonArc v1.2.2 -- Introduction + + +[Next][Contents][FAQ][Bugs][Home] +
+ +

Introduction +

+ +

MHonArc is a Perl program for converting e-mail messages as specified in RFC 822 +and RFC 1521 (MIME) to HTML. MHonArc can perform the following tasks: +

+
    +
  • Convert mh(1) mail folders or UUCP/Unix style mailboxes into an HTML +mail archive. +
  • Add or remove messages to an existing HTML mail archive generated by +MHonArc. +

  • Convert a single message to HTML. +

+

Along with these tasks, MHonArc provides the following: +

+
    +
  • A main customizable index page for mail messages archived. +
  • A customizable thread index page listing messages by thread. +
  • Control over message formatting. +
  • The ability to hook in your own custom message filters. +
+
+

Why Use MHonArc? +

+ +

Here are some reasons for using MHonArc: +

+
    +
  • You want to keep organized archives of mail messages and/or news +articles for a World Wide Web (WWW) server; complete with live +hypertext pointers to their authors and to any url's mentioned. +
  • You would like to control the layout of mail/news archives to keep a +consistent style to your WWW pages. +
  • You have a WWW client, but no MIME mail reader. MHonArc will allow +you to read MIME messages that includes images, audio, video, etc via +your Web client. +
  • Muli-platform support: MS-DOS and Unix. +
  • You think the MHonArc logo is really cool, and it deserves to be used. +
  • You like Perl, and you want to see what it can do. +
  • Just cuz. +
+
+

Supported Platforms +

+ +

MHonArc (version 1.1, or later) will run under Unix or MS-DOS operating systems +with Perl 4 or 5 installed. +

+
+

Availability +

+ +

The latest information on MHonArc, and its availability, may be obtained at +<URL:http://www.oac.uci.edu/indiv/ehood/mhonarc.html>. +

+
+

About the Documentation +

+ +

The documentation is oriented towards Unix users. However, the section on +Installation does conver MS-DOS installation instructions. Notes are made in the +documentation when something may differ due to the operating system. +

+ +
+[Next][Contents][FAQ][Bugs][Home] + + diff --git a/doc/message.html b/doc/message.html new file mode 100644 index 0000000..313d4d9 --- /dev/null +++ b/doc/message.html @@ -0,0 +1,510 @@ + + + +MHonArc v1.2.2 -- Message Customization + + +[Previous][Next][Contents][FAQ][Bugs][Home] +
+ +

Message Customization +

+ +

This sections shows how to customize the appearance of messages when +converted to HTML. +

+
+

Beginning Markup +

+ +

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

End Markup +

+ +

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

+
+

Header and Footer +

+ +

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

Navigational Links +

+ +

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

+

Conditional Links +

+ +

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

+
+
NOTE + +

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

+

+
+
WARNING + +

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

+
+

Message Layout +

+ +

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

+

Excluding Fields +

+ +

The EXCS resource allows you to specify what fields should be excluded in the +HTML output. +

+

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

+

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

+

Field Order +

+ +

The FIELDORDER resource allows you to control the order the message header +fields appear in the HTML output. +

+

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

+

The following represents the default value of the FIELDORDER resource: +

+
<FIELDORDER>
+to
+subject
+from
+date
+-extra-
+</FIELDORDER>
+
+
+ +

Field Formatting +

+ +

The FIELDSTYLES and LABELSTYLES resources allow to control how each +message header field is formatted. +

+

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

+

The default value of FIELDSTYLES is the following: +

+
<FIELDSTYLES>
+-default-
+</FIELDSTYLES>
+
+
+ +

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

+

The default value of LABELSTYLES is the following: +

+
<LABELSTYLES>
+-default-:em
+</LABELSTYLES>
+
+
+ +
+

Other Resources +

+ +

E-mail Links +

+ +

MAILTOURL +

+ +

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

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

+ +
+[Previous][Next][Contents][FAQ][Bugs][Home] + + diff --git a/doc/mhonarc.1 b/doc/mhonarc.1 new file mode 100644 index 0000000..13e8f60 --- /dev/null +++ b/doc/mhonarc.1 @@ -0,0 +1,3787 @@ +.TH MHonArc 1 +.SH NAME +MHonArc \- Mail\-to\-HTML converter +.SH DESCRIPTION +.in 0 +.nf + + [INLINE] + + MHonArc + + An Internet mail\-to\-HTML converter. + + _________________________________________________________________ + +Table of Contents + + * Introduction + + Why Use MHonArc? + + Supported Platforms + + Availability + + About the Documentation + + * Installation + + System Requirements + + Extracting the Distribution File + + Installing the Software + + Tested Environments + + * Quick Start + + Converting MH mail folders or Mailbox files + + Adding Messages to an Archive + + Converting a single message + + * Overview + + Synopsis + + Options + + Environment + + * Resource File + + Resource Syntax + + Resource Elements + + Example Resource File + + Notes on Resource File + + * Adding Messages + + Examples + + * Removing Messages + + Message Numbers + + Scanning an Archive + + * Index Page Customization + + Filename + + Beginning Markup + + End Markup + + Include Files + + Listing Layout + + Icons + + Examples + + * Thread Index Customization + + Filename + + Beginning Markup + + End Markup + + Listing Layout + + * Message Customization + + Beginning Markup + + End Markup + + Header and Footer + + Navigational Links + + Message Layout + + Other Resources + + * MIME + + Default Filters + + Non\-MIME Messages + + Writing Filters + + Specifying Filters + + * Gory Details + + OS Detection + + Processing Steps + + Archive Integrity + + File Formats + + Notes + + * Diagnostics + + Informative messages + + Warnings + + Errors + + Perl Messages + + * Glossary + + * Contacts + + Mailing List + + People + + _________________________________________________________________ + + + Earl Hood + Isogen International Corp + 2200 North Lamar #230 + Dallas, TX 75202 + + Phone: (214) 953\-004 x127 + FAX: (214) 953\-3152 + + _________________________________________________________________ + + + + _________________________________________________________________ + + Introduction + + _MHonArc_ is a Perl program for converting e\-mail messages as + specified in RFC 822 and RFC 1521 (_MIME_) to HTML. _MHonArc_ can + perform the following tasks: + + * Convert mh(1) mail folders or UUCP/Unix style mailboxes into an + HTML mail archive. + * Add or remove messages to an existing HTML mail archive generated + by _MHonArc_. + * Convert a single message to HTML. + + Along with these tasks, _MHonArc_ provides the following: + + * A main customizable index page for mail messages archived. + * A customizable thread index page listing messages by thread. + * Control over message formatting. + * The ability to hook in your own custom message filters. + + _________________________________________________________________ + +Why Use MHonArc? + + Here are some reasons for using _MHonArc_: + + * You want to keep organized archives of mail messages and/or news + articles for a World Wide Web (_WWW_) server; complete with live + hypertext pointers to their authors and to any url's mentioned. + * You would like to control the layout of mail/news archives to keep + a consistent style to your WWW pages. + * You have a WWW client, but no MIME mail reader. _MHonArc_ will + allow you to read MIME messages that includes images, audio, + video, etc via your Web client. + * Muli\-platform support: MS\-DOS and Unix. + * You think the _MHonArc_ logo is really cool, and it deserves to be + used. + * You like Perl, and you want to see what it can do. + * Just cuz. + + _________________________________________________________________ + +Supported Platforms + + _MHonArc_ (version 1.1, or later) will run under Unix or MS\-DOS + operating systems with Perl 4 or 5 installed. + + _________________________________________________________________ + +Availability + + The latest information on _MHonArc_, and its availability, may be + obtained at . + + _________________________________________________________________ + +About the Documentation + + The documentation is oriented towards Unix users. However, the section + on Installation does conver MS\-DOS installation instructions. Notes + are made in the documentation when something may differ due to the + operating system. + + _________________________________________________________________ + + + _________________________________________________________________ + + Installation + + This section instructs you on how to install and get _MHonArc_ running + on your machine. The section covers _Unix_ installation and + _MS\-DOS/Windows_ installation. + + _NOTE_ + For brevity, anything that applies to MS\-DOS also applies to + Windows. + + _________________________________________________________________ + +System Requirements + + _MHonArc_ is written in Perl 4. Therefore, you must have Perl 4 or 5 + installed on your system. If you do not know if Perl is installed on + your system, ask your system administrator. + + If Perl is not installed on your system, you can retrieve Perl at + . I recommend version 4.0 + patchlevel 34, or later. _MHonArc_ has not been tested on earlier + versions. + + _NOTE_ + _MHonArc_ makes use of the Perl libraries newgetopt.pl and + timelocal.pl. These libraries are part of the normal Perl + distribution. + + _________________________________________________________________ + +Extracting the Distribution File + + Before extracting the distribution file, you may want copy the + distribution file into scratch directory, and work in there during + installation. + + Tar/Gzip Distribution + + You must have _gzip_ and _tar_ installed on your system. If _gzip_ is + not installed, you may obtain _gzip_ at + . _Tar_ comes with all Unix + systems. However, MS\-DOS users may have to obtain _tar_. + + To extract the file, type the following command at your shell's + prompt: + + _Unix_ + zcat MHonArc.tar.gz | tar xvof \- + + _MS\-DOS_ + gunzip \-dv MHonArc.tar.gz + tar xvf MHonArc.tar + + A directory called "MHonArc" should be created. The directory contains + all the files need for installing _MHonArc_. + + _NOTE_ + The actual name of the distribution file may differ from the + example given. + + Zip Distribution + + You must have _pkzip_ or _unzip_ installed on your system. + + To extract the file, type the following command at your shell's + prompt: + + unzip mhonarc.zip + + OR + + pkunzip \-d mhonarc.zip + + _IMPORTANT_ + The directory structure of the zip file must be preserved + during extraction to insure proper installation. + + A directory called "MHonArc" should be created. The directory contains + all the files need for installing _MHonArc_. + + _NOTE_ + The actual name of the distribution file may differ from the + example given. + + _________________________________________________________________ + +Installing the Software + + Once you have extracted the distribution file, change your current + working directory into the MHonArc directory created during the + extraction of the distribution file. + + _Example_: Assuming you are in the directory you extracted the + distribution file in, you can type the following on your command\-line: + + _Unix_ + cd MHonArc + + _MS\-DOS_ + cd MHONARC + + install.me + + Contained in the MHonArc directory is a Perl program called + "install.me". This program will perform the tasks required to install + _MHonArc_ on you machine. The install program is capable of running + interactively, or in batch. + + Interactive Mode + + To run install.me in interactive mode, type the following at your + shell's prompt: + + perl install.me + + _NOTE_ + Make sure you are in the same directory as the install.me + program. + + The program will then prompt you for the necessary information to + install _MHonArc_ on your system. + + Here's an example (Unix) session: + +% perl install.me +MHonArc Installation +==================== +The installation process will ask you a series of questions on where +the Perl executable is and where to put MHonArc files. Just hit +to accept the default values listed in ()'s. + +If directory path does not exist on your system, the installation +program will create the path for you. + +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +Note: Make sure all pathnames are absolute. +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + +Hit to continue ... +Perl executable ("/usr/local/bin/perl") +\-> /usr/bin/perl +Location to install programs ("/usr/local/bin") +\-> /mnt/ehood/bin +Location to install libraries ("/usr/local/lib/MHonArc") +\-> /mnt/ehood/lib/MHonArc +Install documentation ("y")? y +Location to install docs ("/usr/local/lib/MHonArc/doc") +\-> /mnt/ehood/lib/MHonArc/doc + +You've specified the following: + Perl location: /usr/bin/perl + Program directory: /mnt/ehood/bin + Library directory: /mnt/ehood/lib/MHonArc + Doc directory: /mnt/ehood/lib/MHonArc/doc +Is this correct ("y")? y +Installing the following into /mnt/ehood/bin + mhonarc +Installing the following into /mnt/ehood/lib/MHonArc + base64.pl + mhexternal.pl + mhtxthtml.pl + mhtxtplain.pl + mhtxtsetext.pl + qprint.pl + readmail.pl +Installing the following into /mnt/ehood/lib/MHonArc/doc + mhonarc.txt + ... + + Batch Mode + + To run install.me in batch mode, type the following at your shell's + prompt: + + perl install.me install.cfg + + _NOTE_ + Make sure you are in the same directory as the install.me + program. + + The install.cfg contains the necessary information for intalling + _MHonArc_ on your system. You will need to edit install.cfg to reflect + your installation requirements. + + Here is an example install.cfg: + +# Should executables be installed. 0 => NO, non\-zero => YES. +# +$dobin = 1; + +# Should libraries be installed. 0 => NO, non\-zero => YES. +# +$dolib = 1; + +# Should documentation be installed. 0 => NO, non\-zero => YES. +# +$dodoc = 1; + +# Location for executable. If using ms\-dos, use something like +# 'C:\\\\BIN'. +# +$bindir = '/usr/local/bin'; + +# Location for libraries. If using ms\-dos, use something like +# 'C:\\\\LIB\\\\MHONARC'. +# +$libdir = '/usr/local/lib/MHonArc'; + +# Location for documents. If using ms\-dos, use something like +# 'C:\\\\DOC\\\\MHONARC'. +# +$docdir = '/usr/local/lib/MHonArc/doc'; + +# Location of perl executable. If using ms\-dos, use something like +# 'C:\\\\BIN\\\\PERL.EXE'. +# +$perlprg = '/usr/local/bin/perl'; + + +1; # DO NOT DELETE THIS LINE + + The file is Perl code, and therefore, must follow Perl syntax rules: + + * Anything following a `#' character is ignored. + * Strings values need to be enclosed in quotes. + * If you need to use a backslash in a string value, it must be + escaped with a backslash. Example: 'C:\\\\LIB\\\\MHONARC'. The same + applies to the '$' character. + * All statements must end with a semi\-colon. + * The "1;" line must not be deleted. + + _NOTE_ + You can verify the syntax of the configuration file by invoking + "perl \-c" on the file. + + After you have successfully executed install.me, _MHonArc_ is ready to + use. + + MS\-DOS Post install.me Note + + If you would like the ability to run _MHonArc_ like other programs, + then create a batch file that contains something like the following: + +@ECHO OFF +C:\\BIN\\PERL.EXE C:\\BIN\\MHONARC %1 %2 %3 %4 %5 %6 %7 %8 %9 + + Of course, you will need to change the paths to Perl and _MHonArc_ to + suit your systems configuration. + + Sample batch files are available in the _MHonArc_ distribution. + + Notes on install.me + + * If you do not know the location of the Perl executable on your + system, ask your system administrator. + * All pathnames must be absolute. + * If a path does not exist that you specify, the path will be + automatically created if running in interactive mode. In batch + mode, all paths specified must already exist. + * During the installation process, the main _MHonArc_ source file is + modified to be aware of the location of the Perl executable and + _MHonArc_'s library files. If you ever need to install _MHonArc_ + in a different location, rerun the install.me program. + _NOTE_: Location of the Perl exectuble is only relevant for Unix + systems. MS\-DOS systems do not make use of the "#!" line in + scripts. + * _MHonArc_ requires the use of timelocal.pl and newgetopt.pl. These + libraries are part of the normal Perl distribution. + + _________________________________________________________________ + +Tested Environments + + This section covers software environments _MHonArc_ has worked + successfully. Feedback is welcome about other success, or failure, + stories covering _MHonArc_ usage in other environments. + + Perl + + _MHonArc_ is known to work with the following version of Perl 4, or + later: + + $RCSfile: perl.c,v $$Revision: 4.0.1.7 $$Date: 92/06/08 14:50:39 $ + Patch level: 34 + + _MHonArc_ is known also to work with Perl 5.001m and Perl 5.002 beta2. + + _NOTE_ + The version numbers are based upon the Unix versions of Perl. + DOS version numbers may differ. + + Unix + + Mail Software + + * _MH_ + * _Elm_, _Mail_, _mail_, and any other mail software that stores + e\-mail in UUCP style mailbox format. UUCP format is where mail + messages are separated by a line beginning with "From " (I.e. the + word "From" followed by a space). You may need to utilize the + MSGSEP resource if the message separator is different from + standard mailbox files (eg. MMDF format). + + News Software + + Different news software store messages differently. Messages are + either stored in a format similiar to _MH_ or similiar to a mailbox + file: + + * _MH_ style is where the messages are stored in a directory with + each post a separate file, and each file has a numeric filename. + * Mailbox style is where messages are stored in a single file. You + may need to utilize the MSGSEP resource if the message separator + is different from standard mailbox files. + + MS\-DOS + + Mail/News Software + + _MHonArc_ has been tested under MS\-DOS with message files created by + the following mail and news programs: + + * _Eudora_ + * _WinVN_ + * _Windows Trumpet_ + * _NUPop_ + + It also works with individual RFC822 mail messages, but you must run + _MHonArc_ without a batch file if you need to use redirection. For + example: + + perl c:\\bin\\mhonarc one.htm + perl c:\\bin\\mhonarc \-add /inbox + + Where represents the path to the directory that contains the + mail folder _inbox_. If you are in the directory that contains inbox, + then you can leave out the "/". + + _MHonArc_ prints out messages showing its progress as your e\-mail is + processed. When _MHonArc_ finishes, the following files will be + created: + + * maillist.html: The main index file containing links to all mail + messages converted. Messages are listed with subjects and who the + messages are from. All messages are listed in sorted order by date + received/sent. + * threads.html: The file listing messages by thread. + * msg*.html: HTML versions of the mail messages, where * represents + a message number from 0 to the number of message processed minus + 1. + * .mhonarc.db (or MHONARC.DB under MS\-DOS): This database file is + needed inorder for _MHonArc_ to perform additions of new mail + messages to the archive. Information is stored to perform mail + threading updates when new messages are added, as well as any + resources set via Environment variables, Resource File, and/or + command\-line Options. + * _Other_: Depending on the content\-types of the e\-mail messages + converted, other files may be created for images, videos, + binaries, etc. See the section on MIME for more information. + + The format of each converted mail message is as follows: + + * A is inserted in the + HEAD element of HTML mail message file. This allows readers of the + message to send comments to the author of the mail message within + Web browsers that support such functionality (like _Lynx_). + * The title (i.e. TITLE element) contains the subject of the + message. + * Hyperlinks to the previous and next messages and the index pages + are located at the top of the message. + * Next, the subject appears in a H1 element. + * Next, follows the mail header with fields listed in a UL element + surrounded by HR's. + * Next, the actual body of the mail message. + * Next, links to any follow\-up, or referenced, messages. The + messages are listed by subject and who they are from. These links + allows you to easily follow mail threads. + * Last, are verbose links to the previous mail message, next mail + message, and index pages. + + The following is also done for each mail message processed: + + * Links are created in the "References" and "In\-Reply\-To" header + fields, and possibly the message body, if the destination + message\-ids are being processed. + * E\-mail addresses are converted to "mailto" hyperlinks in "To:", + "From:", "Cc:", and "Sender:" mail header fields. Currently, not + all Web browsers support the mailto URL. + * Newsgroups listed in a "Newsgroups:" mail header field are + converted to news hyperlinks. + + _MHonArc_ allows you to specify more than one mail folder to process + on the command\-line. + + _Example_ + % mhonarc /home/ehood/mail/inbox1 /home/ehood/mail/inbox2 ... + + All the files created will be put into the current working directory, + by default. You can control the destination of the output location by + using the \-outdir option. + + _Example_ + % mhonarc \-outdir /home/ehood/htmlarchive + /home/ehood/mail/inbox + + Here is a sample session converting a mail folder: + +% mhonarc ~/mail/inbox +Requiring MIME filter libraries ... + mhexternal.pl + mhtxthtml.pl + mhtxtplain.pl + mhtxtsetext.pl +Converting messages to ./maillist.html +Reading /mnt/ehood/mail/inbox .......... +Writing mail ... +Writing tmp/maillist.html ... +Writing tmp/threads.html ... +10 messages + + _________________________________________________________________ + +Adding Messages to an Archive + + If you have new messages you want to add to an existing archive, you + must utilizing the \-add command\-line option. With the \-add, you can do + the following: + + * Add a mail folder to an archive, or + * Add a single message to an archive. + + Adding a mail folder to an archive in the current working directory + can be done like the following: + + % mhonarc \-add /mailfolder + + If you are not in the same directory as the archive, then you can + specify the location of the archive to add to with the \-outdir option: + + % mhonarc \-add \-outdir /mailfolder + + _NOTE_ + _MHonArc_ will skip any messages that already exist in the + archive. Therefore, _MHonArc_ can be used to rescan the same + mail folder and only convert any new messages it finds. + + If no mail folder arguments are specified, then _MHonArc_ will attempt + to add a _single_ message read in from standard input. + + _Example_ + % mhonarc \-add < single.msg + + Or, from a pipe: + + % cat single.msg | mhonarc \-add + + See the section on Adding Messages for more information and examples + for adding messages to an archive. + + _________________________________________________________________ + +Converting a single message + + _MHonArc_ has the ability to process a single mail message independent + of creating, or modifying, and archive. To convert a single message to + HTML use the \-single command\-line option. The message to process can + be specified by a filename on the command\-line, or by reading the + message from standard input if no file is specified. The filtered + message is sent to standard output. All formatting options apply to + the single message as with messages being processed for an archive, + with the exception of formatting related specificly to archive + processing, like index links and mail thread links. + + Examples + + Input from standard input: + % mhonarc \-single < messagefile > file.html + + Filename on command\-line: + % mhonarc \-single messagefile > file.html + + _________________________________________________________________ + + + _________________________________________________________________ + + Overview + + This section gives an overview of _MHonArc_'s command\-line options and + environment variables. The _MHonArc_ resource file is covered in the + section Resource File. The resource file allows you to specify most of + the resources set by environment variables and command\-line options, + plus it give you the capability of completely customizing the HTML + output generated by _MHonArc_. + + _________________________________________________________________ + +Synopsis + + Invoke _MHonArc_ from your shell with the following syntax: + + % mhonarc [_options_] _mhfolder_... + % mhonarc [_options_] _mailbox_ ... + % mhonarc \-add [_options_] < _message_ + % mhonarc \-single [_options_] < _message_ > _message.html + _% mhonarc \-single [_options_] _message_ > _message.html + _% mhonarc \-rmm [_options_] _msg# _..._ + _ + _________________________________________________________________ + +Options + + The following options are available: + + \-add + + Add new messages to an existing archive. If no mail folder arguments + are given, _MHonArc_ assumes that a _single_ message is being added to + the archive via _standard input_. Otherwise, _MHonArc_ adds the + messages contained in the mail folders specified. + + \-dbfile name + + 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 + + Use _url_ as the URL to _MHonArc_ documentation. The default is + "http://www.oac.uci.edu/indiv/ehood/mhonarc.html". + + \-editidx + + This option tells _MHonArc_ to rewrite the index page and re\-edit all + mail messages in the archive. This option is useful if you need to + change the layout of the index page and/or messages. + + \-footer filename + + Insert contents of filename at the bottom of the index page. See + Include Files in Index Page Customization for more information about + the footer file. + + \-force + + Override a lock on an archive if attempts to lock fail. I.e. After + trying unsuccessfully to lock an archive, _MHonArc_ will still perform + the actions requested. + + This option is useful to help dealing with locks that are no longer + valid (i.e. _stale locks_). A stale lock can exist if the _MHonArc_ + process that created the lock abnormally terminated and could not + perform the proper cleanup procedures. + + \-genidx + + Output an index page to standard output based upon the contents of an + archive, and utilizing any extra formatting options specified. + + \-header filename + + Insert contents of _filename_ at the beginning of the index page. See + Include Files in Index Page Customization for more information about + the header file. + + \-help + + Print out a help message about _MHonArc_. + + \-idxfname name + + Sets the name of the main index file to _name_. The default is + "maillist.html". + + \-idxsize # + + Set the maximum number of messages listed in the indexes. + + \-lockdelay # + + The sleep time, in seconds, between attempts to lock the archive. The + default value is 3. + + \-locktries # + + Set the number of time _MHonArc_ tries to lock a mail archive before + processing new messages. The default value is 10. _MHonArc_ waits + approximately 3 seconds before each try. + + See Archive Integrity for more information on the \-locktries options. + + \-mailtourl url + + Use _url_ for e\-mail address hyperlinks in mail message headers. The + url can contain the following _variables_ that get expanded during + run\-time: + + $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. + + The default URL is "mailto:$TO$" + + The \-mailtourl option has no effect if the \-nomailto option is + specified. + + \-maxsize # + + Set the maxinum number of messages allowed in the archive to _#_. If + messages are added to the archive which would cause the total number + of messages to exceed _#_, older messages (based on sort method) are + removed automatically. + + \-msgsep expression + + Use the _expression_ as the Perl regular expression that signifies the + message separator in Unix mailbox files. The default expression is + "^From " (minus the quotes). + + _NOTE_ + There is a space character after the From. + + \-nodoc + + Do not print link to documentation at end of 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 index + page. + + \-nosort + + Do not sort messages by date. Messages will be in the order they + appear in the mailboxes/folders. By default, _MHonArc_ sorts messages + by date sent/received. + + \-nosort takes precedence over the \-sort option. + + \-nothread + + Do not create a thread index page. + + \-notsubsort + + Do not sort threads by subject on thread index page. + + \-notreverse + + List threads in the thread index with oldest thread first. + + \-outdir path + + Set destination/location of the HTML mail archive to _path_. By + default, the current working directory is used. + + \-quiet + + Suppress processing messages when _MHonArc_ is running. + + \-rcfile file + + Use file as the resource file for _MHonArc_. _MHonArc_ does the + following to determine the location of file: + + 1. If its an absolute pathname, use it. + 2. If it is a relative pathname, check for it relative to the current + working directory. + 3. Otherwise, check for it relative to the location of the archive. + + See Resource File for more information. There is no default resource + file. + + \-reverse + + List messages in reverse order of the sorting option specified. For + example, if date sorting is specified, \-reverse will cause messages to + be listed in _reverse_ chronological order. + + \-rmm + + All non\-option command\-line arguments are treated as messages to + remove from the archive. Messages to remove are denoted by their + message numbers. + + \-savemem + + Normally, all messages are stored in memory and then written in one + shot. This option causes _MHonArc_ to write the message data as it is + processesd. This option will cause a slow down in execution time as + more disk I/O required, but it may allow large amounts of data to be + processed in a single process if memory is limited. + + _NOTE_ + The reason more disk I/O is required is that when the message + data is first written, all the archive navigational link + information is non\-existant. The information required to + correctly generate the navigational link information will not + exist until all messages are processed. Therefore, each new + message file must be reopened to add in the navigational link + information after all messages are processed. + + \-scan + + List contents of archive to standard output. + + \-single + + Convert a single mail message to HTML. The message can be specified by + a filename on the command\-line, or read from standard input if no file + is given. The filtered message is sent to standard output. + + The \-single option is useful tp convert individual messages to HTML + not related to a specific mail archive. Any option related to how + message formatting can be used with the \-single option. + + The \-single takes precedence over the \-add option. + + \-sort + + Perform chronological date sorting. This is the default. + + \-subsort + + Sort messages by subject. Subject sorting is case\-insensitive, and + begining "Re:", "A", "An", and "The" words are ignored. + + \-tidxfname name + + Sets the name of the thread index file to _name_. The default is + "threads.html". + + \-time + + Print out total CPU execution time taken when processing messages. + Time information is written to standard error. + + \-title string + + Set the title of the main index page to _string_. The default is + "_Mail Index_". + + \-thread + + Create a thread index page. This is the default. + + \-tlevels + + Set the maximum number of nested lists for the thread index page. The + default is 3. + + \-treverse + + List threads in the thread index with newest thread first. + + \-tsubsort + + List threads in the thread index by subject. + + \-ttitle string + + Set the title of the thread index page to _string_. The default is + "_Mail Thread Index_". + + \-umask umask + + Set the umask of the _MHonArc_ process to _umask_. The value is + treated as an octal number. + + NOTE + + The \-no* options always take precedence over their counterparts. For + example, if \-noreverse and \-reverse are both specified on the + command\-line, the \-noreverse will be applied. + + _________________________________________________________________ + +Environment + + _MHonArc_ supports the use of environment variables. The environment + variables allow you to set default options everytime you invoke + _MHonArc_. The following environment variables may be used: + + M2H_DBFILE + + Sets 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. + + M2H_DOCURL + + Set the URL used to point to _MHonArc_ documentation. The default is, + "http://www.oac.uci.edu/indiv/ehood/mhonarc.html". + + M2H_FOOTER + + Set the HTML footer file to insert at the bottom of the index page. No + default footer file is defined. See Include Files in Index Page + Customization for more information about the footer file. + + M2H_HEADER + + Set the HTML header file to insert at the top of the index page. No + default header file is defined. See Include Files in Index Page + Customization for more information about the header file. + + M2H_IDXFNAME + + Set the name of the index file. The default is, "maillist.html". + + M2H_IDXSIZE + + Sets the maximum number of messages listed in the indexes. + + M2H_LOCKFILE + + The sleep time, in seconds, between attempts to lock the archive. The + default value is 3. + + M2H_LOCKFILE + + Set the name of the lock file. The default name use is ".mhonarc.lck" + (or "MHONARC.LCK" under MS\-DOS). + + _NOTE_ + You should not change the default unless absolutely necessary. + + See Archive Integrity for more information about the lock file. + + M2H_LOCKTRIES + + Set the number of time _MHonArc_ tries to lock a mail archive before + processing new messages. The default value is 10. _MHonArc_ waits + approximately 3 seconds before each try. + + See Archive Integrity for more information on the M2H_LOCKTRIES + environment variable. + + M2H_MAILTOURL + + Sets the URL for e\-mail address hyperlinks in mail message headers. + The URL can contain the following _variables_ that get expanded during + run\-time: + + $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. + + The default URL is "mailto:$TO$" + + M2H_MAXSIZE + + Sets the maximum number of messages that an archive will contain. If + messages are added to the archive which would cause the total number + of messages to exceed M2H_MAXSIZE, older messages (based on sort + method) are removed automatically. + + M2H_OUTDIR + + Sets the destination/location of the HTML mail archive. The default is + the current working directory. + + M2H_RCFILE + + Specifies the Resource File for _MHonArc_. No default resource file is + defined. + + M2H_THREAD + + Flag to determine if _MHonArc_ generates a thread index. If set to + zero, the thread index will not be created. The default behavior is to + create a thread index. + + M2H_TIDXFNAME + + Sets the name of the thread index file. The default is "threads.html". + + M2H_TITLE + + Sets the default title of the index page. The default is "_Main + Index_". + + M2H_TLEVELS + + Sets the maximum number of nested lists for the thread index page. The + default is 3. + + M2H_TTITLE + + Sets the title of the thread index page. The default is "_Mail Thread + Index_". + + NOTE + + Environment variables may be overriden by the Resource File or + command\-line Options. + + _________________________________________________________________ + + + _________________________________________________________________ + + 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: + + * 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 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_: "". + 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. + + 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: + + * $SUBJECT$ + * $FROMNAME$ + * $SUBJECT:50$ + * $SUBJECTNA:60U$ + * $FROMADDR:U$ + + 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: + + +UTC:0 +GMT:0 +AST:4 +ADT:3 +EST:5 +EDT:4 +CST:6 +CDT:5 +MST:7 +MDT:6 +PST:8 +PDT:7 + + + 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 test + + + +MHonArc test + + + + + + +
+Last updated: $LOCALDATE$
+$NUMOFMSG$ messages in chronological order
+
+ +

+Listing format is the following: +

+

  • +Subject +(# of follow\-ups) +From
    +
+

+

+
    + + + + + +
  • +$SUBJECT:40$ +($NUMFOLUP$) $FROMNAME$
    + + + +
+

+

+ +Home + +

+ + + + +

+Thread index
+Last updated: $LOCALDATE$
+$NUMOFMSG$ messages
+
+ +
+ + + + +apparently +errors\-to +followup +forward +lines +message\-id +mime\- +nntp\- +originator +path +precedence +received +replied +return\-path +status +via +x\- + + + +\-default\- +subject:strong +from:strong +to:strong + + + +\-default\- +subject:strong +from:strong +to:strong +keywords:em +newsgroups:strong + + + +
+MHonArc test archive +
+ + + + +Home | +Main Index | +Thread Index + + + + + +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 + + + _________________________________________________________________ + +Notes on Resource File + + * 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. + + _________________________________________________________________ + + + _________________________________________________________________ + + Adding Messages + + Adding messages to an archive is done via the \-add option. If no + mailbox/folder arguments are given, _MHonArc_ assumes that a _single_ + message is being added to the archive via _standard input_. Otherwise, + _MHonArc_ adds the messages contained in the mail folders specified. + + _NOTE_ + _MHonArc_ will skip any messages that already exist in an + archive. If a message to be added has a message\-ID that equals + a message\-ID of an archived message, the message is skipped. + + _________________________________________________________________ + +Examples + + Adding a mail folder + + Here is example session adding an mail folder to an existing archive: + +% mhonarc \-add test/www +Requiring MIME filter libraries ... + mhexternal.pl + mhtxthtml.pl + mhtxtplain.pl + mhtxtsetext.pl +Adding messages to ./maillist.html +Reading test/www/ ........................................ +Writing HTML ... +49 messages + + .forward + + _MHonArc_ can be used to add new messages as they are received by + using the ".forward" file in your home directory. Here is how I would + set up my .forward file to invoke _MHonArc_ on incoming mail: + +\\ehood, "|/mnt/ehood/bin/webnewmail #ehood" + + _NOTE_ on .forward entry: + The "\\ehood" tells sendmail to still deposit the incoming + message to my mail spool file. The "#ehood" Bourne shell + comment is needed to insure the command is unique from another + user. Otherwise, sendmail may not invoke the program for you or + the other user. + + "webnewmail" is a Perl program that calls _MHonArc_ with the + appropriate arguments. A wrapper program is used instead of calling + _MHonArc_ directly to keep the .forward file simple. Here is the code + to the webnewmail program: + +#!/usr/local/bin/perl + +$cmd = "/mnt/ehood/bin/mhonarc \-add \-quiet " . + "\-outdir /mnt/ehood/public_html/newmail"; +open(M2H, "|$cmd"); +print M2H ; +close(M2H); + + The webnewmail can be modified to check the mail header before calling + _MHonArc_ to perform selective archiving of messages. For example, + webnewmail can check the To: field and only archive messages that come + from a specific mailing list. + + Cron + + This example uses cron(1) to update some mail archives from MH mail + folders. + + The following entry is in my crontab file: + +0 0 * * * webmail + + webmail is a script executed every night that calls _MHonArc_ to + perform the update: + +#! /bin/csh \-f + +umask 022 +setenv M2H_RCFILE $HOME/.mhonarc.rc +## WWW messages +mhonarc \-add \\ + \-outdir $HOME/public_html/doc/wwwmail \\ + $HOME/mail/www +folder +www >& /dev/null +refile first\-last +www.ar >& /dev/null # Archive original messages + +## Tools messages +mhonarc \-add \\ + \-outdir $HOME/public_html/doc/toolsmail \\ + $HOME/mail/tools $HOME/mail/dtd +folder +tools >& /dev/null +refile first\-last +tools.ar >& /dev/null # Archive original messages +folder +dtd >& /dev/null +refile first\-last +dtd.ar >& /dev/null # Archive original messages + +folder +inbox >& /dev/null # Set current folder to inbox + + + To avoid mail everynight from cron due to output from _MHonArc_, the + \-quiet option can be used for each call to _MHonArc_, or use the + following line in your crontab file: + +0 0 * * * webmail > /dev/null + + Standard error is not redirected to /dev/null so mail is still + received if errors occured during _MHonArc_ execution. + + _________________________________________________________________ + + + _________________________________________________________________ + + Removing Messages + + Removing messages from an archive is done via the \-rmm option. + Messages to be deleted are designated by message numbers on the + command\-line. + + _Example_ + +% mhonarc \-rmm 24 28 39 48 +Removing messages from ./maillist.html ... + Removing message 24 + Removing message 28 + Removing message 39 + Removing message 48 + +Writing mail ... +Writing tmp/maillist.html ... +Writing tmp/threads.html ... +45 messages + + _________________________________________________________________ + +Message Numbers + + Normally, you will never have to worry about message numbers unless + you want to remove messages from an archive. Therefore, you will need + to know how _MHonArc_ assigns message numbers when processing + messages. + + When a message is processed, the smallest available number is assigned + to it, starting with 0. The number assigned to a message becomes part + of the filename for the HTML version of the message (eg. + msg00042.html). + + To avoid message number conflicts, _MHonArc_ determines the smallest + available number by finding the largest assigned number and adding one + to it. + + _________________________________________________________________ + +Scanning an Archive + + You will quickly find out that finding the message numbers for a + messages you want to remove can be a cumbersome task if all you have + to work with are the message filenames. To ease this task, _MHonArc_ + gives you the ability to scan an archives contents via the \-scan + command\-line option. + + Example + +% mhonarc \-scan +100 messages in .: + +Msg # YY/MM/DD From Subject +\-\-\-\-\- \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 513 95/02/09 Rick Silterra EDComment(sic) + 517 95/02/09 Earl Hood Re: DTD2HTML + 512 95/02/09 Earl Hood Re: edc2html + 516 95/02/09 John Barnum Re: DTD2HTML + 515 95/02/09 Earl Hood Re: DTD2HTML + 511 95/02/09 Rick Silterra edc2html + 514 95/02/08 John Barnum DTD2HTML + 510 95/02/06 jflores mhonarc_diagnostics.doc.html + 509 95/02/06 web Dr.Web: Status Review + Thank You + 508 95/02/05 Earl Hood Re: sgml to html converters + 507 95/02/03 Aileen Barry sgml to html converters + 506 95/01/28 Earl Hood Re: MHonarc: Deleting Messages from an archiv + 505 95/01/28 Floyd Moore MHonarc: Deleting Messages from an archive + 504 95/01/25 Earl Hood Re: MHonArc + 503 95/01/25 Earl Hood Re: MHonArc +... + + The messages are listed in the same order as they are listed in the + archive's index page. You will notice that the list order does not + necessarily correspond with message number order. If you always want + the messages listed in message number order when scanning, use the + following: + +% mhonarc \-scan \-nosort \-noreverse +82 messages in .: + +Msg # YY/MM/DD From Subject +\-\-\-\-\- \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 0 94/05/09 Michael O´Sulli Re: Finger within an html + 1 94/04/31 John M. Troyer Re: TROFF to HTML Converters + 2 94/05/04 John D. Kilburg ANNOUNCE: Chimera 1.53 + 3 94/05/17 Stephen Billing Re: government www? + 4 94/05/21 C. Emory Tate Re: government www? + 5 94/05/24 Daniel W. Conno Re: Comments on HTML 2.0 document/DTD + 6 94/05/24 Dan Connolly Re: Validating HTML documents: + 7 94/05/25 Henrik Frystyk CERN Common World\-Wide Web Library 2.16pre2 A + 8 94/06/04 Denesh Bhabuta Re: Atari on www (revisited) + 9 94/06/07 Dale Newfield ANNOUNCE: Come explore The Edge \- SIGGRAPH 94 + 10 94/06/11 Roy T. Fielding Announcing libwww\-perl 0.12 +... + + _________________________________________________________________ + + + _________________________________________________________________ + + Index Page Customization + + _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. + + _________________________________________________________________ + +Filename + + 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. + + _________________________________________________________________ + +Beginning Markup + + _MHonArc_ allows you to completely override the begining markup of the + index page. I.e. You can control the opening tag, the HEAD + element contents, the opening 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: + + + + + +$IDXTITLE$ + + +

$IDXTITLE$

+ + + _NOTE_ + 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. + + _________________________________________________________________ + +End Markup + + 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: + + + + + + + The resource variables allowed are the same as for IDXPGBEGIN. + + _________________________________________________________________ + +Include Files + + _MHonArc_ allows you to include the contents of files into the index + page via the header and footer resources. + + _NOTE_ + 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. + + _NOTE_ + Filename should not contain the , , and + 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. + + _NOTE_ + Filename should not contain the , and 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. + + _________________________________________________________________ + +Listing Layout + + _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: + + + +
+
    + + + If the NOTHREAD resource is set, the following is the default value: + + +
    +
      + + + 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. + + _NOTE_ + 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: + + +
    • $SUBJECT$ +
      • From: $FROM$
      +
      • +       + + 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: + + +
    + + + _________________________________________________________________ + +Icons + + _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. + + Defining Icons + + 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: + + __:__ + + __ represents a MIME content\-type. __ 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. + + Example + + +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 + + + Using Icons + + In order to incorporate icons into the index page, insert the $ICON$ + variable into the LITEMPLATE resource element. + + Example + + +$ICONURL$$SUBJECT:40$ +($NUMFOLUP$) $FROMNAME$
    +     + + 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. + + Example + + +* $SUBJECT:40$ +($NUMFOLUP$) $FROMNAME$
    +     + + This example overrides what is normally used in the ALT attribute. + + _________________________________________________________________ + +Examples + + Example 1 + + It may be easier to see how the LISTBEGIN, LITEMPLATE, LISTEND + resource elements work when declared together: + + + + +
    +
      + + + +
    • $SUBJECT$ +
      • From: $FROM$
      +
      • +       + + +
    + + + Example 2 + + 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: + + +
    +Last update: $CURDATE$
    +$NUMOFMSG$ messages
    +
    +

    +

    +

    +Messages listed in chronological order. Listing format is the following: +

    +* +Subject +(# of follow\-ups) +From. +
    +

    +

    +     + + +* $SUBJECT:40$ +($NUMFOLUP$) $FROMNAME$
    +     + + + + + _________________________________________________________________ + + + _________________________________________________________________ + + Message Customization + + This sections shows how to customize the appearance of messages when + converted to HTML. + + _________________________________________________________________ + +Beginning Markup + + _MHonArc_ allows you to completely override the begining markup of the + message pages. I.e. You can control the opening tag, the HEAD + element contents, the opening 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: + + + + + +$SUBJECTNA:72$ + + + + + + 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. + + _________________________________________________________________ + +End Markup + + 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: + + + + + + + The resource variables allowed are the same as for MSGPGBEGIN. + + _________________________________________________________________ + +Header and Footer + + 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. + + _________________________________________________________________ + +Navigational Links + + _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: + + +
    +$PREVBUTTON$$NEXTBUTTON$[Index][Thread] +     + + 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: + + +
    +
      +$PREVLINK$ +$NEXTLINK$ +
    • Index(es): +
        +
      • Main
        • +
      • Thread
        • + + + If no thread index is specified, then the thread link markup is + removed. The variables available for BOTLINKS are the same as for + TOPLINKS. + + Conditional Links + + 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 + + +[Prev] + + + NEXTBUTTON + + +[Next] + + + PREVLINK + + +
      • Prev: $PREVSUBJECT$
        • +         + + NEXTLINK + + +
      • Next: $NEXTSUBJECT$
        • +         + + All the "IA" elements default to empty content. + + _NOTE_ + 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. + + _WARNING_ + 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. + + _________________________________________________________________ + +Message Layout + + 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). + + Excluding Fields + + The EXCS resource allows you to specify what fields should be excluded + in the HTML output. + + 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_). + + The default value for EXCS is the following: + + +content\- +errors\-to +forward +lines +message\-id +mime\- +nntp\- +originator +path +precedence +received +replied +return\-path +status +via +x\- + + + 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. + + Field Order + + The FIELDORDER resource allows you to control the order the message + header fields appear in the HTML output. + + 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. + + The following represents the default value of the FIELDORDER resource: + + +to +subject +from +date +\-extra\- + + + Field Formatting + + The FIELDSTYLES and LABELSTYLES resources allow to control how each + message header field is formatted. + + 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. + + The default value of FIELDSTYLES is the following: + + +\-default\- + + + 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. + + The default value of LABELSTYLES is the following: + + +\-default\-:em + + + _________________________________________________________________ + +Other Resources + + E\-mail Links + + MAILTOURL + + 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$". + + _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. + + _________________________________________________________________ + + + _________________________________________________________________ + + MIME + + _MHonArc_ has support for e\-mail messages with _Multipurpose Internet + Mail Extensions_ (MIME) as defined in RFC 1521. _MHonArc_ handles the + filtering of the various content\-types used in MIME in a modular + fashion. Since new content\-types are occasionally defined for MIME, + this modularity allows users to add new filters to accomodate new + content\-types. Also, filters can be hooked in to override _MHonArc's_ + default filters, or provide _MHonArc_ with the ability to process + existing content\-types that it cannot handle currently. + + _________________________________________________________________ + +Default Filters + + The default filters provided by _MHonArc_ supports the following MIME + content\-types, which may be overriden by user\-defined filters: + + * application/* + * audio/* + * image/* + * message/news + * message/partial + * message/rfc822 + * multipart/alternative + * multipart/digest + * multipart/mixed + * multipart/parallel + * text/html + * text/plain + * text/setext + * video/* + + For more information on how to write your filters, or replace existing + filters, see Writing Filters. + + The next sections describes how _MHonArc_ processes the content\-types + listed above. + + application/* + + _MHonArc_ extracts the data into a separate file and puts a hyperlink + to the file into the HTMLized message. + + By default, _MHonArc_ ignores any filename specification (the "_name_" + attribute as defined in the Content\-Type header field) given in the + message when writing the data to disk. _MHonArc_ generates a unique + filename with an extenstion based upon sub\-type. + + If you want _MHonArc_ to use the filename, then you can use the + MIMEARGS resource and specify an argument string of "usename". + + Example: + + +application/postscript:usename + + + If you want _MHonArc_ to use specified filename for all application + types, then use the following: + + +application/*:usename + + + _CAUTION_ + The use of "usename" is discouraged since it can lead to + filename conflicts and security problems. + + Here is the current list of _application_ sub\-types (with their + filename extensions) supported by _MHonArc_: + + * mac\-binhex40 (hqx) + * octet\-stream (bin) + * oda (oda) + * pdf (pdf) + * postscript (ps) + * rtf (rtf) + * x\-bcpio (bcpio) + * x\-cpio (cpio) + * x\-csh (csh) + * x\-dvi (dvi) + * x\-gtar (gtar) + * x\-hdf (hdf) + * x\-latex (latex) + * x\-mif (mif) + * x\-netcdf (cdf) + * x\-patch (_no extension_; processed by the text/plain filter) + * x\-sh (sh) + * x\-shar (shar) + * x\-sv4cpio (sv4cpio) + * x\-sv4crc (sv4crc) + * x\-tar (tar) + * x\-tcl (tcl) + * x\-tex (tex) + * x\-texinfo (texinfo) + * x\-troff (roff) + * x\-troff\-man (man) + * x\-troff\-me (me) + * x\-troff\-ms (ms) + * x\-ustar (ustar) + * x\-wais\-source (src) + * zip (zip) + + audio/* + + _MHonArc_ extracts the data into a separate file and puts a hyperlink + to the file into the HTMLized message. The name of the file created + follows the same guidelines mentioned under application/*. + + Here is the current list of _audio_ sub\-types (with their filename + extensions) supported by _MHonArc_: + + * basic (snd) + * x\-aiff (aif) + * x\-wav (wav) + + image/* + + _MHonArc_ will extract the data into a separate file and puts a + hyperlink to the file into the HTMLized message. The name of the file + created follows the same guidelines mentioned under application/*. In + addition to the filename specification mentioned under application/*, + an "inline" argument may be declared to instruct _MHonArc_ to inline + the image in the generated HTML. + + Example: + + +image/gif:inline + + + The following examples says to inline XBM images and use the name + attribute as the filename if defined: + + +image/x\-xbm:inline usename + + + The following represents the default argument settings used by + _MHonArc_: + + +image/gif:inline +image/x\-xbitmap:inline +image/x\-xbm:inline + + + Here is the current list of _image_ sub\-types (with their filename + extensions) supported by _MHonArc_: + + * gif (gif) + * ief (ief) + * jpeg (jpg) + * tiff (tif) + * x\-bmp (bmp) + * x\-cmu\-raster (ras) + * x\-pcx (pcx) + * x\-pict (pict) + * x\-portable\-anymap (pnm) + * x\-pnm (pnm) + * x\-portable\-bitmap (pbm) + * x\-pbm (pbm) + * x\-portable\-graymap (pgm) + * x\-pgm (pgm) + * x\-portable\-pixmap (ppm) + * x\-ppm (ppm) + * x\-rgb (rgb) + * x\-xbitmap (xbm) + * x\-xbm (xbm) + * x\-xpixmap (xpm) + * x\-xpm (xpm) + * x\-xwindowdump (xwd) + * x\-xwd (xwd) + + If the image is a GIF or XBM (X bitmap), the HTML IMG element will be + used to in\-line the image into the HTMLized message. + + message/news + + _message/news_ signifies an included (MIME) USENET news message. The + data associated with a _message/news_ part is processed by _MHonArc_ + in the same manner as a regular mail message. + + message/partial + + _message/partial_ signifies that the content is a single part of a + message split into multiple mail messages. _message/partial_ is + treated in the same manner as text/plain. + + message/rfc822 + + _message/rfc822_ signifies an included (MIME) mail message. The data + associated with a _message/rfc822_ part is processed by _MHonArc_ in + the same manner as a regular mail message. + + multipart/alternative + + _multipart/alternative_ signifies multiple content\-types with the same + (or similiar) information. _MHonArc_ processes only the latest part + that has a content\-type filter. + + multipart/digest + + mulltipart/digest signifies a series of included mail messages. Each + part is processed in the same manner as message/rfc822 unless an + explicit content\-type is specifed for each part. + + multipart/mixed + + _multipart/mixed_ signifies data with multiple content\-types. _MHonArc_ + extracts each part and calls the appropriate content\-type filter for + each part, if defined. + + multipart/parallel + + _multipart/parallel_ is processed in the same manner as + multipart/mixed. + + text/html + + _text/html_ signifies that the data is HTML markup. The data as left + "as is" with the exception of some processing to legally include the + HTML into the HTMLized mail message. I.e. _MHonArc_ removes the HEAD + an BODY tags, the TITLE element will be replaced with an ADDRESS + element surrounded by HR's, and the BASE element URL will be + propogated to relative URLs. + + text/plain + + _text/plain_ signifies ASCII character data. In the HTMLized message, + the data is wrapped in a PRE element with special characters (< > &) + converted to entity references. _MHonArc_ will also make any URLs into + hyperlinks. The following URL types are recognized: + + * http://... + * ftp://... + * afs://... + * wais://... + * telnet://... + * gopher://... + * news:... + * nntp:... + * mid:... + * cid:... + * mailto:... + * prospero:... + + text/setext + + _text/setext_ signifies "_structure enhanced text_". The data is + converted into HTML containing hyperlinks as defined by the _setext_ + data. For more information on _setext_, see + . + + video/* + + _MHonArc_ extracts the data into a separate file and puts a hyperlink + to the file into the HTMLized message. The name of the file created + follows the same guidelines mentioned under application/*. + + Here is the current list of _video_ sub\-types (with their filename + extensions) supported by _MHonArc_: + + * mpeg (mpg) + * quicktime (mov) + * x\-msvideo (avi) + * x\-sgi\-movie (movie) + + _________________________________________________________________ + +Non\-MIME Messages + + Messages that do not contain a MIME Content\-Type header field are + processed as text/plain messages. + + _________________________________________________________________ + +Writing Filters + + If you want to write your own filter for use in _MHonArc_, you need to + know the Perl programming language. The following information assumes + you know Perl. To learn how to hook in your filters into _MHonArc_, + see Specifying Filters. + + Function Interface of Filter + + _MHonArc_ interfaces with MIME filters by calling a routine with a + specific set of arguments. The prototype of the interface routine is + as follows: + +sub filter { + local($head, *fields, $data, $decoded, $argstring) = @_; + + # Filter code here + + # The last statement should be the return value, unless an + # explicit return is done. See the following for the format of the + # return value. +} + + Argument Descriptions + + $head + This is the header text of the message (or body part if called + in a mulitpart message). + + *fields + This is a pointer to an associative array that has broken down + $head into field label/field value components. The keys are the + lower\-case representations of the field values. _Example_: If + you would like to retrieve the value of the Content\-Type field, + then use the following: $fields{`content\-type'}. + + If a field occurs more than once in a header, _MHonArc_ + separates the field values in the associative array by a `\\034' + character. To make your filter less likely to break due to + changes in _MHonArc_, you may use the $'X variable instead of + `\\034'. + + $data + This is a copy of the message (or body part if called in a + mulitpart message) body. + + $decoded + This flag is set to 1 if _MHonArc_ decoded the message and + $data represents the orginal data before encoded by the sender. + If set to 0, $data has not been decoded. The failure to decode + occurs if _MHonArc_ does not recognizeed the encoding specified + in the Content\-Transfer\-Encoding field. + + _MHonArc_ has decoded the data for you if it was encoded in + 7\-Bit, 8\-Bit, Binary, Quoted\-Printable, Base64, or X\-Uuencode. + + $argstring + This is an optional argument string that may be used to modify + the behavior of the filter. The format of this string is + determined by the filter itself. + + The value of the string is set by the MIMEARGS resource. + + Return Value + + The return value is treated as an array. The first item in the array + is a string representing the HTML markup to insert in the HTMLized + message. An empty string may be returned to tell _MHonArc_ that the + routine was unable to filter data. + + Any other array items are treated as names of any files that were + generated by the filter. _MHonArc_ needs to keep track if any extra + files that a filter may generate in order for _MHonArc_ to delete + those files if the message gets removed from the archive. + + Filter Writing Tips + + The following recommendations/tips are given to help you write + filters: + + * Qualify your filter in its own package. This eliminates possible + variable/routine conflicts with _MHonArc_. + * If the filter creates derived files (like the image filters), you + may use the variable $'OUTDIR to determine the location of the + mail archive. + _NOTE_: _Do not include_ $'OUTDIR _as part as the filename that is + returned to_ _MHonArc_. _If the filter does create files, just + return the base name_. + * Look at the default filters contained in the distribution of + _MHonArc_. You can use these as templates for writing your own. + * Make sure your Perl source file ends with a true statement (like + "1;"). _MHonArc_ just performs a require on the file, and if the + file does not return true, Perl will abort execution. + + Using C + + If a MIME filter requires the utilization of a C program, or other + non\-Perl executable, a Perl wrapper must be written for the program + in\-order to interface with _MHonArc_. The wrapper must follow the + rules as specified in Function Interface of Filter. + + _________________________________________________________________ + +Specifying Filters + + Adding new filters, or overriding existing ones, are done via the + Resource File. The two resources for specifying and controlling MIME + filters are MIMEFILTERS and MIMEARGS. + + MIMEFILTERS + + The resource element MIMEFILTERS in the Resource File is used to hook + in user specifed filters into _MHonArc_. The syntax for each line of + the the MIMEFILTERS element is as follows: + + __:__:__ + + The definition of each colon\-separated value is as follows: + + __ + The MIME content\-type the filter processes. + + __ + The actual routine name of the filter. The name should be fully + qualified by the package it is definedi (e.g. + "mypackage'filter"). + + __ + The name of the file that defines __. If the file + is not a full pathname, _MHonArc_ finds the file by looking in + the standard include paths of Perl, and the paths specified by + the PERLINC resource element. + + Any whitespace is stripped out before processing. + + Example + + The following represents the default value of MIMEFILTERS: + + +application/mac\-binhex40:m2h_external'filter:mhexternal.pl +application/octet\-stream:m2h_external'filter:mhexternal.pl +application/oda:m2h_external'filter:mhexternal.pl +application/pdf:m2h_external'filter:mhexternal.pl +application/postscript:m2h_external'filter:mhexternal.pl +application/rtf:m2h_external'filter:mhexternal.pl +application/x\-bcpio:m2h_external'filter:mhexternal.pl +application/x\-cpio:m2h_external'filter:mhexternal.pl +application/x\-csh:m2h_external'filter:mhexternal.pl +application/x\-dvi:m2h_external'filter:mhexternal.pl +application/x\-gtar:m2h_external'filter:mhexternal.pl +application/x\-hdf:m2h_external'filter:mhexternal.pl +application/x\-latex:m2h_external'filter:mhexternal.pl +application/x\-mif:m2h_external'filter:mhexternal.pl +application/x\-netcdf:m2h_external'filter:mhexternal.pl +application/x\-patch:m2h_text_plain'filter:mhtxtplain.pl +application/x\-sh:m2h_external'filter:mhexternal.pl +application/x\-shar:m2h_external'filter:mhexternal.pl +application/x\-sv4cpio:m2h_external'filter:mhexternal.pl +application/x\-sv4crc:m2h_external'filter:mhexternal.pl +application/x\-tar:m2h_external'filter:mhexternal.pl +application/x\-tcl:m2h_external'filter:mhexternal.pl +application/x\-tex:m2h_external'filter:mhexternal.pl +application/x\-texinfo:m2h_external'filter:mhexternal.pl +application/x\-troff\-man:m2h_external'filter:mhexternal.pl +application/x\-troff\-me:m2h_external'filter:mhexternal.pl +application/x\-troff\-ms:m2h_external'filter:mhexternal.pl +application/x\-troff:m2h_external'filter:mhexternal.pl +application/x\-ustar:m2h_external'filter:mhexternal.pl +application/x\-wais\-source:m2h_external'filter:mhexternal.pl +application/zip:m2h_external'filter:mhexternal.pl +audio/basic:m2h_external'filter:mhexternal.pl +audio/x\-aiff:m2h_external'filter:mhexternal.pl +audio/x\-wav:m2h_external'filter:mhexternal.pl +image/gif:m2h_external'filter:mhexternal.pl +image/ief:m2h_external'filter:mhexternal.pl +image/jpeg:m2h_external'filter:mhexternal.pl +image/tiff:m2h_external'filter:mhexternal.pl +image/x\-bmp:m2h_external'filter:mhexternal.pl +image/x\-cmu\-raster:m2h_external'filter:mhexternal.pl +image/x\-pbm:m2h_external'filter:mhexternal.pl +image/x\-pcx:m2h_external'filter:mhexternal.pl +image/x\-pgm:m2h_external'filter:mhexternal.pl +image/x\-pict:m2h_external'filter:mhexternal.pl +image/x\-pnm:m2h_external'filter:mhexternal.pl +image/x\-portable\-anymap:m2h_external'filter:mhexternal.pl +image/x\-portable\-bitmap:m2h_external'filter:mhexternal.pl +image/x\-portable\-graymap:m2h_external'filter:mhexternal.pl +image/x\-portable\-pixmap:m2h_external'filter:mhexternal.pl +image/x\-ppm:m2h_external'filter:mhexternal.pl +image/x\-rgb:m2h_external'filter:mhexternal.pl +image/x\-xbitmap:m2h_external'filter:mhexternal.pl +image/x\-xbm:m2h_external'filter:mhexternal.pl +image/x\-xpixmap:m2h_external'filter:mhexternal.pl +image/x\-xpm:m2h_external'filter:mhexternal.pl +image/x\-xwd:m2h_external'filter:mhexternal.pl +image/x\-xwindowdump:m2h_external'filter:mhexternal.pl +message/partial:m2h_text_plain'filter:mhtxtplain.pl +text/html:m2h_text_html'filter:mhtxthtml.pl +text/plain:m2h_text_plain'filter:mhtxtplain.pl +text/richtext:m2h_text_plain'filter:mhtxtplain.pl +text/setext:m2h_text_setext'filter:mhtxtsetext.pl +text/tab\-separated\-values:m2h_text_plain'filter:mhtxtplain.pl +text/x\-html:m2h_text_html'filter:mhtxthtml.pl +text/x\-setext:m2h_text_setext'filter:mhtxtsetext.pl +video/mpeg:m2h_external'filter:mhexternal.pl +video/quicktime:m2h_external'filter:mhexternal.pl +video/x\-msvideo:m2h_external'filter:mhexternal.pl +video/x\-sgi\-movie:m2h_external'filter:mhexternal.pl + + + MIMEARGS + + The MIMEARGS resource may be used to pass optional arguments to + filters to control their behavior. Arguments may be defined on a per + content\-type basis, or for a specific filter itself. The syntax for + each line of the the MIMEARGS element is as follows: + + __:__ + + Or, + + __:__ + + The format of argument strings is dependent on the filter that + processes __ or by the specified filter, + __. + + If an argument string is defined for a filter explicitly and for a + content\-type that the filter processes, the content\-type string will + override the filter string. + + Examples + + The following example represents the default settings used by + _MHonArc_: + + +image/gif:inline +image/x\-xbitmap:inline +image/x\-xbm:inline + + + The following example tells the filter that deals handles + content\-types that cannot be converted directly into HTML to use the + "_name_" attribute as defined in the Content\-Type header field as the + name of the file generated: + + +m2h_external'filter:usename + + + The following examples says to inline XBM images and use the name + attribute as the filename if defined: + + +image/x\-xbm:inline usename + + + _________________________________________________________________ + + + _________________________________________________________________ + + Gory Details + + This sections explain in detail how _MHonArc_ functions. Knowing the + material covered in this section may help you when trouble shooting. + + _________________________________________________________________ + +OS Detection + + _MHonArc_ will automatically detect which operating system it is + running under. If the following list of conditions are true, _MHonArc_ + assumes it is running under MS\-DOS: + + * The COMSPEC environment variable is defined. + * The value of the COMSPEC environment variable is a legal MS\-DOS + pathname. + * The value of the COMSPEC environment variable is an executable + file. + + If any of the above conditions is false, _MHonArc_ assumes it is + running under Unix. + + _NOTE_ + The previous conditions are used since the conditions will + exist if Perl has been installed on an MS\-DOS machine. None of + the above conditions exist when Perl is installed on a Unix + system. + + _________________________________________________________________ + +Processing Steps + + This section describes the steps _MHonArc_ performs when + creating/editting an archive. Anytime messages are added or deleted or + the index page layout is changed, _MHonArc_ will perform the following + steps. + + * Creates a lock file. This insures only one _MHonArc_ process is + updating the archive at any given moment. See Archive Integrity + for more information. + * Reads the database file. The name, and location, of the database + file can be explicitly specified via the M2H_DBFILE and M2H_OUTDIR + environment variables or the command\-line options \-dbfile and + \-outdir. Otherwise, the current working directory is used. + _NOTE_: _The database file must be in the same location as the + archive since the _M2H_OUTDIR_ variable and _\-outdir_ option also + specify the location of the archive_. + The database file contains data to update any mail threads and the + resource settings when _MHonArc_ was last invoked. This allows new + messages to contain the same formatting/resource specifications as + existing messages in the archive without having to re\-specify the + resources each time new messages are added. Resources defined in + the database file override the environment variables. + _NOTE_: _If no database file is found, MHonArc will create a new + archive_. + * Read the _MHonArc_ resource file, _if specified_. The resource + file will override any settings contained in the database file. + * Read the settings specified on the command\-line. Command\-line + options override any settings in the database and/or resource + file. + * Update archive. + * Rewrites the index pages to reflect the update. + * Writes a new database file containing the new state of the archive + and all (new) resource settings. + + Normally, knowing all the previous steps is unnecessary. However, it + may be useful to be aware of them if unexpected behavior, or errors, + occur. + + _________________________________________________________________ + +Archive Integrity + + _MHonArc_ applies safeguards to try to insure that a mail archive does + not get corrupted due to exceptional circumstances. _MHonArc_ does the + following to insure a mail archive does not get corrupted: + + * _MHonArc_ creates a lock file, ".mhonarc.lck", when + creating/updating an archive. The lock file insures that only one + _MHonArc_ process is modifying an archive at any given moment. The + \-locktries command\-line option, or the M2H_LOCKTRIES environment + variable, allows you to control how long a given _MHonArc_ process + will wait if an archive is currently locked. If _MHonArc_ can not + lock the archive after the specified number of tries, _MHonArc_ + will exit, unless the \-force option is specified. + * _MHonArc_ will ignore the following signals once messages are + actually being written to disk: SIGABRT, SIGHUP, SIGINT, SIGQUIT, + SIGPIPE, SIGTERM. Possible archive corruption can still occur if a + SIGKILL signal is received since SIGKILLs are uncatchable. A + SIGKILL will also prevent _MHonArc_ from deleting the lock file. + + _________________________________________________________________ + +File Formats + + Database File + + The _MHonArc_ database file is actual Perl code. _MHonArc_ requires it + like any other Perl library to load in the contents of the database. + + _CAUTION_ + You should never modify the database file by hand. Changing the + file by hand could cause future incorrect/unpredictable + behavior when processing the archive. + + Index and Message Files + + The indexes and message files are legal HTML documents. However, + manual editting of the documents is discouraged. The documents contain + special comment declarations. The comment declarations act as markers + which allow _MHonArc_ to correctly edit the documents when needed. + + The comment declarations look like the following: + + + + + +... + + Derived Files + + Derived files are files that are generated by the MIME filters. These + files are created when the data being processed in messages cannot be + converted to HTML (eg. images, postscript, video, binaries). The + format of these files depend on the content\-type of the data. + + _________________________________________________________________ + +Notes + + * Here is the explicit order of decreasing precedence when setting + resources/options: + + command\-line options (_highest precedence_) + + resource file + + database file + + environment variables (_lowest precedence_) + * Mail thread detection is dependent upon the mail messages + containing the message id(s) of referenced messages. Most mailers + _reply function_ will automatically include the message id of the + message being replied to. + * All mail message being converted into HTML are stored in memory + before they are written to disk. This can eat up much memory if + many mail messages are being converted. If you are processing + multiple mailboxes/folders and worried about memory, you can try + the following: + + Invoke _MHonArc_ on each one separately using the \-add + option. + + Or, invoke _MHonArc_ with the \-savemem option. + * The database file, and the index pages, are completely rewritten + evertime new messages are added. This may cause slight slow\-downs + when archives become very large. + * When reading _MH_ mail folders, mail message are assumed to have + numeric filenames. + * When sorting by date, _MHonArc_ tries to use the date listed in + the first _Received_ field of the message. If no _Received_ field + exists, than the _Date_ field is used. + * No distinction is made, in the output, on which messages came from + which mail folder if multiple mail folders are processed. + * _MHonArc_ can probably be modified to handle other types of + mailers (which has been done since the original version only + supported _MH_ mail folders). The MSGSEP resource gives + flexibility in processing Unix style mailbox files. + + _________________________________________________________________ + + + _________________________________________________________________ + + Diagnostics + + Three types of messages exist in _MHonArc_: _Informative_ messages, + _Warnings_, and _Errors_. _Informative_ messages give you the current + status of _MHonArc_'s execution. _Warnings_ signify undesired + conditions, but are _not_ critical in _MHonArc_'s exection. _Errors_ + signify critical conditions that inhibit _MHonArc_ from finishing its + task. + + Another set of messages exists that are generated from the Perl + interpreter itself. _MHonArc_ tries its best to catch any conditions + that may cause Perl to abnormally abort, but conditions may arise + where this is not possible. + + This section describes the various diagnostics _MHonArc_ may produce + and messages Perl may produce. + + _________________________________________________________________ + +Informative messages + + Informative messages may be suppressed via the \-quiet command\-line + option. Only the more important Informative messages are listed here. + + Could not process message with given Content\-Type: ... + + _MHonArc_ will output this statement _in_ filtered mail messages for + content\-types it is unable to process. See Default Filters in MIME for + content\-types that _MHonArc_ supports by default. See Writing Filters + for adding new filters into _MHonArc_. + + This is the only Informative message that does not go to standard + output, but into the actual filtered mail message. + + No new messages + + No mail messages exist when performing an add operation to an archive. + This can occur if an empty _MH_ mail folder, or empty mailbox file, is + passed to _MHonArc_. + + Requiring MIME filter libraries ... + + Indicates _MHonArc_ is loading external libraries for filtering mail + messages. _MHonArc_ will output each library it loads. See MIME for + more information of filter libraries. + + Trying to lock mail archive ... + + The statement means that a lock file is in place for the archive you + are trying to update. Normally, an existing lock file implies that + another _MHonArc_ process is currently using the archive, and other + _MHonArc_ processes will wait awhile to see if the archive will be + unlocked. + + However, there are times when a lock file exists, but no _MHonArc_ + process is modifying the archive. This can occur if _MHonArc_ is + abnormally terminated. If you know that no other _MHonArc_ process is + editting the archive you are try to modify, then manually remove the + lock file or use the \-force option. + + See Archive Integrity for more information. + + _________________________________________________________________ + +Warnings + + Warning messages denote some undesired event occurred, but the event + is not severe enough to cause program termination. + + Warning: Could not find date for message + + _MHonArc_ was unable to find a received/sent date for a mail message. + With respect to other mail messages, a message with no received/sent + date is first in chronological order. + + Warning: Database () != program () version + + Indicates that the version of _MHonArc_ updating an archive is + different from the version of _MHonArc_ that created the database + file. Problems can arise if the database file changes in format from + different version of _MHonArc_. See the release notes of the _MHonArc_ + distribution if changes in the databse format has effects on older + archives. + + Warning: Unable to create / + + Indicates _MHonArc_ was unable to create the database file __ + for the mail archive created/modified in __. This message can + occur if __ permissions changed during _MHonArc_ execution, + the existing __ is read\-only, or the file system is full. + + This message can be severe because no future add operations can be + performed to the archive. + + Warning: Unable to open footer: