Annotating Headers with anno

You can add new header fields to a message in your folder. Here's an example of where this could be useful.

Imagine that you're part of a group of people who maintain some products. When people in your group or in other parts of your company find a problem, they send mail to your group manager. Your group uses MH for a product problem-tracking system. The manager could use anno to add (or annotate) fields like X-found: and X-fixed: to the header fields.

NOTE: To be sure that your field name is legal, it's a good idea to put the characters X- before it. The name should have only letters, digits, and dashes in it. (For regulations about mail headers, see the document "RFC 822 - Standard for the Format of ARPA Internet Text Messages" Or, ask your computer's Postmaster for help.)

Look at the following example commands. Here, I'll use anno to add the following field to the current message header:

    X-fixed: Linda Farpel

Next, I display the message with show -- notice the other X-fixed: field, which anno added with the current time. Also see the X-found: field that shows who found the problem. The annotation text has a space in it, so quotes are required when you type the anno command:

    % date
    Tue Feb 02 13:14:05 CST 1993
    % anno -component X-fixed -text 'Linda Farpel'
    % show
    (Message server:234)
    X-fixed: Tue, 02 Feb 93 13:14:29 -0600
    X-fixed: Linda Farpel
    X-found: Mon, 01 Feb 93 09:25:44 -0600
    X-found: Jody Hammersmith
    From: andyb@field.bigcorp.com (Andy Bowman)
    To: bugtrack@sw.bigcorp.com
        ...

(MH calls the parts of a message header "components." The term used in Internet standards documents like RFC 822 is "field." I use that term in this book. Unfortunately, the anno switch for adding header fields is named -component.)

Besides being able to keep the history of a problem report in the header, you can use pick to search for messages by the dates in any of the annotated fields. For example, if someone wanted to find all the problems fixed in January 1993:

    % pick -datefield X-fixed -after 1-Jan-93 -and -before 1-Feb-93

The -datefield switch tells pick to search X-fixed: field for its dates. (Without -datefield, pick would search the Date: field.) Be sure to put the -datefield switch before (to the left of) the -before and -after switches.

This kind of setup would be a good one for a read-only folder with bug reports that all the maintenance workers could read and that only the manager (the user who owned the folder) could modify. Here's more about folder sharing.

Here are five miscellaneous points about annotation:

By default, anno uses its -noinplace switch. This breaks any existing links to the message. If you want to preserve the links, use anno -inplace.

If you don't use the -component switch, anno will ask for it:

      % anno -text 'Linda Farpel'
      Enter component name: X-fixed

As you've seen, anno usually adds two fields, one with the date and the other with your text. To make anno omit the text field, leave off the -text switch. To omit the date, use the -nodate switch.
```
      % anno -component xyz

      % anno -component xyz -text 'blah blah' -nodate

      
```
When you scan for an annotation with a scan format file, the command will only pay attention to the first annotation with a particular name. The order of the annotations is important. By default, as the previous bug-tracking examples above, each date annotation comes before its corresponding text annotation. If you want to reverse the order of the annotations, use two anno commands this way:
```
      % anno -comp X-fixed
      % anno -comp X-fixed -text 'Linda Farpel' -nodate
      % show
      (Message server:234)
      X-fixed: Linda Farpel
      X-fixed: Tue, 02 Feb 93 13:14:29 -0600
          ...
      
```
The most recent annotation will be found first. In this case, scan would find the text field instead of the date.
You might also decide to give the date and text fields different names.
Your messages can be annotated automatically by the commands repl, forw, and dist.