This file documents AM V1.19beta, a MUA with full intuition Interface and support for reading and sending multimedia mails for the Amiga Copyright (C) 1991, 1992 Christian Riede Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation. * General ******* AM (AmigaMail) is a completely Intuition controlled mail user agent for use with AmigaUUCP and AmigaUUCP+. Is was designed to be easy to use for novice users. As my time to spend with AM is limited I tried to avoid inventing the wheel again and again by using things like gadtools, asl etc. This manual contains installation instructions, a user's manual and a technical description of AM. Use and distribute AM under the Terms of the GNU General Public License Version 1. Although AM runs quite stable now, please note that AM V1.19beta is still beta! Do not use it unless you are familiar with some internals of AmigaUUCP(+). Wait for the first final release that will come out really soon now! AM requires 2.04 (KS 37.175) Installation ************** Installation of AM ================== 1. Make sure that you are running under WB/KS~2.04 (Kickstart 37.175) 2. Install AmigaUUCP (or AmigaUUCP Plus) as described in the documentation for this software. 3. Create an entry in `GETTY:passwd' for each user you want to read mail for. AM needs the fields for the User- and Realname. For details look at documentation for the UUCP-Package. 4. Run the script `aminstall'. This will copy all the necessary binaries and configuration files. 5. If you are running Matt Dillons AmigaUUCP, add the following to `UULIB:Config': `AMFlags DUUCP' (Case is important!) 6. Backup and delete all old mailfolders in `UUMAIL:'. AM is totally incompatible with dmail! Mailforwarding will work as usual, so you just have to remove the actual mailfolders. 7. Delete dmail from your path to avoid starting it accidentally 8. Set the environment variable `USERNAME' to your Username. (You can read mail for other users than specified in this variable, this will be explained later) 9. Make sure that the entries `NodeName', `DomainName' and `TimeZone' are set correctly in `UULIB:Config' (see Documentation for UUCP-Package). 10. When using AM from Workbench, set ToolTypes `USERNAME' (defaults to contents of environment variable `USERNAME'), `CONFIG' (name of config file with full path, defaults to `UULIB:AM.Config' and `FOLDER' (Directory to use as mailfolder, defaults to `UUMAIL:USERNAME.mail') 11. When using ARN, add the following to .arnrc `SENDMAIL uucp:c/sendm %s USERNAME' to have mails sent from within ARN archived correctly. (insert your username, of course) 12. when you are using Matt Dillons AmigaUUCP, then create a line for each user on the system in `UULIB:Aliases' as following: USERNAME::`"|uucp:c/lmail USERNAME' 13. when you are using the AUUCP+ sendmail (included in the AM contrib. distrubution), create a file in UUMAIL: for each user named with contents `forward to |uucp:c/lmail USERNAME' Do not use the original AUUCP+ sendmail, you need at least version 1.02j21 (thanks, wusel). This version is included in the contrib. archive 14. Add the following line to your `s:user-startup': `setenv TZ TIMEZONE' Timezone is in GMT+-xx format, that is GMT+01 for MET, GMT+02 for MET DST etc. 15. If you do not have GCC (Gnu-C) installed, add the following lines to your `s:user-startup': `assign GCC20: SYS:' `assign GCC: GCC20:' `assign LOCAL: GCC:' `assign ETC: GCC:' `assign USR: GCC:' `assign LIB: GCC:' `assign GCC: GCC:' `assign TMP: t:' `assign DEV: GCC:' 16. Reboot your system before using AM 17. After you've started AM sucessfully, edit the entries for Mail Editor, Text Filter, in the config menu. 18. Configuring the MIME-Stuff: Copy the needed binaries from the contrib. archive (see `uulib:mailcap' that has been installed by `aminstall' for which ones are nedded) somewhere to your Harddisk and add this directory to the path in `uucp:c/show-startup'. 19. AM can play a sound via upd each time a mail arrives. The ID used for this is `am_newmail'. If you don't have upd, you can skip this. Updating to a new Version ========================== Rerun the `aminstall' script and check if all things mentioned above are properly done (steps may differ slightly between different versions of AM). Additionally do a `makecontents FOLDER' for each existing mailfolder to correct the contents files. Attention: this marks all mail as old/read! The format of the addressbook has changed from 1.12 on. Backup old files before using newer versions of AM. Conversion utilities are not provided. User's Manual ************** Starting AM ============ AM can be started from CLI or from Workbench. From CLI the Syntax is: `AM' `AM USERNAME' `AM USERNAME CONFIGFILE' Examples: `AM' Start AM for user in environment variable USERNAME `AM foo' Start AM for user "foo" `AM bar work:am.config' Start AM for user `bar' using configfile `work:am.config' When started from Workbench, you can optionally set the tooltypes USERNAME (the name of the user you want to read mail for) and CONFIG (the name of the config file). If something goes wrong during startup, AM will pop up a requester telling you the reason. Only if the intuition.library couldn't be opened (for example because of wrong OS version, AM requires V37-libraries), no requester will pop up. AM will tell you this via stdout if you've started AM from CLI. How to get out of it ===================== You can quit AM by clicking the close gadget or selecting the quit menu item in the project menu. This will mark all mails as old. Do not reboot or turn off your machine immediately after quitting AM because although AM itself has ended, the contentsserver is still running and saving the contents file. Wait for disk activity to finish before rebooting or switching power off. (If this causes problems, AM could be changed not to quit before the contents file is saved. Please let me know about your opinion. Most UUCP-People leave their machine running all day) If a requester pops up, telling you that there are running subprocesses, then you must first finish all pending mail reading/sending actions. With the Exit choice in the Project menu you can leave AM without marking all mails old. General ======== When AM is busy, it shows a busy-indicator in the titlebar of the screen and switches the mousepointer into a clock, when the AM window is active. If AM is in the Busy-state, AM will not respond to any user actions in the main window. This will prevent queued events to be executed accidentally. Requesters will work as normal in busy state. The Mailfolder =============== The AM Window shows the contents of your selected mailfolder. Per default only new mail is visible. You can select the whole mailfolder, the mail of the last week, all mail you've written or all mail others have written to you with the leftmost column of little gadgets by just clicking the with the mouse. You can also control the information that is displayed: Show All: The real name of the sender (Fr:), the receiver (To:) and the Subject (Subj:) is shown. Show From: The whole address of the sender as found in the mailheader is shown Show To: The whole address of the receiver as found in the mailheader is shown Show Subject: Only the subject is shown. Show Date: Show the date the mail was send in local time. Show MsgId: The messageid of the mail is shown Mail can be sorted by several criteria: By the number of the file in the mailfolder (default), the realname of the sender or the receiver, the subject ("re:" is cut off first so that replies are displayed near the original mail) or by thread. Sorting by thread is similar to sorting by subject, but it uses the Message-Id: and In-Reply-To: fields of the mailheader. Because Mail is internally stored as a list, sorting is not very efficient and may last quite a while with large numbers of mailfiles. Please be patient. When new mail arrives while AM is running, it will be added to the list automaticlly. Actions ======== Read Mail ---------- Read mail by double clicking its line in the display. You can also read the actual selected mail with the "Read"-menu item. If it is a multimedia mail or an encoded mail, you will be prompted weather you want to display the mail with metamail and make the pictures etc. visible. Send Mail ---------- To send mail to someone on the net, select the "Send" menu item in the actions-menu. Please note that sending mail runs as a seperate process so that it is possible to use AM while you are editing mail, selecting addresses etc. It is also possible to send (and edit) more than one mail at one time without having to start AM twice. The Address Requester ...................... In the address requester you must provide the address of the receiver, addresses for carbon copies and blind carbon copies (the receiver will not see who else got the mail), a reply-to address and a subject. The entries for `To:' and `Subject:' are required, the ones for `Cc:', `Bcc:' and `Reply-To:' are optional. You can add an address from the listview gadget to the current selected field by just clicking it. You can request a delivery report from the receiving transport agent. This is done by adding `Return-Receipt-To' and `Generate-Delivery-Report' lines to the header of the outgoing mail. Not all systems support this feature, DUUCP and the new AUUCP+ sendmail (included in the distribution) will handle it. Editing the Mail ................. To edit the body of the outgoing mail, press the `Edit' button or return in the `Subject:'-gadget. The Editor will display you the whole body part of the mail. If the configured signature-file (see config menu) exists, it will automaticly be appended to your mail. Your signature may contain information about you (name, address, phone, etc.) What you create with the editor as the body of your mail is exactly the image the receiver will get. Avoid long lines in the body (not more than 80 characters) as not all mailreaders wrap them automaticly. Quit the editor with a command that will save the file, for example AMIGA-Q in CygnusEd, ESC x CR in ED, etc.. Whereever later AM finds a line like `[include FILENAME TYPE/SUBTYPE ENCODING]' it will include the given file in a MIME-compatible way into the outgoing mail. For example, to send a GIF image, you would enter `[include GAGA.GIF image/gif base64]'. The receiving Useragent must be able to interpret MIME-mails to make this feature work. More information about this you can find in RFC1341. Confirm Send ............. After you've finished editing the message, press the `Send'-botton to send the mail. want to send the mail by a requester. Click "OK" to send the mail, "CANCEL" to abort. If your file contains 8-bit characters (german umlauts for example), AM will encode the mail. If the first address in the `To:'-line can be found in the addressbook, the encoding method specified there will be used. Otherwise the default from the config menu is used. If the encoding is `7BIT', German umlauts will automaticlly converted into ae, oe, ue etc. You will be warned about nonconvertible non-ASCII characters. If you would like other transcriptions for 8-bit characters to be added, please let me know. Reply/Forward Mail ------------------- You can reply/forward to the current selected mail directly without having to bother about addresses and subjects. When you select the `Reply', `Group Reply' or the `Forward' menu item, AM will generate all necessary things for you: The address of the receiver is taken from the address of the sender or, if present, the "Reply-To" address. The Subject will be the old subject prepended with `Re: '/`Fwd: '. `Reply' means that only the sender of the mail receives the reply. `Group Reply' means that all people from the `To:' and `Cc:' lines receive the reply, too. Print Mail ----------- You can print the currently selected mail by selecting the "Print" item in the actions menu. Printing will be done in background. There is actually no way to cancel the printing except with the CLI command break (find the number of the printing process with the status command, the command of the printing process is `c:type' for normal text mails, `metamail' for multimedia mails. Then kill it with `break NUMBER' Delete Mail ------------ Messages can be deleted from the mailfolder with the delete menu item in the actions menu. This menu item deletes the currently selected message. A requester will pop up to confirm the deletion. Attention: Mail will be deleted immediately unlike other MUAs, that mark mail only as deleted and delete them on exit. Move Mail ---------- You can move the current message to another folder with the move menu item. The Addressbook ================ AM maintains an addressbook to store frequently used addresses. The information is stored in the file `UULIB:addressbook'. You can edit the Addressbook with a menu item. Each address consists of 5 Parts: Username: The person's email-address Realname: The person's realname Reply-To: A Reply-To address to add each time you send mail to the person. Contents-Transfer-Encoding: How to encode mail to the person: BASE64: The whole mail is encoded in BASE64, which is similar to uuencoded. This is used automaticlly when sending pictures, but is normally not desirable. QUOTED-PRINTABLE: Non-ASCII characters (such with code greater than 127) are encoded in a character sequence. Good for mails that run over SMTP-links which transport only 7 bit of each character. 7BIT: No encoding is done. Use this if you know that the receivers user agent cannot handle 8-bit characters. If your file contains 8-bit characters (german umlauts for example) and the mail will be sent with 7BIT Contents-Transfer-Encoding, German umlauts will automaticlly converted into ae, oe, ue etc. You will be warned about nonconvertible non-ASCII characters. If you would like other transcriptions for 8-bit characters to be added, please let me know. 8BIT BINARY No encoding is done and a 8-bit path is assumed. A new addressbook entry with real-/ and username can be generated from the currently selected mail. The Config Menu ================ Font ----- With a standart system Requester you can select the font that will be used for all the gadgets in the AM window. Colors ------- The colors of the AM screen may be adjusted only if AM has it's own custom screen (see below). AM uses its own color requester now (Thanks to Stefan Sticht). Screen ------- AM can come up on several types of screens. You can select any of the ECS screen modes. Selection of arbitrary public screens is also possible. The public screen can be choosen by entering it's name. If the requested screen mode is not availible or the public screen does not exists on your system, AM will tell you that with a requester and come up on the Workbench Screen. Signature ---------- You can set the name of your signature file with this menu item. `UULIB:.Signature' is taken as default External programs to use for actions ------------------------------------- The "MailEditor" will be used to edit outgoing mail. It must be given with full path and is called with a filename as first parameter. If you are using CygnusEd, you must create `S:cygnus-ed' with the following contents .key filename .bra { .ket } sys:utilities/ed "{filename}" -STICKY and set the s-bit of this file. Then use `S:cygnus-ed' as MailEditor for AM. The TextViewer is used for pure unencoded text mails and for the output of metamail. Reply-To Address ----------------- Here you can configure an Reply-To address that is to be included into all outgoing mails. This setting is overridden by an entry in the addressbook. Content Transfer Encoding -------------------------- This is the default for the Content-Transfer-Encoding headerfield. It is also overridden by an entry in the addressbook. Keyboard shortcuts =================== The following keyboard shortcuts do exist: `SPC', `RET' Read mail, goto next `r' Reply `R' Reply (Quote) `f' Forward `f' Forward (Quote) `d' Delete `s' Send `p' Print CURSOR UP/CURSOR DOWN Moving around in the listview gadget Utilities ========== `lmail' ------- `lmail' is the recommended way to store mail in AM's mailfolderes. It takes a mailfile on stdin and stores it into the mailfolder of the user given in the argument. A flag -r marks the mail as old immediately (used in sendm). Is is actually used by sendm (see below), in `UULIB:aliases' (DUUCP) and in `uumail:USERNAME' (AUUCP+) `newmail' --------- With `newmail' you can check if a user has new mail. It intended for use in sys:wbstartup or from cron. When no arguments are given, `newmail' checks all users in `uulib:passwd'. If arguments are given, only those users are checked. The tooltype `USERNAME' does the same when started from workbench. `makecontents' -------------- To create a new contents file in the mail directories makecontents is used. It deletes all contents entries and builds them new. You should not have AM running while doing that because AM will be notified about all changes to the mailfolder (quite a lot....) `amkill' -------- With `amkill' you can kill the server process. sendm ----- When sending mail from within ARN, the script `sendm' is called. It archives the mail for the specified user. Versions of ARN less than version 069 don't generate a Date:-line. All features of AM that deal with the date of a mail (sort, select last week,...) will not work properly with archived mails sent from within those versions of ARN. This is fixed from version 0.71. See ARN's documentation for details. Technical information ********************** This part is intended to give you a rough idea of how AM is working. For details please look into the source. The Screen ========== If AM doesn't have it's window on a foreign public screen, it makes it own screen public. The name of this public screen is then "AmigaMail". contentsserver ============== All programs access the contents file via tha contentsserver. That way it is ensured that all new items are stored correctly and deleted items do not remain in the mailfolder. The server creates a public port with name `AM-Server'. Clients like AM or lmail send requests to this port. Actions performed by the contentsserver --------------------------------------- The contentsserver creates a public message port with name `AM-Server'. Clients can send messages of type `struct AMMessage' to let the server work for them. The contentsserver will return the Message upon completion. For details see `client.c' `ACT_DIE' ......... Description Die, if there are no locks to Mailfolderes left. Parameters none Results `Msg->rc' is `TRUE' for success, else `FALSE'. `ACT_LOCKCONTENTS' .................. Description Lock mailfolder of given user. The contentsfile will be read, if not already locked Parameters `Msg->Username' contains the Username. Results `Msg->rc' is `TRUE' for success, else `FALSE'. `ACT_UNLOCKCONTENTS' .................... Description Unlock Mailfolder of given user. Save contentsfile if all locks are released and changes were made. Parameters `Msg->Username' contains the Username. Results `Msg->rc' is `TRUE' for success, else `FALSE'. `ACT_GETCONTENTS' ................. Description Provide a copy of the given user's mailfolder. Parameters `Msg->Username' contains the Username, `Msg->Mailbox' the listheader for the copy. This list will be cleared first. Results `Msg->rc' is `TRUE' for success, else `FALSE'. `ACT_MARK_READ' ............... Description Mark Mail as read. All clients that asked for notification will be notified about the change. Parameters `Msg->Username' contains the Username, `Msg->Number' the number of the desired mail. Results `Msg->rc' is `TRUE' for success, else `FALSE'. `ACT_MARK_UNREAD' ................. Description Mark Mail as unread. All clients that asked for notification will be notified about the change. Parameters `Msg->Username' contains the Username, `Msg->Number' the number of the desired mail. Results `Msg->rc' is `TRUE' for success, else `FALSE'. `ACT_MARK_OLD' .............. Description Mark Mail as old. No notification will be done. Parameters `Msg->Username' contains the Username, `Msg->Number' the number of the desired mail. Results `Msg->rc' is `TRUE' for success, else `FALSE'. `ACT_ADD_ITEM' .............. Description Encorporate a new item into the mailfolder. The server will parse the Header and add the information to the contents list. Parameters `Msg->Username' contains the Username, `Msg->Number' the number of the desired mail. Results `Msg->NewMail' is a pointer to a copy of the new item on success (for insertion into the clients list), `NULL' otherwise. `ACT_DELETE_ITEM' ................. Description Delete a mail from the mailfolder. Parameters `Msg->Username' contains the Username, `Msg->Number' the number of the desired mail. Results `Msg->rc' is `TRUE' for success, else `FALSE'. `ACT_NEW_SEQ' ............. Description Get a number for a new file in the users mailfolder. Parameters `Msg->Username' contains the Username. Results New sequential in `Msg->Number', 0 on fault. `ACT_NEW_MSGID' ............... Description Get a new unique message-id for inclusion in mailheaders. Also used for temporary filenames. Parameters none Results New message id in `Msg->MsgId' `ACT_NOTIFY_ON' ............... Description Parameters Results `ACT_NOTIFY_OFF' ................ Description Parameters Results `ACT_VERSION' ............. Description Determine version of the server. Parameters none Results `Msg->MsgId' contains the version string from `am.h' Compiling with GNU-C ==================== When I started using GCC I had to fiddle around with include files a bit. Don't worry, it isn't difficult.