Import a copy of Markus Schnalke's master's thesis: The Modern Mail Handler.
[mmh] / docs / historical / mh-6.8.5 / papers / tutorial / text.tex
1 % begin text
2
3 \banner
4
5 \f\section{Acknowledgements}
6 The \MH/ system described herein is based on the original Rand \MH/ system.
7 It has been extensively developed (perhaps too much so) by Marshall Rose and
8 John Romine at the University of California, Irvine.
9 Einar Stefferud, Jerry Sweet, and Terry Domae provided numerous suggestions
10 to improve the UCI version of \MH/.
11
12 Parts of this document are taken from a Rand tutorial \cite{SPayn85} by
13 Sue Payne.
14
15 \f\section{Disclaimer}
16 The Regents of the University of California issue the following
17 disclaimer concerning the UCI version of MH:
18 \bigquote
19 Although each program has been tested by its contributor,
20 no warranty, express or implied,
21 is made by the contributor or the University of California,
22 as to the accuracy and functioning of the program
23 and related program material,
24 nor shall the fact of distribution constitute any such warranty,
25 and no responsibility is assumed by the contributor
26 or the University of California in connection herewith.
27 \endbigquote
28
29 \f\section{Scope}
30 This document assumes that you have no knowledge of \MH/.
31 However, to use \MH/ you should have some familiarity with the \unix/ 
32 operating system,
33 particularly with the way commands are given,
34 how files are named,
35 the jargon (e.g. {\it shell}, {\it argument}, {\it home directory},
36 {\it pathname\/}),
37 and how to use a text editor (such as \pgm{ex}, \pgm{vi}, or \pgm{emacs\/}).
38
39 This tutorial covers only basic material.
40 For additional information about \MH/,
41 consult the {\it User's Manual} \cite{MRose85a}.
42 Other documents of possible interest to you include
43 {\it The UCI BBoards Facility} \cite{MRose84}
44 and
45 the {\it MH Administrator's Guide} \cite{MRose85b}.
46
47 \f\section{How To Use This Tutorial}
48 Different typefaces and symbols are used in this document to denote the
49 kinds of things you (the user) must type on your keyboard.
50 \smallskip
51 {\advance\leftskip by\parindent
52 \item{1.} The names of programs are given in {\it text italics}:
53 \smallskip\hskip 1in \pgm{comp}\smallskip
54 \item{2.} Arguments to programs are given in {\tt typewriter style},
55 delimited by single-quotes:
56 \smallskip\hskip 1in \arg{msgs}\smallskip
57 \item{3.} \unix/ pathnames are given in {\sl slanted roman}:
58 \smallskip\hskip 1in \file{/usr/uci/}\smallskip
59 \item{4.} Text giving a full example is presented in {\tt typewriter style}:
60 \example comp\ -editor\ vi\endexample
61 The ``\hbox{\tt\char`\ }'' glyph % (visible space glyph)
62 is used to indicate an explicit space (the kind you make with the
63 space bar on your keyboard).
64 \smallskip}
65
66 \f\section{Introduction}
67 With \MH/ you can send messages to other people on your system
68 and read messages that other people send to you.
69 Depending on how things have been set up on your system,
70 it may be possible for you to send messages to people on remote systems.
71 You can also reply to messages that you have received,
72 review them,
73 organize them in {\it folders},
74 and delete them.
75
76 \MH/ differs from other mail programs in that it is composed of many
77 small programs instead of just one very large program.
78 Among new users this sometimes causes some confusion
79 along the lines of ``what program do I run?''
80 With \MH/, you use the shell to invoke one program at a time.
81 This means that when you handle mail,
82 the entire power of the shell is at your disposal
83 in addition to the facilities that \MH/ provides.
84 In the beginning, this may not make much sense or may not seem important.
85 However, we have found that as new users of \MH/ gain experience, 
86 they find this style of interface to be very useful.
87
88 \f\section{Summary}
89 The most minimal list of \MH/ commands that you can get by with is:
90 \smallskip
91 {\advance\leftskip by\parindent
92 \item{\pgm{inc}}        - incorporate mail (get new mail)
93 \item{\pgm{show}}       - show the first message
94 \item{\pgm{next}}       - show the next message
95 \item{\pgm{prev}}       - show the previous message
96 \item{\pgm{comp}}       - compose a new message to send
97 \item{\pgm{repl}}       - reply to a received message
98 \smallskip}
99 \pgm{Comp} and \pgm{repl} give enough prompting possibly to get you along.
100 However, it is suggested that you take the time to peruse this
101 tutorial before leaping into things.
102
103 \f\section{Messages and Folders}
104 A message takes the form of a memorandum,
105 and is composed of two major parts:
106 a {\it header},
107 which contains such information as
108 \eg{To} and \eg{From} addresses, \eg{Subject}, \eg{Date}, etc.;
109 and the {\it body},
110 which is the actual text of the message.
111 Each {\it component} in the header starts with a keyword followed by
112 a colon and additional information.
113 For example, in the message:
114 \example
115     Date: 10 Oct 84 17:41:14 EDT (Wed)\\
116     To: News@udel-dewey\\
117     Subject: UCI Software Talk\\
118     From: UCI Portal (agent: Marshall Rose) <uci@udel-dewey>\\\\
119     This is the text.
120 \endexample
121 there are four header items, and one line of text in the body.
122 Note that a blank line separates the body from the headers.
123
124 \MH/ stores a message as an ordinary file in a \unix/ directory.
125 This directory is called a {\it folder}.
126 If you choose to keep and organize your messages,
127 you may create as many folders as you wish.
128 There is no limit as to the number of messages in a folder.
129 Typically messages are numbered from~1 up.
130 All of your personal folders,
131 along with some other information that \MH/ needs to know,
132 are kept in a special directory called \file{Mail} under your home directory.
133 Normally, \MH/ manages these files and directories automatically,
134 so you needn't muck around with them directly unless you really want to.
135
136 You won't have any folders until somebody sends mail to you, as a rule.
137 If you are anxious to try out \MH/, but no one has sent you mail yet,
138 try sending mail to yourself to start out with.
139
140 \f\section{Reading New Mail}
141 When you are notified that you have mail (usually when you log in),
142 perhaps with the message
143 \example You have mail.\endexample
144 then you know that messages are waiting in your {\it maildrop}.
145 To read these messages, you first have to {\it incorporate} the mail
146 into your ``in-box'' by typing the command:
147 \example inc\endexample
148 This incorporates the new mail from your mail drop to your in-box,
149 which is a folder named (naturally enough) \arg{+inbox}.
150 As \pgm{inc} incorporates your new mail,
151 it generates a {\it scan listing} of the mail:
152 $$\vbox{\tenpoint\tx\halign{\hfil#&#\hfil&&     \quad#\hfil\cr
153 \noalign{\noindent Incorporating new mail into inbox...\medskip}
154 2&+&    10/10&  WESTINE\%USC-ISIF&      RFC 916 Now Available&
155                                         <<A new Request for Co\cr
156 3&&     10/10&  G B Reilly&             Gosling EMACS manual&
157                                         <<Marshall, I am lookin\cr
158 4&&     10/11&  WESTINE\%USC-ISIF&      Internet Monthly Report&\cr
159 }}$$
160 Each time \pgm{inc} is invoked,
161 any new messages are added to the end of your \eg{+inbox} folder.
162
163 To read the first message,
164 use the \pgm{show} command:
165 \example show\endexample
166 This displays the current message.
167 To read each subsequent message,
168 use the \pgm{next} command:
169 \example next\endexample
170 If you want to back up,
171 the command \pgm{prev} shows the previous message.
172 Another way to read your messages is to name them all at once:
173 \example show\ all\endexample
174 This command displays them all, one after the other.
175 The \arg{all} argument to \pgm{show} above might also be replaced
176 with \arg{next} or \arg{prev}, as in
177 \example
178     show\ next\\
179     show\ prev
180 \endexample
181 which are respectively equivalent to the \pgm{next} and \pgm{prev}
182 commands.
183
184 If you have had occasion to type \pgm{inc} more than once, then
185 you will find that \eg{show\ all} is showing not only the new messages,
186 but also the old messages that you've already seen.
187 Therefore, you might find it better to use
188 \example show\ cur-last\endexample
189 instead.
190 This command displays messages from the current message (\arg{cur})
191 to the last message (\arg{last}).
192 Each time \pgm{inc} is invoked, it makes the first new message
193 the current message.
194 It should be noted here that the name \arg{all} given in a previous
195 example is equivalent to the {\it message range} \arg{first-last},
196 where \arg{first} is the name of the first message in \arg{+inbox}.
197 Also, \eg{show} by itself is equivalent to
198 \example show\ cur\endexample
199
200 As mentioned earlier,
201 with the \unix/ shell as your interface to \MH/,
202 it becomes easy to list a message on a line printer or to another file.
203 For example,
204 \example show\ all\ |\ lpr\endexample
205 lists all the messages in the current folder to the line printer.
206
207 To summarize, the preceding has introduced these important concepts:
208 {\it folders} (in particular, the \arg{+inbox} folder),
209 {\it messages},
210 {\it message names} (e.g. \arg{prev}, \arg{next}, \arg{cur}, \arg{last}),
211 and {\it message ranges} (e.g. \arg{cur-last}, \arg{all}).
212 More will be said about folders and messages in succeeding sections.
213
214 \f\section{Sending Messages}
215 To send a message, you compose a message {\it draft},
216 either by replying to a message that someone sent to you,
217 or by creating a draft from scratch.
218 The \pgm{send} command is used {\bf after} completing the final draft
219 of a message, 
220 in the same way that you mail a paper letter only after you are finished
221 writing it.
222 This is a common source of confusion among new \MH/ users who
223 may have had experience with other mail systems.
224
225 This section discusses how to originate messages
226 and how to reply to messages that were previously received,
227 along with a word or two about addresses.
228
229 \subsection{Originating Messages}
230 To create a message draft from scratch,
231 use the \pgm{comp} program.
232 You will be prompted for the header components
233 and then the body of the message.
234 If you make a mistake, you may correct it later with a text editor.
235 The draft will be sent only if you give an explicit \pgm{send} command,
236 so you do not have to worry about the draft getting away from you
237 prematurely.
238
239 To start, you simply type:
240 \example comp\endexample
241
242 {\bf To:}
243 First, the prompt \arg{To:} appears.
244 Here you type the address of the person to whom you wish the message sent.
245 If this person is on the same computer system as you,
246 then that person's login ID should serve as the address
247 (e.g. \arg{mrose} or \arg{jsweet}).
248
249 Here we digress briefly to discuss addresses.
250 A full discussion of addresses is beyond the scope of this
251 tutorial, but it should be mentioned that there are other
252 kinds of addresses besides login IDs.
253 To send messages to people on remote systems, 
254 the usual way is to type \arg{login-id@host} in the \arg{To:} component,
255 as in \arg{MRose@UCI-ICSA}.
256 Examples of \arg{host} names at UCI include
257 \arg{uci-icsa},
258 \arg{uci-icse},
259 and \arg{uci-cip1}.
260 Upper and lower case letters may be used interchangeably.
261 Sometimes a person's last name (e.g. \arg{Rose}, \arg{Sweet}) can be used
262 instead of a login ID,
263 but this cannot be relied upon in a world without unique surnames.
264
265 {\bf cc:}
266 After you have given an address to the \arg{To:} prompt, 
267 you are prompted for the \arg{cc:}
268 (``carbon copy''--an archaism)
269 address.
270 It is customary, but not required, to put your own address
271 here so that you get a copy of the message when it is sent.
272
273 To put more than one address in the \arg{To:} and
274 \arg{cc:} components,
275 just use a comma (``,'') between each address on a line.
276
277 {\bf Subject:}
278 The third prompt is for the \arg{Subject:} component.
279 Here a line of any descriptive text will do.
280 Once you have typed a line of text, a dashed line is printed,
281 and you are then expected to type the body of the message.
282 End the body with EOT (usually CTRL-D).
283
284 An example of a complete message draft, as it appears on your screen,
285 might be:
286 \example
287     To: News\\
288     cc: farber, mrose\\
289     Subject: UCI Software Talk\\
290     --------\\
291     A presentation on the UCI software suite, including\\
292     the Rand/UCI Mail Handling System (MH), will be given\\
293     in CS220 on October 31st at 2:30 PM.  Refreshments\\
294     will be served afterward.\\\\
295     /mtr\\
296     \^{}D
297 \endexample
298 (The ``\^{}D'' does not appear in the draft.)
299
300 At this point, you are asked
301 \example What\ now?\endexample
302 This is known as being at \whatnow/ level.
303 For now, there are probably only four options that will interest you:
304 \smallskip
305 {\advance\leftskip by\parindent
306 \item{\pgm{edit}} - edit the draft
307 \item{\pgm{list}} - list the draft on your screen
308 \item{\pgm{quit}} - quit, without sending the draft
309 \item{\pgm{send}} - send the draft, then quit
310 \medskip}
311 \noindent
312 All of these options take various arguments,
313 but only \pgm{edit} really needs an argument.
314
315 {\bf Edit:}
316 The \pgm{edit} option will let you edit the draft before sending it.
317 If your favorite text editor is \pgm{vi},
318 then you would use the \pgm{edit} option as:
319 \example edit\ vi\endexample
320 Just specifying \pgm{edit} with no argument
321 will only let you append text to the body of the
322 message draft.
323 Another editor (e.g. \pgm{vi}, \pgm{ex}, \pgm{emacs\/})
324 should really be run to finish the draft up.
325 When you leave the editor, you will come back to the \whatnow/ level,
326 where you can re-edit the draft, send it, list it, or simply quit
327 without sending the draft at all.
328
329 Caution: while in the editor,
330 you should not delete colons in the headers
331 or change the spelling of \arg{To:}, \arg{cc:}, or \arg{Subject:};
332 and do not leave blank lines between these lines.
333 Feel free to change the addresses that you typed previously,
334 or to add these lines if they are missing.
335 Do not delete the dashes that separate the header lines from
336 the text of the message.
337 You should not add additional header lines unless you understand
338 precisely what you are doing.  
339 This means particularly that you should not type or fill in a \arg{From:}
340 line.
341 When the message is sent, the system automatically adds this line.
342 Also, you should not type a \arg{Date:} line in the header.
343 When the message is sent, the system automatically adds the current
344 date and time.
345
346 {\bf Quit:}
347 If you \pgm{quit} without sending the draft,
348 the draft is saved in a file called \file{Mail/draft} under your
349 home directory.
350 This file can be recalled later using the \arg{-use} argument
351 to \pgm{comp}:
352 \example comp\ -use\endexample
353 The \whatnow/ level will permit you to do further editing
354 and to send the final draft when you are ready.
355
356 {\bf Send:}
357 When it is time to send the draft on its way,
358 use the \pgm{send} option by itself.
359 If there are any problems with the draft 
360 (for example,
361 if one or more of the people whom you specified in the \arg{To:} and \arg{cc:}
362 components do not exist)
363 then you will be notified at this time.
364
365 \subsection{Replying to Messages}
366 To reply to a message,
367 use the \pgm{repl} command.
368 For example,
369 \example repl\endexample
370 creates a reply to the current message.
371 You may also reply to a specific message (other than the current one)
372 by giving a {\it message number} (e.g. \arg{1}, \arg{4}, etc.)
373 or a {\it message name} (e.g. \arg{first}, \arg{last}, \arg{prev}):
374 \example repl\ prev\endexample
375 We haven't really introduced message numbers yet.
376 They will be discussed in the next section.
377
378 The process of replying to a message is very similar to composing
379 a message from scratch (see the previous section),
380 but \pgm{repl} conveniently constructs and displays the header
381 of the reply draft for you.
382 You need only type in the text of the reply.
383 An EOT (usually CTRL-D) indicates that you are done typing.
384 If you make a mistake, you may correct it later with a text editor.
385 The draft will be sent only if you give an explicit \pgm{send} command,
386 so you do not have to worry about the draft getting away from you
387 prematurely.
388
389 An example of a complete reply draft, as it appears on your screen might be:
390 \example
391     To: MRose\\
392     cc: JSweet\\
393     Subject: Re: UCI Software Talk\\
394     In-reply-to: Your message of 10 Oct 84 18:15:08 PDT (Wed).\\
395     --------\\
396     I'll be there.\\
397     -jns\\
398     \^{}D       
399 \endexample
400 (The ``\^{}D'' does not appear in the draft.)
401
402 At this point, you are asked
403 \example What\ now?\endexample
404 This is known as being at \whatnow/ level.
405 Refer to the previous section regarding how to edit,
406 display, or send the draft at this point.
407
408 As with \pgm{comp}, 
409 if you \pgm{quit} without sending the reply draft,
410 the draft is saved in a file called \file{Mail/draft} under your
411 home directory.
412 This file can be recalled later using the \arg{-use} argument
413 to \pgm{comp}:
414 \example comp\ -use\endexample
415 The \whatnow/ level will permit you to do further editing
416 and to send the final draft when you are ready.
417
418 \f\section{Scanning Messages}
419 The scan listing created by \pgm{inc} shows the {\it message number},
420 the date on which the message was sent,
421 the sender,
422 and the subject of the message.
423 If there is sufficient space remaining on the line,
424 the beginning of the text of the message is displayed as well,
425 preceded by two left angle brackets (``{\tenpoint\tx$<<$\/}'').
426 An example of a scan listing is:
427 $$\vbox{\tenpoint\tx\halign{\hfil#&#\hfil&&     \quad#\hfil\cr
428 1&+&    10/10&  WESTINE\%USC-ISIF&      RFC 916 Now Available&
429                                         <<A new Request for Co\cr
430 2&&     10/10&  G B Reilly&             Gosling EMACS manual&
431                                         <<Marshall, I am lookin\cr
432 3&&     10/11&  WESTINE\%USC-ISIF&      Internet Monthly Report&\cr
433 }}$$
434 Note that all messages have message numbers.
435
436 To generate your own scan listing, use the \pgm{scan} program.
437 Typing simply
438 \example scan\endexample
439 will list all the messages in the current folder.
440 To scan a subset of these messages,
441 you can specify the numbers of the messages that you consider interesting,
442 e.g.,
443 \example scan\ 2\ 3\endexample
444 Message names may be specified in addition to discrete message numbers.
445 The built-in message names recognized by \MH/ are:
446 \smallskip
447 {\advance\leftskip by\parindent
448 \item{\underbar{all}:}  all messages in the folder (\arg{first-last})
449 \item{\underbar{first}:}        the first message in the folder
450 \item{\underbar{last}:} the last message in the folder
451 \item{\underbar{prev}:} the message immediately before the current message
452 \item{\underbar{cur}:}  the current message
453 \item{\underbar{next}:} the message immediately after the current message
454 \medskip}
455 \noindent
456
457 Message ranges may be specified in addition to discrete message numbers
458 or names by separating the beginning
459 and final message numbers with a dash (``-'').
460 For example,
461 \example scan\ 5-10\endexample
462 scans messages~5 through~10 inclusive.
463 A range of messages may also be specified by separating a beginning
464 message number and a relative number of messages with
465 a colon (``:'').
466 For example,
467 \example scan\ last:3\endexample
468 scans the last three messages in the folder.
469 Similarly,
470 \example scan\ first:3\endexample
471 scans the first three messages in the folder;
472 \example scan\ next:3\endexample
473 scans the next three messages;
474 \example scan\ cur:3\endexample
475 scans the three messages beginning from the current message;
476 \example scan\ 100:4\endexample
477 scans four messages beginning from message number 100.
478
479 To summarize, the important concepts that have been discussed
480 in the section are:
481 {\it message ranges},
482 {\it message numbers},
483 and {\it message names}.
484 When an \MH/ command is described as taking a \arg{msg} argument,
485 it accepts either a message name or a message number.
486 Most \MH/ commands are described as taking \arg{msgs} arguments,
487 meaning that more than one message or message range is accepted.
488
489 \f\section{Deleting Messages}
490 To delete a message, use the \pgm{rmm} program.
491 By default, \pgm{rmm} deletes the current message,
492 but you can give \pgm{rmm} a list of messages to be removed as well.
493 There is no corresponding ``\pgm{unrmm}'' program,
494 but clever users with a need will find out how to change the way \pgm{rmm}
495 works so that it simply moves messages to another folder
496 (say, \arg{+wastebasket}).
497
498 \f\section{Filing Messages}
499 The possibility of having folders other than \eg{+inbox} has been mentioned
500 previously.
501 The methods for moving messages between folders and manipulating folders
502 are discussed here.
503
504 The \pgm{refile} command moves messages from a {\it source folder} to one or
505 more {\it destination folders}.
506 By default, the current message is moved from the {\it current folder} 
507 (typically \arg{+inbox}) to another folder specified as an
508 argument to \pgm{refile}.
509 For example,
510 \example refile\ +todo\endexample
511 moves the current message from the current folder to the folder \eg{+todo}.
512 To move messages from a folder other than the current folder,
513 use the \switch{src +folder} switch, as in
514 \example refile\ -src\ +todo\ last\ +save\ +notes\endexample
515 which moves the last message in the \eg{+todo} folder to the folders
516 \eg{+save} and \eg{+notes}.
517 Note that this operation is a {\it move}, not a {\it copy};
518 it removes the message from the source folder.
519 To keep a copy in the source folder as well, use the \switch{link} switch
520 \example refile\ -link\ -src\ +todo\ last\ +save\ +notes\endexample
521
522 Whenever a folder argument is given to an \MH/ command,
523 that folder becomes the {\it current folder}.
524 To find out which folder is current, use the command
525 \example folder\endexample
526 The \pgm{inc} command sets the current folder back to \arg{+inbox}
527 by default.
528 To find out about all of a user's folders, use the command
529 \example folders\endexample
530 Since folders can contain other folders,
531 the command
532 \example folders\ -recurse\endexample
533 will recursively examine each folder for you.
534
535 To set the current folder, without doing anything else,
536 use the \pgm{folder} program with a folder argument.
537 Hence,
538 \example folder\ +inbox\endexample
539 makes \eg{+inbox} the current folder.
540
541 After a using \pgm{rmm} and \pgm{refile} on a folder a number of times,
542 there tend to be gaps in the numbering sequence.
543 To compress the numbers for the all messages in a folder,
544 use
545 \example folder\ -pack\endexample
546
547 \f\section{The Profile}
548 You can customize the \MH/ environment by editing your \profile/ file.
549 Although there are lots of options,
550 here are the most useful:
551 \smallskip
552 {\advance\leftskip by\parindent
553 \item{\underbar{Editor}:} lists the default editor that \pgm{comp} and
554 \pgm{repl} should use.
555 The default is
556 \example editor:\ prompter\endexample
557 but another editor might be preferred.
558
559 \item{\underbar{{\it editor}-next}:} lists the editor that should be used
560 after the last edit with {\it editor}.
561 Hence, if you have a profile entry
562 \example prompter-next:\ vi\endexample
563 after editing a draft with \pgm{prompter},
564 and being at \whatnow/ level,
565 you could say \eg{edit} (instead of \eg{edit vi})
566 to continue to edit the draft with \pgm{vi}.
567
568 \item{\underbar{Msg-Protect}:}
569 Whenever \MH/ creates a message (for example, with \pgm{inc\/}),
570 this is the octal protection mode that the message is created with.
571 The default is
572 \example Msg-Protect:\ 644\endexample
573 This protection mode permits all other users on the system to read
574 your messages.
575 To maintain privacy, the mode 600 should be used.
576 Note that changing the mode in the profile does not change the modes
577 of messages that have been created already.
578 Use the \unix/ command \pgm{chmod} to change the modes of your
579 existing messages.
580
581 \item{\underbar{Folder-Protect}:}
582 Whenever \MH/ creates a folder (for example, with \pgm{refile\/}),
583 this is the octal mode that the folder is created with.
584 The default is
585 \example Folder-Protect:\ 711\endexample
586 This mode permits other users on the system to make access to
587 specific messages in your folders.
588 To maintain stricter privacy, the mode 700 should be used.
589
590 \item{\underbar{{\it program\/}}:}
591 Each \MH/ program that reads user's \profile/ file
592 looks for an entry beginning with its own
593 name to determine its initial defaults.
594 For example,
595 if you want the default editor for \pgm{repl} to be \pgm{emacs},
596 the line
597 \example repl:\ -editor\ emacs\endexample
598 is sufficient.
599 Command line arguments tend to override profile settings.
600 Given the profile setting for \pgm{repl} above,
601 if you invoked \pgm{repl} with
602 \example repl\ -editor\ vi\endexample
603 \pgm{repl} would use the \pgm{vi} editor instead
604 of \pgm{emacs}.
605
606 \item{\underbar{signature}:}
607 When \MH/ posts mail for you,
608 it looks for this profile entry for your ``real world'' name.
609 For example,
610 \example signature:\ Marshall\ Rose\endexample
611 The contents of the \eg{signature:} entry in the profile should be a simple
612 phrase, with no embedded periods (e.g. ``Marshall T.~Rose'').
613 \medskip}
614 \noindent
615 Note that your profile resembles the header portion of a message.
616 Be sure that it is properly formatted by placing a colon after each entry
617 name,
618 and keep each entry on a single line.
619
620 \f\section{Conventions}
621 Now let's summarize the conventions that \MH/ programs use:
622 \smallskip
623 {\advance\leftskip by\parindent
624 \item{1.} Any \MH/ command that deals with messages can be given a
625 \arg{+folder} argument to say which folder to use.
626 However, only one \arg{+folder} argument may be given per command
627 in most cases.
628
629 \item{2.} If an \MH/ command accepts a \arg{msgs} argument,
630 then any number of messages can be given to the command.
631 The \MH/ command will expand all the ranges and process each message,
632 starting with the lowest numbered one and working its way to the message with
633 the highest number.
634
635 \item{3.} If an \MH/ command accepts a \arg{msg} argument,
636 then at most one message can be given.
637
638 \item{4.} Switches (options) to \MH/ commands start with a dash.
639 Unlike the standard \unix/ convention,
640 each switch consists of more than one character,
641 for example \switch{header}.
642 To minimize typing,
643 only a unique abbreviation of the switch need be typed;
644 thus for \switch{header}, \switch{hea} is probably sufficient,
645 depending on the other switches accepted by the command.
646
647 \item{5.} All \MH/ commands have a \switch{help} switch,
648 which {\it must} be spelled out fully.
649 When an \MH/ command encounters the \switch{help} switch,
650 it prints out the syntax of the command,
651 the switches that it accepts,
652 and version information.
653 In the list of switches,
654 parentheses indicate required characters.
655 For example,
656 all \switch{help} switches will appear as \switch{(help)},
657 indicating that no abbreviation is accepted.
658
659 \item{6.} Many \MH/ switches have both on and off forms,
660 such as \switch{format} and \switch{noformat}.
661 In these cases,
662 the last occurrence of the switch on the command line determines the setting
663 of the option.
664
665 \item{7.} All \MH/ commands that read your \MH/ profile operate the
666 same way:
667 \underbar{first},
668 the profile is consulted for an entry matching the name with which
669 the command was invoked;
670 \underbar{second},
671 if such an entry was found,
672 then the command immediately uses the arguments listed;
673 \underbar{third},
674 any arguments on the command line are then interpreted.
675 Since most switches have both on and off forms,
676 it's easy to customize the default options for each \MH/ command in the
677 \profile/,
678 and to override those defaults on the command line.
679 \smallskip}
680
681 \f\section{Online Documentation}
682 Each \MH/ program has its own \unix/ manual entry.
683 For example, to get information about \pgm{comp},
684 type
685 \example man\ comp\endexample
686 The manual entry for \man mh(1) lists all \MH/ commands,
687 while the manual entry for \man mh-chart(1) lists the syntax and switches for
688 all \MH/ commands.
689
690 In addition,
691 here are a few other manual entries might be found useful:
692 \smallskip
693 {\advance\leftskip by\parindent
694 \item{\man mh-alias(5)} to find out how aliases in \MH/ work;
695 \item{\man mh-mail(5)} to find out how \MH/ stores and interprets messages
696 (this manual entry explains all of the standard header components);
697 \item{\man mh-profile(5)} to find out about the \MH/ user-environment.
698 \smallskip}
699
700 The manual pages for \MH/ are in the standard \unix/ format,
701 but contain additional sections unique to \MH/.
702 Here's a summary of the sections one might find in an \MH/ manual entry:
703 \smallskip
704 {\advance\leftskip by\parindent
705 \item{\sc Name} command name and one-line description.
706
707 \item{\sc Synopsis} syntax of the command.\hbreak
708 All commands accept a \switch{help} switch.
709
710 \item{\sc Description} semantics of the command.
711
712 \item{\sc Files} files used by the command\hbreak
713 Almost always this includes \file{.mh\_profile}.
714
715 \item{\sc Profile} entries in the \profile/ used by the command;
716 \vskip -\parskip
717 \item{\sc Components} these do not include the profile entry for the
718 command itself.
719
720 \item{\sc See Also} other \unix/ manual entries (usually \MH/ programs) that
721 are related to this command.
722
723 \item{\sc Defaults} default arguments for the command\hbreak
724 If the command takes a \arg{+folder} argument,
725 this defaults to the current folder.
726 If the command takes a \arg{msg} argument,
727 this defaults to the current message.
728 If the command takes a \arg{msgs} argument,
729 this defaults to the current message or all messages,
730 depending on which one makes more sense.
731
732 \item{\sc Context} changes to your \MH/ context made by the command.
733
734 \item{\sc Hints} Helpful hints discussing the easy way to do things.
735
736 \item{\sc History} A historical perspective on why \MH/ works the way it does.
737
738 \item{\sc Bugs} Too embarrassing to mention.\hbreak
739 Just kidding.
740 \medskip}
741 \noindent
742 Obviously, not all \MH/ manual entries may have all of these sections.
743
744 \f\section{Reporting Problems}
745 If problems are encountered with an \MH/ program,
746 the problems should be reported to the local maintainers of \MH/.
747 When doing this,
748 the name of the program should be reported,
749 along with the version information for the program.
750 To find out what version of an \MH/ program is being run,
751 invoke the program with the \switch{help} switch.
752 In addition to listing the syntax of the command,
753 the program will list information pertaining to its version.
754 This information includes the version of \MH/,
755 the host it was generated on,
756 the date the program was loaded,
757 and the configuration options in effect when \MH/ was generated.
758 For example,
759 \example
760     version: MH 6.1 \#1[UCI] (gremlin) of Wed Nov  6 01:13:53 PST 1985\\
761     options: [BSD42] [MHE] [NETWORK] [SENDMTS] [MMDFII] [SMTP] [POP]\endexample
762 The \eg{6.1~\#1[UCI]} indicates that the program is from the UCI \mh6
763 version of \MH/.
764 The program was generated on the host \eg{gremlin} on
765 \eg{Wed Nov  6 01:13:53 PST 1985}.
766 It's usually a good idea to send the output of the \switch{help} switch along
767 with your report.
768
769 If there is no local \MH/ maintainer,
770 try the address {\tx Bug-MH}.
771 If that fails, use the Internet mailbox {\tx Bug-MH@UCI.ARPA}.
772
773 \f\section{More on MH}
774 There are myriad aspects of \MH/ that this tutorial hasn't touched upon.
775 Here are a few to whet your appetite:
776 \smallskip
777 {\advance\leftskip by\parindent
778 \item{1.} user-defined sequences\hbreak
779 Define {\it meaningful} message names and shorten type-in considerably
780 (see \man pick(1) for details).
781
782 \item{2.} draft folders\hbreak
783 Maintain a folder of drafts so that more than one draft can be edited at a
784 time,
785 and allow a draft to be edited over several \unix/ sessions independently of
786 other drafts
787 (see the {\bf Advanced Features} section of the \MH/ user's manual for
788 details).
789
790 \item{3.} draft pushing\hbreak
791 Post a draft in the background
792 and immediately free your terminal for other activities
793 (see the {\bf Advanced Features} section of the \MH/ user's manual for
794 details).
795
796 \item{4.} aliases\hbreak
797 Maintain one or more alias files containing the addresses of the people
798 frequently (or infrequently) sent to.
799 This lets you shorten type-in of addressees
800 and saves you from looking up
801 their addresses all the time.
802 (see \man mh-alias(5) for details).
803 \smallskip}