![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to text.tex CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSD / contrib / mh / papers / tutorial|
Return to text.tex CVS log | Up to [CSRG BSD Unix] / 43BSD / contrib / mh / papers / tutorial |
1.1 root 1: % begin text
2:
3: \banner
4:
5: \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: \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: \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: \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: \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: \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: \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: \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: \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: \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: \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: \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: \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: \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: \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: \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 [email protected]}.
772:
773: \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}
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.