MultiMail(1)

NAME
mm - offline mail reader for Blue Wave, QWK, OMEN and SOUP packets

SYNOPSIS
mm [filename1] [filename2] [...]

DESCRIPTION
MultiMail is an offline mail packet reader, supporting the Blue Wave, QWK, OMEN and SOUP formats. It uses a simple curses-based interface. The first three formats are used primarily by dialup BBSes, to save connect time, and to provide a better interface to the message base. SOUP is used for Internet email and Usenet. This manpage is for version 0.30.

USAGE
On most screens, the available keystroke commands are displayed in the lower part of the screen. In the mail-reading window, pressing F1 or '?' will show the commands available there. The navigation keys, most of which work throughout the program, are briefly summarized only on the packet screen, for lack of space. :-) Basically, they 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. It also makes Left equivalent to selecting ".." in the packet list, except at the top level (where it's equivalent to Quit). 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 areas of the program, it functions as an alias for PgDn; but in the mail-reading window, it works as a combination PgDn/Enter key, allowing you to page through an area with one key. In the letter list, only unread messages are displayed, by default, but you can toggle this by pressing L. 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. Packet names may be specified on the command line, bypassing the packet menu. If multiple packets are named, they'll be opened sequentially. 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.)

SEARCHING
A case-insensitive search function is available on all screens. Press '/' to specify the text to look for, or '>' or '.' to repeat the last search. 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.

OFFLINE CONFIGURATION
At present, offline config is limited to subscribe (add) and unsubscribe (drop) functions. The Blue Wave, OMEN, QWKE, and QWK Add/Drop (with DOOR.ID) methods are supported. (The QMAIL "CONFIG" method is not supported yet.) Offline config is not available in SOUP mode. 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, 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, neither the QWKE mode nor the OMEN mode has actually been tested; I no longer have access to a QWKE door, and the OMEN doors I've used don't support offline config. But I believe these conform to the specs. Reports welcome.

HIDDEN LINES AND ROT13
In the letter window, you can toggle viewing of Fidonet "hidden" lines (marked with a ^A in the first position) by pressing 'x'. The lines are shown as part of the text, but in a different color. In Internet email and Usenet areas, the full headers of the messages are available in the same way. Pressing 'd' toggles rot13 encoding, the crude "encryption" method used for spoiler warnings and such, primarily on Usenet.

ANSI VIEWER
If a message contains ANSI color codes, you may be able to view it as originally intended by activating the ANSI viewer. Press 'v' to start it. Press 'q' to leave the ANSI viewer; the navigation keys are the same as in the mail-reading window. 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.

CHARACTER SETS
MultiMail supports two character sets: the IBM PC set (Code Page 437), and Latin-1 (ISO 8859-1). Messages can be in either character set; the set is determined by the area attributes -- Internet and Usenet areas default to Latin-1, while all others default to IBM -- and by a CHRS or CHARSET kludge, if one is present. OMEN packets indicate their character set in the INFOxy.BBS file. MultiMail automatically translates between these character sets when displaying messages and creating replies. 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 in the .mmailrc, or on a temporary basis by pressing 'c'.

REPLY SPLITTING
Replies may be split, either automatically, or manually via CTRL-B in the reply area. For automatic splitting, the default maximum number of lines per part is set in the .mmailrc. The split occurs whenever the reply packet is saved. This allows you to defer the split and still re-edit the whole reply as one. However, with autosave on, the split will occur immediately after entering a reply (because the save does, too). Setting MaxLines in the .mmailrc to 0 disables automatic splitting; manual splitting is still allowed. Attempts to split at less than 20 lines are assumed to be mistakes and are ignored.

ENVIRONMENT
MultiMail uses the HOME or MMAIL environment variable to find its configuration file, .mmailrc; and EDITOR for the default editor. MMAIL is takes precedence over HOME if it's defined. If neither is defined, the startup directory is used. Depending on the implementation, TMP and/or TEMP may also be used to specify the directory for temporary files. The use of EDITOR can be overridden in .mmailrc; however, environment variables can't be used within .mmailrc. If you're using SOUP, you'll want to make sure 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.).

FILES
The only hardwired file is the configuration file: .mmailrc (mmail.rc in DOS, OS/2 or Win32). It's used to specify the pathnames to MultiMail's other files, and the command lines for external programs (the editor and the archivers). By default, the other permanent files are placed in the MultiMail home directory ($HOME/mmail or $MMAIL/mmail). For temporary directories and files, MultiMail uses the tmpnam() function (the location is system-dependent). Directories specified in the .mmailrc are created automatically; the default values are shown here:

