MH & nmh: Email for Users & Programmers

May, 2006

Quick Folder Access

Typing folder names can get tedious -- especially if they're long. This section covers two ways to save typing. One is tcsh completion, where you type part of the name at a shell prompt and the shell fills in the rest. The second is a system that uses a table of folder abbreviations to create commands and shell variables that you can use at a shell prompt. With more programming, the second system can be extended to all parts of your MH setup.

Folder Name Completion

Most UNIX shells (csh, bash, etc.) have a feature that lets you type the first part of a pathname -- then hit a key (TAB or ESC) to ask the shell to complete the rest of the name. Some shells can let you complete things other than pathnames -- like hostnames and usernames. tcsh can do programmed completion from a list you supply. This section shows how to give tcsh a list of your MH folder names and do folder name completion. I adapted this from an article that Jesse Montrose posted to the comp.mail.mh newsgroup in January, 1997 -- with more information from Jesse since then.

Here's how folder name completion works. First, type an MH command, like refile. Then, as you type the argument list, type a plus sign (+) and the first part of a folder name; then press the TAB key to complete the name. If the shell finds a unique folder name, it will show you all of the name. Otherwise, the shell will beep. If the shell beeps, you can press CTRL-D to get a list of all possible completions, or type part or all of the folder name yourself. In the example below, I type the first part of a name, then get a list of the possible completions:

    % folder +mh-book/rev[TAB]
        ...terminal bell rings...
    % folder +mh-book/revi[CTRL-D]
    reviewers/  revisions/
    % folder +mh-book/revi
    
I can type enough of the subfolder name to make it unique, then hit TAB to complete it. There's a hidden "gotcha" in the example above: If a folder has subfolders of its own, they aren't shown unless you type part of their name (past the /) first. For instance, there are actually DELETE subfolders under the reviewers and revisions subfolders. If you have a lot of similar folder names, or you use subfolders, you may have to type most of the name before completion can finish it. Also, you'll need to keep hitting TAB to complete subfolder names; that can be either an advantage or a pain.

Still, for people who don't have many folders, the simple setup works great. Here's how to set it up. Put a line like this one in your tcsh setup file (like ~/.tcshrc):

    complete {show,pick,scan,refile} "c,+,D:$HOME/Mail,,"
    
The list of command names in the curly braces are the MH commands which will have folder name completion enabled. The path $HOME/Mail is the location of your MH mail directory.

You can customize that setup to include only certain folder names. For instance, you might want to omit the DELETE subfolders. The setup above also doesn't include read-only folders that aren't under your MH Mail directory (see the section Sharing Other Users' Folders). Finally, you might not want to have to press TAB to complete each subfolder name. Here's a setup that handles all of those; it's more complicated but also more flexible. To do this, first make a cron or at job that builds a list of your folders in a file. The file should contain the folder nanes you want to match. For example, to make a file named folderlist in your MH directory, run a command like the one below. The sed command adds a plus sign (+) to the start of each folder name:

    folders -fast -recurse | sed 's/^/+/' > $HOME/Mail/folderlist
    
The command above includes all folders, including read-only folders. If you want to omit some folder names, add a sed expression. (You could also use perl or awk.) For example, to skip all DELETE subfolders:
    folders -fast -recurse | sed -e '/DELETE$/d' -e 's/^/+/' > $HOME/Mail/folderlist
    
Next, add a command like the following to your shell startup file (typically .tcshrc). In the curly braces, list the command names which should have expansion:
    complete {folder,refile,scan,show} 'C@*@`cat ~/Mail/folderlist`@'
    
Each time you use a completion, tcsh will run the cat command to read the current folder list. You can update the list at any time without waiting for cron to rebuild it.

Folder Name Variables

The folder name completion system above is nice because you don't need to remember anything but your folder names. As the example showed, though, you may need to type quite a bit of a folder name (especially a subfolder name) to match it. Here's another approach. It uses a table of common folder names and abbreviations. The system has three parts:

  1. A file named folder_table holds a list of the folders I use a lot. It has two tab-separated fields; the first holds the abbreviation and the second has the folder name that the abbreviation stands for:
          # "MH & xmh" book:
          mb	+mh-book
          mba	+mh-book/authors
                  ...etc...
          # Mailing lists:
          mj	+m/majordomo
          mw	+m/mh-workers
          # Ms. Cellaneous:
          fr	+friends
          
    The folder names are mnemonic, so I memorize them pretty quickly. The names can be as long or short as you want.
  2. When each shell starts, it sets up shell variables from those abbreviations. For instance, the variable $mba expands to the string +mh-book/authors. Unlike the folder name completion setup, these variables work for any command, at any shell prompt. So, to change the current folder to mh-book/authors:
          % folder $mba
               mh-book/authors+ has  144 messages (   1- 311); cur= 310; (others).
          
    Or, to scan the last ten messages in the friends folder:
          % scan last:10 $fr
           374  05/14 To:dirk@anum.edu   About the weekend **rfl digest**
              ...
          
  3. The table is also used to set up commands for filing messages with the refile and rfl programs. These are even "shorter" shortcuts than the variable names. The command names start with r for refile and a ("append") for rfl; they end with the abbreviation for the folder. For example, to refile (f) the current message into the mh-book/authors (mba) folder, I type:
          % fmba
          
    To "rfl" (append as a digest) messages 23 and 25 to the friends folder:
          % afr 23 25
          rfl: adding message 23 to 375 in +friends.
          rfl: adding message 25 to 324 in +friends.
              ...
          
    Those commands are created from the folder_table file by a script named mk_fol_names.install. You can easily add other commands (that do a scan, for example) that start with another letter, like s.
If you don't remember an abbreviation, you can list the shell variable names or the folder_table file. If you want to be sure the abbreviation for your m/mh-users folder is mu, you can check it with echo. Or grep the folder table:
    % echo $mu
    +m/mh-users
    % grep users ~/Mail/folder_table
    mu	+m/mh-users
    mj	+m/majordomo-users
    
If you use that grep command often, it's easy to shorten into an alias or shell function.

These programs and the folder table are explained in the Section Explanation of mk_fol_names Package.