* mh-customize.el (mh-adaptive-cmd-note-flag)

(mh-scan-format-file, mh-scan-prog): Sync docstrings with manual.

* mh-e.el (mh-scan-format-mh, mh-note-deleted, mh-note-refiled)
(mh-note-cur, mh-scan-good-msg-regexp)
(mh-scan-deleted-msg-regexp, mh-scan-refiled-msg-regexp)
(mh-scan-valid-regexp, mh-scan-cur-msg-number-regexp)
(mh-scan-date-regexp, mh-scan-rcpt-regexp, mh-scan-body-regexp)
(mh-scan-subject-regexp, mh-scan-format-regexp)
(mh-folder-font-lock-keywords, mh-set-cmd-note): Sync docstrings with
manual.

* mh-funcs.el (mh-note-copied): Sync docstrings with manual.

* mh-utils.el (mh-goto-msg): Use mh-scan-msg-search-regexp instead of
hard-coded string.
(mh-mail-header-separator, mh-signature-separator-regexp): Use
"regular expression" in docstring instead of regexp.
(mh-scan-msg-number-regexp)
(mh-scan-msg-overflow-regexp, mh-scan-msg-format-regexp)
(mh-scan-msg-format-string, mh-scan-msg-search-regexp)
(mh-cmd-note): Sync docstrings with manual.

5 files changed, 149 insertions, 89 deletions

diff --git a/lisp/mh-e/ChangeLog b/lisp/mh-e/ChangeLog
index 96f743b10ba..d0dcac9c728 100644
--- a/lisp/mh-e/ChangeLog
+++ b/lisp/mh-e/ChangeLog
@@ -1,5 +1,28 @@
 2005-10-27  Bill Wohler  <wohler@newt.com>
 
+        * mh-customize.el (mh-adaptive-cmd-note-flag)
+        (mh-scan-format-file, mh-scan-prog): Sync docstrings with manual.
+
+        * mh-e.el (mh-scan-format-mh, mh-note-deleted, mh-note-refiled)
+        (mh-note-cur, mh-scan-good-msg-regexp)
+        (mh-scan-deleted-msg-regexp, mh-scan-refiled-msg-regexp)
+        (mh-scan-valid-regexp, mh-scan-cur-msg-number-regexp)
+        (mh-scan-date-regexp, mh-scan-rcpt-regexp, mh-scan-body-regexp)
+        (mh-scan-subject-regexp, mh-scan-format-regexp)
+        (mh-folder-font-lock-keywords, mh-set-cmd-note): Sync docstrings
+        with manual.
+
+        * mh-funcs.el (mh-note-copied): Sync docstrings with manual.
+
+        * mh-utils.el (mh-goto-msg): Use mh-scan-msg-search-regexp instead
+        of hard-coded string.
+        (mh-mail-header-separator, mh-signature-separator-regexp): Use
+        "regular expression" in docstring instead of regexp.
+        (mh-scan-msg-number-regexp)
+        (mh-scan-msg-overflow-regexp, mh-scan-msg-format-regexp)
+        (mh-scan-msg-format-string, mh-scan-msg-search-regexp)
+        (mh-cmd-note): Sync docstrings with manual.
+
         * mh-comp.el (mh-insert-signature, mh-insert-auto-fields):
         Checkdoc fixes.
 