~/mmail
    To store the tagline file, netmail addressbook, etc.

taglines
    A plain text file, one tagline per line.

addressbook (address.bk in DOS, OS/2 or Win32)
    A list of names and corresponding Fido netmail or Internet email addresses. Note that Internet addresses are prefaced with an 'I'.

colors
    Specifies the colors to use. (See README.col.)

~/mmail/down
    To store the packets as they came from the bbs.

~/mmail/up
    To store the reply packet(s) which you have to upload to the bbs.

~/mmail/save
    The default directory for saving messages.

CONFIG FILE
The config file (see above) is a plain text file with a series of values, one per line, in the form "KeyWord: Value". The case of the keywords is not signifigant. Additional, comment lines may be present, starting with replaced by the defaults when you upgrade to a new version.) If any of the keywords are missing, default values will be used. Here are the keywords and their functions:

Version
    Specifies the version of MultiMail which last updated the file. This is used to check whether the file should be updated and the "new version" prompt displayed. Note that old values are preserved when the file is updated; the update merely adds any keywords that are new. This keyword is also used in the colors file.

UserName
    Your name in plain text, e.g., "UserName: William McBrine". This is used together with InetAddr to create a default "From:" line for SOUP replies; and by itself in OMEN for display purposes (the actual From name is set on upload), and for matching personal messages.

InetAddr
    Your Internet email address, e.g., "InetAddr: wmcbrine@clark.net". This is combined with the UserName in the form "UserName <InetAddr>" ("William McBrine <wmcbrine@clark.net>") to create a default "From:" line for SOUP replies. Note that if neither value is specified, and nothing is typed manually into the From: field when creating a message, no From: line will be generated -- which is perfectly acceptable to at least some SOUP programs, like UQWK.

QuoteHead, InetQuote
    These strings are placed at the beginning of the quoted text when replying in normal or Internet/Usenet areas, respectively. (The distinction is made because the quoting conventions for BBSes and the Internet are different.) Replaceable parameters are indicated with a '%' character, as follows: %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.

homeDir
    User's home directory.

mmHomeDir
    MultiMail's home directory.

signature
    Path to optional signature file, which should be a simple text file. If specified, it will be appended to every message you write. You should give the full path, not just the name.

editor
    The editor MultiMail uses for replies, along with any command-line options. This may also be a good place to insert spell-checkers, etc., by specifying a batch file here. Note that the default value is just the editor that's (almost) guaranteed to be available, for a given OS (although the Unix "EDITOR" environment variable is checked first), and is in no way a preferred editor; you can and should change it.

PacketDir
    Default packet directory.

ReplyDir
    Default reply packet directory.

SaveDir
    Default directory for saved messages.

