Changing Table of Contents

[previous] [next] [table of contents] [index]

You can change the appearance of the Table of Contents. This section shows how to use MH scan format files such as scan.timely. It also gives an example of creating your own format with a custom format file. There's more information about this in the Sections scan Format Files and MH Format Strings.


xmh makes its Table of Contents by running the MH scan command. It stores scan output in a .xmhcache file in each folder. xmh displays the .xmhcache file in its Table of Contents area. Before displaying .xmhcache, xmh "edits" the file (in effect) to add characters like the plus sign (+) (for the current message), D (for messages marked to be deleted), and so on.

Whenever xmh rescans a folder, it remakes the .xmhcache file. If you'd like to see the file for yourself, you can read the inbox file with more(1) by using commands like the following.

% ls -l `mhpath +inbox`/.xmhcache
-rw-r--r--  1 ehuser  400 Jul 14 04:47 /u/ehuser/Mail/inbox/.xmhcache
% more `mhpath +inbox`/.xmhcache
   1  12/07 "Joe Doe"          Here's the first message you asked for<<Hi, Angela! You asked me to
   2+ 12/07 "Joe Doe"          Another message for you<<Want some pizza? I could order and they'd b
That .xmhcache file is actually 100 characters wide (see Section TocWidth about TocWidth). Each message is all on one line -- just like the output of scan(1) in its standard format.

If you follow some simple rules, you can change what's shown by the Table of Contents. Those rules are:

  1. The message number goes in the first four columns, right justified (just like the standard scan(1) output). If your format file tries to make the message number wider or left-justify it, xmh can get unhappy.
  2. Column 5 is reserved for xmh to write the plus sign (+), D, and so on.
  3. The rest of the line -- columns 6 to the column width set by the TocWidth resource -- are yours to play with.
  4. Each message summary must fit on one line; there are no multiline scans in xmh.
A good overall rule for changing things is: don't try to edit the .xmhcache file yourself. Instead, change the output of the scan(1) command. You do that by changing the scan switches in your MH profile. (Don't try to set -width in MH profile, though. Instead, use the TocWidth resource -- in your .Xdefaults file.)

If you change the scan format, remember that old .xmhcache files won't be updated automatically. It's a good idea to do a Rescan Folder in any folders you use much. In the same way, if you stop using a format file, you'll need to Rescan again.

Using a Standard scan Format File

For example, to make scan use its standard scan.timely format file in its Table of Contents, use this entry in your MH profile:
scan: -form scan.timely
Then, use the Rescan Folder command to rebuild .xmhcache. Your Table of Contents will change from the default, in the first Figure below, to the new version with scan.timely in the second Figure below. (If you haven't seen scan.timely before, look at the date column in the second Figure and see the Section scan Format Files.)

Figure: Table of Contents with default scan(1) format


Figure: Table of Contents with scan.timely format file


In the next section, we'll be adapting the format file called scan.default. It's explained in the Section The Default scan Format File. By the way, if you haven't read the Chapter MH Formatting yet, this is a good time. You won't need to understand it to make the changes shown in the next section. Reading it will help you understand what's happening, though -- and go on to make your own changes. The Example below has a copy of scan.default. The file has been replaced with a more-complex file in recent MH versions, but this simpler version is fine as an example.

Example: scan.default format file

1> %; NOTE: This file is supplied for reference only; it shows the default
2> %;  format string (for non-UK sites) which was compiled into "scan".
3> %;  See the source file "h/scansbr.h" for details.
4> %4(msg)%<(cur)+%| %>%<{replied}-%?{encrypted}E%| %>\
5> %02(mon{date})/%02(mday{date})%<{date} %|*%>\
6> %<(mymbox{from})%<{to}To:%14(friendly{to})%>%>%<(zero)%17(friendly{from})%>  \
7> %{subject}%<{body}<<%{body}>>%>

A Wider Table of Contents

If your xmh window usually doesn't come close to filling your screen's width, and you'd like more information across the screen, this section shows how.

The next Figure is an example of what the wide Table of Contents looks like.

Figure: Wide main window (and normal composition window)


(Yours doesn't have to look just like this.) The date is spelled out. The time is shown (on a 24-hour clock). Next comes the size of the message, in characters. The space for the sender's (or the addressee's) address is wider -- in most cases, you can see the whole address instead of just the first part. The leftover room goes to the subject and body. That took just a few changes to the scan.default format file (shown in the previous Example). Compare it to the edited scan.xmhwide format file in the next Example.

Example: scan.xmhwide format file

%4(msg)%<(cur)+%| %>%<{replied}-%| %>\
%(month{date}) %02(mday{date})'%02(year{date})\
%<{date} %|*%> \
%2(hour{date}):%02(min{date}) \
%5(size) \
  %{subject}%<{body} <<%{body}>>%>
If you haven't read Section MH Format Strings, you can just copy the text from the Example above into your MH directory, in a file named scan.xmhwide, and try it. See the Section Obtaining Example Files From This Book.

You'll need to set a wider TocWidth so that the standard scan(1) command will make enough output to fill the window. A resource entry of *TocWidth:133 is right in this example, but yours may be different. Also, because you'll be setting a wide master window (in the xmh -geometry command below), you should explicitly make your composition windows normal size.

Tell scan to read this new format file. Do that by editing a scan entry in your MH profile:

scan: -form scan.xmhwide
Finally, start xmh. To set the master window size, I like to use the -geometry option on the command line (but your resource file might be a better place for it after you get a setting you like):
xmh -geometry 830x450+50+5 -xrm '*CompGeometry: 660x460' &
When you understand scan format files and the way that xmh uses them, you can use almost any format that will fit on a line.

[Table of Contents] [Index] [Previous: Template Draft Files Set Headers] [Next: Changing the Print Command]

Last change $Date: 1996/06/06 15:09:10 $

This file is from the third edition of the book MH & xmh: Email for Users & Programmers, ISBN 1-56592-093-7, by Jerry Peek. Copyright © 1991, 1992, 1995 by O'Reilly & Associates, Inc. This file is freely-available; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation. For more information, see the file copying.htm.

Suggestions are welcome: Jerry Peek <>