Mahogany User Manual
Version 0.62 ``Mars''

Copyright 1997-2001 by The Mahogany Development Team
Written by Karsten Ballüder, Vadim Zeitlin et.al.
http://mahogany.sourceforge.net/
<mahogany-developers@lists.sourceforge.net>


Contents

Using Mahogany

Release Notes

This is another public release of Mahogany. As with usual we make the source available and binaries for the most common operating systems supported. Mahogany should generally work on any Unix flavour.

Due to the fact that it is a cross-platform effort, the compilation and make system are a bit more complex than the average package. However, the source code is provided and you can attempt to compile it yourself. If you are trying to port it to a new platform, let us know and we will be happy to help you.

Changes against the previous version

0.62 against 0.61

The main changes in this release concern the Mahogany internals: the stability and efficiency have been both greatly improved, in particular it is believed that all fatal crashes using IMAP servers are now gone. Deleting, expunging and changing the status of the messages is now much faster, especially for the folders with a lot of messages. Of course, there are also several new features:

Many bugs have been fixed:

And a few improvements too:

0.61 against 0.60

Note: the version 0.61 wasn't officially released

A couple of new features, most importantly:

0.60 against 0.50

Most importantly, all known major bugs in 0.5 have been fixed in this release. We still have some minor buglets and lots of wishes and enhancements on our list, but all serious bugs should be gone now. A couple of new features have been added:

New experimental features include:

Known bugs:

0.5 against 0.23a

This release has long been delayed, mainly due to us waiting for changes in wxWindows to be completed. As we introduced new features in the meantime, those introduced new delays, and so on. It has been more than half a year since the last release, so changes are major. We hope to stick to a much faster cycle of minor update releases for the future. The main new features are:

0.23a against 0.22a

The main news is, of course, the long-waited for availability of Win32 version. Also:

We have also made good progress on the filtering code, PGP/GPG support, multi-threading support and support for loadable external modules, but these features are not complete yet and disabled in the release. Expect them to appear in the next releases.

0.22a against 0.21a

Release 0.22a is mainly a bugfix release against 0.21a.

0.10a to 0.21a

First, there are some user-visible changes against the latest version, most notably the much improved message editor. This is still work in progress and the next release should add the sorely missed cut and paste support which only recently became functional in the underlying wxGTK toolkit. Also, configurability has been much extended. For the first time, Mahogany now defaults to collecting all mail from the system's INBOX (whatever that is) to a central ``New Mail'' folder. It can easily be set up to watch any number of different mail accounts or newsgroups and collect mail from them.

This release got a bit delayed because we decided to finish some long planned changes under the hood, mainly a complete rewrite of the internal configuration system which now provides the inheriting configuration settings we had planned, something that will become obvious in the next release when full GUI support for it will be added. Also, we seriously improved the mailfolder handling code to reliably handle all kinds of error conditions, such as modified or disappearing mailboxes or terminated connections and recover from them safely. Also, Mahogany now has full working support for IMAP, NNTP and newsspools.

Apart from this there were many minor fixes and changes, both GUI and mail code, documented in detail at the end of the TODO file.

Known bugs

TODO, features to implement

The next few things to be implemented:

Help Needed

As you can see, we have big plans for Mahogany. To achieve all this, we need some help. Areas where we would use some help are

Copyright

Mahogany is copyright by The Mahogany Development Team (Founding members Karsten Ballüder and Vadim Zeitlin). It is licensed under the Mahogany ``Artistic License'' as stated in section1.1.6 or, alternatively, under GNU General Public License. Some part of the source tree distributed with Mahogany is not covered under this license. These additional sources can be found in the ``extra/src'' subdirectory. Please check the files in the individual directories for their copyright notices. However, they can be freely distributed under certain conditions.

Why not the GPL/BSD/QPL/my favourite license?

Recently discussions about which license to chose for which project provoked major flamewars in the Unix community. There is a trend to put everything under the GPL or LGPL1.1. We do not want to get involved in this highly emotional and political discussion. Our intent is to allow everyone to use and modify Mahogany while preserving some form of control over its development. That is why we chose a modified version of Perl's Artistic License. It is both more and less restrictive than the GPL in certain ways. We do not believe that there is one right license for everything. The Mahogany Artistic License is much simpler and easier to understand than the GPL, so we feel more comfortable with it. If you want to do something with Mahogany and feel that the license poses a problem, please contact us! We do not want the license to be a problem and any reasonable request for deviating uses of Mahogany will be likely to be granted. If in doubt, ask us and we will find a solution.


The Mahogany ``Artistic License''

Preamble

The intent of this document is to state the conditions under which this software package may be copied, such that the Copyright Holder maintains some semblance of artistic control over the development of the package, while giving the users of the package the right to use and distribute the Package in a more-or-less customary fashion, plus the right to make reasonable modifications.

This license is based on Perl's ``Artistic License'' and has been adapted to better suit Mahogany. It aims to confirm with the Open-Source specification. If you should have any questions about this license, are unhappy with it or simply would like to comment on it, please get in touch with us.

Definitions

``Package'' refers to the collection of files distributed by the Copyright Holder, and derivatives of that collection of files created through textual modification.

``Standard Version'' refers to such a Package if it has not been modified, or has been modified in accordance with the wishes of the Copyright Holder as specified below.

``Copyright Holder'' is whoever is named in the copyright or copyrights for the package.

``You'' is you, if you're thinking about copying or distributing this Package.

``Reasonable copying fee'' is whatever you can justify on the basis of media cost, duplication charges, time of people involved, and so on. (You will not be required to justify it to the Copyright Holder, but only to the computing community at large as a market that must bear the fee.)

``Freely Available'' means that no fee is charged for the item itself, though there may be fees involved in handling the item. It also means that recipients of the item may redistribute it under the same conditions they received it.

Conditions of Use

.
You may make and give away verbatim copies of the source form of the Standard Version of this Package without restriction, provided that you duplicate all of the original copyright notices and associated disclaimers and only distribute the complete package as a whole.
.
You may apply bug fixes, portability fixes and other modifications derived from the Public Domain or from the Copyright Holder. A Package modified in such a way shall still be considered the Standard Version.
.
You may otherwise modify your copy of this Package in any way, provided that you insert a prominent notice in each changed file stating how and when you changed that file, and provided that you do at least ONE of the following:

)
place your modifications in the Public Domain or otherwise make them Freely Available, such as by posting said modifications to Usenet or an equivalent medium, or placing the modifications on a major archive site such as sunsite.unc.edu, or by allowing the Copyright Holder to include your modifications in the Standard Version of the Package, and rename any non-standard executables so the names do not conflict with standard executables, which must also be provided, and provide a separate manual page for each non-standard executable that clearly documents how it differs from the Standard Version. You must not make the modified version depend on any other software or library if that software or library is not Freely Available or if it is covered under a license more restrictive than this.
)
use the modified Package only within your corporation or organisation.
)
make other distribution arrangements with the Copyright Holder.
.
You may distribute the programs of this Package in object code or executable form, provided that you do at least ONE of the following:

)
distribute a Standard Version of the executables and library files, together with instructions (in the manual page or equivalent) on where to get the Standard Version.
)
accompany the distribution with the machine-readable source of the Package with your modifications, including the complete machine-readable source of the unmodified Standard Version. You must not make the modified version depend on any other software or library if that software or library is not Freely Available or if it is covered under a license more restrictive than this.
)
give non-standard executables non-standard names, and clearly document the differences in manual pages (or equivalent), together with instructions on where to get the Standard Version. d.make other distribution arrangements with the Copyright Holder.
.
You may charge a reasonable copying fee for any distribution of this Package. You may charge any fee you choose for support of this Package. You may not charge a fee for this Package itself. However, you may distribute this Package in aggregate with other (possibly commercial) programs as part of a larger (possibly commercial) software distribution provided that you do not advertise this Package as a product of your own.
.
The name of the Copyright Holder may not be used to endorse or promote products derived from this software without specific prior written permission. However, all products derived from this software must reproduce the original copyright notice as found in the Standard Version.
.
THIS PACKAGE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

