Initial import from kshowmail 3.3.1 sources

2 files changed, 526 insertions, 0 deletions

diff --git a/doc/en/Makefile.am b/doc/en/Makefile.am
new file mode 100644
index 0000000..ff41fa8
--- /dev/null
+++ b/doc/en/Makefile.am
@@ -0,0 +1,10 @@
+####### kdevelop will overwrite this part!!! (begin)##########
+
+
+EXTRA_DIST = index.docbook 
+
+####### kdevelop will overwrite this part!!! (end)############
+
+KDE_LANG = en
+KDE_DOCS = kshowmail
+
diff --git a/doc/en/index.docbook b/doc/en/index.docbook
new file mode 100644
index 0000000..4832400
--- /dev/null
+++ b/doc/en/index.docbook
@@ -0,0 +1,516 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd" [
+  <!ENTITY kshowmail '<application>Kshowmail</application>'>
+  <!ENTITY kapp "&kshowmail;"><!-- replace kshowmail here -->
+  <!ENTITY % addindex "IGNORE">
+  <!ENTITY % English "INCLUDE"><!-- change language only here -->
+  
+  
+  <!-- Do not define any other entities; instead, use the entities
+       from kde-genent.entities and $LANG/user.entities. -->
+]>
+<!-- kdoctemplate v0.8 October 1 1999 
+     Minor update to "Credits and Licenses" section on August 24, 2000
+     Removed "Revision history" section on 22 January 2001   -->
+
+<!-- ................................................................ -->
+
+<!-- The language must NOT be changed here. -->
+
+<book lang="&language;">
+
+<!-- This header contains all of the meta-information for the document such
+as Authors, publish date, the abstract, and Keywords -->
+
+<bookinfo>
+<title>The Kshowmail Handbook</title>
+
+<authorgroup>
+<author>
+<firstname>Eggert</firstname>
+<surname>Ehmke</surname>
+<affiliation>
+<address><email>[email protected]</email></address>
+</affiliation>
+</author>
+<author>
+<firstname>Allistar</firstname>
+<surname>Melville</surname>
+<affiliation>
+<address><email>[email protected]</email></address>
+</affiliation>
+</author>
+</authorgroup>
+
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+
+<copyright>
+<year>2000</year>
+<year>2001</year>
+<year>2002</year>
+<year>2003</year>
+<year>2004</year>
+<holder>Eggert Ehmke</holder>
+</copyright>
+<!-- Translators: put here the copyright notice of the translation -->
+<!-- Put here the FDL notice.  Read the explanation in fdl-notice.docbook 
+     and in the FDL itself on how to use it. -->
+<legalnotice>&FDLNotice;</legalnotice>
+
+<!-- Date and version information of the documentation
+Don't forget to include this last date and this last revision number, we
+need them for translation coordination !
+Please respect the format of the date (DD/MM/YYYY) and of the version
+(V.MM.LL), it could be used by automation scripts.
+Do NOT change these in the translation. -->
+
+<date>01/02/2004</date>
+<releaseinfo>3.1.1</releaseinfo>
+
+<!-- Abstract about this handbook -->
+
+<abstract>
+<para>
+This Handbook describes Kshowmail Version 3.1.1
+</para>
+</abstract>
+
+<!-- This is a set of Keywords for indexing by search engines.
+Please at least include KDE, the KDE package it is in, the name
+ of your application, and a few relevant keywords. -->
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>kshowmail</keyword>
+<keyword>kmail</keyword>
+<keyword>pop3</keyword>
+<keyword>mail checker</keyword>
+</keywordset>
+
+</bookinfo>
+
+<!-- The contents of the documentation begin here.  Label
+each chapter so with the id attribute. This is necessary for two reasons: it
+allows you to easily reference the chapter from other chapters of your
+document, and if there is no ID, the name of the generated HTML files will vary
+from time to time making it hard to manage for maintainers and for the CVS
+system. Any chapter labelled (OPTIONAL) may be left out at the author's
+discretion. Other chapters should not be left out in order to maintain a
+consistent documentation style across all KDE apps. -->
+
+<chapter id="introduction">
+<title>Introduction</title>
+
+<!-- The introduction chapter contains a brief introduction for the
+application that explains what it does and where to report
+problems. Basically a long version of the abstract.  Don't include a
+revision history. (see installation appendix comment) -->
+
+<para>
+Kshowmail is a KDE tool to watch mails on a POP3 server.
+Headers and complete mails can be viewed without loading them to the
+local mail client.
+Unpleasant mail can be deleted from the server.
+The list of displayed mails can be refreshed via configurable timers.
+Filters can be defined to mark known spam and unwanted mail.
+Mails marked by filters can be deleted automatically.
+A sound can be played if new mail arrives.
+A command menu allows user configurable commands like dcop commands to launch kmail.
+A special command can be defined to send complain mail against spam.
+Multiple accounts are supported.
+</para>
+</chapter>
+
+<chapter id="using-kshowmail">
+<title>Using Kshowmail</title>
+
+<!-- This chapter should tell the user how to use your app. You should use as
+many sections (Chapter, Sect1, Sect3, etc...) as is necessary to fully document
+your application. -->
+
+<sect1 id="kshowmail-features">
+<title>General Usage</title>
+<para>
+Add some accounts in the "Options" config dialog. Connect to the internet. Now you may list the
+mails on the pop3 servers by pressing the "Refresh" button. All other buttons and menu entries
+should explain themself.
+Have fun !
+</para>
+</sect1>
+<sect1 id="shortcuts">
+  <title>Keyboard-Shortcuts</title>
+  <variablelist>
+    <title>These keyboard shortcuts are defined:</title>
+    <varlistentry>
+      <term>F2</term>
+      <listitem>
+        <para>Show headers of selected mails</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>F3</term>
+      <listitem>
+        <para>Show complete selected mails</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>F5</term>
+      <listitem>
+        <para>Refresh new mails</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>Shift-F5</term>
+      <listitem>
+        <para>Force refresh of all mails</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>F10</term>
+      <listitem>
+        <para>Configure accounts</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>Del</term>
+      <listitem>
+        <para>Delete selected mails from server</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>Ctrl-C</term>
+      <listitem>
+        <para>Clear the mail list.
+        (No mails will be deleted from the server)</para>
+      </listitem>
+    </varlistentry>
+  </variablelist>
+</sect1>
+
+<sect1 id="filter">
+  <title>Filters</title>
+  <para>
+    Filters can be used to select known spam and other unwanted mail.
+    You can define as much filters as you want.
+    They will be applied on all mails each time the message list is refreshed.
+  </para>
+  <para>
+    In the Dialogue "Filter" you can select a state.
+    In the state "Deactivated" all filters are switched off.
+    In the state "Activated" all filters are switched on.
+    Filtered mails are selected in the message list and can be deleted manually.
+    In the state "Automatic delete" all filtered mails are deleted immediatly.
+    Please be careful when you select this state !
+    It may be useful to test new filters some time in the "Activated" state.
+    In the file ~/.kde/share/apps/kshowmail/kshowmail.log you can monitor mails that have been deleted automatically.
+  </para>
+
+  <para>
+    Each filter contains one or two conditions, that can be linked together.
+    Especially powerful conditions can be created using regular expressions.
+    Here the regular expressions of the Qt-Library are utilized,
+    for a detailed documentation see the documentation of the class KRegExpEditor,
+    or one of the numerous texts about regular expressions in the internet.
+    <ulink url="help:/KRegExpEditor/whatIsARegExp.html">
+      What is a regular expression?
+    </ulink>
+  </para>
+
+  <sect2>
+    <title>Regular Expressions examples</title>
+    <para>
+      MS Corporation|Microsoft: either "MS Corporation" or "Microsoft" will be recognized
+    </para>
+    <para>
+      (mail|message) delivery: either "mail delivery" or "message delivery" will be recognized
+    </para>
+    <para>
+      ms (program )?security: either "ms security" or "ms program security" will be recognized
+    </para>
+    <para>
+      [\x0100-\xffff]: all characters outside the ASCII character set are recognized (chinese and korean characters)
+    </para>
+    <para>
+      These templates can be combined arbitrarily.
+    </para>
+  </sect2>
+</sect1>
+
+<sect1 id="cmdline">
+<title>Command Line Parameters</title>
+<para>
+You can provide the selected account on the command line.
+If the option -config is set on the command line, the configuration dialog is started immediatly.
+This can be helpful, if the function "Terminate kshowmail if no new mail" is activated.
+The option -refresh can be used to start the refresh processing immediatly.
+</para>
+</sect1>
+<sect1 id="extprog">
+<title>External programs</title>
+<para>
+To start external programs like kmail, add a entry in the commands menu.
+Command names show up in the Actions menu. If they contain the character '&amp;', the following letter will
+be used as keyboard shortcut.
+</para>
+<para> The following parameters are placeholders and will be substituted by the actual values:</para>
+<para> &lt;user&gt; User name</para>
+<para> &lt;passwd&gt; Password</para>
+<para> &lt;server&gt; Server</para>
+<para> &lt;header&gt; The mail header will be copied to a temporary file, the name of this file will be substituted here.</para>
+<para> &lt;body&gt; The mail body will be copied to a temporary file, the name of this file will be substituted here.</para>
+<para>
+  A very effective method is the dcop command that allows to call selected methods of
+  other KDE programs.
+  You can create a command that calls KMail to get the mail from the server:
+</para>
+<para>
+  <command>dcop kmail KMailIface checkMail</command> 
+</para>
+<para>
+  The KDE program kdcop is useful to evaluate the functions of other KDE programs.
+</para>
+</sect1>
+<sect1 id="complain">
+<title> Sending complain mails </title>
+<para>
+  The command to send complain mails is a special one.
+  To keep flexibility, it has been implemented as an external command too.
+  I suggest to use the perl program "spam.pl" version 0.20 or better of Daniel Stenberg.
+  It can be received at <ulink url="http://spam.sourceforge.net">http://spam.sourceforge.net.</ulink>
+  To make it run with kshowmail, follow these steps:
+</para>
+<para>
+  1. Install spam.pl in a suitable directory, say /usr/local/bin.
+</para>
+<para>
+  2. Create the files ~/.spam/friends and ~/.spam/from.
+  More details are available in the spam.pl documentation.
+</para>
+<para>
+  3. Create an entry in the kshowmail command menu.
+  The name of the entry has to be "complain" !
+  Otherwise the command will not be recognized correctly.
+  Enter this text as command line:
+</para>
+<para>
+  <command>spam.pl -d &lt; &lt;body&gt;</command>
+</para>
+<para>
+  This causes the mail body to be piped into spam.pl.
+</para>
+<para>
+  The debug option -d may be removed later, if you are satisfied with the results.
+  Only then the complain mails will be actually sent.
+  Add other options as you like.
+</para>
+<para>
+  Be careful to choose the right entries in the ~/.spam/friends file.
+  At least the local domain should be inserted.
+  Use this feature at your own risk !
+</para>
+<para>
+  As you press the button "Send complain mail", for each highlighted mail
+  there will be one or more complain mails generated and sent immediatly.
+  The receiver of these mails are determined by spam.pl.
+  As long as the option -d is activated, only a message will be displayed to show what would happen.
+  To activate the feature, remove the debug flag.
+</para>
+<para>
+  If you prefer other anti spam programs, try to set them up in a similar way.
+  Contact me if there are any problems.
+</para>
+</sect1>
+</chapter>
+
+<chapter id="faq">
+<title>Questions and Answers</title>
+
+<!-- (OPTIONAL but recommended) This chapter should include all of the silly
+(and not-so-silly) newbie questions that fill up your mailbox. This chapter
+should be reserved for BRIEF questions and answers! If one question uses more
+than a page or so then it should probably be part of the
+"Using this Application" chapter instead. You should use links to
+cross-reference questions to the parts of your documentation that answer them.
+This is also a great place to provide pointers to other FAQ's if your users
+must do some complicated configuration on other programs in order for your
+application work. -->
+
+&reporting.bugs;
+&updating.documentation;
+
+<qandaset id="faqlist">
+<qandaentry>
+<question>
+<para>To be provided</para>
+</question>
+<answer>
+<para>To be provided.</para>
+</answer>
+</qandaentry>
+</qandaset>
+</chapter>
+
+<chapter id="credits">
+
+<!-- Include credits for the programmers, documentation writers, and
+contributors here. The license for your software should then be included below
+the credits with a reference to the appropriate license file included in the KDE
+distribution. -->
+
+<title>Credits and License</title>
+
+<para>
+&kapp;
+</para>
+<para>
+Program copyright 2000-2003 Eggert Ehmke <email>[email protected]</email>
+</para>
+<para>
+Contributors:
+<itemizedlist>
+<listitem>
+<para>
+Nicolas Vignal <email>[email protected]</email> who provided RPMs for RedHat,
+and the french translation.
+</para>
+</listitem>
+<listitem>
+<para>
+Edgardo Garcia <email>[email protected]</email> who provided the spanish translation
+</para>
+</listitem>
+<listitem>
+<para>
+Mattias Newzella <email>[email protected]</email> who provided the swedish translation
+</para>
+</listitem>
+<listitem>
+<para>
+Sandor Laza <email>[email protected]</email> who provided the hungarian translation
+</para>
+</listitem>
+<listitem>
+<para>
+Gabriele Postorino <email>[email protected]</email> who provided the italian translation
+</para>
+</listitem>
+<listitem>
+<para>
+Many users did a lot of testing and created a lot of
+ideas that are now part of kshowmail.
+I want to say "thank you" to all of you !
+</para>
+</listitem>
+</itemizedlist>
+</para>
+
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+
+&underFDL;               <!-- FDL: do not remove. Commercial development should -->
+<!-- replace this with their copyright and either remove it or re-set this.-->
+
+<!-- Determine which license your application is licensed under, 
+     and delete all the remaining licenses below:
+
+     (NOTE:  All documentation are licensed under the FDL, 
+     regardless of what license the application uses) -->
+
+&underGPL;        	 <!-- GPL License -->
+</chapter>
+
+<appendix id="installation">
+<title>Installation</title>
+
+<sect1 id="getting-kshowmail">
+<title>How to obtain Kshowmail</title>
+
+<para>
+The actual version is to be found on
+<ulink url="http://sourceforge.net/projects/kshowmail">
+http://sourceforge.net/projects/kshowmail</ulink>
+or on
+<ulink url="http://freshmeat.net">http://freshmeat.net</ulink>
+
+</para>
+</sect1>
+
+<sect1 id="requirements">
+<title>Requirements</title>
+
+<!--
+List any special requirements for your application here. This should include:
+.Libraries or other software that is not included in kdesupport,
+kdelibs, or kdebase.
+.Hardware requirements like amount of RAM, disk space, graphics card
+capabilities, screen resolution, special expansion cards, etc.
+.Operating systems the app will run on. If your app is designed only for a
+specific OS, (you wrote a graphical LILO configurator for example) put this
+information here.
+-->
+
+<para>
+  Developed and tested under SuSE 8.2.
+  In order to successfully use Kshowmail, you need KDE 3.1.x and Qt 3.1.x.
+</para>
+
+<!-- For a list of updates, you may refer to the application web site
+or the ChangeLog file, or ... -->
+<para>
+You can find a list of changes at
+<ulink url="http://sourceforge.net/projects/kshowmail">
+http://sourceforge.net/projects/kshowmail</ulink>
+</para>
+</sect1>
+
+<sect1 id="compilation">
+<title>Compilation and Installation</title>
+
+<para>
+  In order to compile and install Kshowmail on your system, type the following in the base
+  directory of Kshowmail:
+  <screen width="40">
+    <prompt>%</prompt> <userinput>./configure</userinput>
+      or even:
+    <prompt>%</prompt> <userinput>./configure --prefix=$KDEDIR</userinput>
+
+    <prompt>%</prompt> <userinput>make</userinput>
+
+      as root:
+    <prompt>%</prompt> <userinput>make install</userinput>
+  </screen>
+  It may be useful to set the environment variable KDEDIR before these steps.
+</para>
+
+<para>
+  Since Kshowmail uses autoconf and automake you should have not trouble compiling it.
+  Should you run into problems please report them to me.
+</para>
+
+</sect1>
+
+</appendix>
+
+&documentation.index;
+</book>
+<!--
+Local Variables:
+mode: sgml
+sgml-minimize-attributes:nil
+sgml-general-insert-case:lower
+sgml-indent-step:0
+sgml-indent-data:nil
+End:
+-->
+
+
+
+
+
+
+
+
+
+
+
+
+