Updated pop instructions and indicated use of standard "./configure"
[mmh] / man / msh.man
1 .\"
2 .\" %nmhwarning%
3 .\" $Id$
4 .\"
5 .\" include the -mh macro file
6 .so %etcdir%/tmac.h
7 .\"
8 .TH MSH %manext1% MH.6.8 [%nmhversion%]
9 .SH NAME
10 msh \- nmh shell (and BBoard reader)
11 .SH SYNOPSIS
12 .in +.5i
13 .ti -.5i
14 msh
15 \%[\-prompt\ string]
16 \%[\-scan] \%[\-noscan]
17 \%[\-topcur] \%[\-notopcur]
18 \%[file]
19 \%[\-version]
20 \%[\-help]
21 .in -.5i
22 .SH DESCRIPTION
23 \fImsh\fR is an interactive program that implements a subset of the normal
24 \fInmh\fR commands operating on a single file in \fIpackf\fR'd format.
25 That is, \fImsh\fR is used to read a file that contains a number
26 of messages, as opposed to the standard \fInmh\fR style of reading
27 a number of files, each file being a separate message in a folder.
28 \fImsh\fR's chief advantage is that the normal \fInmh\fR style does not
29 allow a file to have more than one message in it.  Hence, \fImsh\fR is
30 ideal for reading \fIBBoards\fR, as these files are delivered by the
31 transport system in this format.  In addition, \fImsh\fR can be used on
32 other files, such as message archives which have been \fIpack\fRed (see
33 \fIpackf\fR\0(1)).  Finally, \fImsh\fR is an excellent \fInmh\fR tutor.
34 As the only commands available to the user are \fInmh\fR commands, this
35 allows \fInmh\fR beginners to concentrate on how commands to \fInmh\fR
36 are formed and (more or less) what they mean.
37
38 When invoked, \fImsh\fR reads the named file, and enters a command loop.
39 The user may type most of the normal \fInmh\fR commands.  The syntax and
40 semantics of these commands typed to \fImsh\fR are identical to their
41 \fInmh\fR counterparts.  In cases where the nature of \fImsh\fR would be
42 inconsistent (e.g., specifying a `+folder' with some commands), \fImsh\fR
43 will duly inform the user.  The commands that \fImsh\fR currently supports
44 (in some slightly modified or restricted forms) are:
45 .sp 1
46 .in +.5i
47 ali
48 .br
49 burst
50 .br
51 comp
52 .br
53 dist
54 .br
55 folder
56 .br
57 forw
58 .br
59 inc
60 .br
61 mark
62 .br
63 mhmail
64 .br
65 mhn
66 .br
67 msgchk
68 .br
69 next
70 .br
71 packf
72 .br
73 pick
74 .br
75 prev
76 .br
77 refile
78 .br
79 repl
80 .br
81 rmm
82 .br
83 scan
84 .br
85 send
86 .br
87 show
88 .br
89 sortm
90 .br
91 whatnow
92 .br
93 whom
94 .in -.5i
95
96 In addition, \fImsh\fR has a \*(lqhelp\*(rq command which gives a
97 brief overview.  To terminate \fImsh\fR, type CTRL\-D, or use the
98 \*(lqquit\*(rq command.  If \fImsh\fR is being invoked from \fIbbc\fR,
99 then typing CTRL\-D will also tell \fIbbc\fR to exit as well, while
100 using the \*(lqquit\*(rq command will return control to \fIbbc\fR, and
101 \fIbbc\fR will continue examining the list of BBoards that it is scanning.
102
103 If the file is writable and has been modified, then using \*(lqquit\*(rq
104 will query the user if the file should be updated.
105
106 The `\-prompt string' switch sets the prompting string for \fImsh\fR.
107
108 You may wish to use an alternate \fInmh\fR profile for the commands that
109 \fImsh\fR executes; see \fImh-profile\fR\0(5) for details about the
110 \fB$MH\fR environment variable.
111
112 When invoked from \fIbbc\fR, two special features are enabled:
113 First, the `\-scan' switch directs \fImsh\fR to do a `scan\0unseen'
114 on start\-up if new items are present in the BBoard.  This feature is
115 best used from \fIbbc\fR, which correctly sets the stage.  Second, the
116 \fImark\fR command in \fImsh\fR acts specially when you are reading a
117 BBoard, since \fImsh\fR will consult the sequence \*(lqunseen\*(rq in
118 determining what messages you have actually read.  When \fImsh\fR exits,
119 it reports this information to \fIbbc\fR.  In addition, if you give the
120 \fImark\fR command with no arguments, \fImsh\fR will interpret it as
121 `mark\0\-sequence\0unseen\0\-delete\0\-nozero\0all' Hence, to discard
122 all of the messages in the current BBoard you're reading, just use the
123 \fImark\fR command with no arguments.
124
125 Normally, the \*(lqexit\*(rq command is identical to the \*(lqquit\*(rq
126 command in \fImsh\fR.  When run under \fIbbc\fR however, \*(lqexit\*(rq
127 directs \fImsh\fR to mark all messages as seen and then \*(lqquit\*(rq.
128 For speedy type\-in, this command is often abbreviated as just
129 \*(lqe\*(rq.
130
131 When invoked from \fIvmh\fR, another special feature is enabled:
132 The `topcur' switch directs \fImsh\fR to have the current message
133 \*(lqtrack\*(rq the top line of the \fIvmh\fR scan window.  Normally,
134 \fImsh\fR has the current message \*(lqtrack\*(rq the center of the window
135 (under `\-notopcur', which is the default).
136
137 \fImsh\fR supports an output redirection facility.  Commands may be
138 followed by one of
139
140 .nf
141 .in +.5i
142 .ta \w'| \fIcommand\fR  'u
143 ^> \fIfile\fR~^write output to \fIfile\fR
144 ^>> \fIfile\fR~^append output to \fIfile\fR
145 ^| \fIcommand\fR~^pipe output to UNIX \fIcommand\fR
146 .re
147 .in -.5i
148 .fi
149
150 If \fIfile\fR starts with a `\~' (tilde), then a \fIcsh\fR-like expansion
151 takes place.  Note that \fIcommand\fR is interpreted by \fIsh\fR\0(1).
152 Also note that \fImsh\fR does NOT support history substitutions, variable
153 substitutions, or alias substitutions.
154
155 When parsing commands to the left of any redirection symbol, \fImsh\fR
156 will honor `\\' (back\-slash) as the quote next\-character symbol, and
157 `"' (double\-quote) as quote\-word delimiters.  All other input tokens
158 are separated by whitespace (spaces and tabs).
159 .Fi
160 ^$HOME/\&.mh\(ruprofile~^The user profile
161 ^%etcdir%/mts.conf~^nmh mts configuration file
162 .Pr
163 ^Path:~^To determine the user's nmh directory
164 .Ps
165 ^Msg\-Protect:~^To set mode when creating a new `file'
166 .Ps
167 ^fileproc:~^Program to file messages
168 .Ps
169 ^showproc:~^Program to show messages
170 .Sa
171 bbc(1)
172 .De
173 `file' defaults to \*(lq./msgbox\*(rq
174 .Ds
175 `\-prompt\ (msh)\ '
176 .Ds
177 `\-noscan'
178 .Ds
179 `\-notopcur'
180 .Co
181 None
182 .Bu
183 The argument to the `\-prompt' switch must be interpreted as a single
184 token by the shell that invokes \fImsh\fR.  Therefore, one must usually
185 place the argument to this switch inside double\-quotes.
186
187 There is a strict limit of messages per file in \fIpackf\fR'd format
188 which \fImsh\fR can handle.  Usually, this limit is 1000 messages.
189
190 Please remember that \fImsh\fR is not the \fICShell\fR, and that a lot of
191 the nice facilities provided by the latter are not present in the former.
192
193 In particular, \fImsh\fR does not understand back\-quoting, so the only
194 effective way to use \fIpick\fR inside \fImsh\fR is to always use the
195 `\-seq\0select' switch.  Clever users of \fInmh\fR will put the line
196
197 .ti +.5i
198 pick:\0\-seq\0select\0\-list
199
200 in their \&.mh\(ruprofile file so that \fIpick\fR works equally well
201 from both the shell and \fImsh\fR.
202
203 \fIsortm\fR always uses \*(lq\-noverbose\*(rq and if
204 \*(lq\-textfield\ field\*(lq is used, \*(lq\-limit 0\*(rq.
205
206 The \fImsh\fR program inherits most (if not all) of the bugs from the
207 \fInmh\fR commands it implements.
208 .En