The License Dialog

When you start Mahogany for the first time, it will display the license and conditions of use and ask you to accept or reject the license. If you do not accept it, Mahogany will terminate. If you have any questions about the license or want to otherwise comment on it, please email the development team at mahogany-developers@lists.sourceforge.net .

Additional Credits

C-Client library:

The use of the c-client library requires us to display the following copyright notice:

Copyright 1999 by the University of Washington
Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appears in all copies and that both the above copyright notice and this permission notice appear in supporting documentation, and that the name of the University of Washington not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission.  This software is made available "as is", and THE UNIVERSITY OF WASHINGTON DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, WITH REGARD TO THIS SOFTWARE, INCLUDING WITHOUT LIMITATION ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, AND IN NO EVENT SHALL THE UNIVERSITY OF WASHINGTON BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, TORT (INCLUDING NEGLIGENCE) OR STRICT LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

The OpenSSL toolkit:

Mahogany can be linked with the OpenSSL toolkit to support secure communications over SSL. In that case, we must give due credit to the authors and copyright of this library:

This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit .This product includes cryptographic software written by Eric Young (eay@cryptsoft.com) This product includes software written by Tim Hudson (tjh@cryptsoft.com)"

wxWindows:

We gratefully acknowledge the use of the wxWindows cross-platform class library and the excellent work and support of the wxWindows developer team.

Introduction / Tutorial

To get started on Mahogany, you should look at the following sections of this manual:

Obviously, the more of this manual you read, the better use you can make of Mahogany. Once the manual has grown too large, we will provide a short tutorial, but for now we go on coding instead.

Getting started

When you start Mahogany for the first time, it will present you with a rather lengthy configuration dialog where you can configure all kinds of more or less useful options. Don't be afraid of it - just make sure that the main points, notably the settings on the Identity (1.7.2) and Network (1.7.2) page are correct and ignore the rest for now. The defaults should be suitable for most situations.

The main window will then show you a tree of folders (1.4.2) on the left and a view of the currently selected folder (1.4.4) to the right of it. By default, you will find a small number of folders that Mahogany sets up for you, usually these are ``INBOX'', ``SentMail'' and ``New Mail''. So, what are they?

So how about setting up POP access? And what is IMAP?

Setting up POP access is dead easy: You simply click the right mouse button in the folder tree and select ``Create new folder''. Then fill in the details: your username and password for accessing the account and the hostname of the POP server. Optionally you can enter a port number after a colon. By default, Mahogany will collect all mail from here and move it to ``New Mail'' automatically. If you don't want this (i.e. you prefer to leave the messages on server or maybe only move some of them to ``New Mail'' selectively using filters), clear the ``Collect all mail'' checkbox. Note that the default behaviour works better in most cases and that it is impossible to remember the status of the messages on a POP3 server so if you do leave on it, they will always appear as new, even if you had already seen them before.

IMAP - what's that?

IMAP is POP's big brother. Faster, more powerful and better, even more secure. If your ISP supports it, use IMAP rather than POP, your phone bills will go down, too. It's really just a different protocol for accessing the folder, but can do a few fancy things, more about that later.

How to set up your mail accounts

** This is currently missing, see the text in the FAQ. I will explain here how to set up your accounts.

Setting up Mahogany, its configuration files

User configuration files

When run for the first time, Mahogany creates a directory called .M in the user's home directory. The file $HOME/.M/config will contain the current program configuration for this user. Only values different from the default configuration are stored here. If you want to obtain a list of all possible options (although arguably if you are so curious, you'd better read Mahogany sources directly), you can manually add the entry

RecordDefaults = 1
to the [M/Profiles] section of the configuration file. This will cause all values which are used to be written to the configuration file.

System wide configuration file

Mahogany can be pre-configured on a system wide basis by supplying a M.conf file in the installation directory (e.g. /usr/share/Mahogany/M.conf). The syntax for this configuration file is identical to the user's configuration file, so you can just copy a user's file to this location and edit it by hand. Useful settings for a system wide default are servers or mail return addresses. Entries prefixed with an exclamation mark ``!'' are marked as immutable and cannot be overwritten by the user. This can be used by the system administrator to hard-wire certain settings, like, for example the return mail addresses or mail servers to use.

The User Interface

The Main Window

Mahogany's main window is vertically divided into two parts. On the left it has a tree view (1.4.2)of all available mail or news folders. On the right of it, it shows the currently selected folder in a folder view(see 1.4.4).

The Folder Tree

The folder tree shows a hierarchical view of all folders managed by Mahogany, this includes both mail folders and newsgroups. Folders can be grouped hierarchical and inherit settings from their parent folders (e.g. the server host). Clicking the right mouse button on any tree node will pop up a menu with some options. To open a folder or connection to a server for the first time, choose ``Create New Folder'' which will show you a dialog (1.4.3).

Create New Folder Dialog

This menu entry allows you to open a connection to a server or view a mailfolder. No matter whether it is a POP, IMAP, NNTP connection , a file based mailfolder, a newsgroup or whatever, Mahogany treats them all the same and calls them all ``folder''. The dialog has (when the user level is set to ``novice'') three tabs, Access (1.4.3), Compose (1.7.2) and MessageViewer (1.7.2).

Access

Folder Views

A Folder View is a window or part of a window displaying the contents of a mail folder or a newsgroup. It consists of two parts:

Understanding the folder view

The messages are displayed in the folder view according to the curent sort order which may be changed either from the folder properties dialog (of course, it can be set independently for each folder or be the same for all folders at once) or by clicking on the column header. In the latter case, clicking on, for example, ``SUBJECT'' column, will sort the messages by subject if they were not sorted by subject already, otherwise it will sort them by subject in the reverse order. This allows you to sort the listing on some column by just clicking it and to reverse the sort order by clicking it again.

