Factor trim format function out
[mmh] / man / mark.man1
1 .\"
2 .\" %nmhwarning%
3 .\"
4 .TH MARK %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
5 .SH NAME
6 mark \- manipulate message sequences
7 .SH SYNOPSIS
8 .HP 5
9 .na
10 .B mark
11 .RI [ +folder ]
12 .RI [ msgs ]
13 .RB [ \-sequence
14 .I name
15 \&...]
16 .RB [ \-add " | " \-delete ]
17 .RB [ \-list ]
18 .RB [ \-public " | " \-nopublic ]
19 .RB [ \-zero " | " \-nozero ]
20 .RB [ \-Version ]
21 .RB [ \-help ]
22 .ad
23 .SH DESCRIPTION
24 The
25 .B mark
26 command manipulates message sequences by adding or deleting
27 message numbers from folder\-specific message sequences, or by listing
28 those sequences and messages.
29 .PP
30 A message sequence is a keyword, just like one of the `reserved'
31 message names, such as `f' or `n' (see mh-sequence(7)).  Unlike the
32 `reserved' message names, which have a fixed semantics on
33 a per\-folder basis, the semantics of a message sequence may be
34 defined, modified, and removed by the user.  Message sequences are
35 folder\-specific, e.g., the sequence name `seen' in the context
36 of folder
37 .RI ` +inbox '
38 need not have any relation whatsoever to the
39 sequence of the same name in a folder of a different name.
40 .PP
41 Three action switches direct the operation of
42 .BR mark .
43 These switches
44 are mutually exclusive: the last occurrence of any of them overrides
45 any previous occurrence of the other two.
46 .PP
47 The
48 .B \-add
49 switch tells
50 .B mark
51 to add messages to sequences or to
52 create a new sequence.  For each sequence named via the
53 .B \-sequence
54 .I name
55 argument (which must occur at least once) the messages named via
56 .I msgs
57 (which defaults to `c' if no
58 .I msgs
59 are given), are added to the
60 sequence.  The messages to be added need not be absent from the sequence.
61 If the
62 .B \-zero
63 switch is specified, the sequence will be emptied prior
64 to adding the messages.  Hence,
65 .B \-add
66 .B \-zero
67 means that each sequence
68 should be initialized to the indicated messages, while
69 .B \-add
70 .B \-nozero
71 means that each sequence should be appended to by the indicated messages.
72 .PP
73 The
74 .B \-delete
75 switch tells
76 .B mark
77 to delete messages from sequences, and is the dual of
78 .BR \-add .
79 For each of the named sequences, the
80 named messages are removed from the sequence.  These messages need
81 not be already present in the sequence.  If the
82 .B \-zero
83 switch is
84 specified, then all messages in the folder are added to the sequence
85 (first creating the sequence, if necessary) before removing the messages.
86 Hence,
87 .B \-delete
88 .B \-zero
89 means that each sequence should contain
90 all messages except those indicated, while
91 .B \-delete
92 .B \-nozero
93 means
94 that only the indicated messages should be removed from each sequence.
95 As expected, the command
96 .RB ` mark
97 .B \-sequence
98 .I foo
99 .B \-delete
100 all'
101 deletes the sequence `foo' from the current folder.
102 .PP
103 When creating or modifying sequences, you can specify the switches
104 .B \-public
105 or
106 .B \-nopublic
107 to force the new or modified sequences to be
108 `public' or `private'.  The switch
109 .B \-public
110 indicates
111 that the sequences should be made `public'.  These sequences
112 will then be readable by all
113 .B mmh
114 users with permission to read the relevant folders.  In contrast, the
115 .B \-nopublic
116 switch indicates that the
117 sequences should be made `private', and will only be accessible by
118 you.  If neither of these switches is specified, then existing sequences
119 will maintain their current status, and new sequences will default to
120 `public' if you have write permission for the relevant folder.
121 Check the
122 .BR mh\-sequence (7)
123 man page for more details about the difference
124 between `public' and `private' sequences.
125 .PP
126 The
127 .B \-list
128 switch tells
129 .B mark
130 to list both the sequences defined
131 for the folder and the messages associated with those sequences.
132 .B Mark
133 will list the name of each sequence given by
134 .B \-sequence
135 .I name
136 and the messages associated with that sequence.  If the
137 sequence is private, this will also be indicated.  If no sequence is
138 specified by the
139 .B \-sequence
140 switch, then all sequences for this folder
141 will be listed.  The
142 .B \-zero
143 switch does not affect the operation of
144 .BR \-list .
145 .PP
146 The current restrictions on sequences are:
147 .PP
148 .IP \(bu 2
149 The name used to denote a message sequence must consist of an alphabetic
150 character followed by zero or more alphanumeric characters, and cannot
151 be one of the (reserved) message names `c', `f',
152 `l', `a', `n', `p', or `b'.
153 .PP
154 .IP \(bu 2
155 Only a certain number of sequences may be defined for a given folder.
156 This number is usually limited to 29 (13 on small systems). (The
157 +internal implementation relies on bitmasks, with some bits set aside
158 +for internal use.)
159 .PP
160 .IP \(bu 2
161 Message ranges with user\-defined sequence names are restricted to the
162 form `name:n', `name:+n', or `name:-n', and refer
163 to the first or last `n' messages of the sequence `name', respectively.
164 Constructs of the form `name1\-name2' are forbidden for user
165 defined sequences.
166
167 .SH FILES
168 .fc ^ ~
169 .nf
170 .ta \w'%etcdir%/ExtraBigFileName  'u
171 ^$HOME/.mmh/profile~^The user profile
172 .fi
173
174 .SH "PROFILE COMPONENTS"
175 .fc ^ ~
176 .nf
177 .ta 2.4i
178 .ta \w'ExtraBigProfileName  'u
179 ^Path:~^To determine the user's mail storage
180 ^Current\-Folder:~^To find the default current folder
181 .fi
182
183 .SH "SEE ALSO"
184 flist(1), pick(1), mh-sequence(7)
185
186 .SH DEFAULTS
187 .nf
188 .RB ` +folder "' defaults to the current folder"
189 .RB ` \-add "' if " \-sequence " is specified, " \-list " otherwise"
190 .RB ` msgs "' defaults to `c' (or `a' if " \-list " is specified)"
191 .RB ` \-nozero '
192
193 .SH CONTEXT
194 If a folder is given, it will become the current folder.
195
196 .SH "HELPFUL HINTS"
197 Use
198 .B flist
199 to find folders with a given sequence, and
200 .RB ` pick
201 .I sequence
202 .BR \-list '
203 to enumerate those messages in the sequence (such as for
204 use by a shell script).