* uip/pick.c: Print matching messages immediately, instead of
[mmh] / man / msh.man
1 .\"
2 .\" %nmhwarning%
3 .\" $Id$
4 .\"
5 .TH MSH %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
6 .SH NAME
7 msh \- nmh shell (and BBoard reader)
8 .SH SYNOPSIS
9 .HP 5
10 .na
11 .B msh
12 .RB [ \-prompt
13 .IR string ]
14 .RB [ \-scan " | " \-noscan ]
15 .RB [ \-topcur " | " \-notopcur ]
16 .RI [ file ]
17 .RB [ \-version ]
18 .RB [ \-help ]
19 .ad
20 .SH DESCRIPTION
21 .B msh
22 is an interactive program that implements a subset of the normal
23 .B nmh
24 commands operating on a single file in
25 .BR packf 'd format.
26 That is,
27 .B msh
28 is used to read a file that contains a number
29 of messages, as opposed to the standard
30 .B nmh
31 style of reading
32 a number of files, each file being a separate message in a folder.
33 .BR msh 's
34 chief advantage is that the normal
35 .B nmh
36 style does not
37 allow a file to have more than one message in it.  Hence,
38 .B msh
39 is
40 ideal for reading BBoards, as these files are delivered by the
41 transport system in this format.  In addition,
42 .B msh
43 can be used on
44 other files, such as message archives which have been
45 .BR pack ed
46 (see
47 .BR packf (1)).
48 Finally,
49 .B msh
50 is an excellent
51 .B nmh
52 tutor.
53 As the only commands available to the user are
54 .B nmh
55 commands, this
56 allows
57 .B nmh
58 beginners to concentrate on how commands to
59 .B nmh
60 are formed and (more or less) what they mean.
61 .PP
62 When invoked,
63 .B msh
64 reads the named file, and enters a command loop.
65 The user may type most of the normal
66 .B nmh
67 commands.  The syntax and
68 semantics of these commands typed to
69 .B msh
70 are identical to their
71 .B nmh
72 counterparts.  In cases where the nature of
73 .B msh
74 would be
75 inconsistent (e.g., specifying a
76 .I +folder
77 with some commands),
78 .B msh
79 will duly inform the user.  The commands that
80 .B msh
81 currently supports
82 (in some slightly modified or restricted forms) are:
83 .PP
84 .RS 5
85 .nf
86 ali
87 burst
88 comp
89 dist
90 folder
91 forw
92 inc
93 mark
94 mhmail
95 mhn
96 msgchk
97 next
98 packf
99 pick
100 prev
101 refile
102 repl
103 rmm
104 scan
105 send
106 show
107 sortm
108 whatnow
109 whom
110 .fi
111 .RE
112 .PP
113 In addition,
114 .B msh
115 has a
116 .B help
117 command which gives a
118 brief overview.  To terminate
119 .BR msh ,
120 type CTRL\-D, or use the
121 .B quit
122 command.  If
123 .B msh
124 is being invoked from
125 .BR bbc ,
126 then typing CTRL\-D will also tell
127 .B bbc
128 to exit as well, while
129 using the
130 .B quit
131 command will return control to
132 .BR bbc ,
133 and
134 .B bbc
135 will continue examining the list of BBoards that it is scanning.
136 .PP
137 If the file is writable and has been modified, then using
138 .B quit
139 will query the user if the file should be updated.
140 .PP
141 The
142 .B \-prompt
143 .I string
144 switch sets the prompting string for
145 .BR msh .
146 .PP
147 You may wish to use an alternate
148 .B nmh
149 profile for the commands that
150 .B msh
151 executes; see
152 .BR mh-profile (5)
153 for details about the
154 .B $MH
155 environment variable.
156 .PP
157 When invoked from
158 .BR bbc ,
159 two special features are enabled:
160 First, the
161 .B \-scan
162 switch directs
163 .B msh
164 to do a
165 .RB \*(lq scan
166 .BR unseen \*(rq
167 on start\-up if new items are present in the BBoard.  This feature is
168 best used from
169 .BR bbc ,
170 which correctly sets the stage.  Second, the
171 .B mark
172 command in
173 .B msh
174 acts specially when you are reading a
175 BBoard, since
176 .B msh
177 will consult the sequence \*(lqunseen\*(rq in
178 determining what messages you have actually read.  When
179 .B msh
180 exits,
181 it reports this information to
182 .BR bbc .
183 In addition, if you give the
184 .B mark
185 command with no arguments,
186 .B msh
187 will interpret it as
188 .RB \*(lq mark
189 .B \-sequence
190 .B unseen
191 .B \-delete
192 .B \-nozero
193 .BR all \*(rq
194 Hence, to discard
195 all of the messages in the current BBoard you're reading, just use the
196 .B mark
197 command with no arguments.
198 .PP
199 Normally, the
200 .B exit
201 command is identical to the
202 .B quit
203 command in
204 .BR msh .
205 When run under
206 .B bbc
207 however,
208 .B exit
209 directs
210 .B msh
211 to mark all messages as seen and then
212 .BR quit .
213 For speedy type\-in, this command is often abbreviated as just
214 .BR qe .
215 .PP
216 When invoked from
217 .BR vmh ,
218 another special feature is enabled:
219 The `topcur' switch directs
220 .B msh
221 to have the current message
222 \*(lqtrack\*(rq the top line of the
223 .B vmh
224 scan window.  Normally,
225 .B msh
226 has the current message \*(lqtrack\*(rq the center of the window
227 (under
228 .BR \-notopcur ,
229 which is the default).
230 .PP
231 .B msh
232 supports an output redirection facility.  Commands may be
233 followed by one of
234 .PP
235 .RS 5
236 .nf
237 .ta \w'| \fIcommand\fR  'u
238 ^> \fIfile\fR~^write output to \fIfile\fR
239 ^>> \fIfile\fR~^append output to \fIfile\fR
240 ^| \fIcommand\fR~^pipe output to UNIX \fIcommand\fR
241 .fi
242 .RE
243 .PP
244 If
245 .I file
246 starts with a \*(lq\~\*(rq (tilde), then a
247 .BR csh \-like
248 expansion
249 takes place.  Note that
250 .I command
251 is interpreted by
252 .BR sh .
253 Also note that
254 .B msh
255 does NOT support history substitutions, variable
256 substitutions, or alias substitutions.
257 .PP
258 When parsing commands to the left of any redirection symbol,
259 .B msh
260 will honor `\\' (back\-slash) as the quote next\-character symbol, and
261 `\*(lq' (double\-quote) as quote\-word delimiters.  All other input tokens
262 are separated by whitespace (spaces and tabs).
263
264 .SH FILES
265 .fc ^ ~
266 .nf
267 .ta \w'%etcdir%/ExtraBigFileName  'u
268 ^$HOME/\&.mh\(ruprofile~^The user profile
269 ^%etcdir%/mts.conf~^nmh mts configuration file
270 .fi
271
272 .SH "PROFILE COMPONENTS"
273 .fc ^ ~
274 .nf
275 .ta 2.4i
276 .ta \w'ExtraBigProfileName  'u
277 ^Path:~^To determine the user's nmh directory
278 ^Msg\-Protect:~^To set mode when creating a new `file'
279 ^fileproc:~^Program to file messages
280 ^showproc:~^Program to show messages
281 .fi
282
283 .SH "SEE ALSO"
284 bbc(1)
285
286 .SH DEFAULTS
287 .nf
288 .RB ` file "' defaults to \*(lq./msgbox\*(rq"
289 .RB ` "\-prompt\ (msh)\ "'
290 .RB ` \-noscan '
291 .RB ` \-notopcur '
292 .fi
293
294 .SH CONTEXT
295 None
296
297 .SH BUGS
298 The argument to the
299 .B \-prompt
300 switch must be interpreted as a single
301 token by the shell that invokes
302 .BR msh .
303 Therefore, one must usually
304 place the argument to this switch inside double\-quotes.
305 .PP
306 There is a strict limit of messages per file in
307 .BR packf 'd
308 format which
309 .B msh
310 can handle.  Usually, this limit is 1000 messages.
311 .PP
312 Please remember that
313 .B msh
314 is not the C\-Shell, and that a lot of
315 the nice facilities provided by the latter are not present in the former.
316 .PP
317 In particular,
318 .B msh
319 does not understand back\-quoting, so the only
320 effective way to use
321 .B pick
322 inside
323 .B msh
324 is to always use the
325 .B \-seq
326 .I select
327 switch.  Clever users of
328 .B nmh
329 will put the line
330 .P
331 .RS 5
332 pick:\0\-seq\0select\0\-list
333 .RE
334 .PP
335 in their
336 .I \&.mh\(ruprofile
337 file so that
338 .B pick
339 works equally well from both the shell and
340 .BR msh .
341 .PP
342 .B sortm
343 always uses
344 .B \-noverbose
345 and if
346 .B \-textfield
347 .I field
348 is used,
349 .B \-limit
350 .IR 0 .
351 .PP
352 The
353 .B msh
354 program inherits most (if not all) of the bugs from the
355 .B nmh
356 commands it implements.