kbiff/doc/en/index.docbook

<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd" [
 <!ENTITY kbiff "<application>kbiff</application>">
]>

<book id="kbiff" lang="en">
<bookinfo>
<title>The KBiff Handbook</title>
<authorgroup>
<author>
<firstname>Kurt</firstname>
<surname>Granroth</surname>
<affiliation>
<address><email>granroth@kde.org</email></address>
</affiliation>
</author>
</authorgroup>
<date></date>
<releaseinfo></releaseinfo>
<abstract>
<para>KBiff is a KDE aware mail notification utility. It supports MBOX (Unix
 style), Maildir (Qmail), MH, POP3(S), IMAP4(S), and NNTP mailboxes.</para>
</abstract>
<keywordset>
<keyword>KDE</keyword>
<keyword>KBiff</keyword>
<keyword>mailboxes</keyword>
<keyword>incoming mail</keyword>
</keywordset>
</bookinfo>

<chapter id="introduction">
<title>Introduction</title>

<sect1 id="features">
<title>Features</title>

<para>KBiff is a mail notification utility for the KDE project. It has several
advantages over much of its competition:
<itemizedlist>
<listitem>
<para><emphasis>Pure GUI configuration</emphasis>. No more command line parameters to remember (well,
one optional one to make things easier for some people) or strange config files.
All settings for KBiff can be done from one setup dialog.</para>
</listitem>
<listitem>
<para><emphasis>Session Management</emphasis>. KBiff starts up with the same configuration you left
it with.</para>
</listitem>
<listitem>
<para><emphasis>Panel Docking</emphasis>. KBiff can be docked into the panel very easily. Handy when
you are monitoring several mailboxes and don't have room anywhere else.</para>
</listitem>
<listitem>
<para><emphasis>Animated GIFs</emphasis>. You can use animated GIFs as your icons.</para>
</listitem>
<listitem>
<para><emphasis>Sounds</emphasis>. KBiff has an option to play .wav files when new mail arrives.</para>
</listitem>
<listitem>
<para><emphasis>POP3(+SSL), IMAP4(+SSL), NNTP, Maildir, MBOX, MH</emphasis>. KBiff supports all major mailbox formats!</para>
</listitem>
<listitem>
<para><emphasis>Multiple Mailbox</emphasis>. KBiff can monitor several mailboxes with one instance.</para>
</listitem>
<listitem>
<para><emphasis>Secure Authentication</emphasis>.  KBiff can authenticate using APOP or CRAM-MD5 if the POP3 or IMAP4 server supports it.
</para>
</listitem>
<listitem>
<para><emphasis>Others</emphasis>. KBiff has scads of other options.</para>
</listitem>
</itemizedlist>
</para>

<para>Kurt Granroth</para>

<para><ulink url="mailto:granroth@kde.org">&lt;granroth@kde.org&gt;</ulink></para>
</sect1>
</chapter>

<chapter id="installation">
<title>Installation</title>

<sect1 id="howtoobtainkbiff">
<title>How to obtain KBiff</title>

<para>The most current release version in both source and binary formats can
always be found at the KBiff homepage. This is at 
<ulink url="http://kbiff.granroth.org">http://kbiff.granroth.org</ulink></para>
</sect1>

<sect1 id="requirements">
<title>Requirements</title>

<para>In order to successfully compile KBiff, you need at least the 2.0 version
of KDE. All required libraries can be found starting at the 
<ulink url="http://www.kde.org">KDE</ulink> website.</para>

<para>A note on the minimum KDE version: while KBiff should compile
with KDE2, this hasn't been verified or tested in years.  The
effective minimum version is KDE3.</para>
</sect1>

<sect1 id="compilationandinstallation">
<title>Compilation and Installation</title>

<para>Compiling KBiff is very easy. The following should do it:
<programlisting>&percnt; ./configure
&percnt; make
&percnt; make install</programlisting>
</para>

