File: usage.html

package info (click to toggle)
mhonarc 2.6.24-1
links: PTS, VCS
area: main
in suites: forky, sid, trixie
size: 9,020 kB
sloc: perl: 280,086; makefile: 11
file content (417 lines) | stat: -rw-r--r-- 16,824 bytes
parent folder | download | duplicates (6)
<HTML>
<HEAD>
<TITLE>MHonArc FAQ: General Usage</TITLE></HEAD>
<link rel="stylesheet" type="text/css" href="../docstyles.css">
<BODY>

<!--X-NavButtons-Start-->
<table width="100%"><tr><td align="left"><nobr>[<a href="envs.html">Prev</a>]</nobr></td><td align="center" width="100%">[<a href="faq.html">TOC</a>][<a href="../mhonarc.html">Manual</a>][<a href="http://www.mhonarc.org/">Home</a>]</td><td align="right"><nobr>[<a href="archives.html">Next</a>]</nobr></td></tr></table>
</p>
<!--X-NavButtons-End-->

<!-- ===================================================================== -->
<HR>
<H2><a name="genusage">General Usage</a></H2>

<!--X-TOC-Start-->
<ul>
<li><a href="#resources">What are "resources"?</a></li>
<li><a href="#rfileedit">Is there a resource file editor?</a></li>
<li><a href="#nilresource">How do you set a resource to nil?</a></li>
<li><a href="#todefaults">How do I reset an archive's resources to the default values?</a></li>
<li><a href="#newgetopt">I get an error that "newgetopt.pl" cannot be required, where is it?</a></li>
<li><a href="#searching">Does MHonArc provide searching of archives?</a></li>
<li><a href="#webui">Is there a Web interface for MHonArc?</a></li>
<li><a href="#orgmsg">Does MHonArc require that the original message be available when updating an archive?</a></li>
<li><a href="#respecify">Do I have to respecify the resource file each time I update an archive?</a></li>
<li><a href="#sepfiles">Can I have MHonArc process a bunch of separate message files?</a></li>
<li><a href="#stdin">Can I tell MHonArc to read a mailbox from standard input?</a></li>
<li><a href="#parsedate">Why am I getting "Could not parse date for message ..."?</a></li>
<li><a href="#parsedate">Why doesn't MHonArc extract the date from "From ..." line?</a></li>
<li><a href="#count">Why is the number of messages reported by MHonArc less than what is reported by my MUA?</a></li>
</ul>
<!--X-TOC-End-->

<!-- ??????????????????????????????????????????????????????????????? -->
<hr noshade size=1>
<table border=0>
<tr valign=baseline><td><img src="monicon.png" align="bottom" alt=""></td><td>
<h3><b><a name="resources">What are "resources"?</a></b></h3>
</td></tr></table>

<p>The behavior of MHonArc is controled by <em>resources</em>.
Resources are set, or defined, by command-line options, environment
variables, or a resource file.  For example, the MAXSIZE resource tells
MHonArc the maximum number of messages allowed in an archive.  To set
the resource, you can use the <strong><code>-maxsize</code></strong>
command-line option, the <strong>M2H_MAXSIZE</strong> envariable, or the
<strong><code>&lt;MAXSIZE&gt;</code></strong> resource file element.
</p>

<p>See the <a href="../resources.html"><cite>Resources</cite></a>
section of the documentation for more information.
</p>

<!-- ??????????????????????????????????????????????????????????????? -->
<hr noshade size=1>
<table border=0>
<tr valign=baseline><td><img src="monicon.png" align="bottom" alt=""></td><td>
<h3><b><a name="rfileedit">Is there a resource file editor?</a></b></h3>
</td></tr></table>

<p>If you are Vim user,
<a href="http://www.vim.org/">&lt;http://www.vim.org/&gt;</a>,
a syntax file
for MHonArc resource files is included in the examples directory
(<b>mhonarc.vim</b>).  To use it, copy mhonarc.vim to an appropriate location
and add something like the following to your .vimrc file:
</p>
<pre class="code">
au BufNewFile,BufRead *.mrc     so $HOME/share/vim/syntax/mhonarc.vim
</pre>
<p>Of course, change the pathname to mhonarc.vim to where ever you copied
it to.
</p>
<p>Now, any file with ".mrc" extension will put Vim into MHonArc resource
file highlighting mode.  The mode is best used with color-capable
terminals.
</p>

<!-- ??????????????????????????????????????????????????????????????? -->
<hr noshade size=1>
<table border=0>
<tr valign=baseline><td><img src="monicon.png" align="bottom" alt=""></td><td>
<h3><b><a name="nilresource">How do you set a resource to nil?</a></b></h3>
</td></tr></table>