Most of the columns are self explanatory. It should be mentioned that the date format is configurable from the folder view page of the folder properties dialog and you may set it to anything you like. In particular, some people find it very useful to show the date in GMT instead of the local time.

The status column (which is usually the first one, although you may change the column order from the same page already mentioned above) may be empty or contain one or more flags:

Symbol Meaning
* message is flagged or important
A message was answered to
D message is marked as deleted and will disappear after expunge
U message is unread: you haven't seen its body yet
R message is recent: this is the first time you see it
N message is new: it is recent and unread

Accordingly, if nothing appears in the status column, the message was read but wasn't deleted nor flagged and this is not the first time you see it. Note that not all kinds of folders support all kinds of flags: while IMAP servers always do, POP servers are not capable of storing the message flags and so all messages will always appear as new in them.

Note that each message flag has also the corresponding colour which is used to highlight the message in the folder view and also to highlight the folder containing this message in the folder tree. These colours can be changed from the folder view page of the options dialog, as usual.

Keyboard and mouse handling

The reaction to a mouse click in the list of messages depends on the preferences setting ``Preview message when selected``. When the option is selected, a single mouse click will select the message and load it into the preview window. If the option is not set, the message will only be selected but not previewed automatically, which is very useful for accessing mail folders through a slow connection. The same setting effects the behaviour of the space bar, it acts exactly like a single mouse click in the window and will only cause a message to be previewed if a single mouse click is configured to do so. The space key can be used to view the message under the current cursor.

Other keyboard bindings are summarized in the following table:



Key Action performed
* mark/unmark message under cursor
SPACE preview message under cursor
D or DEL mark selected messages for deletion
U remove deletion mark from selected messages
X or # expunge messages marked for deletion
C copy marked messages to another folder
M move selected messages to another folder
S save marked messages to files
P print marked messages
R reply to messages
F forward messages
O open messages in separate window
H toggle display of all headers
BACK/PG UP scroll the message preview one page up
PG DOWN scroll the message preview one page down
Ctrl-U view next unread message



Note that all commands for which it makes sense operate either on the current message only if there is no selection or on all selected messages at once. You can use the mouse or the cursor arrows together with the SHIFT or CTRL keys to select multiple messages at once. The commands which affect the message preview are inactive if no message is previewed.

Migrating from another mail client

Mahogany supports importing the settings from a few other popular mail clients. The current list includes Pine, XFMail and Eudora. Depending on the mail client only part of its settings may be imported but in the best case Mahogany can import the address books, the configuration settings, the filter rules and the list of folders to use. To use this feature, choose ``MAIL|IMPORT...'' command and follow the dialogs.

Even if you don't find your email client in the list proposed in the dialog, everything is not lost. You won't be able to import its configuration information nor the filter rules but you might still recuperate the address book information if your program can export the addresses in the standard comma separated format or as vCards. In either case you can then import just the address books from the address book editor.

Finally, Mahogany can automatically create the entries in the folder tree for all MBOX (standard Unix format, also used by Eudora) files under the given directory. To do this, select the folder in the tree which you want the new folders to appear under and choose ``FOLDER|IMPORT FOLDER TREE...'' command.

Reading Mail

The INBOX Folder

The folder named INBOX has a special meaning. It is the main system mailbox and cannot be deleted or renamed. All new mail will arrive in here. At present, Mahogany leaves all messages in the system inbox. Mahogany will collect mail from several different incoming mailboxes, e.g. the INBOX and some additional POP3 accounts, and move them to a new folder.

The ``New Mail'' Folder

Created by Mahogany the first time you start it, this is a file mailbox which by default receives all new mail. If you mark any folder as incoming, its contents will be checked regularly and any new mail in it moved to the ``New Mail'' folder. If you do not like this name, you can change it in the preferences dialog. Mahogany should in all situations recover from closed connections or disappearing mailboxes, so it is safe to let it run over long periods of time. If a server connection times out, you will receive one or possibly a few error messages but Mahogany will reopen the connection and continue as usual.

Other Folders

The folders are organized in a tree structure: this is purely for the convenience of the user, so any folder may contain as many other folders as needed. Folders can be managed either from the top level menu or from the popup menu in the folder control invoked by pressing the right mouse button in it. You can group folders together by making the sub folders of another folder. This builds no physical connection between the folders but makes the sub folder inherit certain configuration defaults settings from their parent folder. We will soon add a ``folder group'' folder type not representing any mailbox but just being a group of folders.

Accessing Mail Remotely

Mahogany supports two protocols for accessing remote mail servers: POP3 and IMAP. While POP3 is more commonly available, IMAP is definitely the superiour protocol and should be used where available. It will generally give you more functionality and will be much faster over slow connections. Both normally require you to log in with a username and password, but can be configured to work anonymously if supported by the server. IMAP additionally allows you to access any mailfolder file on the remote machine. For example, if you use Mahogany on a remote machine ``atwork.company.com'', you might have your local INBOX (which could be /var/spool/mail/MyUserName on a unix box) and also your ``New Mail'' folder, which usually is ``/.M/New Mail''. With IMAP, if you log in from home, you can not only access your INBOX on the atwork.company.com mail server, but also the ``New Mail'' folder there, by telling Mahogany to use ``/home/MyUserName/.M/New Mail'' as the path to the mailbox file. Like this, you can access any mail folder on that machine that you have access to locally, making remote access to your mail much more flexible than just accessing your new messages.

Sending Mail

To: CC: and BCC: Settings

All of these fields accept either mail addresses, aliases or folder names. Aliases must be expanded by using the tabulator key or the Expand button next to the fields. If multiple entries match the text, you will be prompted with a list to choose from.

Using Folder names as an address

Folder names can be entered by prefixing them with a hash ('#') sign. This will cause a copy of the message to be saved in the folder with this name. If no such folder exists, it will be created in the mail folder directory. For example, entering ``joe.user@foo.com, #myMail'' in the To: field, will send the mail to Joe User and save a copy of it in the folder ``myMail''. Note, that if you have your folders organised hierarchically, you must specify the full path to the folder in the folder tree control. An example: If you have a group of folders in the tree, called ``Work'' and want to save a copy of the message to the folder ``TODO'' which is a sub-folder of ``Work'', you need to add ``#Work/TODO'' in the address field. Instead of using the To: field for this, you can also use CC: or BCC:, there is no difference.

To:

The primary address to which to send the message, multiple addresses can be entered and must be comma-separated.

CC:

CC means Carbon Copy - copies of the message will get sent to the addresses listed here.

BCC:

BCC means Blind Carbon Copy - like CC:, copies will be sent to the addresses listed here, but the addresses will not be stored in the mail header. This allows you to send copies without other recipients of the message knowing about it.

Key Bindings in the Message Editor



Key Function
ALT-D delete word
CTRL-Y delete line
CTRL-U delete to begin of line
CTRL-K delete to end of line
CTRL-C copy selection to clipboard
SHIFT-INSERT  
CTRL-X cut selection to clipboard
SHIFT-DELETE  
CTRL-V paste text from clipboard
CTRL-INSERT  
CTRL-S search for text
CTRL-T search same text again