<para>That should do it! Should you run into any problems, please report them
to the <ulink url="mailto:granroth@kde.org">author</ulink></para>
</sect1>
</chapter>

<chapter id="usingkbiff">
<title>Using KBiff</title>

<para>Almost every feature of KBiff can be configured from the Setup dialog.
What few command line parameters KBiff has are mostly for convenience -- some
options just make more sense on the command line.</para>

<sect1 id="theprofile">
<title>The "profile"</title>

<para>KBiff revolves around something called a "profile" A profile is simply
a container for one or mailboxes that KBiff will monitor. For instance, there
will always be one default profile called "Inbox" (or something else if you
rename it). This profile will contain one mailbox, usually something like "/var/mail/username".
It could just as well hold several mailboxes, though. Each instance of KBiff
(that is, each visible icon) corresponds to one profile.</para>
</sect1>

<sect1 id="commandlineparameters">
<title>Command Line Parameters</title>

<para>KBiff supports three command line parameters. They are: <emphasis>profile</emphasis>, <emphasis>debug</emphasis>,
and <emphasis>secure</emphasis>.
<programlisting>-profile &lt;profile_name&gt; Bypass the Setup dialog and start KBiff directly in the 
                        given profile. e.g., 'kbiff -profile Inbox'
-debug                  Turns on verbose debugging. Use this only if you are
                        having problems with KBiff
-secure                 Disables the setup dialog. Useful when you want KBiff
                        displayed but don't want others to modify it.</programlisting>
</para>
</sect1>
</chapter>

<chapter id="thesetupdialog">
<title>The Setup Dialog</title>

<para>The setup dialog handles all configuration items for KBiff. As a result,
there is no need for command line parameters in nearly all cases.</para>

<sect1 id="profilename">
<title>Profile Name</title>

<para>The top part of the dialog consists of a drop down list and three buttons.
The drop down list contains the names of all the "profiles." A profile is a
set of configuration settings for one mailbox under one name. The three
buttons are New, Rename, and Delete. The buttons work on the profiles,
only. They do not touch the actual mailbox files. When KBiff is started for
the first time, there will be one profile automatically created. This is
the Inbox profile which monitors the system mailbox.</para>
</sect1>

<sect1 id="preferencetabs">
<title>Preference Tabs</title>

<para>There are four preference tabs. These are full of options that apply to the
current profile. The current profile is the one that is currently displayed
in the drop down list. There are no global settings.</para>

<sect2 id="generalpreferences">
<title>General Preferences</title>

<para>The general preferences for each profile are contained in this tab. There
are five fields here:</para>

<sect3 id="poll">
<title>Poll</title>

<para>This setting controls how much time KBiff will wait until it checks the
mailbox again. The time is in seconds. The default is 60 seconds (one
minute).</para>

<para>To choose a time other than the default, here, it is a good idea to analyze
the frequency in which your mail arrives. If, for instance, you have
<literal>fetchmail</literal> downloading new mail every 5 minutes, then it doesn't make sense
to set the time for less than that. On the other hand, if you are using the
POP3 or IMAP4 feature of KBiff, you should probably use a higher interval. Setting
it less than 60 might give you unexpected results if your network
connection isn't very fast.</para>
</sect3>

<sect3 id="mailclient">
<title>Mail client</title>

<para>This field specifies what command will run when KBiff is left-clicked.
While this is typically a mail client, it does not have to be. It can be
any command that can be run with its own X window. In other words, putting
<literal>elm</literal> in this field will not work. Putting <literal>konsole -e elm</literal> would.
The default is <literal>kmail -check</literal></para>
</sect3>

<sect3 id="dockinpanel">
<title>Dock in panel</title>

<para>This controls whether or not KBiff will start docked into the panel or not
when the user exits the setup dialog. Note that it is still possible to
switch between docked and undocked regardless of this option. This only
controls the initial state. This is checked by default.</para>
</sect3>

<sect3 id="enablesessionmanagement">
<title>Enable session management</title>

