From 3b4b5a1fad7ffa13a3c41162eadb51b01915014d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sl=C3=A1vek=20Banko?= Date: Thu, 22 Jul 2021 11:21:34 +0200 Subject: Use common rules for build and install documentation and translations. Simplify the structure of the documentation directories. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Slávek Banko --- doc/en/index.docbook | 651 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 651 insertions(+) create mode 100644 doc/en/index.docbook (limited to 'doc/en/index.docbook') 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 @@ + +kbiff"> +]> + + + +The KBiff Handbook + + +Kurt +Granroth + +
granroth@kde.org
+ + + + + + +KBiff is a KDE aware mail notification utility. It supports MBOX (Unix + style), Maildir (Qmail), MH, POP3(S), IMAP4(S), and NNTP mailboxes. + + +KDE +KBiff +mailboxes +incoming mail + + + + +Introduction + + +Features + +KBiff is a mail notification utility for the KDE project. It has several +advantages over much of its competition: + + +Pure GUI configuration. 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. + + +Session Management. KBiff starts up with the same configuration you left +it with. + + +Panel Docking. KBiff can be docked into the panel very easily. Handy when +you are monitoring several mailboxes and don't have room anywhere else. + + +Animated GIFs. You can use animated GIFs as your icons. + + +Sounds. KBiff has an option to play .wav files when new mail arrives. + + +POP3(+SSL), IMAP4(+SSL), NNTP, Maildir, MBOX, MH. KBiff supports all major mailbox formats! + + +Multiple Mailbox. KBiff can monitor several mailboxes with one instance. + + +Secure Authentication. KBiff can authenticate using APOP or CRAM-MD5 if the POP3 or IMAP4 server supports it. + + + +Others. KBiff has scads of other options. + + + + +Kurt Granroth + +<granroth@kde.org> + + + + +Installation + + +How to obtain KBiff + +The most current release version in both source and binary formats can +always be found at the KBiff homepage. This is at +http://kbiff.granroth.org + + + +Requirements + +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 +KDE website. + +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. + + + +Compilation and Installation + +Compiling KBiff is very easy. The following should do it: +% ./configure +% make +% make install + + +That should do it! Should you run into any problems, please report them +to the author + + + + +Using KBiff + +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. + + +The "profile" + +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. + + + +Command Line Parameters + +KBiff supports three command line parameters. They are: profile, debug, +and secure. +-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. + + + + + +The Setup Dialog + +The setup dialog handles all configuration items for KBiff. As a result, +there is no need for command line parameters in nearly all cases. + + +Profile Name + +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. + + + +Preference Tabs + +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. + + +General Preferences + +The general preferences for each profile are contained in this tab. There +are five fields here: + + +Poll + +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). + +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 +fetchmail 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. + + + +Mail client + +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 +elm in this field will not work. Putting konsole -e elm would. +The default is kmail -check + + + +Dock in panel + +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. + + + +Enable session management + +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 -profile +command line option instead. + +In all other cases, session management should probably be left on. + + + +Icons + +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. + + + + +New Mail Preferences + +This tab groups together the options that control what happen when new mail +arrives. + + +Run Command + +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. + + + +Play Sound + +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. + + + +System Beep + +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. + + + +Notify + +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. + + + +Floating Status + +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! + + + + +Mailbox Preferences + +This groups together the options controlling the physical mailboxs themself. + +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. + + +Mailbox list + +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. + +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. + + + +Protocol + +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. + + + +Mailbox + +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). + + + +Server + +This is active only for the IMAP4 and POP3 protocols. + + + +User + +This is active only for the IMAP4 and POP3 protocols. + + + + +Password + +This is active only for the IMAP4 and POP3 protocols. + + + + +Store Password + +This will save the password between sessions. + +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 + + + +Advanced + +This will popup a dialog containing advanced features. + + +Mailbox URL + +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, + + + +Port + +Set this to whatever port your server is at. By default, it will be 110 for +POP3 and 143 for IMAP4 + + + +PREAUTH + +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. + + + +Keep Alive + +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. + + + + + +About + +This tab has information about KBiff. + + +About KBiff + +This contains information about which version of KBiff is being used. It +also has contact information about the author. + +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 MAILER. If it finds it, it will use the +contents of this variable as the email program to use. + +For example, if MAILER is set like so: + % setenv MAILER "konsole -e mutt" +then KBiff will use konsole -e mutt as the default mail client, here. + + + + + + +The Popup Menu + +The popup menu is activated whenever the right mouse button is clicked +in the KBiff icon area. + + +(Un)Dock + +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. + + + +Setup + +This will activate the setup dialog. See the Setup Dialog section for more details. + + + +Help + +This activates the online help (this). + + + +Check Mail Now + +This forces KBiff to check for new mail right now, regardless of the poll +time. This will check all mailboxes in a profile. + + + +Read Mail Now + +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. + + + +Stop/Start + +This will either stop or start KBiff. + + + + +Questions, Answers, and Tips + + +Are there other KDE-aware "biff" utilities? + +Yes. There are at least three that I know of. Each "biff" has its own strengths. +KOrn 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 KNewMail. +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. + + + +What is the difference between a "profile" and a "mailbox" again? + +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". + + + +How do I use my own pixmaps? + +Short answer: select them using the setup dialog. +Longer answer: KBiff +searches for its icons in the standard KDE icon path. Currently, this is +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 + + +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. + +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. + +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. + + + +How do I use elm (or mutt or PINE) with KBiff? + +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: +konsole -caption Mail -e mutt & + +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. + + + +Why won't KBiff play my newmail.au file? + +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. + + + +Does KBiff work without session management? + +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. + + + +Clicking on your email address in About does nothing! + +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. +e.g. +% setenv MAILER konsole -e mutt + + +Note that this has the pleasant side effect that 'mailto:' links in the +regular kfm will also use your mailer. + + + +When I use KBiff to monitor my mailbox, all other 'biff' utilities stop + working. What's up? + +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. + +There are three ways around this: + +Don't use KBiff. + + +Use the 'file' protocol instead of the 'mbox' protocol (note that you'll +no longer know how many new mails have arrived) + + +Convert all of your 'mbox' mailboxes to 'maildir' + + + + + + +How do I use Netscape Mail with KBiff? + +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 +(sboger@marcus-online.net) +Create a shell script like so: +#!/bin/sh +if [ -L "$HOME/.netscape/lock" ]; +then +netscape -remote 'xfeDoCommand(openInbox)' +else +netscape -mail & +fi + + + + +KBiff truncates the initial slash in IMAP mode. Is this a bug? + +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. + +If you are trying to read /var/spool/mail/username try entering +inbox as the mailbox name. + + + +I have this great feature I want implemented. What should I do? + +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. + + + + -- cgit v1.2.1