diff --git a/lisp/mh-e/mh-customize.el b/lisp/mh-e/mh-customize.el
index d566250cacf..9708de52005 100644
--- a/lisp/mh-e/mh-customize.el
+++ b/lisp/mh-e/mh-customize.el
@@ -959,38 +959,48 @@ default). If you need to scan just the message 200, then use the range
 ;;; Scan Line Formats (:group 'mh-scan-line-formats)
 
 (defcustom mh-adaptive-cmd-note-flag t
-  "*Non-nil means that the message number width is determined dynamically.
-This is done once when a folder is first opened by running scan on the last
-message of the folder. The message number for the last message is extracted
-and its width calculated. This width is used when calling `mh-set-cmd-note'.
-
-If you prefer fixed-width message numbers, set this variable to nil and call
-`mh-set-cmd-note' with the width specified by the scan format in
-`mh-scan-format-file'. For example, the default width is 4, so you would use
-\"(mh-set-cmd-note 4)\" if `mh-scan-format-file' were nil."
+  "*On means that the message number width is determined dynamically.
+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 this option is on (the default).
+
+If you prefer fixed-width message numbers, turn off this option 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)\"."
   :type 'boolean
   :group 'mh-scan-line-formats)
 
 (defcustom mh-scan-format-file t
   "Specifies the format file to pass to the scan program.
-If t, the format string will be taken from the either `mh-scan-format-mh'
-or `mh-scan-format-nmh' depending on whether MH or nmh is in use.
-If nil, the default scan output will be used.
-
-If you customize the scan format, you may need to modify a few variables
-containing regexps that MH-E uses to identify specific portions of the output.
-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 the width of your message
-numbers. See also `mh-adaptive-cmd-note-flag'."
+
+The default setting for this option 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\" to get the
+same output as you would get if you ran \"scan\" from the shell. 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.
+
+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' to modify `mh-cmd-note'
+with the column for your notations if you turn off
+`mh-adaptive-cmd-note-flag'. However, 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\"."
   :type '(choice (const :tag "Use MH-E scan Format" t)
                  (const :tag "Use Default scan Format" nil)
                  (file  :tag "Specify a scan Format File"))
   :group 'mh-scan-line-formats)
 
 (defcustom mh-scan-prog "scan"
-  "*Program to run to generate one-line-per-message listing of a folder.
-Normally \"scan\" or a file name linked to scan.  This file is searched
-for relative to the `mh-progs' directory unless it is an absolute pathname."
+  "*Program used to scan messages.
+The name of the program that generates a listing of one line per message is
+held in this option. 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."
   :type 'string
   :group 'mh-scan-line-formats)
 (make-variable-buffer-local 'mh-scan-prog)
diff --git a/lisp/mh-e/mh-e.el b/lisp/mh-e/mh-e.el
index 283499b2c66..c442947b789 100644
--- a/lisp/mh-e/mh-e.el
+++ b/lisp/mh-e/mh-e.el
@@ -131,7 +131,8 @@ The string is displayed after the folder's name.  nil for no annotation.")
    "%<(mymbox{from})%<{to}To:%14(friendly{to})%>%>"
    "%<(zero)%17(friendly{from})%>  "
    "%{subject}%<{body}<<%{body}%>")
-  "*Scan format string for MH, provided to the scan program via the -format arg.
+  "*Scan format string for MH.
+This string is passed to the scan program via the -format arg.
 This format is identical to the default except that additional hints for
 fontification have been added to the fifth column (remember that in Emacs, the
 first column is 0).
@@ -167,88 +168,106 @@ 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.")
 
 (defvar mh-note-deleted ?D
-  "Deleted messages are marked by this character.
+  "Messages that have been deleted are marked by this character.
 See also `mh-scan-deleted-msg-regexp'.")
 
 (defvar mh-note-refiled ?^
-  "Refiled messages are marked by this character.
+  "Messages that have been refiled are marked by this character.
 See also `mh-scan-refiled-msg-regexp'.")
 
 (defvar mh-note-cur ?+
-  "The current message (in MH) is marked by this character.
+  "The current message (in MH, not in MH-E) is marked by this character.
 See also `mh-scan-cur-msg-number-regexp'.")
 
 (defvar mh-scan-good-msg-regexp  "^\\( *[0-9]+\\)[^D^0-9]"
-  "This regexp specifies the scan lines that are 'good' messages.
-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 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.")
 
 (defvar mh-scan-deleted-msg-regexp "^\\( *[0-9]+\\)D"
-  "This regexp matches deleted messages.
-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\".
-See also `mh-note-deleted'.")
+  "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'.")
 
 (defvar mh-scan-refiled-msg-regexp  "^\\( *[0-9]+\\)\\^"
-  "This regexp matches refiled messages.
-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]+\\\\)\\\\^\".
-See also `mh-note-refiled'.")
+  "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'.")
 
 (defvar mh-scan-valid-regexp "^ *[0-9]"
-  "This regexp matches scan lines for messages (not error messages).")
+  "This regular expression describes a valid scan line.
+This is used to eliminate error messages that are occasionally produced by
+\"inc\".")
 
 (defvar mh-scan-cur-msg-number-regexp "^\\( *[0-9]+\\+\\).*"
-  "This regexp matches the current message.
-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]+\\\\+\\\\).*\". Don't
-disable this regexp as it's needed by non-fontifying functions.
-See also `mh-note-cur'.")
+  "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'.")
 
 (defvar mh-scan-date-regexp "\\([0-9][0-9]/[0-9][0-9]\\)"
-  "This regexp matches a valid date.
-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]\\\\)\"}.
-See also `mh-scan-format-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'.")
 
 (defvar mh-scan-rcpt-regexp  "\\(To:\\)\\(..............\\)"
-  "This regexp specifies the recipient in messages you sent.
+  "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:\\\\)\\\\(..............\\\\)\".")
+as in the default of \"\\\\(To:\\\\)\\\\(..............\\\\)\". If this
+regular expression is not correct, the recipient will not be highlighted.")
 
 (defvar mh-scan-body-regexp "\\(<<\\([^\n]+\\)?\\)"
-  "This regexp matches the message body fragment displayed in scan lines.
+  "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]+\\\\)?\\\\)\".")
+body text as in the default of \"\\\\(<<\\\\([^\\n]+\\\\)?\\\\)\". If this
+regular expression is not correct, the body fragment will not be highlighted.")
 
 (defvar mh-scan-subject-regexp
   "^ *[0-9]+........[ ]*...................\\([Rr][Ee]\\(\\[[0-9]+\\]\\)?:\\s-*\\)*\\([^<\n]*\\)"
-  "This regexp matches the subject.
-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 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
+\(broken on multiple lines for readability):
+  ^ *[0-9]+........[ ]*...................
+  \\\\([Rr][Ee]\\\\(\\\\\\=[[0-9]+\\\\]\\\\)?:\\\\s-*\\\\)*
+  \\\\([^<\\n]*\\\\)
+This regular expression should be correct as it is needed by non-fontifying
+functions.")
 
 (defvar mh-scan-format-regexp
   (concat "\\([bct]\\)" mh-scan-date-regexp " *\\(..................\\)")
-  "This regexp matches the output of scan.
+  "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, 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
-                     \"*\\\\(..................\\\\)\")\".")
+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.")
 
 
 
@@ -281,7 +300,7 @@ default of \"(concat \"\\\\([bct]\\\\)\" mh-scan-date-regexp
    (list mh-scan-format-regexp
          '(1 mh-folder-date-face)
          '(3 mh-folder-scan-format-face)))
-  "Regexp keywords used to fontify the MH-Folder buffer.")
+  "Keywords (regular expressions) used to fontify the MH-Folder buffer.")
 
 (defvar mh-scan-cmd-note-width 1
   "Number of columns consumed by the cmd-note field in `mh-scan-format'.
