MHonArc Resources: RCFILE

[Prev: QUIET] | [Resources][TOC] | [Next: RECONVERT]

# RCFILE

- Syntax
- Description
  - Resource file syntax
  - Resource variables
  - Localized resource file variations
- Default Setting
- Resource Variables
- Examples
- Version
- See Also

## Syntax

Envariable

  `M2H_RCFILE=`filename

Element

  N/A

Command-line Option

  `-rcfile` filename

## Description

RCFILE tells MHonArc what the resource file is. 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 `-rcfile` command-line option can be specified multiple times. For example,

    prompt> mhonarc -rcfile file1.mrc -rcfile file2.mrc ...

Each resource file specified will be loaded in the order specified on the command-line.

### Resource file 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 conflicts if more stricter parsing rules are adopted.

- The opening tag of an element must occur by itself on a single line.

  Correct:

      <LiTemplate>
      <li><strong>$SUBJECT$</strong>
      <ul><li><em>From</em>: $FROM$</li></ul>
      </li>
      </LiTemplate>

  Wrong:

      <LiTemplate><li><strong>$SUBJECT$</strong>
      <ul><li><em>From</em>: $FROM$</li></ul>
      </li>
      </LiTemplate>

- Comments inside elements are treated as part of the element content.

- Each element must have a close tag, `</`element_name`>`, on its own line.

  Correct:

      <LiTemplate>
      <li><strong>$SUBJECT$</strong>
      <ul><li><em>From</em>: $FROM$</li></ul>
      </li>
      </LiTemplate>

  Wrong:

      <LiTemplate>
      <li><strong>$SUBJECT$</strong>
      <ul><li><em>From</em>: $FROM$</li></ul>
      </li></LiTemplate>

  Close tags are not needed for boolean resources.

- Some elements can take an optional attribute called "`Override`", if applicable. This tells MHonArc that the contents of the element will completely override the default behavior of MHonArc, and previous instances of the element, for example: "`<EXCS Override>`". If "`Override`" is not specified, then the contents of the element augment the current setting.

- Some elements can take an optional attribute called "`Chop`", if applicable. This tells MHonArc to remove the last line-break of the element's content.

- Element names are case-insensitive.

- Elements can occur in any order in the resource file.

- Elements canNOT be nested. Many resources define the values of resource variables, which may be used within resource elements:

  Correct:

      <TTitle>
      Example List Threads
      </TTitle>

      <TIdxPgBegin>
      <html>
      <head>
      <title>$TIDXTITLE$</title>
      ...
      </TIdxPgBegin>

  Wrong:

      <TIdxPgBegin>
      <html>
      <head>
      <title>
      <TTitle>
      Example List Threads
      </TTitle>
      </title>
      ...
      </TIdxPgBegin>

### Resource variables

Many resources are allowed to have resource variables as part of there content. Resource variables represent data that can only be defined during run-time. I.e. Resource variables will get expanded to an appropriate value during the execution of MHonArc. For more information on resource variables, see the section: Resource Variables.

The description for each resource will contain a list of all applicable variables that may be used in defining the resource's value.

### Localized resource file variations

MHonArc supports the ability to define locale specific variations of a resource file based upon the LANG resource setting. For example, take the following command-line invocation:

    prompt> mhonarc -lang en_US -rcfile settings.mrc ...

MHonArc will check for and read the following resource files, in order:

1. `settings.mrc`
2. `settings.mrc.en`
3. `settings.mrc.en_us`

NOTE: | MHonArc will quietly ignore any locale-specific files that do not exist.

NOTE: | Setting LANG via a resource file element will only affect subsequent resource file resolution: subsequent resource files loaded via multiple `-rcfile` options and resource files loaded via the INCLUDE and OTHERINDEXES resource.

Therefore, if you manage multiple archives comprising multiple languages, you can define generic settings in a shared resource file and then define language-specific overrides and/or variations. Continuing with the previous example, the following invocation can be used for a French Canadian archive:

    prompt> mhonarc -lang fr_CA -rcfile settings.mrc ...

Causing the following resource files to be examined:

1. `settings.mrc`
2. `settings.mrc.fr`
3. `settings.mrc.fr_ca`

The following is the list of files examined given a resource file `file.mrc` and the generic locale setting `language_country.codeset`:

1. `file.mrc`
2. `file.mrc.language`
3. `file.mrc.language.codeset`
4. `file.mrc.language_country`
5. `file.mrc.language_country.codeset`

By leveraging the use of custom resource variables, you can parameterize textual labels so the locale-specific resource files only need to define variable values instead of redefining layout. For example, take the following default value of the NEXTBUTTON resource:

    <NextButton chop>
    [<a href="$MSG(NEXT)$">Date Next</a>]
    </NextButton>

To facilitate the the localization of your archives, the resource should be changed so the button label becomes a custom resource variable references:

    <NextButton chop>
    [<a href="$MSG(NEXT)$">$BUTTON-DATE-NEXT-LABEL$</a>]
    </NextButton>

