#!/usr/bin/perl -w =head1 NAME

- SYNOPSIS
- DESCRIPTION
- RESULTS
- OPTIONS
- INSTALLATION FOR SCAN
- INSTALLATION FOR EXMH
- NOTES
- TODO
- BUGS
- DOWNLOAD
- AUTHOR
- VERSION

# SYNOPSIS

            mhthread [options] +folder
            mhthread [options] /path/to/folder

options accepted: [-debug] [-no-write] [-fast] [-lock]

# DESCRIPTION

This will thread an MH folder. It re-orders the messages (as `sortm(1)` would do), and annotates each one with a new header, ``X-MH-Thread-Markup'', which can be displayed by scan(1).

Together, this results in the messages being displayed in ``threaded'' order, as in `trn(1)` or mutt(1).

Sequences will be rewritten appropriately. The folder will also be ``packed'', as if 'folder -pack' had been run; see folder(1).

# RESULTS

Here's some sample output from scan(1), after threading the folder:

      430  03/23 mathew              3  [Asrg] Re: [OffTopic - NNTP]
      431  03/23 Kee Hinckley        5  |- [Asrg] Re: [OffTopic - NNTP]
      432 -03/23 Chuq Von Rospach   11  | |- Parameters for success? (was Re: [A
      433  03/23 To:Chuq Von Rospa   4  | | \- Re: Parameters for success? (was
      434  03/23 Matt Sergeant       3  | \- Re: [Asrg] Re: [OffTopic - NNTP]
      435  03/23 Chuq Von Rospach    7  \- Re: [Asrg] Re: [OffTopic - NNTP]

# OPTIONS

-fast
  Use an on-disk cache to speed up operation.

-lock
  Use a folder-wide lock-file to synchronize access to folders, so that multiple processes will not stomp on each other's changes or cause folder corruption. If you use this, you should ensure that you also use a locking version of other tools, such as the `lockedrcvstore` script that comes with ExMH (typical location: `/usr/lib/exmh*/misc/lockedrcvstore`).

-no-write
  Do not rewrite the messages; instead, output a line for each message noting the actions that would be taken.

-debug
  Output debugging info to stderr.

Note that options will also be read from the `mhthread` entry in your `.mh_profile` file, in traditional MH style.

# INSTALLATION FOR SCAN

To display the results in `scan(1)` output, use something like the following for the subject-display part of the scan.form file:

      %(decode{x-mh-thread-markup})%(decode{subject})

If you do not have a ``scan.form'' file of your own, you will need to set it up. This functionality is accessed using the -form or -format switches to the `scan(1)` command. To use this, copy the /etc/nmh/scan.default file to your ~/Mail dir and modify it with the above line, then add

      scan: -form scan.form

to your ~/.mh_profile.

# INSTALLATION FOR EXMH

Add the following function to your `~/.tk/exmh/user.tcl` file:

      proc Folder_Thread {} {
        global exmh
        Background_Wait
        Exmh_Status "Threading folder..." blue
        if {[Ftoc_Changes "Thread"] == 0} then {
          if {[catch {MhExec mhthread +$exmh(folder)} err]} {
              Exmh_Status $err error
          } else {
            # finish off by using the ExMH packing logic to redisplay folder
            Folder_Pack
            # then show the first unseen message
            Msg_ShowUnseen
          }
        }
      }

Next, you need to rebuild the `tclIndex` file. Run `tclsh` and type:

      auto_mkindex ~/.tk/exmh *.tcl

Now add a button to run this function. To do this, you must exit ExMH first, then edit the `~/.exmh/exmh-defaults` file and add these files at the top of the file:

      *Fops.ubuttonlist: thread
      *Fops.thread.text: Thread
      *Fops.thread.command: Folder_Thread

Restart ExMH, and there should be a new button marked Thread on the folder button-bar. Press this to re-thread the current folder.

# NOTES

The threading algorithm uses the In-Reply-To, Message-Id and References headers. Thanks to JWZ for guidance, in the form of his page on threading at `http://www.jwz.org/doc/threading.html`.

The 'X-MH-Thread-Markup' headers are encoded using RFC-2047 encoding, using 'no-break space' characters for whitespace, as otherwise MH's `scan(1)` format code will strip them. Here's an example of the results:

      X-MH-Thread-Markup: =?US-ASCII?Q?=a0=a0=a0=a0=5c=2d=a0?=

# TODO

dealing with private sequences (stored in .mh_profile); limiting displayed thread-depth to keep UI readable (so far has not been a problem).

# BUGS

duplicate messages will always be shuffled in order each time `mhthread` is run, due to handling of identical Message-Ids.

# DOWNLOAD

Latest version can be found at http://jmason.org/software/mhthread/ .

# AUTHOR

Justin Mason, `jm dash mhthread dash nospam at jmason dot org`

# VERSION

version = 1.5, Apr 25 2003 jm