@@ -1701,10 +1720,13 @@ Return in the folder's buffer."
     (mh-notate-deleted-and-refiled)))
 
 (defun mh-set-cmd-note (width)
-  "Set `mh-cmd-note' to WIDTH characters (minimum of 2).
+  "Set `mh-cmd-note' to WIDTH (minimum of 2).
+
+If `mh-scan-format-file' is set to \"Use Default scan Format\" or \"Specify a
+scan Format File\", then this function will NOT update `mh-cmd-note'. In these
+cases, the user should change `mh-cmd-note' with `setq' if necessary.
 
-If `mh-scan-format-file' specifies nil or a filename, then this function
-will NOT update `mh-cmd-note'."
+Note that columns in Emacs start with 0."
   ;; Add one to the width to always have whitespace in column zero.
   (setq width (max (1+ width) 2))
   (if (and (equal mh-scan-format-file t)
diff --git a/lisp/mh-e/mh-funcs.el b/lisp/mh-e/mh-funcs.el
index 6ce1da8fe90..755be4a1560 100644
--- a/lisp/mh-e/mh-funcs.el
+++ b/lisp/mh-e/mh-funcs.el
@@ -51,7 +51,7 @@ For example, '(\"-nolimit\" \"-textfield\" \"subject\") is a useful setting.")
 ;;; Scan Line Formats
 
 (defvar mh-note-copied "C"
-  "Copied messages are marked by this character.")
+  "Messages that have been copied are marked by this character.")
 
 (defvar mh-note-printed "P"
   "Messages that have been printed are marked by this character.")
diff --git a/lisp/mh-e/mh-utils.el b/lisp/mh-e/mh-utils.el
index 295d64ec8fd..87f521d605a 100644
--- a/lisp/mh-e/mh-utils.el
+++ b/lisp/mh-e/mh-utils.el
@@ -86,32 +86,37 @@ of `search' in the CL package."
 ;;; Scan Line Formats
 
 (defvar mh-scan-msg-number-regexp "^ *\\([0-9]+\\)"
-  "This regexp is used to extract the message number from a scan line.
-Note that the message number must be placed in a parenthesized expression as
-in the default of \"^ *\\\\([0-9]+\\\\)\".")
+  "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]+\\\\)\".")
 
 (defvar mh-scan-msg-overflow-regexp "^[?0-9][0-9]"
-  "This regexp matches scan lines in which the message number overflowed.")
+  "This regular expression matches overflowed message numbers.")
 
 (defvar mh-scan-msg-format-regexp "%\\([0-9]*\\)(msg)"
-  "This regexp is used to find the message number width in a scan format.
+  "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)\".")
+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\".")
 
 (defvar mh-scan-msg-format-string "%d"
   "This is a format string for width of the message number in a scan format.
-Use `0%d' for zero-filled message numbers.")
+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\".")
 
 (defvar mh-scan-msg-search-regexp "^[^0-9]*%d[^0-9]"
-  "This format string regexp matches the scan line for a particular message.
-Use `%d' to represent the location of the message number within the
-expression as in the default of \"^[^0-9]*%d[^0-9]\".")
+  "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]\".")
 
 (defvar mh-cmd-note 4
-  "This is the number of characters to skip over before inserting notation.
+  "Column where notations begin.
 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 non-nil and
-`mh-scan-format-file' is t.")
+may be updated dynamically if `mh-adaptive-cmd-note-flag' is on and
+`mh-scan-format-file' is set to \"Use MH-E scan Format\".
+
+Note that columns in Emacs start with 0.")
 (make-variable-buffer-local 'mh-cmd-note)
 
 (defvar mh-note-seq ?%
@@ -133,12 +138,12 @@ This variable should not be used directly in programs. Programs should use
 `mh-mail-header-separator' in `mh-letter-mode'; in other contexts, you may
 have to perform this initialization yourself.
 
-Do not make this a regexp as it may be the argument to `insert' and it is
-passed through `regexp-quote' before being used by functions like
+Do not make this a regular expression as it may be the argument to `insert'
+and it is passed through `regexp-quote' before being used by functions like
 `re-search-forward'.")
 
 (defvar mh-signature-separator-regexp "^-- $"
-  "Regexp used to find signature separator.
+  "This regular expression matches the signature separator.
 See `mh-signature-separator'.")
 
 (defvar mh-signature-separator "-- \n"
@@ -1853,7 +1858,7 @@ Non-nil third argument DONT-SHOW means not to show the message."
   (let ((point (point))
         (return-value t))
     (goto-char (point-min))
-    (unless (re-search-forward (format "^[ ]*%s[^0-9]+" number) nil t)
+    (unless (re-search-forward (format mh-scan-msg-search-regexp number) nil t)
       (goto-char point)
       (unless no-error-if-no-message
         (error "No message %d" number))