<para>This controls whether or not KDE session management is enabled. This should
be turned off only in rare cases. The most common case where session
management is disabled is when a user is running KDE under the same account
on several different computers at the same time. In this case, it would
probably be desirable to turn off session management and use the <literal>-profile</literal>
command line option instead.</para>

<para>In all other cases, session management should probably be left on.</para>
</sect3>

<sect3 id="icons">
<title>Icons</title>

<para>KBiff uses three icons to represent the three states: No Mail, Old Mail,
and New Mail. The icons shown are the "large" icons. To select new ones,
click on the buttons and a icon loader dialog will pop up. Note that even
though KBiff supports animated GIFs, they will not appear animated here.</para>
</sect3>
</sect2>

<sect2 id="newmailpreferences">
<title>New Mail Preferences</title>

<para>This tab groups together the options that control what happen when new mail
arrives.</para>

<sect3 id="runcommand">
<title>Run Command</title>

<para>This is a shell command that will be executed when new mail arrives. A
typical example of this would be play newmail.au. This would cause the file
newmail.au to be played whenever new mail arrives. By default, this is
turned off.</para>
</sect3>

<sect3 id="playsound">
<title>Play Sound</title>

<para>This specifies a sound to play when new mail arrives. As of this version,
it will only play .wav files. Simply specify the path to the file to have
it played. By default, this is turned off.</para>
</sect3>

<sect3 id="systembeep">
<title>System Beep</title>

<para>Enabling this will cause KBiff to beep whenever new mail arrives. This is
probably the least intrusive, yet still active, method of alerting the user
that new mail as arrived. By default, this is on.</para>
</sect3>

<sect3 id="notify">
<title>Notify</title>

<para>Enabling this will cause KBiff to popup a window when new mail arrives. The
"notify" message box will list both the mailbox in question and the number of
new mails.  This option is not recommended on mailboxes that receive lots of
mail.</para>
</sect3>

<sect3 id="floatingstatus">
<title>Floating Status</title>

<para>If this is enabled, KBiff will popup a small box listing all mailboxes
with their newmail count whenever you the mouse is over the icon (after
a one second delay).  The effect is similar to that of a tooltip... only
better.  This isn't technically a new mail feature... but it doesn't fit
easily anywhere else!</para>
</sect3>
</sect2>

<sect2 id="mailboxpreferences">
<title>Mailbox Preferences</title>

<para>This groups together the options controlling the physical mailboxs themself.</para>

<para>All options on this tab are PER mailbox.  So if you have three mailboxes in
this profile, each mailbox will have its own settings on this tab.  However,
all settings in the other tabs apply profile-wide.  This means that if you
have the Notify option checking the the New Mail tab, then KBiff will notify
you that new mail has arrived in all of the mailboxes in this profile.</para>

<sect3 id="mailboxlist">
<title>Mailbox list</title>

<para>The listbox on the left of the tab contains the list of mailboxes that the
current profile will monitor. In most cases, there will be only one (the
"Default" mailbox).  However, you may have as many mailboxes per profile as
you wish.</para>

<para>There are two buttons below the mailbox list.  The button with the mailbox on
it will create a new mailbox.  The button with the cross will delete a
mailbox.  If you wish to rename a mailbox, you must delete the old one and
create a new one with identical properties.</para>
</sect3>

<sect3 id="protocol">
<title>Protocol</title>

<para>This determines the protocol for the currently selected mailbox. There are 4
(and a half) protocols - mbox (Unix style), maildir (Qmail), POP3, and IMAP4.
The 'file' protocol can be used to monitor any local file as it uses only
the last read and last modified times to determine the state.</para>
</sect3>

<sect3 id="mailbox">
<title>Mailbox</title>

<para>This field will not be active with the POP3 protocol.  In all other cases, put
the path to your mailbox here. In the case of mbox, this will be a file.  With
maildir, this will be a directory.  It is a folder with IMAP4 (almost
always called 'INBOX' or 'inbox' for your main mail folder).</para>
</sect3>