<p>For page layout resources, do something like the following in
your resource file:
</p>
<pre class="code">
<b>&lt;BotLinks&gt;</b>

<b>&lt;/BotLinks&gt;</b>
</pre>
<p>Notice the blank line.  If you specify no content, MHonArc will
fallback to the default value of the resource.
</p>
<table class="caution" width="100%">
<tr valign="baseline">
<td><strong style="color: red;">WARNING:</strong></td>
<td width="100%"><p>
Only do the above for page layout related resources.
For other resources, the above technique will have no effect, or
it may cause unexpected results.  See
<a href="#todefaults">How do I reset an archive's resources to the default
values?</a> for more information on reseting resources to default
values.
</p>
</td>
</tr>
</table>

<!-- ??????????????????????????????????????????????????????????????? -->
<hr noshade size=1>
<table border=0>
<tr valign=baseline><td><img src="monicon.png" align="bottom" alt=""></td><td>
<h3><b><a name="todefaults">How do I reset an archive's resources to the default values?</a></b></h3>
</td></tr></table>

<p>The following two commands will reset an archive to use default
resource values:
</p>
<pre class="shell">
prompt&gt; <b>mha-dbedit <a class="shell" href="../resources/saveresources.html">-nosaveresources</a> <a class="shell" href="../resources/outdir.html">-outdir</a> <var>/path/to/your/archive</var></b>
prompt&gt; <b>mhonarc <a class="shell" href="../resources/saveresources.html">-saveresources</a> <a class="shell" href="../resources/editidx.html">-editidx</a> <a class="shell" href="../resources/outdir.html">-outdir</a> <var>/path/to/your/archive</var></b>
</pre>
<p>You could also include
<a href="../resources/rcfile.html"><tt>-rcfile</tt></a> option
to the last step if
you want to modify some resources from the default in case you want
to reset some resources and not all of them.
</p>

<!-- ??????????????????????????????????????????????????????????????? -->
<hr noshade size=1>
<table border=0>
<tr valign=baseline><td><img src="monicon.png" align="bottom" alt=""></td><td>
<h3><b><a name="newgetopt">I get an error that "newgetopt.pl" cannot be required, where is it?</a></b></h3>
</td></tr></table>

<p>newgetopt.pl comes with the standard Perl distribution.  Check with
your sys admin on where it is located (it should be in the default Perl
search path).
</p>

<table class="note" width="100%">
<tr valign="baseline">
<td><strong>NOTE:</strong></td>
<td width="100%"><p>v2.3 and later use <b>Getopt::Long</b>, which is included
in the Perl 5 distribution.
</p>
</td>
</tr>
</table>

<!-- ??????????????????????????????????????????????????????????????? -->
<hr noshade size=1>
<table border=0>
<tr valign=baseline><td><img src="monicon.png" align="bottom" alt=""></td><td>
<h3><b><a name="searching">Does MHonArc provide searching of archives?</a></b></h3>
</td></tr></table>

<p>No, but searching can be provided by another utility.
The following list of search indexing tools have been used with 
MHonArc archives:
</p>
<ul>
<li><strong>Glimpse</strong>:
<a href="http://glimpse.cs.arizona.edu/"
>&lt;http://glimpse.cs.arizona.edu/&gt;</a></li>
<li><strong>ht://Dig</strong>:
<a href="http://www.htdig.org/">&lt;http://www.htdig.org/&gt;</a></li>
<li><strong>Lucene</strong>:
<a href="http://lucene.apache.org/">&lt;http://lucene.apache.org/&gt;</a></li>
<li><strong>Namazu</strong>:
<a href="http://www.namazu.org/">&lt;http://www.namazu.org/&gt;</a>
(MHonArc aware and supports Japanese)</li>
<li><strong>mnoGoSearch</strong>:
<a href="http://search.mnogo.ru/">&lt;http://search.mnogo.ru/&gt;</a></li>
</ul>
<p>For more information, see
the respective documentation of the search engine software of
interest.
</p>

<table class="note" width="100%">
<tr valign="baseline">
<td><strong>NOTE:</strong></td>
<td width="100%"><p>You may also want to check out the following:
</p>
<ul>
<li><strong><a href="http://www.mhonarc.org/release/mharc/">mharc</a></strong>
    at <a href="http://www.mhonarc.org/release/mharc/"
    >&lt;http://www.mhonarc.org/release/mharc/&gt;</a>:
    Mharc is a web-based mail archiving system for multiple mailing
    lists using Procmail, MHonArc, and Namazu.
    </li>
