mk-procmailrc - Generate procmailrc from lists.def


NAME

mk-procmailrc - Generate procmailrc from lists.def


SYNOPSIS

  mk-procmailrc
  mk-procmailrc [options]


DESCRIPTION

This program generates the main procmailrc used by the filter-spool program. The procmailrc is generated from <mharc-root>/lib/lists.def.

This program is typically invoked by calling make from the mharc root directory with configuration options specified in <mharc-root>/lib/config.sh.


LIST DEFINITION FILE

The list definition file, <mharc-root>/lib/lists.def, controls how the procmailrc used by filter-spool is generated. The format of the file is simple and more convenient than writing the procmailrc file yourself.

The basic format of the file is as follows:

lists.def Supported Options

Name
Starts, and defines, the name of an archive. This name serves as the directory name containing archive data and the list title (the $LIST-TITLE$ MHonArc resource variable) for archive pages. A common practice is to use the list address, but this is not required, especially if the archive is a combination of multiple lists, or it is prefered to use a more abstract name for simplicity.

The name also is used when the the web-archive manpage script looks for an archive specific MHonArc resource settings. If the following resource file exists,

  $MHA_RC_DIR/<name>.mrc

where $MHA_RC_DIR is the value of the MHA_RC_DIR config.sh variable and <name> is the name of the archive, the web-archive manpage will pass the resource file to MHonArc when processing the HTML archive. This provides a convenient way to provide list-specific customization to the archive.

Address
Mail address of the list. Multiple Address options can be specified for an archive if a list has more than one known address (e.g. due to migration) or the archive is a collection of multiple lists.

NOTE: The address is technically treated as part of a procmail regular expression. Take the following as an example:

  Address: mharc-users@mhonarc.org

In regular expressions, the '.' character represents any character. Therefore, the following strings would match the above specification:

  mharc-users@mhonarc#org
  mharc-users@mhonarcXorg
  mharc-users@mhonarc@org

In practice, this technicality will generally have no affect, but if you want to be pendantic, do the following:

  Address: mharc-users@mhonarc\.org

The '\' tells procmail to treat the '.' literally.

Because the actual address string given is treated as part of a regular expression, you can specify a range of addresses with a single option. For example,

  mharc-[^@]*@mhonarc\.org

will match the following addresses:

  mharc-users@mhonarc.org
  mharc-rules@mhonarc.org
  mharc-rocks@mhonarc.org
  mharc-is-the-best@mhonarc.org
  ...

All-Lists-Name
Label to use for Name column of all-lists index. If not specified, the name provided by the Name option is used.

Check-No-Archive
Boolean option (0 or 1) if author specified archiving permission is honored. The author can request no archiving should be done by defining one of the the following header fields:
  Restrict: no-external-archive
  X-no-archive: yes

If Check-No-Archive is enabled, a message to the list with either field defined will not be archived.

CVS-Commits
Boolean option (0 or 1) if CVS commit messages should be archived separately.

Use this option for development lists that have CVS project commits mailed to the list, and you want to avoid cluttering regular discussion mail.

CVS-Subject-Prefix
Specifies the Subject: prefix denoting CVS commits to the list. This option is only used if CVS-Commits is specified.

Description
Brief description of archive and serves as the main title of archive index pages.

Final
Boolean option (0 or 1) if generated rule should be final. I.e. If a message matches, further rules will not be examined.

Use this option to short-circuit messages from being stored in multiple archives. For example, you may want to catch messages cross-posted to a special address to only be archived in a special archive and not any of the regular archives.

Another example is if you use the special Name ``.catch'' (or the -catch-archive setting described in OPTIONS). Using ``.catch'' is handy for Final definitions to pre-catch messages that should not be placed in any list archive.

From-Address
Mail address of the list. This option is an alternative to Address where a list can only be donoted by the From: field of messages. This is fairly common for one-way lists, like newsletters, where subscribers receive list messages but cannot post to the list.

Multiple From-Address options can be specified if a list has more than one known address (e.g. due to migration) or the archive is a collection of multiple lists.

Hide-From-All-Lists
Boolean option (0 or 1) if archive should not be listed in the all-lists index. If set to 1, the archive will not be shown. The default value for this option is 0.

Lang
Sets the language/locale of the archive.

CAUTION: Only set this option if using a version of MHonArc (v2.6.7, or later) that supports the LANG resource. Otherwise, you will get a runtime error when web-archive is invoked.

See the LANG resource reference page of the MHonArc documentation for more information.

MHonArc-Options
Additional MHonArc command-line options.

No-Raw-Link
Boolean option (0 or 1) if links to raw archives should exist. If set to 1, links will not be created or disabled. The default value for this option is 0.

