Added -noall/-all switches to sortm(1).

[mmh] / man / sortm.man

diff --git a/man/sortm.man b/man/sortm.man
index 283cf12..dd24014 100644 (file)
--- a/man/sortm.man
+++ b/man/sortm.man
@@ -10,6 +10,7 @@ sortm \- sort messages
 .B sortm
 .RI [ +folder ]
 .RI [ msgs ]
 .B sortm
 .RI [ +folder ]
 .RI [ msgs ]

+.RB [ \-all | \-noall ]

 .RB [ \-datefield
 .IR field ]
 .RB [ \-textfield
 .RB [ \-datefield
 .IR field ]
 .RB [ \-textfield

@@ -27,6 +28,21 @@ sortm \- sort messages
 sorts the specified messages in the named folder according
 to the chronological order of the \*(lqDate:\*(rq field of each message.
 .PP
 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
 The
 .B \-verbose
 switch directs

@@ -53,11 +69,11 @@ The
 .I field
 switch causes
 .B sortm
 .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
 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
 .PP
 With
 .B \-textfield

@@ -66,7 +82,7 @@ if
 .B \-limit
 .I days
 is specified, messages
 .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.
 appear together.  Specifying
 .B \-nolimit
 makes the limit infinity.

@@ -75,7 +91,8 @@ With
 .IR 0 ,
 the sort is instead made textfield\-major, date\-minor.
 .PP
 .IR 0 ,
 the sort is instead made textfield\-major, date\-minor.
 .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
 .PP
 .RS 5
 sortm -textfield subject +folder

@@ -103,7 +120,8 @@ folder(1)
 .SH DEFAULTS
 .nf
 .RB ` +folder "' defaults to the current folder"
 .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 ` \-datefield "' defaults to date"
 .RB ` \-notextfield '
 .RB ` \-noverbose '

@@ -114,7 +132,7 @@ folder(1)
 If a folder is given, it will become the current folder.  If the current
 message is moved,
 .B sortm
 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.
 
 .SH HISTORY
 Timezones used to be ignored when comparing dates: they aren't any more.