Using the address book

Although you may directly enter the addresses of recipients of your message into the different address fields (``To:``, ``Cc:`` and ``Bcc:`` although the last two are optional and so might not appear), there is a more convenient way to do it using the address book. To insert an address fromyour address book you should type the first few letters of either the ``nick name'' (or the ``alias'') for this address or the the first letters of the e-mail address and press <TAB> key or click on the ``Expand'' button. If there is only one possible expansion for the letters you have typed, Mahogany will automatically replace them with the corresponding full e-mail address. Other possible cases: either there are no matches at all and a message in the status line of the window will tell you so, or there are more than one match in which case you will be presented with a choice of all possible completions.

Hint: if you press <TAB> immediately after the address expansion it will bring you to the next text entry zone and will not attempt the address expansion the second time.

A special feature of the address expansion is the so-called ``group extension'': if you type the first few letters of an address group name (see ``Address Book Editor'' description for more about it) it will be replaced by the addresses of all the addresses in this group. So, for example, if you have a group called ``Friends'' you may type ``fri'' in the ``To:`` text entry zone and after pressing <TAB> it will be replaced by the e-mail addresses of all your friends.

The Mail Composition Window

The composition window's appearance depends on your configuration settings (1.7.2). Generally, it will at least show text entry fields to specify who to send the message to, for the subject and a large editing window below for the actual message itself. It also features an EXPAND button next to the address field, which allows you to lookup addresses in the currently loaded addressbooks. If you type in the beginning or a substring of a name, alias or email address and either press the expand button or the tabulator key, Mahogany will look up a list of matching addressbook entries and either expand it directly or prompt you with the matching choices. This works for the main address field (``To'') as well as for the carbon copy addresses (``CC'' and ``BCC''). If you specify an address in the ``CC'' or ``BCC'' fields, these people will receive a copy of the message. The difference between them is that the list of addresses in ``CC'' is included in the message, while the ``BCC'' (blind carbon copy) addresses will be suppressed in the message keeping them anonymous. If you enter an address like ``#myfolder'', Mahogany will interpret it as the name of a mailfolder and save a copy of the message to that folder (in this case ``myfolder'').

The News Article Composition Window

This window is essentially identical to the mail composition window (1.6.4), but instead of specifying a mail address to send the message to, you can enter one or more newsgroups names (comma separated). The newsserver used depends on from where this window was opened, if it was opened while reading a specific newgroup, it will use the same newsserver that the newsgroup was read from, otherwise it will fall back to the setting in the global preferences.

Understanding program options

One of the goals of the Mahogany project is to be as configurable as possible. Of course, it means that Mahogany has a lot of options - however we hope that it doesn't make the program more difficult to use because you have the complete liberty to ignore all options until you need to use them. Moreover, some program options are completely transparent to the user because they are automatically remembered by the program. All the other ones may be changed from the main options dialog which may be invoked from the main window toolbar or from the menu. Generally, Mahogany configuration settings are inherited in a logical fashion. The settings in the preferences dialog are the global default settings and can be overridden on a per-folder basis. Subfolders inherit from their parent folders. Currently there is no full GUI support for this, but the next release will have the full set of program options available on the per-folder basis. Currently you can already achieve this by editing the configuration file manually. Also, system administrators can provide other defaults in a global /etc/Mahogany.conf file (also found in /usr/etc, /usr/local/etc, /opt/etc, ...).

Automatically remembered options

These options include the sizes and the positions of all windows, the texts of all prompts, the positions of splitters in the main program window and the other folder views as well as several other things. These options are special in that they do not appear in the options dialog and so can not be changed directly - instead Mahogany remembers them each time it is shut down, so when it is reopened it will be in exactly the same state as during the last run. Try to play with it: adjust the sizes of the main program window and the splitters in it as you like, exit Mahogany and restart it (this is for testing only, of course, you do not need to do it each time!) - you should see that the window reappears on the same position (although this might not work under some window managers), has the same size and is split in the same manner.

Other options

All other options except those mentioned in the previous subsection can be changed from the program options dialog. This dialog has several pages which are described in more details below:

Identity page

Here several important settings are configured, so it is advised (as the program itself will tell you when it is run for the first time) to set them up before starting using Mahogany. These include your personal identity settings - see also your preferred mail and news servers which is configured from the network page (1.7.2).

This page allows you to configure the network-related settings. Please notice that the four server names (for POP3, IMAP4, SMTP and NNTP) are only the default values and that Mahogany can use as many different servers (in particular, POP3 and NNTP) as you wish - for this, it is just enough to change the server name when creating a new folder from the default value specified here.


Compose Page

On this page you may configure different settings which control the behaviour of the message composer (it is also used when replying or forwarding mail messages, not only for composing the new ones).

Folders page

Python page

(only if you have a Python-enabled version of Mahogany)

Callbacks

Callbacks are python functions that can be called from different parts of Mahogany's code. See the Scripting and Extending chapter (2) and the Hacker's guide ([*]) for more information on this.

Message Viewer

Addressbook page

Mahogany may automatically remember all addresses from all e-mail messages you receive (actually, only those which you read). This is called address autocollection and, as almost any other feature of Mahogany can be turned on and off as desired. In this page you may choose whether you want to use this feature at all (it is on by default) and, if so, where should be the autocollected addresses be put and other settings. See the Addressbook section (1.8) for more information on Mahogany's built-in addressbook.

In addition to its own built-in addressbook format, Mahogany also supports the addressbook files of the BBDB addressbook used with Emacs (see 1.8.3). Some settings can be set here which apply only to the BBDB addressbook support:

Helpers

On this page you can customise which external helper applications Mahogany uses for different action that it does not perform itself.

Miscellaneous

All options which don't fit in any other pages are collected here.

Remote configuration synchronisation

Mahogany can automatically save a subset of its configuration settings in a mailbox at program exit and automatically retrieve that information the next time it is started up. This option becomes useful if you are using the program from different systems, e.g. if sometimes from the office and some other times from home over a dialup link. In this case, you can save some settings in a special IMAP folder and tell the program to use this for some of the settings. Like that, you can share the program settings no matter from where you run Mahogany and you do not need to manually adjust both configurations.

To use this option, first create a folder on an IMAP server. Do not use a POP3 server, as the program cannot store information via POP3, IMAP is required for this to work. Then, activate the ``Sync options with remote server'' setting and choose which settings you wish to share. Currently supported are:

Some Other Dialogs You May Encounter

Date Format

The dates of messages for the list of headers can be displayed in a format of your choice. The same format is used for inserting the current date in templates when writing messages. The format of the date is controlled by a list of format specifiers (as accepted by the strftime() function in the c-library). Most of the available format specifiers are available via a little popup menu which appears if you press the right-mouse button in the input field.

Display time in GMT/UST