<sect3 id="server">
<title>Server</title>

<para>This is active only for the IMAP4 and POP3 protocols.</para>
</sect3>

<sect3 id="user">
<title>User</title>

<para>This is active only for the IMAP4 and POP3 protocols.</para>

</sect3>

<sect3 id="password">
<title>Password</title>

<para>This is active only for the IMAP4 and POP3 protocols.</para>

</sect3>

<sect3 id="storepassword">
<title>Store Password</title>

<para>This will save the password between sessions.</para>

<para>KBiff does not encrypt the password when it is saved! It will scramble it a
little, but anybody with the source code (or a little patience) could
unscramble it in an instant. If you are on an insecure network, it is
strongly recommended that the store password option be turned off</para>
</sect3>

<sect3 id="advanced">
<title>Advanced</title>

<para>This will popup a dialog containing advanced features.</para>

<sect4 id="mailboxurl">
<title>Mailbox URL</title>

<para>KBiff handles mailboxes internally as a URL. If you know what you are doing,
you can directly modify the URL here.  Modifying this is discouraged unless
you are familiar with the code,</para>
</sect4>

<sect4 id="port">
<title>Port</title>

<para>Set this to whatever port your server is at.  By default, it will be 110 for
POP3 and 143 for IMAP4</para>
</sect4>

<sect4 id="preauth">
<title>PREAUTH</title>

<para>If you don't know what this means, you probably don't need to use it.
Basically, it will start checking for new mail in IMAP4 without logging in.</para>
</sect4>

<sect4 id="keepalive">
<title>Keep Alive</title>

<para>When checked in POP3 or IMAP4 mode, this will keep the connection "alive".
That is, KBiff will login once and stay logged in. This is not recommended if
your POP3 or IMAP4 server uses locks.  If locks are in place and KBiff does
not log out then your mail client will not be able to access your account.</para>
</sect4>
</sect3>
</sect2>

<sect2 id="about">
<title>About</title>

<para>This tab has information about KBiff.</para>

<sect3 id="aboutkbiff">
<title>About KBiff</title>

<para>This contains information about which version of KBiff is being used. It
also has contact information about the author.</para>

<para>Note that the email address is a hyperlink. Clicking on it is supposed to
pop up your mail client in order to send mail to the author. Unfortunately,
there is no automated way of doing this in KBiff at the present time. There
is some code here, though. To send email using this hyperlink, KBiff looks
for the environment variable <literal>MAILER</literal>. If it finds it, it will use the
contents of this variable as the email program to use.</para>

<para>For example, if <literal>MAILER</literal> is set like so:
<literal>  % setenv MAILER "konsole -e mutt"</literal>
then KBiff will use <literal>konsole -e mutt</literal> as the default mail client, here.</para>
</sect3>
</sect2>
</sect1>
</chapter>

<chapter id="thepopupmenu">
<title>The Popup Menu</title>

<para>The popup menu is activated whenever the right mouse button is clicked
in the KBiff icon area.</para>

<sect1 id="undock">
<title>(Un)Dock</title>

<para>This docks or undocks KBiff from the panel. This option will only work
in KDE complient window managers like KWin. The default state is determined
by the setup dialog.</para>
</sect1>

<sect1 id="setup">
<title>Setup</title>

<para>This will activate the setup dialog. See the Setup Dialog section for more details.</para>
</sect1>

<sect1 id="help">
<title>Help</title>

<para>This activates the online help (this).</para>
</sect1>

<sect1 id="checkmailnow">
<title>Check Mail Now</title>

<para>This forces KBiff to check for new mail right now, regardless of the poll
time. This will check all mailboxes in a profile.</para>
</sect1>

<sect1 id="readmailnow">
<title>Read Mail Now</title>

<para>This will force KBiff to act like all mailboxes in the current profile
are "old." This makes most sense when you have new mail on a remote server
(pop3 or imap4) and don't feel like downloading it right then.</para>
</sect1>