<!--
<li><strong><a href="http://www.hpc.uh.edu/majordomo/#wilma">Wilma</a></strong>
    at <a href="http://www.hpc.uh.edu/majordomo/#wilma"
    >&lt;http://www.hpc.uh.edu/majordomo/#wilma&gt;</a>:
    Wilma is the Web Interface to List Mail Archives, written by Dave Wolfe
    and Jason Tibbitts with nods to Achim Bohnet and Tom Christiansen.
    WIlma is a relatively simple bit of Perl which links together the
    MHonArc  mail-to-HTML converter and the Glimpse search engine.
    The result is a useful tool for allowing folks to browse your list
    archives over the web. It works very well with the archives generated
    by Majordomo's archive2.pl script.
    </li>-->
<p> </p>
</ul>
</td>
</tr>
</table>

<!-- ??????????????????????????????????????????????????????????????? -->
<hr noshade size=1>
<table border=0>
<tr valign=baseline><td><img src="monicon.png" align="bottom" alt=""></td><td>
<h3><b><a name="webui">Is there a Web interface for MHonArc?</a></b></h3>
</td></tr></table>

<p>No official ones.  Several users have created home-grown interfaces
to perform various tasks.  An experimental, <strong>unsecure</strong>
web admin tool comes in
with the MHonArc distribution under the "admin" directory.
I recommend searching the
MHonArc mailing list archives for discussion about web interfaces.
</p>

<!-- ??????????????????????????????????????????????????????????????? -->
<hr noshade size=1>
<table border=0>
<tr valign=baseline><td><img src="monicon.png" align="bottom" alt=""></td><td>
<h3><b><a name="orgmsg">Does MHonArc require that the original message be available when updating an archive?</a></b></h3>
</td></tr></table>

<p>No.  Once a message is archived, the original can be stored
away.  MHonArc preserves all relevant information in its
database.  For possible recovering purposes, it is recommended
to preserve original messages in a storage archive.  This allows
you to rebuild MHonArc archives in case of data corruption.
</p>

<!-- ??????????????????????????????????????????????????????????????? -->
<hr noshade size=1>
<table border=0>
<tr valign=baseline><td><img src="monicon.png" align="bottom" alt=""></td><td>
<h3><b><a name="respecify">Do I have to respecify the resource file each time I update an archive?</a></b></h3>
</td></tr></table>

<P>No. The archive database stores all resource settings. The only
time you need to respecify the resource file is if changes are required
in the layout of the archive.  </P>

<table class="note" width="100%">
<tr valign="baseline">
<td><strong>NOTE:</strong></td>
<td width="100%"><p>
When utilizing the <strong>OTHERINDEXES</strong> resource,
the resource filenames listed in the main resource file are stored
in the database, but the resources for each additional index are
<STRONG>NOT</STRONG>. Hence, the resource files defining the additional
indexes must be accesible.
</p>
</td>
</tr>
</table>

<!-- ??????????????????????????????????????????????????????????????? -->
<hr noshade size=1>
<table border=0>
<tr valign=baseline><td><img src="monicon.png" align="bottom" alt=""></td><td>
<h3><b><a name="sepfiles">Can I have MHonArc process a bunch of separate message files?</a></b></h3>
</td></tr></table>

<p>Yes.  MH mail folder processing is just processing a bunch of
separate message files in a directory.  MHonArc uses
the MHPATTERN resource to determine which files to process.  Therefore,
all you need to do is redefine the MHPATTERN resource and pass
the directory your message files are in when invoking MHonArc.
</p>

<p>For example, say I want to process all files in a directory
called "messages".  I'd do the following:
</p>
<pre class="shell">
prompt&gt; <b>mhonarc -mhpattern "^[^.]" messages</b>
</pre>
<p>MHPATTERN can be any Perl regular expression.  The one in
the example matches any file not beginning with ".".  This
is to avoid the special files "." and ".." which are directories.
</p>

<p>The other way to process individual message files is to do
it one at a time.  For example:
</p>
<pre class="shell">
prompt&gt; <b>mhonarc -add &lt; file1.822</b>
prompt&gt; <b>mhonarc -add &lt; file2.822</b>
...
</pre>

<!-- ??????????????????????????????????????????????????????????????? -->
<hr noshade size=1>
<table border=0>
<tr valign=baseline><td><img src="monicon.png" align="bottom" alt=""></td><td>
<h3><b><a name="stdin">Can I tell MHonArc to read a mailbox from standard input?</a></b></h3>
</td></tr></table>