If you tick this box, all times will be displayed in Greenwich Mean Time (= Universal Standard Time) rather than local time. If not checked, all dates and times will be displayed in your own timezone. Note that the time and date displayed is not the local time in the sender's timezone but the time it was in your local timezone when the message was sent.

Message Sorting Dialog

Here you can choose the criteria for sorting mailfolder listings. If you want to use message score as a sort criterium, you need to have a plugin module loaded which provides the ``Scoring'' interface. At time of writing no such plugin is available, it will appear soon, though.

Use Threading

If you tick this box, all messages will be threaded, i.e. sorted in hierarchical orders, with replies following earlier messages in the same discussion thread. Very useful for newsgroups. - Currently not yet implemented! -

Re-Sort on status change

The effect of this option feels a bit strange at first and you might not like it. If selected, the messages will be re-sorted each time the status of a message changes. If you sort messages by message status and delete a message, it will immediately drop to the bottom of the list. Useful to always maintain a strict sorting order, but can be confusing.

Mahogany Plugin Modules

Mahogany can load plugin modules at runtime to extend its functionality. Currently we are working on plugins to supply PGP/GPG encryption support and a scoring engine for sorting mailfolder listings. A plugin to use IBM's ViaVoice will be started work on as soon as the Debian/Linux ``Potato'' release becomes stable.

Generally, if you want to write an extension for Mahogany without using Python (which we hope to turn into a plugin, too, soon), you can do that very easily by writing it as a plugin module. Get in touch with the developers and we will show you how to do so.

The Plugin Module Configuration Dialog

This dialog allows you to decide which plugins get loaded at program start. At present, modules don't get loaded/unloaded at runtime, so you need to restart Mahogany for these options to take effect. On the top left you see a list of all modules that Mahogany has found in either the global modules directory or in your local directory ($HOME/.M/modules/). The window below shows some information about the module currently selected in the list, such as the name, author, a description of what it does and the name of the interface it provides. The interface would e.g. be ``Scoring'' for the plugin providing the functionality for scoring messages and is used by the program to find the right plugin for a given operation.

Any changes to the plugin module settings will only take effect after you re-started Mahogany!


The Address Database

Mahogany has a built-in address book system with flexible support for different addressbook formats. It can easily expanded to handle other programs' file formats and at present supports two formats, it's own ADB format (1.8.1) and (X)Emacs' BBDB (1.8.1) address book format. Generally the address books are ordered hierarchical, with the possibility to order entries in groups and sub-groups in a tree-like fashion. Alias expansion is configurable and also handles group names, to expand to the full list of email addresses within that given group.

The native Address Book

This is Mahogany's own address book format, offering you the maximum set of functionality supported by the address book editor. It offers hierarchical grouping of address entries and it also the default address book format used by the address auto-collection mechanisms, which uses different groups for address entries collected from different mail folders.

The Address Book Editor

To edit the address book, open the address book editor. If the book is already present in the address book tree on the left side of the window, you may expand it (and any subgroups it might have) and start editing immediately. If not, you must first add it to the tree by choosing ``New..'' from the ``Book'' submenu or using the corresponding toolbar button.

Generally speaking, there are several ways to perform the same action in the address book editor:

.
use the menus: the commands for creating and deleting address book entries are in the ``Edit'' menu, the corresponding commands for the address books - in ``Book'' one.
.
use the toolbar: this may be more convenient because, depending on the current position of the selected item in the tree it will propose to create either an address book or an entry.
.
use keyboard: <INSERT> key creates a new entry or address book if the current selection is the root of the tree, <DELETE> deletes an item and <Alt-ENTER> brings up the ``Properties'' dialog.
To edit the entry, simply select it in the tree. The data associated to it is spread over several notebook pages - select the one which contains the field you want to change and change it. If you want to undo your changes, simply press ``Cancel'' at any moment - however, this only works while you're editing the entry. As soon as you pass to another one, all previous changes are saved and cannot be undone any more. The changes are saved automatically when you select another entry or close the address book editor - there is no special ``Save'' button.

To quickly move in the address book tree you may use either the ``Find'' or ``Go to'' dialogs (both available in the ``Find'' menu). The first dialog allows you to find the entry by its contents while the second one allows you to quickly go to the entry (in thecurrent address book only) if you know its nickname. In the ``Find'' dialog you have several options to configure the search: it may be either case sensitive or not (should ``mike'' match ``Mike''?) and try to find only the whole string or just the substring of it (should ``mik'' match ``Mike''?). You may also choose among which fields should the search be done. You may choose as many fields as you like (possibly all of them) but you must choose at least one.

After you used the ``Find'' dialog once, you may choose the ``Find next'' menu item to go to the next address book entry matching your search criterium (notice that a message in the status bar will notify you about how many matches, if any, were found). Keep hitting ``Find next'' until the search wraps to the beginning (again, watch the status line for the message) or until you find the entry you're looking for.

You may import your existing address book file by choosing the ``Import book...''entry from the ``Book'' menu - this will open the address book import dialog proposing you to select the

Support for BBDB Address Books

Mahogany supports reading and writing of BBDB address book files. BBDB is the Big Brother DataBase used with the Emacs family of editors. If you have an existing address book file, usually called .bbdb, you can load it into Mahogany and use it. This is especially useful if you have an existing file with auto-collected email addresses that you want to continue to use.

Caution:

The BBDB address book format supports different fields than Mahogany's native database. When reading a BBDB file, Mahogany will only read the first two addresses and telephone numbers and assign them to the ``Home'' and ``Work'' addresses and phone numbers. All additional addresses and phone numbers, the AKA list and the comments will get lost. Mahogany will only save the information displayed in the address editor window. Currently saving of phone numbers to BBDB files is unsupported as it uses a different format from Mahogany. Therefore, reading a BBDB file and saving it back to disk may lead to a loss of information!

Support for Palm Address Books

Mahogany does currently support reading of Palm Addressbooks (referring to a ``Palm'' we mean the handheld organizer Palm Pilot running PalmOS). For being able to do that it is required to include the PalmOS-Module (see below). The support of Palm Addressbooks is not yet fully implemented, as so far it is only possible to download the addresses from the Palm and to display them. Changing and uploading changed/new addresses to the Palm is something we plan to add in the next release.

To display the Palm addressbook, create a new addressbook of type ``PalmOS''. You will be asked to put your Palm into the cradle and to push the HotSync-button. After the download the addressbook is accessible in read-only mode. Restarting Mahogany requires to download the addressbook again.


Scripting and Extending Mahogany

Python Scripting

Introduction

Mahogany has an embedded Python interpreter, if compiled with Python support enabled. Python is an object-oriented script language which can be used to write scripts to be executed by Mahogany or even to extend Mahogany's functionality. Python scripts have full access to all internal Mahogany data structures and objects.

A number of user definable callback functions are available. Scripts have access to most objects living in Mahogany. Scripting can be disabled in the Preferences dialog (see 1.7.2).

Currently the scripting support is quite basic. If you are interested in writing scripts and need additional callbacks or support for them within Mahogany, please get in touch with the developers who will be happy to add it.

