diff options
Diffstat (limited to 'doc/en/index.docbook')
| -rw-r--r-- | doc/en/index.docbook | 651 |
1 files changed, 651 insertions, 0 deletions
diff --git a/doc/en/index.docbook b/doc/en/index.docbook new file mode 100644 index 0000000..c6ac889 --- /dev/null +++ b/doc/en/index.docbook @@ -0,0 +1,651 @@ +<?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>[email protected]</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:[email protected]"><[email protected]></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>% ./configure +% make +% make install</programlisting> +</para> + +<para>That should do it! Should you run into any problems, please report them +to the <ulink url="mailto:[email protected]">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 <profile_name> 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 +$HOME/.kde/share/apps/kbiff/toolbar +$HOME/.kde/share/toolbar +$HOME/.kde/share/icons +$HOME/.kde/share/apps/kbiff/pics</programlisting> +</para> + +<para>Where "tdedir()" is usally "/opt/kde" and $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 &</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 > /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:[email protected]' 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. +% 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:[email protected]">([email protected])</ulink> +Create a shell script like so: +<literal>#!/bin/sh</literal> +<programlisting>if [ -L "$HOME/.netscape/lock" ]; +then +netscape -remote 'xfeDoCommand(openInbox)' +else +netscape -mail & +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> |