SOUP is used for Internet email and Usenet. The other formats are primarily used with dialup (or telnet) BBSes, to save connect time and to provide a better interface to the message base.
Not all packet formats may be available, depending on how the program was compiled.
This manpage is for version 0.49.
In the letter window or ANSI viewer, pressing F1 or '?' will bring up a window listing the available commands.
The basic navigation keys, available throughout the program, consist of the standard cursor and keypad keys, with <Enter> to select. For terminals without full support for these keys, aliases are available for some of them:
ESC = Q
PgDn = B
PgUp = F
Right = +
Left = -
(Although shown in capitals, these may be entered unshifted.)
With "Lynx-style navigation", activated by the "UseLynxNav" option, the Left arrow key backs out from any screen, while the Right arrow key selects. The plus and minus keys are no longer aliases for Right and Left, but perform the same functions as in the traditional navigation system.
Of special note is the space bar. In most screens, it functions as an alias for PgDn; but in the letter window, it works as a combination PgDn/Enter key, allowing you to page through an area with one key.
In the area list, the default view (selectable in the .mmailrc) is of Subscribed areas only, or of Active areas (i.e., those with messages) if the Subscribed areas are unknown. By pressing L, you can toggle between Active, All, and Subscribed views. (Some formats, like plain QWK, don't have any way to indicate subscribed areas. In other cases, you may have received an abbreviated area list, so that the Subscribed and All views are the same.) In all modes, areas with replies always appear, flagged with an 'R' in the leftmost column.
In the letter list, only unread messages are displayed, by default; but you can toggle this by pressing L. If there are any marked messages, L first switches to a marked-only mode, then to all messages, then back to unread-only. Also, the default mode -- unread or all -- can be set in the .mmailrc.
Multiple sort modes are available in the packet and letter lists; you can cycle through them by pressing '$'. The default sort modes are set in the .mmailrc.
Options can be specified on the command line as well as in the .mmailrc. Option names are the same as those which appear there, though they must be prefaced by one or two dashes, and should not be followed by a colon. There must be a space between the option name and the value; values which include spaces must be quoted. All options must be specified before any packet names or directories on the line. Finally, options which take a filename or path should always include the full path. (This is not, however, necessary for packet names.)
Packet names may be specified on the command line, bypassing the packet menu. If multiple packets are named, they'll be opened sequentially. If a directory is specified instead of a file, the packet window will by opened on that directory, and no further items will be read from the command line. 'T' in the packet menu may need clarification: it stamps the highlighted file with the current date and time.
You can abort the program immediately from any screen with CTRL-X. You won't be prompted to confirm the exit, but you will still be prompted to save replies and pointers (unless autosaving is set). Note that if you've specified multiple packets on the command line, this is the only way to terminate the sequence prematurely.
You can obtain a temporary command shell anywhere by pressing CTRL-Z. In the DOSish ports (MS-DOS, OS/2, Win32), it spawns a command shell, and you return to MultiMail via the "exit" command. In Unix, it relies on the shell to put MultiMail in the background; you return with "fg". (This has always been available in the Unix versions; however, it won't work if MultiMail wasn't launched from an interactive shell, or if the shell doesn't support it.)
In each list window, button 1 highlights a line, or selects it (the same as pressing Enter) if it's already highlighted. Double-click to select it immediately. Click on the scrollbar to page up or down, or on the line just above or below it to scroll a line at a time. In the packet, area, and letter lists, click on the appropriate part of the window title to change the sort or list type.
In the letter window, page up by clicking in the top half of the message text, or down (and on to the next message) by clicking in the bottom half (equivalent to the space bar). Scroll the message a single line up or down by clicking on the status bars at top and bottom. The status flags "Read" and "Marked" can be toggled by clicking on them; clicking on "Save" saves, clicking on "Repl" starts a reply (followup; i.e., the same as 'R'), and "Pvt" starts a private reply (email or netmail; i.e., same as 'N').
In text-entry windows, button 1 works the same as the Enter key; and the dialog boxes work in the obvious way.
Button 3 backs out of any screen, equivalent to ESC.
New searches (specified with '/') always start at the beginning of the list or message. Repeat searches (with '>' or '.') start with the line below the current one. You can take advantage of this to manually adjust the starting point for the next search.
Searches started in the letter, area or packet lists allow the searches to extend below the current list. "Full text" searches all the way through the text of each message; "Headers" searches only the message headers (the letter list), "Areas" only the area list, and "Pkt list" only the packet list. So, a "Full text" search started from the packet list will search every message in every packet (but only in the current directory).
When scanning "Full text", the automatic setting of the "Read" marker is disabled. However, if you find a search string in the header of a message and then select it manually, the marker will be set. But if you start scanning from the packet list, and exit the packet via a repeat search, the last-read markers won't be saved.
Scans of "Headers" or "Full text" that start from the area list or packet list will automatically expand the letter lists they descend into. Similarly, scans that start at the packet list will expand the area lists. Otherwise, if you're viewing the short list, that's all that will be searched.
I hope the above makes some sense. :-) The searching functions are difficult to explain, but easy to use.
Press '|' to bring up the filter prompt, and specify the text to filter on. To clear a filter, press '|', and then press return at a blank filter prompt. (A string that's not found in the list will have the same effect.) Press ESC to leave the filter as it was.
The list will now be limited to those items that contain the text you entered, and that text will appear at the end of the window's title as a reminder. The filter will be retained through lower levels, but will be cleared by exiting to a higher level. Note that a search in, e.g., the letter list will search only the message headers (and only those which are visible in the list), and not the bodies.
When the filter is active in the letter list, the "All" option in the Save menu will save only the items that match the filter. This can be used as a quick alternative to marking and saving. You can also combine filtering and marking.
Changing modes and sort types will not clear the filter. A search in a filtered list will search only the items that match the filter.
In the area list, press 'U' or 'Del' to unsubscribe from the highlighted area. To subscribe to a new conference, first expand the list ('L'), then highlight the appropriate area and press 'S' or 'Ins'. Dropped areas are marked with a minus sign ('-') in the first column; added areas with a plus ('+'). In the expanded area list, already-subscribed areas are marked with an asterisk ('*'). (This and also applies to the little area list. With plain QWK packets, the asterisk should not be relied upon; other areas may also be subscribed.) Added or dropped areas are highlighted in the "Area_Reply" color. Yeah, I'll have to change that name now. ;-)
Pressing 'S' on an area marked with '-', or 'U' on an area marked '+' turns the flag off again.
In Blue Wave, OPX, OMEN or QWKE mode, the list of added and dropped areas is read back in when the reply packet is reopened. If the reply packet has already been uploaded, and you're reading a packet with the altered area list, this is benign. If it's an older packet, you can alter the list before uploading, as with reply messages. In QWK Add/Drop mode, the changed area flags are converted to reply messages when the reply packet is saved. Note: Adding or dropping areas sets the "unsaved replies" flag, like entering a reply message, but does not invoke automatic reply packet saving until you exit the packet.
Unfortunately, the OMEN mode has not actually been tested; but I believe it conforms to the specs. Reports welcome.
Pressing 'd' toggles rot13 encoding, the crude "encryption" method used for spoiler warnings and such, primarily on Usenet.
The ANSI viewer includes support for animation. While within the ANSI viewer, press 'v' again to animate the picture. Press any key to abort the animation.
The ANSI viewer is also used to display the new files list and bulletins, if any are present.
New in version 0.43 is support for the '@' color codes used by PCBoard and Wildcat. This is on by default in the ANSI viewer, but it can be toggled to strip the codes, or pass them through untranslated, by pressing '@'.
As of version 0.46, the ANSI viewer also includes limited support for AVATAR (level 0) and BSAVE (text only) screens. These can be toggled via ^V and ^B, respectively.
The Unix versions of MultiMail assume that the console uses Latin-1, while the DOSish versions (DOS, OS/2, and Win32) assume the IBM PC set. You can override this via the .mmailrc option "Charset", or on a temporary basis by pressing 'c'.
You can also use a different character set by disabling the conversion in MultiMail, and letting your terminal handle it. For SOUP packets, and for Internet or Usenet areas in other packets, everything will be passed through unchanged if you set MultiMail to "Latin-1". For most other packet types, setting MultiMail to "CP437" will have the same effect.
Beginning with version 0.33, a new character set variable is available: "outCharset". This is a string which MultiMail puts into the MIME identifier lines in SOUP replies if the text includes 8-bit characters. It's also used for the pseudo-QP headers which are generated under the same conditions; and when displaying such headers, MultiMail only converts text back to 8-bit if the character set matches. The default is "iso-8859-1".
By default, if a header line in a SOUP reply contains 8-bit characters, MultiMail now writes it out with RFC 2047 (pseudo-QP) encoding. You can disable this for mail and/or news replies via the "UseQPMailHead" and "UseQPNewsHead" options, though I don't recommend it. The bodies can also be encoded in quoted-printable; this is now on by default for mail, and off for news. The options "UseQPMail" and "UseQPNews" toggle QP encoding. (The headers and bodies of received messages will still be converted to 8-bit.)
QP decoding is temporarily disabled when you toggle the display of hidden lines ('X') in the letter window, so that you can see the raw text of the message.
You can pull up the address book from most screens by pressing 'A', which allows you to browse or edit the list. While reading in the letter window, you can grab the current "From:" address by invoking the address book and pressing 'L'.
The use of EDITOR can be overridden in .mmailrc; however, environment variables can't be used within .mmailrc.
You should also make sure that your time zone is set correctly. On many systems, that means setting the TZ environment variable. A typical value for this variable is of the form "EST5EDT" (that one's for the east coast of the U.S.A.).
By default, the other files are placed in the MultiMail home directory ($HOME/mmail or $MMAIL). Directories specified in the .mmailrc are created automatically; the default Unix values are shown here:
As of version 0.41, any of these keywords except "Version" may also be specified on the command line. Command-line options take precedence over those in the config file, but their effect is not guaranteed -- some internal pathnames are initialized before the command line is read, for example.
Here are the keywords and their functions:
%f = "From" in original message
%t = To
%d = Date (of original message)
%s = Subject
%a = Area
%n = newline (for multi-line headers)
%% = insert an actual percent character
Note that you can't put white space at the start of one of these strings (it will be eaten by the config parser), but you can get around that by putting a newline first.
Version 0.48 adds the .mmailrc option "Mouse", which allows you to enable or disable mouse input (for instance, if you don't want to see the mouse cursor).
Version 0.45 adds "TempDir". Note that temporary files are handled differently in this version, and the TEMP and TMP environment variables are ignored. "homeDir" has been removed.
Version 0.43 adds "ClockMode", and makes "UseColors" available in all ports. Also note that CPU usage while idle may be higher in some configurations.
Version 0.41 adds the option "IgnoreNDX".
Version 0.39 changes the function of the "Transparency" option slightly. It now operates on the color set in "Main_Back", rather than Black. Also, if you're accustomed to using the mouse to cut and paste under X or gpm, note that you now have to hold down the shift key while doing this.
Version 0.38 adds "ExpertMode", "Transparency", "UseColors", and "BackFill", while removing the options "BuildPersArea", "UseScrollBars", "MakeOldFlags", and "AutoSaveRead".
Version 0.37 adds "tarUncompressCommand" and "tarCompressCommand".
Version 0.36 adds "LetterMode" and "AreaMode".
Version 0.33 adds "ReOnReplies", "outCharset", "UseQPMailHead", "UseQPNewsHead", "UseQPMail" and "UseQPNews"; changes some default values.
Version 0.32 adds "BuildPersArea" and "MakeOldFlags".
Version 0.30 adds "UserName", "InetAddr", "QuoteHead", "InetQuote", and "QuoteWrapCols".
Version 0.29 adds "UseScrollBars" and "UseLynxNav".
Version 0.28 adds "MaxLines", "StripSoftCR", and "BeepOnPers".
Version 0.26 adds "AutoSaveReplies", "AutoSaveRead", and "UseTaglines".
Version 0.25 adds "Charset", "PacketSort", and "LetterSort". The default packet sort is now by time instead of name.
If you're upgrading from 0.19 to 0.20 or later, and you have a customized ColorFile, be sure to note the new options.
The ColorFile is new in 0.19. Check it out (~/mmail/colors, by default).
As of 0.16, the HOME environment variable can be overridden with MMAIL, or omitted altogether.
If you're upgrading from a version before 0.9, and you have existing reply packets (.rep or .new) whose names are partly or wholly in uppercase, you must rename them to lowercase before version 0.9 or higher will recognize them. (Downloaded packets are not at issue.)
If you're upgrading from a version below 0.8, you may want to manually delete the /tmp/$LOGNAME directory created by previous versions. (0.8 and higher clean out their own temp directories, and use different names for each session.)
If you're upgrading from a version prior to 0.7, please note the changes in the default directories; previously they were "~/mmail/bwdown", etc.
OPX reply packets are always created with a .rep extension, which differs from the behavior of some other readers. If you switch from QWK packets to OPX packets on the same board, MultiMail will _not_ open an old QWK .rep in OPX mode, nor vice versa. (It will try, and will terminate with "Error opening reply packet".)
SOUP reply packets are created with the name "basename.rep", where basename is the part of the original packet name before the first period. (Unlike other formats, there's no actual standard for this in SOUP, but this seems to be the most common form among the SOUP readers I surveyed.) Also, not that I expect anyone to try this, but currently MultiMail is only able to read reply packets generated by other SOUP readers if the replies are in 'b' or 'B' mode, and are one to a file within the packet. Most readers meet the first criterion, but some of them batch all mail and news replies into a single file for each type. A future version of MultiMail will be able to read these, too.
When re-editing a reply, it gets pushed to end of the list of replies.
The R)ename function in the packet window can also be used to move files between directories; however, the destination filename must still be specified along with the path.
If you're using the XCurses (PDCurses) version, and your editor isn't an X app, it will work better if you set MultiMail's "editor" keyword to "xterm -e filename" (instead of just "filename"). I decided not to do this automatically because someone might actually use it with an X editor.
Editing and deletion of old replies are available through the REPLY area, which always appears at the top of the area list. This differs from Blue Wave and some other readers.
The Escape key works to back out from most screens, but after you press it, you'll have to wait a bit for it to be sensed (with ncurses; not true with PDCurses).
Only Blue Wave style taglines (beginning with "...") are recognized by the tagline stealer. The tagline must be visible on the screen to be taken.
Netmail only works in Blue Wave, OMEN and OPX modes, and is still slightly limited. Netmail from points includes the point address. Internet email is available in Blue Wave and OPX modes, for those doors that support it, and in SOUP mode, using the same interface as Fido netmail.
Additional code has been contributed by Peter Karlsson, Mark D. Rejhon, Ingo Brueckl, Robert Vukovic and Mark Crispin.
Red Hat Linux 6.0 (and possibly 6.x) comes with a defective installation of ncurses. When linked to this, MultiMail mostly works, but odd effects appear when scrolling. (Users describe it as double-spaced.) The problem can be fixed by reinstalling ncurses from the source -- not the source RPM that comes with Red Hat, but the original source from the ncurses site (see INSTALL).
SOUP area type 'M' is not recognized yet. First I have to find a program that can generate one. :-)
The ANSI viewer eats a lot less memory than it used to, but it can still be a problem. (Each character/attribute pair takes up four bytes in memory. But lines which have the same attribute throughout are stored as plain text.)
The new file list and bulletin viewer is, as yet, a hack. A better means of selecting which ones to view will be forthcoming, if I can ever decide just how it should look. (Your opinion is welcome.)
If you find any bugs, or have ideas for improvement, please write to me.