Initialisation

At startup, Mahogany will load a file called Minit.py and call the Minit() function defined in there, without any arguments.

Callback Functions (Hooks)

There are a number of callbacks available which will be called from different places within Mahogany. These are defined in the header file Mcallbacks.h. The documentation of these callbacks can be found in the Classes documentation(Classes online docs). All of these callbacks are called with at least two arguments:

.
The name of the hook for which the function got called, e.g. FolderOpenHook
.
A pointer to the object from which it was called. E.g. for FolderOpenHook, this would be a pointer to a MailFolder object. This object does not carry a useable type with it and needs to be converted in the callback, e.g. if the argument is called arg and the object is a MailFolder, the object must either be used as MailFolder.MailFolder(arg) or be converted as mf = MailFolder.MailFolder(arg).
.
Some callbacks have a third argument. This is either a single value or a tuple holding several values.

Namespaces

To avoid repeatedly typing in the name of the module (MailFolder in this case), it can be imported into the global namespace with ``from MailFolder import *''. By default modules are not imported into the global namespace and must be explicitly named.

List of Callbacks



0 8 1 0 0 0 00 8 1 0 0 0 0Callback Name Object Type Additional Arguments/Types Return Value Documentation
FolderOpenHook MailFolder   void Called after a folder has been opened.
FolderUpdateHook MailFolder   void Called after a folder has been updated.
FolderSetMessageFlag MailFolder (long) index of message 1 if changing flags is ok,0 otherwise Called before changing flags for a message.
    (string)name of flag    
FolderClearMessageFlag MailFolder (long) index of message 1 if changing flags is ok,0 otherwise Called before changing flags for a message.
    (string) name of flag    
FolderExpungeHook MailFolder   1 to expunge, 0 to abort Called before expunging messages.
FolderNewMailHook MailFolder   1 to suppress default message, 0 else Called when new mail arrived in folder.
GlobalNewMailHook mApplication (string) sender of mail 1 to suppress default message, 0 else Called when new mail arrived anywhere.
    (string) subject of mail    



Supported Classes

Python has access to Mahogany's internal class hierarchy. At present we supply interface definitions and Python modules for only a small number of classes, however if there is need for more classes being supported, we can easily extend the list - please ask us if you want more support!

Some automatically generated documentation of the Python interface to Mahogany classes can be found in the doc/Python directory. Documentation about all classes, including those not available to Python, can be found in the doc/classes directory.

Plugins

Introduction

Starting with release 0.5, Mahogany allows the use of plugins (modules). This allows for an easy and comfortable way to enlarge Mahoganyīs functionality. These modules can be loaded at runtime and do not need to be part of the main executable. At the time of release 0.5 we are still linking them statically, but they can be loaded dynamically and future releases are likely to use this feature to keep the size of the main executable down.

The Filters Module

This module provides a filtering language for Mahogany. It allows you to have Mahogany look at different message properties, such as message contents, size or header lines and execute arbitrary action on them. The most common use would be to sort mails from different mailing lists in corresponding mailfolders, to reduce the number of messages in your main incoming mailbox. Filters can be specified in three possible ways:

The normal way to set up filters is to specify them in the filters dialog (2.2.2) and then tell Mahogany folder which of the filter rules to use for the individual folders with athe folder filters dialog (2.2.2).


The Filters Dialog

This dialog allows you to define any number of filter rules available to Mahogany. In a seaparate dialog (2.2.2) you can then pick any rule from the list and assign it to a folder. As you can have different sets of rules for each folder and might want to share rules for some folders, this dialog simply sets up rules and you can later specify for which folders to use them. When editing or adding a new filter rule, you will get to the following dialog:

The Filter-Rule Dialog

This dialog allows you to set up or edit an individual filtering rule, it contains of the following components:

You can add more pattern matching controls by pressing the [More] button, and you can delete the last pattern matching rule by pressing the [Less] button. The number of actions to execute is fixed to one.

You can use several condition and connect them via logical AND and OR, optionally negating them by ticking the [Not] box. The following conditions can be tested for at present:

The possible actions which can be performed, are:

If you are not using a Trash folder, it is a good idea to add a rule at the end of the list of filtering rules, that always expunges all messages. For testing filters, you can leave that rule disabled, an all messages will get treated and marked as deleted, but stay around. Only when expunge is executed, will they really disappear in the original mailbox. Notice, if you are using a Trash folder, this does not apply, as messages won't be marked as deleted but moved straight to Trash.


The Folder Filters dialog

This dialog allows you to assign filter rules to a folder. You can pick them from the set of existing filter rules (set up via the Filters Dialog (2.2.2)) and change the order of the rules. The listbox on the left lists the existing filtering rules for the currently selected folder in the order in which they are executed. You can use the buttons to change the order or rules. You can also activate/deactivate rules by clicking on the litte checkbox ([X] or [ ]) next to their name.

If you want to apply rules to all incoming messages and are collecting mail from different servers, simply apply the rules to the ``New Mail'' folder if you have one, alternatively you can set up rules for individual servers or INBOX.

The PalmOS Module

When 3Com released its first PalmPilots several years ago, many people did not believe in a success. But they were proven wrong, the Palm Pilot (or short: Palm) is today the most used handheld organizer.

For all the people possessing one of thoseīs little helpers, the PalmOS Module allows (or will allow) for an easy integration of the Palmīs data in Mahogany. In future releases there will be full support for addressbook synching, schedules etc. Currently you can only view the Palmīs addressbook (see above) and use Mahogany as your Palm desktop software.

Desktop functionality

As there is not really a common Palm desktop in the Unix/Linux environment (not like under MS Windows), we thought it a nice idea to include the desktop into Mahogany. Therefore Mahogany does allow to

To use this functionality, you must of course have the PalmOS module enabled. You can access the functions via the Plugin menu. In addition to the above mentioned tasks, you can specify quite a lot of options to adapt for instance the backup process to your personal needs.

There is an additional function not mentioned yet, labelled ``Synchronize''. Via the configuration dialog you can specify what should happen during synchronization - starting with mail exchange, backups and automatic installations. Read the following section about the configuration dialog to get see how you can customize your PalmOS-Module.

The configuration dialog

You can configure the PalmOS module via the Plugin menu in a lot of ways. Letīs go through every single item in the configuration dialog which you can access using the Plugin-Menu:

l
When you have this enabled, you can specify a mailbox which will be used as place of exchange for mails. Mails in this folder will be transfered to the Palm at the next hotsync and the outbox of the Palmīs mail program will be send. This mailbox is also used as a configuration setting for messages sent. Mahogany will use the properties of this mailbox when sending the messages retrieved from the Palm's Outbox. If you have enabled the ``advanced user'' option in the program preferences' identity tab, you can set up a separate return-address or completely different options for this mailbox and therefore have the mail sent from the PalmPilot with different settings as those sent normally. The options for user name and return address as set on the Palm are ignored when mails are sent with Mahogany.
e
Enter here the name of the mailbox that should be used for mail exchange when you have the ``Synchronise Mail'' feature enabled (see above).
e
This specifies what to do with outgoing e-mails retrieved from the PalmPilot and sent. You have three options:

