MHonArc FAQ: Index Pages

[Prev][Next][TOC][Home]

## Index Pages

- What are all the different index types?
- Can I have additional indexes beyond the default main and thread index?
- Can I have multi-page indexes?
- Can I sort messages by author?
- How does the OTHERINDEXES resource work?
- Can I include links to message attachments on index pages?

| ### What are all the different index types?

MHonArc catagorizes indexes into to types: main and thread. Main covers indexes listing messages by the following criteria:

- Author
- Date
- Subject
- Message number

When the documentation refers to main index, it refers to the index listing messages by author, date, or subject. Therfore, all resources. and resource variables, that refer to the main index apply to either an author, date, or subject index. The type of main index is controled by the SORT, SUBSORT, AUTHSORT resources.

By default, MHonArc creates a date index and a thread index. Author index support is available only in v2.0 beta 2 or later.

| ### Can I have additional indexes beyond the default main and thread index?

Yes. In version 1.2 (or later), a resource was added called OTHERINDEXES. With this resource, you are able to define an arbitrary number of indexes you desire. The additional indexes may be in any format you desire and that is supported by MHonArc. Refer to the documentation for the usage of OTHERINDEXES (also see "How does the OTHERINDEXES resource work?").

NOTE

  MHonArc will NOT automatically create links to any indexes created via the OTHERINDEXES resource. You will need to modify the relevant index and messages resources to contain the additional links. See the LISTBEGIN and THEAD resources.

| ### Can I have multi-page indexes?

Yes, in v2.0 or later. Setting the MULTIPG and IDXSIZE will cause indexes to to be listed across multiple pages with IDXSIZE determine the number of messages listed per page.

| ### Can I sort messages by author?

Yes, with v2.0 beta 2, or later.

| ### How does the OTHERINDEXES resource work?

I am going to describe a basic example on how OTHERINDEXES can be used.

First, lets have the top resource file (call it "top.rc") that defines the formatting of the default 2 indexes (a main and a thread). Example:

    *** snip "top.rc" ***
    <MAIN>
    <THREAD>
    <SORT>
    <NOTREVERSE>
    <NOREVERSE>
    *** snip "top.rc" ***

I may have a bunch of layout stuff, but that is not important for this discussion.

The above tells MHonArc to create a date and thread index. I am explicit with the settings to avoid potential unknown settings from a default resource file (ie. It is always good to be explicit, especially when we get to otherindexes).

Now, I would like to also create subject and author indexes. In "top.rc" I would add the following:

    *** snip "top.rc" ***
    <OTHERINDEXES>
    subject.rc
    date.rc
    </OTHERINDEXES>
    *** snip "top.rc" ***

The filenames listed are arbitrary, but it is useful if they imply their purpose. Since absolute pathnames were not used, the files will be looked for in the current working directory, or in the archive directory. Since the current working directory may not be appropriate, it is usually best to put the files in the archive directory.

The following now shows the important settings for each file:

    *** snip "subject.rc" ***
    <MAIN>
    <NOTHREAD>
    <SUBSORT>
    <IDXFNAME>
    subject.html
    </IDXFNAME>
    <IDXPREFIX>
    subject
    </IDXPREFIX>
    <NOREVERSE>
    *** snip "subject.rc" ***

    *** snip "author.rc" ***
    <MAIN>
    <NOTHREAD>
    <AUTHSORT>
    <IDXFNAME>
    author.html
    </IDXFNAME>
    <IDXPREFIX>
    author
    </IDXPREFIX>
    <NOREVERSE>
    *** snip "author.rc" ***

Again, notice how I am being explicit. MHonArc does not reset resources when reading the otherindexes resource files. with one exception: THREAD is shut-off. To avoid overriding the default index files, I must explicitly redefine IDXFNAME (amd IDXPREFIX if MULTIPG is active). If I want different layouts for my other indexes, I must explicitly define those, or they will use what was ever set in top.rc (or the applicable default resource setting(s) when no explicit setting provided).

NOTE: Otherindexes resource file only defines a *single* index type: main or thread. If you specify the THREAD, a thread index will be created and all MAIN related resources are ignored. I.e. THREAD overrides MAIN.

WARNING: Do NOT define OTHERINDEXES in your otherindexes resource files. Also, make sure there is no self references. If you do not heed these warnings, you will cause an infinite loop, and/or unpredictable results.

Make sure OTHERINDEXES resource files are present for all updates to an archive. Mhonarc only stores settings for the default indexes, so the resource files are needed each time for other indexes.

What I left out in this example is the redefinition of the navigational based resources. Since I am adding more indexes, I would have to redefine resources like TOPLINK, BOTLINKS, LISTBEGIN, THEAD, etc, so there will be links to the other indexes.

| ### Can I include links to message attachments on index pages?

Not directly, but a (dirty) work-around maybe possible. You can modify the mhexternal.pl filter to write to a file (name based off the message number) with some HTML markup that creates the HTML attachment list (mhexternal.pl knows about content-types and other stuff, so it can make a useful list). Note, since mhexternal.pl works on a single part at a time, it needs to create the list via append operations to the file. The implementation is similiar to how mhexternal.pl supports placing attachments into a subdirectory. Make sure that mhexternal.pl returns the file as part of the return value so it is automatically deleted if the message is removed from the archive.

Then, you define the LITEMPLATE resource to use a server-side include to include the file as part of the message listing. I did say it was dirty, but it should work.

[Prev][Next][TOC][Home]