<sect1 id="stopstart">
<title>Stop/Start</title>

<para>This will either stop or start KBiff.</para>
</sect1>
</chapter>

<chapter id="questionsanswersandtips">
<title>Questions, Answers, and Tips</title>

<sect1 id="arethereotherkde-awarebiffutilities">
<title>Are there other KDE-aware "biff" utilities?</title>

<para>Yes. There are at least three that I know of. Each "biff" has its own strengths.
<emphasis>KOrn</emphasis> was the original. It's main strength is the ability to monitor multiple
mailboxes with one instance and effectively show the number of messages in
each. If you have many mailboxes and don't care for the cutesy icons, then
KOrn is probably a better choice than KBiff. Another "biff" is <emphasis>KNewMail</emphasis>.
KNewMail attempts to emulate the Windows utility NewMail. It checks for POP3
mail and displays the subject line for each message.  I don't know if
this is still an viable project, though, since it doesn't look like
it's been updated since 2003.

The final (and most common) mail monitor is the one that ships with
KMail.  Its major advantages are all related to the fact that it's
integrated with KMail itself.  KBiff is more flexible, though, and
works with mailers other than KMail.</para>
</sect1>

<sect1 id="whatisthedifferencebetweenaprofileandamailbo">
<title>What is the difference between a "profile" and a "mailbox" again?</title>

<para>A "profile" is a group of one or more mailboxes that one instance of
KBiff will monitor. And example of a profile is "Inbox". A "mailbox" is
a physical entity that can be monitored by KBiff. An example of a mailbox is
"/var/mail/username".</para>
</sect1>

<sect1 id="howdoiusemyownpixmaps">
<title>How do I use my own pixmaps?</title>

<para>Short answer: select them using the setup dialog.
Longer answer: KBiff
searches for its icons in the standard KDE icon path. Currently, this is
<programlisting>tdedir()/share/apps/kbiff/toolbar
tdedir()/share/toolbar
tdedir()/share/icons
tdedir()/share/apps/kbiff/pics
&dollar;HOME/.kde/share/apps/kbiff/toolbar
&dollar;HOME/.kde/share/toolbar
&dollar;HOME/.kde/share/icons
&dollar;HOME/.kde/share/apps/kbiff/pics</programlisting>
</para>

<para>Where "tdedir()" is usally "/opt/kde" and &dollar;HOME is your home
directory. If you put your pixmaps in any of these directories (the last one
listed is recommended), then KBiff should have no problems finding and using
them.</para>

<para>If you plan on docking KBiff, you should have a 22x22 (or smaller) version
of your pixmap. The name of the small pixmap should be the name of the larger
pixmap preceded by "mini-". So if you want to use the default "oldmail.xpm"
pixmap for old mail but want to use your own "mycoolpixmap.xpm" smaller pixmap
when it's docked, you should rename your pixmap to "mini-oldmail.xpm" If
you do not do this, KBiff will use the large version even in the panel.</para>

<para>Note that KBiff determines its size by the old mail pixmap. So if your
pixmap for old mail is 100x100, but all the other ones are 32x32... well, KBiff
will look very strange every time new mail arrives.</para>
</sect1>

<sect1 id="howdoiuseelmormuttorpinewithkbiff">
<title>How do I use elm (or mutt or PINE) with KBiff?</title>

<para>You tried putting "elm" into the Mail Client edit box, didn't you? Whoops!
'elm', 'mutt', and 'PINE' all need a terminal to run in and KBiff does not
supply one. The author used to use the following as his Mail Client: 
<literal>konsole -caption Mail -e mutt &amp;</literal></para>

<para>If you use a graphical email client such as KMail or Thunderbird, then you
simply need to put the name of the client in the edit box. No terminal is necessary.</para>
</sect1>

<sect1 id="whywontkbiffplaymynewmailaufile">
<title>Why won't KBiff play my newmail.au file?</title>