Use this option if your HTML archives have been customized to obscure addresses to prevent address harvesting.

No-Search
Boolean option (0 or 1) if searching should be disabled. If set to 1, no search index is created and the $SEARCH-FORM$ custom MHonArc resource variable will be set to the empty string.

NOTE: Disable searching will diable some navigational features that are dependent upon the search index.

Period
If archive is a yearly or monthly archive. Legal values are year or month. If Period is not defined, month is the default.

Procmail-Condition
Additional condition to apply to base address check. The condition must be legal procmailrc syntax and should include any prefixing *, !, et. al. This option can be specified multiple times.

Procmail-Condition can also be used inplace of Address and From-Address to provide arbitrary matching rules for archiving messages. This is useful for rare cases where messages to be archived cannot be determined by receipient or from addresses.

CAUTION: Exercise caution when using this option, especially if CVS-Commits is true. When CVS-commits is true, an additionaly rule already exists to check for the CVS-Subject-Prefix setting.

lists.def Notes

lists.def Example

  ##  In this definition, we define multiple addresses to check.
  Name: mhonarc-users
  Description: MHonArc Users
  Address: mhonarc-users@mhonarc.org
  Address: mhonarc@ncsa.uiuc.edu
  Address: mhonarc@rosat.mpe-garching.mpg.de
  ##  This definition defines a list that receives CVS commits and those
  ##  commits should be separated into a special archive as to not
  ##  pollute the discussion messages with cvs commit messages
  Name: mhonarc-dev
  Description: MHonArc Development
  Address: mhonarc-dev@mhonarc.org
  CVS-Commits: 1
  CVS-Subject-Prefix: CVS:


OPTIONS

You should never have to invoke this program with any options since config.sh specifies any options used by this program. However, for advanced uses, or you do not care if you mess things up, the following options are available:

-catch-address mail-address
The name of the email address to forward all unmatched message to. This is an alternative to -catch-archive, and will supercede -catch-archive, if defined. If this option is not specified, the CATCH_ADDRESS variable in config.sh is used.

-catch-archive name
The name of the catch archive. The catch archive collects all messages that do not match any list rules. If this option is not specified, the CATCH_ARCHIVE variable in config.sh is used, else the name ``.catch'' is used.

Note: If you use this option, it is recommended that the name starts with a . (a dot). This insures that no search index is built and it will not be listed in the all-lists page.

-disable-catch-archive
If specified, no catch archive will be defined.

CAUTION: Care should be used when using this option since any message that does not match a normal rule will be lost.

-final-dest mailbox
The destination of messages that make it to the end of the procmailrc. It is normal for messages to make it to the end since the list matching rules create copies of the message during filtering. Hence, it is normal to see ``Folder: /dev/null'' destinations in the procmail log and it does not indicate that a message was lost.

Message copying is done inorder to properly archive a message that has been cross-posted to multiple lists. Message copying is not done for archives with the Final option set to 1, for CVS commit archives, or for messages that are captured by the catch archive.

This option is generally only used for debugging purposes.

If -final-dest is not specified, the FINAL_MSG_DESTINATION variable in config.sh is used, else /dev/null is used.

-help
Print out usage information.

-home pathname
You should not use this option.

Root pathname of software and archives. If not specified, SW_ROOT variable in config.sh is used, else the parent directory that containing this program is used.

-man
Print out entire manpage.

-mbox-dir pathname
Root pathname containing raw mailbox archives. If not specified, MBOX_DIR variable in config.sh is used, else -home/mbox is used.

-msgid-cache-size number-of-bytes
The maximum size, in bytes, of the message-id cache. The message-id cache helps avoid processing duplicate messages.

If this option is not specified, the MSGID_CACHE_SIZE variable in config.sh is used, else 16384 will be used.

-out pathname
Output filename. If this option is not specified, the PROCMAILRC variable in config.sh is used, else -home/procmailrc.mharc is used.

If ``-'' is the pathname, then the procmailrc will be dumped to standard out.

-procmail-path pathname-list
The search path for procmail to use. If this option is not specified, the PROCMAIL_PATH variable in config.sh is used.


FILES

<mharc-root>/lib/lists.def
Mailing lists definition file.

<mharc-root>/lib/config.sh
Main configuration file for mharc.


VERSION

$Id: mk-procmailrc,v 1.25 2003/08/09 17:51:04 ehood Exp $


AUTHOR

Earl Hood, earl@earlhood.com

This program is part of the mharc archiving system and comes with ABSOLUTELY NO WARRANTY and may be copied only under the terms of the GNU General Public License, which may be found in the mharc distribution.

 mk-procmailrc - Generate procmailrc from lists.def