Mike Kupfer <kupfer@...> wrote:
> I have on my Todo list (fairly low) something about getting MH-E to
> use a different date format. (I have mail dating back to 1984 or
> 1985, and I want to see the year in the scan output.)
If you're feeling brave, read this:
http://sourceforge.net/tracker/index.php?func=detail&aid=627472&group_id=13357&atid=363357
> I don't know when I'll get to it, but I'd certainly appreciate it if
> the manual is complete in this area.
I have a few open questions for the developers (marked with XXX in the
following text), but here's what I have as of today. I just added the
example at the bottom and have improved the variable descriptions so
that you won't have to go to the source (like I did) to see how a
variable is interpreted. Corrections, additions, comments, welcome!
(Especially for the questions marked with XXX.)
Appendix A Scan Line Formats
****************************
This appendix discusses how MH-E creates, parses, and manipulates scan
lines. If you have your own MH scan or inc format files, you *can*
teach MH-E how to handle them, but it isn't easy as you'll see.
This table lists the options in the `mh-scan-line-formats'
customization group.
`mh-adaptive-cmd-note-flag'
On means that the message number width is determined dynamically
(default: `on').
`mh-scan-format-file'
Specifies the format file to pass to the scan program (default:
`Use MH-E scan Format').
`mh-scan-prog'
Program used to scan messages (default: `"scan"').
There are a couple of caveats when creating your own scan format
file. First, MH-E will not work if your scan lines do not include
message numbers. It will work poorly if you don't dedicate a column for
showing the current message and notations.
If you've created your own format to handle long message numbers,
you'll be pleased to know you no longer need it since MH-E adapts its
internal format based upon the largest message number if
`mh-adaptive-cmd-note-flag' is on (the default). If you prefer
fixed-width message numbers, turn off `mh-adaptive-cmd-note-flag' and
call `mh-set-cmd-note' with the width specified by your format file
(see `mh-scan-format-file'). For example, the default width is 4, so
you would use `(mh-set-cmd-note 4)'.
The default setting for `mh-scan-format-file' is `Use MH-E scan
Format'. This means that the format string will be taken from the
either `mh-scan-format-mh' or `mh-scan-format-nmh' depending on whether
MH or nmh (or GNU mailutils) is in use. You can also set this option to
`Use Default scan Format'. If you have a format file that you want MH-E
to use but not MH, you can set this option to `Specify a scan Format
File' and enter the name of your format file.
*XXX If `mh-scan-format-file' is anything but `Use MH-E scan
Format', the function `mh-set-cmd-note' doesn't do anything-maybe it
should. Docstring for `mh-adaptive-cmd-note-flag' doesn't realize this.
`mh-set-cmd-note' and `mh-cmd-note' deal with column locations but
speak of widths.*
The scan format that MH-E uses when `mh-scan-format-file' is set to
its default of `Use MH-E scan Format' is held in the variables
`mh-scan-format-nmh' and `mh-scan-format-mh' depending on whether you
are using nmh (or GNU mailutils) or not. Typically, you create your own
format files rather than modifying these variables. The value of
`mh-scan-format-nmh' is:
(concat
"%4(msg)"
"%<(cur)+%| %>"
"%<{replied}-"
"%?(nonnull(comp{to}))%<(mymbox{to})t%>"
"%?(nonnull(comp{cc}))%<(mymbox{cc})c%>"
"%?(nonnull(comp{bcc}))%<(mymbox{bcc})b%>"
"%?(nonnull(comp{newsgroups}))n%>"
"%<(zero) %>"
"%02(mon{date})/%02(mday{date})%<{date} %|*%>"
"%<(mymbox{from})%<{to}To:%14(decode(friendly{to}))%>%>"
"%<(zero)%17(decode(friendly{from}))%> "
"%(decode{subject})%<{body}<<%{body}%>")
The setting for `mh-scan-format-mh' is similar, except that MH
doesn't have the `decode' function (which is used to decode RFC 2047
encodings).
These strings are passed to the scan program via the `-format' arg.
The formats are identical to the defaults except that additional hints
for fontification have been added to the existing notations in the
fifth column (remember that in Emacs, the first column is 0). The
values of the fifth column, in priority order, are: `-' if the message
has been replied to, `t' if an address in the `To:' field matches one
of the mailboxes of the current user, `c' if the `Cc:' field matches,
`b' if the `Bcc:' field matches, and `n' if a non-empty `Newsgroups:'
field is present. *XXX Is it kosher to modify these variables?*
The name of the program that generates a listing of one line per
message is held in `mh-scan-prog' (default: `"scan"'). Unless this
variable contains an absolute pathname, it is assumed to be in the
`mh-progs' directory. You may link another program to `scan' (see
`mh-profile'(5)) to produce a different type of listing(1).
If you change the format of the scan lines you'll need to tell MH-E
how to parse the new format. As you will see, quite a lot of variables
are involved to do that. Use `M-x apropos RET mh-scan.*regexp'' to
obtain a list of these variables. You may also have to call
`mh-set-cmd-note' with column for your notations if you turn off
`mh-adaptive-cmd-note-flag' although you will need to set the
`mh-cmd-note' variable manually with `setq' if `mh-scan-format-file' is
set to anything other than `Use MH-E scan Format'. Note that unlike
most of the user options described in this manual, these are variables
and must be set with `setq' instead of in a customization buffer. The
first variable has to do with pruning out garbage.
`mh-scan-valid-regexp'
This regular expression describes a valid scan line. This is used
to eliminate error messages that are occasionally produced by
`inc'(2) or `scan' (default: `"^ *[0-9]"').
Next, many variables control how the scan lines are parsed.
`mh-scan-body-regexp'
This regular expression matches the message body fragment. Note
that the default setting of `mh-folder-font-lock-keywords' expects
this expression to contain at least one parenthesized expression
which matches the body text as in the default of
`"\\(<<\\([^\n]+\\)?\\)"'. If this regular expression is not
correct, the body fragment will not be highlighted.
`mh-scan-cur-msg-number-regexp'
This regular expression matches the current message. It must match
from the beginning of the line. Note that the default setting of
`mh-folder-font-lock-keywords' expects this expression to contain
at least one parenthesized expression which matches the message
number as in the default of `"^\\( *[0-9]+\\+\\).*"'. This regular
expression should be correct as it is needed by non-fontifying
functions. See also `mh-note-cur'. *XXX Why is space inside
parenthesis?*
`mh-scan-date-regexp'
This regular expression matches a valid date. It must *not* be
anchored to the beginning or the end of the line. Note that the
default setting of `mh-folder-font-lock-keywords' expects this
expression to contain only one parenthesized expression which
matches the date field as in the default of
`"\\([0-9][0-9]/[0-9][0-9]\\)"'. If this regular expression is not
correct, the date will not be highlighted. See also
`mh-scan-format-regexp'.
`mh-scan-deleted-msg-regexp'
This regular expression matches deleted messages. It must match
from the beginning of the line. Note that the default setting of
`mh-folder-font-lock-keywords' expects this expression to contain
at least one parenthesized expression which matches the message
number as in the default of `"^\\( *[0-9]+\\)D"'. This regular
expression should be correct as it is needed by non-fontifying
functions. See also `mh-note-deleted'. *XXX Why is space inside
parenthesis?*
`mh-scan-format-regexp'
This regular expression matches the output of scan. Note that the
default setting of `mh-folder-font-lock-keywords' expects this
expression to contain at least three parenthesized expressions. The
first should match the fontification hint (see
`mh-scan-format-nmh'), the second is found in
`mh-scan-date-regexp', and the third should match the user name as
in the default of
`"(concat "\\([bct]\\)" mh-scan-date-regexp "*\\(..................\\)")"'.
If this regular expression is not correct, the notation hints and
the sender will not be highlighted.
`mh-scan-good-msg-regexp'
This regular expression matches "good" messages. It must match from
the beginning of the line. Note that the default setting of
`mh-folder-font-lock-keywords' expects this expression to contain
at least one parenthesized expression which matches the message
number as in the default of `"^\\( *[0-9]+\\)[^D^0-9]"'. This
regular expression should be correct as it is needed by
non-fontifying functions. *XXX Why is space inside parenthesis?*
`mh-scan-msg-format-regexp'
This regular expression finds the message number width in a scan
format. Note that the message number must be placed in a
parenthesized expression as in the default of
`"%\\([0-9]*\\)(msg)"'. This variable is only consulted if
`mh-scan-format-file' is set to `Use MH-E scan Format'. *XXX
Internal use only? Delete?*
`mh-scan-msg-format-string'
This is a format string for the width of the message number in a
scan format. Use `0%d' for zero-filled message numbers. This
variable is only consulted if `mh-scan-format-file' is set to `Use
MH-E scan Format' (default: `"%d"'). *XXX Internal use only?
Delete?*
`mh-scan-msg-number-regexp'
This regular expression extracts the message number. It must match
from the beginning of the line. Note that the message number must
be placed in a parenthesized expression as in the default of
`"^ *\\([0-9]+\\)"'.
`mh-scan-msg-overflow-regexp'
This regular expression matches overflowed message numbers
(default: `"^[?0-9][0-9]"').
`mh-scan-msg-search-regexp'
This regular expression matches a particular message. It is a
format string; use `%d' to represent the location of the message
number within the expression as in the default of
`"^[^0-9]*%d[^0-9]"'.
`mh-scan-rcpt-regexp'
This regular expression specifies the recipient in messages you
sent. Note that the default setting of
`mh-folder-font-lock-keywords' expects this expression to contain
two parenthesized expressions. The first is expected to match the
`To:' that the default scan format file generates. The second is
expected to match the recipient's name as in the default of
`"\\(To:\\)\\(..............\\)"'. If this regular expression is
not correct, the recipient will not be highlighted.
`mh-scan-refiled-msg-regexp'
This regular expression matches refiled messages. It must match
from the beginning of the line. Note that the default setting of
`mh-folder-font-lock-keywords' expects this expression to contain
at least one parenthesized expression which matches the message
number as in the default of `"^\\( *[0-9]+\\)\\^"'. This regular
expression should be correct as it is needed by non-fontifying
functions. See also `mh-note-refiled'. *XXX Why is space inside
parenthesis?*
`mh-scan-subject-regexp'
This regular expression matches the subject. It must match from the
beginning of the line. Note that the default setting of
`mh-folder-font-lock-keywords' expects this expression to contain
at least three parenthesized expressions. The first is expected to
match the `Re:' string, if any. The second matches an optional
bracketed number after `Re:', such as in `Re[2]:' (and is thus a
sub-expression of the first expression) and the third is expected
to match the subject line itself as in the default of
`"^ *[0-9]+........[ ]*...................\\([Rr][Ee]\\(\\[[0-9]+\\]\\)?:\\s-*\\)*\\([^<\n]*\\)"'.
This regular expression should be correct as it is needed by
non-fontifying functions.
Finally, there are a slew of variables that control how MH-E
annotates the scan lines.
`mh-cmd-note'
Column where notations begin (default: 4). This variable should be
set with the function `mh-set-cmd-note'. This variable may be
updated dynamically if `mh-adaptive-cmd-note-flag' is on. The
following variables contain the notational characters.
Note that the first column in Emacs is 0.
`mh-note-copied'
Messages that have been copied are marked by this character
(default: `?C').
`mh-note-cur'
The current message (in MH, not in MH-E) is marked by this
character (default: `?+'). See also
`mh-scan-cur-msg-number-regexp'.
`mh-note-deleted'
Messages that have been deleted are marked by this character
(default: `?D'). See also `mh-scan-deleted-msg-regexp'.
`mh-note-dist'
Messages that have been redistributed are marked by this character
(default: `?R').
`mh-note-forw'
Messages that have been forwarded are marked by this character
(default: `?F').
`mh-note-printed'
Messages that have been printed are marked by this character
(default: `?P').
`mh-note-refiled'
Messages that have been refiled are marked by this character
(default: `?^'). See also `mh-scan-refiled-msg-regexp'.
`mh-note-repl'
Messages that have been replied to are marked by this character
(default: `?-').
`mh-note-seq'
Messages in a user-defined sequence are marked by this character
(default: `?%'). Messages in the `search' sequence are marked by
this character as well.
For example, let's say I have the following in `scan.format' which
displays the sender, the subject, and the message number. It also
allows a column for notations to the left of the message number and
places a `+' after the message number for the current message according
to MH.
%20(decode(friendly{from})) %50(decode{subject}) %4(msg)%<(cur)+%| %>
The first thing you have to do is tell MH-E to use this file.
Customize `mh-scan-format-file' and set its value to `Use Default scan
Format'.
Next, tell MH-E what a valid scan line looks like so that you can at
least display the output of scan in your MH-Folder buffer.
(setq mh-scan-valid-regexp "[0-9]+[+D^ ]$")
Now, in order to get rid of the `Cursor not pointing to message'
message, you need to tell MH-E how to access the message number. You
should also see why MH-E requires that you include a message number in
the first place.
(setq mh-scan-msg-number-regexp "^.* \\([0-9]+\\)[+D^ ]$")
(setq mh-scan-msg-search-regexp " %d[+D^ ]$")
In order to get the next and previous commands working, add this.
(setq mh-scan-good-msg-regexp "^.* \\([0-9]+\\)[+D^ ]$")
Note that the current message isn't marked with a `+' when moving
between the next and previous messages. Here are the variables required
to get this working.
(setq mh-cmd-note 76)
(setq mh-scan-cur-msg-number-regexp "^.* \\([0-9]+\\)\\+$")
Finally, add the following to delete and refile messages.
(setq mh-scan-deleted-msg-regexp "^.* \\([0-9]+\\)D$")
(setq mh-scan-refiled-msg-regexp "^.* \\([0-9]+\\)\\^$")
A couple of more settings round out the highlighting.
(setq mh-scan-subject-regexp "^.....................\\([Rr][Ee]\\(\\[[0-9]+\\]\\)?:\\s-*\\)*\\(.*\\) [0-9]+[+D^ ]$")
---------- Footnotes ----------
(1) See the section Find and Specify with scan pick Ranges Sequences
(http://www.ics.uci.edu/~mh/book/mh/faswsprs.htm) in the MH book.
(2) See the section Reading Mail: inc show next prev
(http://www.ics.uci.edu/~mh/book/mh/reapre.htm) in the MH book.
--
Bill Wohler <wohler@...> http://www.newt.com/wohler/ GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.
|