+.TH SORTM %manext1% "October 11, 2012" "%nmhversion%"
.\"
.\" %nmhwarning%
-.\" $Id$
.\"
-.TH SORTM %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
.SH NAME
sortm \- sort messages
.SH SYNOPSIS
.HP 5
+.na
.B sortm
.RI [ +folder ]
.RI [ msgs ]
+.RB [ \-all " | " \-noall ]
.RB [ \-datefield
.IR field ]
.RB [ \-textfield
.RB [ \-limit
.IR days ]
.RB [ \-nolimit ]
+.RB [ \-check " | " \-nocheck ]
.RB [ \-verbose " | " \-noverbose ]
.RB [ \-version ]
.RB [ \-help ]
+.ad
.SH DESCRIPTION
.B Sortm
sorts the specified messages in the named folder according
to the chronological order of the \*(lqDate:\*(rq field of each message.
.PP
+If no messages are specified, the default is all messages in the folder.
+However, if no messages are specified and the
+.B \-noall
+switch is enabled, then
+.B sortm
+reports that as an error and exits with non-zero status.
+.B \-noall
+is most useful in the user's profile, to avoid inadvertant sorting of
+an entire folder. The
+.B \-all
+switch can then be used on the command line to disable it. Of course,
+a message specification of
+.I all
+can be used in any case.
+.PP
The
.B \-verbose
switch directs
.I field
switch causes
.B sortm
-to sort messages
-by the specified text field. If this field is \*(lqsubject\*(rq, any
-leading "re:" is stripped off. In any case, all characters except
+to sort messages by the specified text field. All characters except
letters and numbers are stripped and the resulting strings are sorted
-datefield\-major, textfield\-minor, using a case insensitive comparison.
+datefield\-major, textfield\-minor, using a case insensitive
+comparison. If this field is \*(lqsubject\*(rq, any leading "re:" is
+stripped off.
.PP
With
.B \-textfield
.B \-limit
.I days
is specified, messages
-with similar textfields that are dated within `days' of each other
+with the same textfields that are dated within `days' of each other
appear together. Specifying
.B \-nolimit
makes the limit infinity.
With
.B \-limit
.IR 0 ,
-the sort is instead made textfield\-major, date\-minor.
+the sort is instead simply textfield\-major.
.PP
-For example, to order a folder by date-major, subject-minor, use:
+For example, to order a folder by date-major, grouping messages with
+the same subject on the same date together, use:
.PP
.RS 5
sortm -textfield subject +folder
.RE
-
+.PP
+.B sortm
+always issues a warning for each message that is missing a
+\*(lqDate:\*(rq field, has a \*(lqDate:\*(rq field that cannot be
+parsed, or has a format error in any header field. With the
+.B \-check
+switch,
+.B sortm
+inhibits all modifications to the folder if there are any such
+messages, and exits with non-zero status. With the default of
+.BR \-nocheck ,
+.B sortm
+sorts messages with a missing or invalid
+\*(lqDate:\*(rq field using their file modification times.
.SH FILES
.fc ^ ~
.nf
-.ta \w'/usr/local/nmh/etc/ExtraBigFileName 'u
+.ta \w'%etcdir%/ExtraBigFileName 'u
^$HOME/\&.mh\(ruprofile~^The user profile
.fi
-
.SH "PROFILE COMPONENTS"
.fc ^ ~
.nf
^Path:~^To determine the user's nmh directory
^Current\-Folder:~^To find the default current folder
.fi
-
.SH "SEE ALSO"
-folder(1)
-
+.IR folder (1)
.SH DEFAULTS
.nf
.RB ` +folder "' defaults to the current folder"
-.RB ` msgs"' defaults to all"
+.RB ` msgs"' defaults to all without -noall, no default with -noall"
+.RB ` \-all '
.RB ` \-datefield "' defaults to date"
.RB ` \-notextfield '
.RB ` \-noverbose '
.RB ` \-nolimit '
+.RB ` \-nocheck '
.fi
-
.SH CONTEXT
If a folder is given, it will become the current folder. If the current
message is moved,
.B sortm
- will preserve its status as current.
-
+will preserve its status as current.
.SH HISTORY
Timezones used to be ignored when comparing dates: they aren't any more.
.PP
numbering in a folder, use
.RB \*(lq "folder\ \-pack" \*(rq
as always.
-
.SH BUGS
-If
-.B sortm
-encounters a message without a date\-field, or if the
-message has a date\-field that
-.B sortm
-cannot parse, then
-.B sortm
-attempts to keep the message in the same relative position. This does
-not always work. For instance, if the first message encountered lacks
-a date which can be parsed, then it will usually be placed at the end
-of the messages being sorted.
-.PP
When
.B sortm
complains about a message which it can't temporally
projects / mmh / blobdiff