<para>KBiff uses the KAudio class to play sounds when new mail arrives. Currently,
this class only supports .wav files. If you wish to play an .au file when new
mail arrives, try getting the SOX package and put 'play newmail.au' (or just
'cat newmail.au &gt; /dev/audio') in the Run Command option.</para>
</sect1>

<sect1 id="doeskbiffworkwithoutsessionmanagement">
<title>Does KBiff work without session management?</title>

<para>Yes. Session management is on by default, but you can turn it off in the
setup dialog. You can still have KBiff start up when KDE starts up by putting
KBiff into your Autostart folder with the '-profile' option.</para>
</sect1>

<sect1 id="clickingonyouremailaddressinaboutdoesnothing">
<title>Clicking on your email address in About does nothing!</title>

<para>It would be nice to pass the 'mailto:granroth@kde.org' URL to kfm to process
it.. unfortunately, this is not implemented yet. I did code in some support,
though. Just set an environment variable MAILER to whatever your mailer is
and the link should work.
<programlisting>e.g.
&percnt; setenv MAILER konsole -e mutt</programlisting>
</para>

<para>Note that this has the pleasant side effect that 'mailto:' links in the
regular kfm will also use your mailer.</para>
</sect1>

<sect1 id="wheniusekbifftomonitormymailboxallotherbiffu">
<title>When I use KBiff to monitor my mailbox, all other 'biff' utilities stop
 working. What's up?</title>

<para>This is a result of the new message counting code in KBiff. In order for
KBiff to know how many new messages are in an mbox mailbox, it must open it
up to read it. When this happens, most other 'biff' utilities (including your
shell's built-in one) will assume that you read your mailbox and announce it
as old (or "read") mail.</para>

<para>There are three ways around this:
<orderedlist><listitem>
<para>Don't use KBiff.</para>
</listitem>
<listitem>
<para>Use the 'file' protocol instead of the 'mbox' protocol (note that you'll
no longer know how many new mails have arrived)</para>
</listitem>
<listitem>
<para>Convert all of your 'mbox' mailboxes to 'maildir'</para>
</listitem>
</orderedlist>
</para>
</sect1>

<sect1 id="howdoiusenetscapemailwithkbiff">
<title>How do I use Netscape Mail with KBiff?</title>

<para>You tried 'netscape -mail', didn't you? You then discovered that this caused
Netscape to complain about a lockfile if it was already running, right? Well,
here's a workaround from KBiff user Steven Boger 
<ulink url="mailto:sboger@marcus-online.net">(sboger@marcus-online.net)</ulink>
Create a shell script like so:
<literal>&num;!/bin/sh</literal>
<programlisting>if &lsqb; -L "&dollar;HOME/.netscape/lock" &rsqb;; 
then 
netscape -remote 'xfeDoCommand(openInbox)' 
else 
netscape -mail &amp; 
fi</programlisting>
</para>
</sect1>

<sect1 id="kbifftruncatestheinitialslashinimapmodeisthi">
<title>KBiff truncates the initial slash in IMAP mode.  Is this a bug?</title>

<para>No, it's a feature!  It is very very rare that one uses an absolute path
with IMAP.  Nearly all mailbox can (and are) accessed either relative to
the user's home directory or use symbolic names like 'inbox.</para>

<para>If you are trying to read <literal>/var/spool/mail/username</literal> try entering
<literal>inbox</literal> as the mailbox name.</para>
</sect1>

<sect1 id="ihavethisgreatfeatureiwantimplementedwhatsho">
<title>I have this great feature I want implemented.  What should I do?</title>

<para>Unfortunately, the answer is likely "write it yourself".  KBiff
is maintained in only a minimal sense.  Patches are applied and it's
updated enough to compile with the latest KDE, but I will be adding
very few features in the future and likely none that are just
suggestions.  Nearly all patches are accepted, though.
</para>
</sect1>
</chapter>
</book>