p
Setting this checkbox to true will make a backup take place every time you ``Synchronize''.
s
This field does contain a valid directory path where the PalmOS-Module will store the backup of your Palmīs databases.
s
This checkbox determines whether you want files to be deleted on the PC that are residing in the backup directory but are not any longer on the Palm. This makes it possible to really keep the backup identical to the Palm, but has the disadvantage that you might loose data if you (accidently?) delete important data on the Palm and do a backup, as the backup-ed databases will be deleted too. So think carefully whether you do really want to do this.
y
Enable this checkbox if you only want to make an incremental backup. Using this features will speed the backup process up, as only changed or new databases are downloaded from the Palm.
s
Enabling this checkbox will make the PalmOS-Module ignore the backup flags of the databases. By default the PalmOS-Module does only backup files with a set backup flag. Use this option if you want all files to be backupīed.
s
Here you can specify a comma separated list of databases (without spaces!) that should not be backupīed.
l
Using this feature enables the auto-install feature and everytime you ``Synchronize'' the module will check the auto-install directory for Palm databases. If databases are found they will be installed and deleted without further notice!
y
Specify here a directory where the files to be auto-installed can be found.
Besides that, some general options are available:

e
Here you can specify the device where the Pilot is residing (this ought to be /dev/pilot under Unix/Linux and Com1: or Com2: under MS Windows (not yet supported)).
d
You have the choice beetween different hotsync speeds (``connection speed''), measured in baud.
e
You can force a lock of the above set device by enabling ``Try to lock device''

Accessing the Palms

There is the ``general'' approach to get the Palm databases on your computer and the more selective one. For the first one, just use the ``Synchronize'' menu point in the plugin menu. Depending on what you have enabled in the configuration dialog (see above), different actions will be taken (backup, mail exchange, ...).

If you only want to update your backup or to install a file or to restore your Palmīs contents, you can access these functions individually by using the corresponding menu points in the plugin menu.

Getting Help and Support

WWW Support

Mahogany has a home on the world wide web where you can get up to date information about development and the last releases. Come and visit us at the Mahogany Homepage

Mailing Lists

Several mailing lists exist to contact the developers, to receive updates of new releases and to exchange information and experiences with other users. Please visit the Mahogany Project Pagefor more information and to join the lists.

If you want to help further development of Mahogany, please go to the same place and you will find all the information you need about how to contribute or how to contact us.

Advanced Usage

Compiling Mahogany from source

For detailed information on how to compile Mahogany yourself and how to change it or get involved in its development, please refer to the Hackers' Guide, included either in the online docs or on the Mahogany Web page.

Some quick notes about common compilation problems can be found in the FAQ, in section 5.1.3.

Using Mahogany more efficiently

This section contains assorted tips about how you can make Mahogany run faster.

Speeding up Mahogany startup

Unix users only: Mahogany accesses the file /.M/CONFIG which stores all program options on startup. If this file is located on a slow partition such as a network disk (NFS), the startup time can be reduced just by moving it elsewhere and creating a link to it from /.M directory.

You can choose to not open any folders at startup (``Folders'' page of the options dialog) if doing this takes too long in your case. Also, remember to close the address book editor window if you don't want it to be reopened the next time you run Mahogany.


Limiting Amount of Data Transferred

When using a remote server, especially over a slow link (such as a modem), it may be undesirable to automatically retrieve all messages from the server. Mahogany provides several options to help you with limiting the amount of data transferred.

First, you should probably disable the ``Open folder at single click'' and ``Preview message when selected'' options from the ``Message View'' and ``Miscellaneous'' pages of the options dialog to avoid accidentally open a folder or a message.

Second, there are several useful settings in the ``Folders'' page. Note that they can be set for each folder separately so you can only choose to change the default values for some slow servers but keep the original values for all the other ones. These options allow you to specify a threshold for message size: before downloading a message of size bigger than the specified (in Kb), you will be asked for the confirmation. They also allow to set a similar threshold for the number of message headers retrieved: you will be asked before retrieving more than the specified number of headers (default is 100) from server. This limit is called ``soft limit'' and there is, of course, also a ``hard'' one which can be set in the same page. The hard limit, if set (it has value 0, i.e. disabled, by default) says that at most that many message headers will be downloaded. Unlike the soft limit, it is unconditional and no questions will be asked if it is exceeded.

The hard limit is mostly useful for ``write only'' folders, such as SentMail. Indeed, Mahogany accesses it very often (each time a message is sent) and it quickly grows big resulting in delays after message sending. Unconditionally limiting the number of messages retrieved from the server helps a lot in this situation.

FAQ - Frequently Asked Questions

Being a brand new program, this section is currently pretty empty. However, we will constantly update this chapter with questions received on the mailing lists.

Installation Problems

All Mahogany icons show a questionmark

I'm a linuxuser (redhat) who just found Mahogany and really likes it, but I have a problem, I cant get all the widgets to work, the pictures on the buttons and the ones before the mailboxes all appear as an questionmark. Do I need some library to make it look like your screenshot? If you would assist me in this matter I would be very grateful.

It depends how you installed it. If the icon with the questionmark appears, it means that Mahogany didn't find its installation directory with the icons. If you installed the linux version from the .tar.gz with the binary, it should go into /usr/local or a similar place and you should have the icons in /usr/local/share/M/icons. If they are not there, Mahogany cannot find them. If you have installed it in a different location, Mahogany should ask you for the installation ("global Mahogany directory") when you start it for the first time.

If you have compiled it yourself, make sure you do a "make install" or "make install_all" (of which parts might fail, depending on your setup), to install everything in the right place. If you just grabbed the binary of the daily snapshot, you need to have a working Mahogany installation as well or it won't get the icons. You do not need any additional library, Mahogany handles xpm files internally.

How do I unpack the compressed files?

The distribution files for Solaris and some of the other ones, are in compressed tar format, having the ending .tar.gz . To unpack them, you need gzip and tar. Change to the directory where you want to install Mahogany, e.g to /usr or /opt or /usr/local and issue the following command:

gzip -dc < thedistributionfile | tar xvof -
Where thedistributionfile is the complete path to the file you downloaded. You will need to have proper write access to the directory where you install it and tar should show you a list of all files being installed as it unpacks them.

Compiling aborts with errors

A common problem with compiling wxGTK and Mahogany is, that you need to follow the instructions in Mahogany's README file and use the configure script to set them up as explained. If you use different arguments for configure than those shown in README, things will not work! Also, before running configure again, remove any *.cache and *status files in the working directory or configure will re-use some old settings.

Also, as we are omitting some unused subdirectories from the wxGTK source, to save you download time, you may need to run ``make -k'' rather than just ``make'' to get it to ignore some errors caused by this. On non-Linux/GNU systems, you need to use the GNU linker, i.e. ``gmake'' rather than the default ``make''.