You will notice that "`Date Next`" has been changed to "`$BUTTON-DATE-NEXT-LABEL$`". Therefore, in the locale specific resource file, all that needs to be done is to define `$BUTTON-DATE-NEXT-LABEL$`. Continuing with the `settings.mrc` example, the following would be defined in `settings.mrc.en` to set the English version of the label:

    <DefineVar chop>
    $BUTTON-DATE-NEXT-LABEL$
    Date Next
    </DefineVar>

## Default Setting

Nil.

## Resource Variables

N/A

## Examples

The following shows you what a resource file looks like:

    <!-- MHonArc resource file
      -->
    <SORT>
    <TITLE>
    MHonArc test
    </TITLE>

    <TTITLE>
    MHonArc test (by thread)
    </TTITLE>

    <!--=== Index Page Customizations =========================================-->

    <!-- Have LISTBEGIN contain last updated information
      -->
    <LISTBEGIN>
    <address>
    Last updated: $LOCALDATE$<br>
    $NUMOFMSG$ messages in chronological order<br>
    </address>
    <ul>
    <li><a href="$TIDXFNAME$">Thread Index</a></li>
    </ul>
    <p>
    Listing format is the following:
    <p>
    <ul><li>
    <strong>Subject</strong>
    (# of follow-ups)
    <em>From</em><br>
    </ul>
    <p>
    <hr>
    <ul>
    </LISTBEGIN>

    <!-- A compact listing template
      -->
    <LITEMPLATE>
    <li>
    <strong>$SUBJECT:40$</strong>
    ($NUMFOLUP$) <em>$FROMNAME$</em><br>
    </LITEMPLATE>

    <LISTEND>
    </ul>
    <p>
    <hr>
    <strong>
    <a href="http://example.com/">Home</a>
    </strong>
    <p>
    </LISTEND>

    <!--=== Thread Index Page Customizations ==================================-->
    <THEAD>
    <address>
    Thread index<br>
    Last updated: $LOCALDATE$<br>
    $NUMOFMSG$ messages<br>
    </address>
    <ul>
    <li><a href="$IDXFNAME$">Main Index</a></li>
    </ul>
    <hr>
    </THEAD>

    <!--=== Message Customizations ============================================-->
    <EXCS override>
    apparently
    errors-to
    followup
    forward
    lines
    message-id
    mime-
    nntp-
    originator
    path
    precedence
    received
    replied
    return-path
    status
    via
    x-
    </EXCS>

    <LABELSTYLES>
    -default-
    subject:strong
    from:strong
    to:strong
    </LABELSTYLES>

    <FIELDSTYLES>
    -default-
    subject:strong
    from:strong
    to:strong
    keywords:em
    newsgroups:strong
    </FIELDSTYLES>

    <MSGHEAD>
    <address>
    MHonArc test archive
    </address>
    </MSGHEAD>

    <MSGFOOT>
    <strong>
    <a href="http://example.com/">Home</a> |
    <a href="$IDXFNAME$">Main Index</a> |
    <a href="$TIDXFNAME$">Thread Index</a>
    </strong>
    </MSGFOOT>

    <!--=== Icons =============================================================-->
    <ICONS>
    application/*;[20x22]/icons/generic.gif
    application/msword;[20x22]/icons/layout.gif
    application/postscript;[20x22]/icons/ps.gif
    application/rtf;[20x22]/icons/layout.gif
    application/x-csh;[20x22]/icons/script.gif
    application/x-dvi;[20x22]/icons/dvi.gif
    application/x-gtar;[20x22]/icons/tar.gif
    application/x-gzip;[20x22]/icons/compressed.gif
    application/x-ksh;[20x22]/icons/script.gif
    application/x-latex;[20x22]/icons/tex.gif
    application/octet-stream;[20x22]/icons/binary.gif
    application/x-patch;[20x22]/icons/patch.gif
    application/pdf;[20x22]/icons/pdf.gif
    application/x-script;[20x22]/icons/script.gif
    application/x-sh;[20x22]/icons/script.gif
    application/x-tar;[20x22]/icons/tar.gif
    application/x-tex;[20x22]/icons/tex.gif
    application/x-zip-compressed;[20x22]/icons/compressed.gif
    application/zip;[20x22]/icons/compressed.gif
    audio/*;[20x22]/icons/sound1.gif
    chemical/*;[20x22]/icons/sphere2.gif
    image/*;[20x22]/icons/image2.gif
    message/external-body;[20x22]/icons/link.gif
    multipart/*;[20x22]/icons/layout.gif
    text/*;[20x22]/icons/text.gif
    video/*;[20x22]/icons/movie.gif
    */*;[20x22]/icons/generic.gif
    </ICONS>

More examples are available under Appendix: Resource File Examples.

## Version

1.0

## See Also

LANG

[Prev: QUIET] | [Resources][TOC] | [Next: RECONVERT]