AddressBook
    Path and filename of the address book. (You might change this to share it with another installation, but basically this keyword isn't too useful.)

TaglineFile
    Path and filename of the tagline file. This could be altered from a batch file to swap between different sets of taglines. (But note that this value is only read at startup.) You could also share taglines with another program, but be careful with that; MultiMail truncates the lines at 76 characters.

ColorFile
    Path and filename of the colors file. See README.col.

*UncompressCommand, *CompressCommand
    Command lines (program name, options, and optionally the path) for the archivers to compress and uncompress packets and reply packets. ZIP, ARJ, RAR and LHA are recognized. The "unknown" values are a catch-all, attempted for anything that's not recognized as one of the other four types; if you have to deal with ARC or ZOO files, you might define the archiver for them here.

PacketSort
    The packet list can be sorted either in inverse order of packet date and time (the newest at the top), or in alphabetical order by filename. "Time" specifies the former, and "Name" the latter. (Actually only the first letter is checked, and case is not signifigant. This applies to the other keywords of this type (the kind that have a fixed set of values to choose from) as well.) The sort type specified here is only the default, and can be toggled from the packet window by pressing '$'.

LetterSort
    The sort used by default in the letter list. Can be "Subject" (subjects sorted alphabetically, with a case-insensitive compare), "Number" (sorted by message number), "From" or "To". (This can be overridden, as in the packet list.)

Charset
    The character set that the console is assumed to use. Either "CP437" (code page 437, the U.S. standard for the IBM PC and clones) or "Latin-1" (aka ISO-8859-1, the standard for most other systems). Note that the character set of messages is determined separately (q.v.).

UseTaglines
    Yes/No. If no, the tagline window is not displayed at all when composing a message.

AutoSaveReplies
    Yes/No. If yes, the reply packet is saved automatically -- the equivalent of pressing F2, but without a confirmation prompt -- whenver the contents of the reply area are changed. This can be convenient, and even a safety feature if your power supply is irregular, but it provides less opportunity to take back a change (like deleting a message). If no, you're prompted whether to save the changes on exiting the packet. Note that if you say no to that prompt, nothing that you wrote during that session will be saved (unless you saved it manually with F2).

AutoSaveRead
    Yes/No. If yes, the read/marked/etc. indicators are saved automatically when exiting a packet. If no, you'll be prompted whether to save them; if you say no, the indicators will remain as they were before you opened the packet.

StripSoftCR
    Yes/No. Some messages on Fido-type networks contain spurious instances of character 141, which appears as an accented 'i' in code page 437. These are really so-called soft returns, where the message was wrapped when composing it, but not indicating a paragraph break. Unfortunately, the character can also appear legitimately as that accented 'i', so this option defaults to no. It can be toggled temporarily via the 'I' key in the letter window, and it doesn't apply to messages in the Latin-1 character set.

BeepOnPers
    Yes/No. If yes, MultiMail beeps when you open a message addressed to or from yourself in the letter window. (These are the same messages which are highlighted in the letter list.)

UseLynxNav
    Yes/No. See the description under USAGE.

UseScrollBars
    Yes/No. In list windows, when the number of items in the list exceeds the number of lines in the window, MultiMail puts a scroll bar on the right border of the window, showing the highlight bar's position relative to the entire list. Older versions of MultiMail (pre-0.29) didn't do this, and I figure some people may not like it, so you can disable it here.

QuoteWrapCols
    Numeric. The right margin for quoted material in replies (including the quote indicator).

MaxLines
    Numeric. See the description under REPLY SPLITTING.

UPGRADING
When you run a new version of MultiMail (0.19 or later) for the first time, it automatically updates your .mmailrc and ColorFile with any new keywords. (Old keywords, and the values you've set for them, are preserved. However, comments are lost.) Some notes on specific upgrades: Version 0.30 adds the .mmailrc options "UserName", "InetAddr", "QuoteHead", "InetQuote", and "QuoteWrapCols". See above for description. Version 0.29 adds the .mmailrc options "UseScrollBars" and "UseLynxNav". Version 0.28 adds the options "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.

NOTES
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 and OMEN mode, and is still slightly limited. Netmail from points now includes the point address. Internet email is available in Blue Wave mode, for those doors that support it, and in SOUP mode, using the same interface as Fido netmail.

AUTHORS
MultiMail was originally developed under Linux by Kolossvary Tamas and Toth Istvan. John Zero was the maintainer for versions 0.2 through 0.6; since version 0.7, the maintainer is William McBrine <wmcbrine@clark.net>. Additional code has been contribued by Peter Karlsson, Mark D. Rejhon, Ingo Brueckl, and Robert Vukovic.

BUGS AND KNOWN PROBLEMS
If your editor produces automatic backup files, you should disable this feature, if possible, or wrap it with a batch file to delete them when done. MultiMail will erase the temporary files it creates itself, but it doesn't know to erase the backup files from an editor. The Win32 version is reported to be incompatible with 4DOS: shelling to external programs (archivers or editors) fails. Thanks to Tony Summerfelt for figuring this one out. You can set the MultiMail session to use COMMAND.COM while retaining 4DOS elsewhere. On some platforms, specifying a packet on the command line fails if the filename is exactly 10 characters. (Both shorter and longer names are OK.) This appears to be due to strange bugs in the standard library, and I haven't found a satisfactory solution. I noticed it now because all OMEN packets fit this description. :-( Packets chosen from the packet menu are unaffected. SOUP area type 'M' is not recognized yet. First I have to find a program that can generate one. :-) The ANSI viewer eats up a huge amount of memory -- the number of rendered lines, times the screen width, times four bytes. (And when it's used as a file viewer, add the length of the disk file to that.) That wasn't much of a problem when viewing ANSI messages, but it can get severe now that the ANSI viewer is used for new file lists. (A list of several hundred K may require several megs of memory.) 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.