<p>Yes, but only in v2.0 or later (v2.0 beta releases do not have
the capability).  The syntax is something like the following:
</p>
<pre class="shell">
prompt&gt; <b>mhonarc </b><var>[options-here]</var> <b>-- -</b>
</pre>
<p>The "--" tells MHonArc to terminate all command-line
option processing and treat all following arguments as mail
folders.  The "-" signifies to use standard input as a mailbox
source.
</p>

<p>Since MHonArc can read a mailbox from stdin, this
allows MHonArc to be part of a pipeline where MHonArc
takes input from some preprocessor that massages some data to
make it suitable for processing by MHonArc.  For example:
</p>
<pre class="shell">
prompt&gt; <b>mypreproc | mhonarc -- -</b>
</pre>

<!-- ??????????????????????????????????????????????????????????????? -->
<hr noshade size=1>
<table border=0>
<tr valign=baseline><td><img src="monicon.png" align="bottom" alt=""></td><td>
<h3><b><a name="parsedate">Why am I getting "Could not parse date for message ..."?</a></b></h3>
</td></tr></table>

<p>This warning is generated when a message does not contain any date
information, or the date format used in the message is not recognized
by MHonArc.  The warning may also indicate an improper end of a message
and start of a new message when processing a mailbox file.  You
may also want to see:
<a href="archives.html#split">Why does a 
message get split into mulitple messages with no headers?</a>.
</p>

<!-- ??????????????????????????????????????????????????????????????? -->
<hr noshade size=1>
<table border=0>
<tr valign=baseline><td><img src="monicon.png" align="bottom" alt=""></td><td>
<h3><b><a name="parsedate">Why doesn't MHonArc extract the date from "From ..." line?</a></b></h3>
</td></tr></table>

<p>The "From ..." line (applicable in UUCP-style mailbox files) is
the message separator and normally includes a date.  The problem
is that <em>it is the message separator</em>.  The message separator
is not part of actual message data, and the value of
the message separator is controled by the MSGSEP resource.  I.e.
The MSGSEP resource can be set anything, so there is no reliable
way to extract a date from it.
</p>
<p>Do not lose hope.  Provided in the extras directory of the
MHonArc distribution (v2.1.1 and later) is a Perl program called
<b>prsfrom.pl</b> by A.R. Burgers,
<a href="mailto:burgers&#37;40ecn.nl">burgers<!--
-->&#64;<!--
-->ecn.nl</a>.  The program
will supply missing Date: and From: fields to mailboxes based upon
the message separator line.
</p>

<!-- ??????????????????????????????????????????????????????????????? -->
<hr noshade size=1>
<table border=0>
<tr valign=baseline><td><img src="monicon.png" align="bottom" alt=""></td><td>
<h3><b><a name="count">Why is the number of messages reported by MHonArc less than what is reported by my MUA?</a></b></h3>
</td></tr></table>

<p>This usually implies that you have duplicate messages.  MHonArc
skips messages that have already been archived.
A way to check if message duplication is the culprit, try the following
on your mailbox:
</p>
<pre class="shell">
prompt&gt; <b>grep -i '^message-id:' <var>my.mbox</var> | sort | uniq | wc -l</b>
</pre>
and
<pre class="shell">
prompt&gt; <b>grep -i '^message-id:' <var>my.mbox</var> | sort | wc -l</b>
</pre>

<p>If numbers printed by both commands differ, you have duplicate messages.
</p>

<!-- ===================================================================== -->
<hr>

<!--X-NavButtons-Start-->
<table width="100%"><tr><td align="left"><nobr>[<a href="envs.html">Prev</a>]</nobr></td><td align="center" width="100%">[<a href="faq.html">TOC</a>][<a href="../mhonarc.html">Manual</a>][<a href="http://www.mhonarc.org/">Home</a>]</td><td align="right"><nobr>[<a href="archives.html">Next</a>]</nobr></td></tr></table>
</p>
<!--X-NavButtons-End-->

<hr>
<address>
$Date: 2011/01/01 02:43:26 $ <br>
<img align="top" src="monicon.png" alt="">
<a href="http://www.mhonarc.org/"
><strong>MHonArc</strong></a><br>
Copyright &#169; 1997-1999, <a href="http://www.earlhood.com/"
>Earl Hood</a>, <a href="mailto:mhonarc&#37;40mhonarc.org"
>mhonarc<!--
-->&#64;<!--
-->mhonarc.org</a><br>
</address>
</body>
</html>