make fails

If Mahogany's own make process fails after configuring it, this is likely caused by the ``make depend'' stage. Simply run ``make -i depend'' from the toplevel (mahogany-0.50) directory and it will run through, ignoring all errors. After that, a normal ``make'' will succeed.

How can I get it to compile on Caldera Linux?

You will need to install a libcrypt library with a working crypt() function. The source for one such library can be found on the Mahogany ftp server.

Mahogany fails to find wxWindows, Configure fails

The following steps should identify and solve the problem:

.
Do a "make install" for wxWindows and watch the output, it should copy lots of things to /usr/local/....
.
Do a "which wx-config", it should report wx-config to be in /usr/local/bin
.
Just type "wx-config -cflags", it should run the wx-config script and report the compiler flags, which should include something like "-I/usr/local/include".
.
Then go to the Mahogany directory and "rm *cache*" to remove old configuration info and run ./configure
.
This *should* find wx/wx.h if all of the above worked, if not, look at the end of config.log to see what went wrong.
.
If it does not find the wxWindows library, you need to add /usr/local/lib to either your LD_LIBRARY_PATH or to /etc/ld.conf (and run ldconfig as root), then remove *cache* and try again. Again, if something fails, look at config.log.

Other Problems / Questions

The Preferences Dialog does not show up properly

When I set up Mahogany or select the preferences dialog, its contents do not appear. Sometimes I cannot enter anything in the fields.

wxGTK has a problem with constraint handling which can cause this dialog to sometimes get into an endless loop trying to do the layout. On most windowmanagers it helps if you resize the dialog a little and it will appear correctly. This seems to depend on the platform and windowmanager. Also, wxGTK does not seem to work correctly with OpenLook which does not allow you to enter anything.

How to use Mahogany with fetchpop/procmail?

I use fetchpop and procmail do deliver my mail (Redhat Linux). I'm reading mail with Netscape right now and I want to move to M. I cannot for the life of me get M to open my files when it loads. I have to open them manually. Can someone please help me (if its possible) to get M to open all of my Linux Folders at startup.

You should be able to right-click on the folder treecontrol on the left of the main screen and "Create a new folder". Make it of type "file" and specify the path to the the folder file as the filename. Your normal mailspool /var/spool/mail/username is available under the name INBOX anyway, but I guess you have fetchpop/procmail deliver your mail to some other place.

Mahogany cannot create some files when run as root

Mahogany will not work properly when executed by the root super-user. The underlying mail handling library used in Mahogany will change to some other user id for security reasons and therefore the program will not be able to create some files needed. For security reasons it is a bad idea anyway to run any X11 application as root.

Does Mahogany have group aliases?

Mahogany supports alias expansion for individual entries and for groups. There are two ways in which you can expand an alias to a group of addresses:

How can I set up my POP3 access (applies to IMAP, too)?

It is not immediately apparent how to set up my POP3 server under 0.23a , can someone give me a hand, please? It appears there is no section in the initial configuration utility for this.

Mahogany allows you to have as many folders or mail accounts as you like. That's why it doesn't ask you at the beginning. To add a POP account:

.
right click on the folder tree and choose "Create Folder"
.
give the folder a name, set its type to POP and fill in the required fields, such as server and login
.
Click on [OK]. The folder will now appear in the tree
.
Double-click on the folder to open it.

How can I set up IMAP access?

Follow the rules for setting up POP3 access5.2.5 but set the folder type to be ``IMAP folder''. Then enter the name of your IMAP server, your username and password (or leave it empty to be asked later) for that server and, optionally, the path to the folder on the IMAP server. You can leave the path empty, and it will use the default folder (INBOX).

If you want to access many IMAP folders on the same server, or a directory there, you can create foldertree entries representing the IMAP server itself (i.e. the top-level directory on it) or a directory on the IMAP server. For these, if not using the Wizard dialog, make sure that the folder properties dialog has the ``is directory'' checkbox ticked, which tells Mahogany that it is not a mailbox file to open, but a directory which can be browsed for entries via the popup menu.

Can I have multiple POP or IMAP accounts?

Can I access multiple different POP3 or IMAP accounts?

Yes, Mahogany allows you to have any number of different folders configured. Just right-click on the folder tree control and choose the ``Create Folder...'' option from the popup-menu. You can then switch between the different folders by selecting them (usually with a double-click on the tree control) for display in the main window, or, by selecting ``Open'' from the popup-menu which will open the folders in their own individual windows.

You can also select the ``Collect all mail from this folder'' option when creating the entries for them (or later, via the ``Preferences'' popup-menu option) to let Mahogany automatically check these accounts for new mail and collect it from there.

Can I have multiple identities?

Does Mahogany allow me to send email as different people? That is, if I monitor two IMAP or POP servers, one for my work email, and one for my home email, can I reply to emails and specify it to use my home or work email address as the sender?

Yes, you can set almost *all* options on a per-folder basis, including your name or return address, even outgoing SMTP servers to make it perfect. To have full access to all these configuration options in the folder properties dialog, you must first set your user level to ``advanced'' in the main configuration dialog, otherwise only a small subset of configuration options is available.

Can I run Mahogany as root?

Very simple question: can I run Mahogany on a unix system as the superuser (root)?

Not directly. There are two problems with it:

.
It is not a good idea for security reasons. In fact, you should not even run X11 as root. Though, we would not dare to impose that on you, if you want to, that is your problem.
.
The technical reason, and this is why Mahogany does not allow it: The c-client library that we use for accessing mail folders and servers uses the user-Id 0 (root) internally and does not work when called as root. When inquiring why this is so, c-client's author told us that it was bad to read mail as root - he thinks he knows what is good for you. Unless we find an easy way to circumvent that problem, you will not be able to run Mahogany as root as we have no time and desire to re-write the c-client library just for this.
There is a workaround however:

You can forward your email to another user, say ``user1'', by creating a /root/.forward file containing that user's name. Then, run Mahogany through the ``su'' command: ``su user1 -c mahogany''. This will work just fine. If you get an error message about it being unable to access your X11 display, do a ``xhost localhost'' before, which will allow all local users to access your display. All this is not very safe from a security point of view if you don't trust your local machine, but perfectly fine for standalone or dialup boxes.

How can I set which language to use?

Under Unix: simply set and export your LANG environment variable like for any other program, too. Under Windows: the environment variable LANG will be recognised if it is set, but in addition Mahogany will automatically detect which language your system is set to use.

How can I delete messages?

If I press 'D' or use the menu to delete messages, they get marked as deleted but never disappear. How can I delete them?

Simple, press '#' or 'x' or select Message/Expunge from the menu. Mahogany will also ask you if you want to expunge them when closing the folder. If you use the Trash folder, this only applies to that one as all other folders will move messages straight to Trash instead of marking them deleted.


Footnotes

... LGPL1.1
which we recently felt victim of - due to some strong demand, we have decided to allow alternatively licensing Mahogany under GPL



2001-03-23