• NAME
• SYNOPSIS
• DESCRIPTION
• RESOURCE FILES
• Special Resource Variables
• Customizing the Layout
• Additional Pre-defined Resource Variables
• OPTIONS
• FILES
• NOTES
• DEPENDENCIES
• SEE ALSO
• VERSION
• AUTHOR

NAME

mha-cisco - Generate thread discussion message archives.

SYNOPSIS

mha-cisco [options]

DESCRIPTION

mha-cisco is a customized version of MHonArc developed for Cisco Systems that supports the generation of thread discussion pages with all messages for a thread on a single page.

The rest of this manual pages assumes you are familiar with MHonArc terminalogy and concepts, especially resources and resource variables. If you are not familiar, please read the MHonArc documentation.

RESOURCE FILES

mha-cisco is designed to work with the special resource files, cisco.mrc and cisco-dsc.mrc, to generate the discussion threads. cisco.mrc defines the basic layout of regular archive pages with a default layout based upon the common.mrc resource file provided with the mharc, <http://www.mhonarc.org/mharc/>, software package.

A critical function of cisco.mrc is to include special comment markers to delimit the portion of each message page that will be included in discussion pages. The comment markers are:

  <!--mha-cisco:msgdata-->
  ... 
  <!--/mha-cisco:msgdata-->

The starting comment should occur just before the converted message header and the end comment right after the converted message body.

cisco-dsc.mrc defines resources for use in generating the thread discussion pages, including the redefinition of some resources to support intra-page navigation of messages in the same thread.

Both resource files are installed in the library path during mha-cisco's installation process. If either resource file cannot be found in Perl's @INC search path, mha-cisco will abort with an error.

Special Resource Variables

If you examine cisco.mrc and cisco-dsc.mrc, you will notice that many custom resource variables are used. This helps make the resource files more maintainable by isolating reusable markup and by making customization of text labels and similiar items easier.

However, there are some custom resource variables used directly by mha-cisco for generating the discussion pages. These variables are defined, with reasonable default values, in cisco-dsc.mrc. The variables are:

$DSC-BEGIN$

Defines the beginning markup of discussion pages.

$DSC-END$

Defines the end markup of discussion pages.

Customizing the Layout

It is highly recommended to not edit the special resource files to customize the layout since they may get overwritten during a software upgrade.

Therefore, to customize the layout, the -rcfile and -cis-dsc-rcfile options can be used to specify resource files with custom settings. The standard -rcfile is used for a resource file that will set general resources and/or customize standard archive pages. The -cis-dsc-rcfile is used for a resource file to customize the layout of discussion pages.

NOTE: Before customizing any layout resources, review the default cisco.mrc and cisco-dsc.mrc since they define many resource settings that differ from MHonArc's default.

Additional Pre-defined Resource Variables

mha-cisco pre-defines the following resource variables for use within resource files:

$CIS-GROUP$

The value of the -cis-group command-line option.

$CIS-LOCATION$

The directory location. Basically, this is just the value of $CIS-GROUP$ with '.'s converted to '/'s. It is mainly for use in defining the msglocation and dsclocation meta tags for message and discussion pages.

$LIST-TITLE$

The title the discussion list. Right now, it is equivalent to $CIS-GROUP$.

OPTIONS

mha-cisco takes all the options available to mhonarc along with the following additional options:

-cis-group newsgroup

The name of the newsgroup being processed. This option is required.

-cis-dsc-rcfile pathname

Resource file to read before generating thread discussion pages. This option can be specified multiple times.

NOTE: To customize regular archive pages, MHonArc's standard -rcfile option can be used.

-help

Print usage and options summary for mha-cisco.

-man

Print manpage for mha-cisco.

FILES

cisco.mrc

MHonArc resource defining the archive layout. The file is automatically searched for in Perl's @INC search path.

cisco-dsc.mrc

MHonArc resources defining layout needed for thread discussion pages. discussion pages. The file is automatically searched for in Perl's @INC search path.

dscNNNNN.html

Thread discussion pages generated for MHonArc archives. The NNNNN will equal the message number of the first message in the thread.

NOTES

Care must be taken when redefining layout resources with a local resource file. For example, if invoking mha-cisco like the following:

  prompt> mha-cisco -rcfile myrc.mrc ...

myrc.mrc can define layout resources, and they will take precedence over layout resources in cisco.mrc. However, some of the functionality of mha-cisco depends on certain layout structures as described under RESOURCE FILES.

Since cisco-dsc.mrc is loaded after regular MHonArc processing, cisco-dsc.mrc will always override any previous resource settings, including those defined in myrc.mrc.

Resource settings defined in cisco-dsc.mrc are not saved in archive databases. Discussion page generation is performed after the archive database has been written.
Discussion pages are generated after MHonArc releases the lock on the archive. However, since discussion page generation does not mutate regular archive files and the database file, corruption will not occur.
Due to requirements in the format of the searchdate meta tag in message and discussion pages, cisco.mrc enables the POSIXSTRFTIME resource to utilize the %e conversion specifier, which MHonArc does not support. See strftime(3) for more information.

DEPENDENCIES

POSIX

MHonArc v2.6.0, or later

SEE ALSO

mhonarc(1)

VERSION

$Id: mha-cisco,v 1.6 2003/03/13 05:11:28 ehood Exp $

AUTHOR

Earl Hood, earl@earlhood.com

Copyright (C) 2003 Earl Hood, earl@earlhood.com mha-cisco comes with ABSOLUTELY NO WARRANTY and mha-cisco may be copied only under the terms of the GNU General Public License.