Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdebase@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

3 files changed, 515 insertions, 0 deletions

diff --git a/doc/klipper/Makefile.am b/doc/klipper/Makefile.am
new file mode 100644
index 000000000..085981d9b
--- /dev/null
+++ b/doc/klipper/Makefile.am
@@ -0,0 +1,4 @@
+
+KDE_LANG = en
+KDE_DOCS = AUTO
+
diff --git a/doc/klipper/index.docbook b/doc/klipper/index.docbook
new file mode 100644
index 000000000..71327f14c
--- /dev/null
+++ b/doc/klipper/index.docbook
@@ -0,0 +1,511 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" 
+"dtd/kdex.dtd" [
+  <!ENTITY kappname "&klipper;">
+  <!ENTITY package "kdebase">
+  <!ENTITY % addindex "IGNORE">
+  <!ENTITY % English "INCLUDE" > <!-- change language only here -->
+]>
+
+<book lang="&language;">
+<bookinfo>
+<title>The &klipper; Handbook </title>
+
+<authorgroup>
+<author>&Philip.Rodrigues; &Philip.Rodrigues.mail;</author>
+
+<othercredit role="developer">
+&Carsten.Pfeiffer; &Carsten.Pfeiffer.mail;
+<!-- <contrib>Developer</contrib> -->
+</othercredit>
+
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+
+</authorgroup>
+
+<copyright>
+<year>2000-2003</year>
+<holder>&Philip.Rodrigues;</holder>
+</copyright>
+
+<legalnotice>&FDLNotice;</legalnotice>
+
+<date>2005-01-31</date>
+<releaseinfo>2.92.00</releaseinfo>
+
+<abstract>
+<para>&klipper; is the &kde; clipboard cut &amp; paste utility.</para>
+</abstract>
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>Klipper</keyword>
+<keyword>kdebase</keyword>
+<keyword>clipboard</keyword>
+</keywordset>
+</bookinfo>
+ 
+<chapter id="introduction">
+<title>Introduction</title>
+<para>&klipper; is the &kde; clipboard utility. It stores clipboard
+history, and allows you to link clipboard contents to application
+actions. Please report any problems or feature requests to Esben Mose
+Hansen (see <ulink
+url="http://mosehansen.dk/about">http://mosehansen.dk/about</ulink>
+for contact details).</para>
+
+</chapter>
+
+<chapter id="using-klipper">
+<title>Using &klipper;</title>
+
+<sect1 id="basic-usage">
+<title>Basic Usage</title>
+<screenshot>
+<screeninfo>The &klipper; icon.</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="screenshot.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>The &klipper; icon</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+<para>To display the clipboard history, click on the &klipper; icon in
+ the &kde; panel, or press <keycombo
+ action="simul">&Ctrl;&Alt;<keycap>V</keycap> </keycombo>. Previous
+ clipboard entries are shown at the top of the pop-up menu which
+ appears. Selecting one of these copies it to the clipboard, from
+ where it can be pasted into any &kde; or X application as
+ usual.</para>
+
+<para>You can search through the clipboard history by opening it
+(click on &klipper;) and typing your query. The results are updated as
+you type. In case you're wondering how to use the accelerator keys in
+the &klipper; menu, just press &Alt; and the accelerator you want. For
+example, to clear the clipboard history when the &klipper; menu is
+open, press <keycombo action="simul">&Alt;<keycap>L</keycap>
+</keycombo>.</para>
+
+<para>To remove &klipper;, click on its icon in the System Tray, and from the
+menu that appears, select <guimenuitem>Quit</guimenuitem>.</para>
+
+</sect1>
+
+<sect1 id="actions">
+<title>Actions</title>
+
+<para>&klipper; can perform actions on the contents of the clipboard,
+based on whether they match a particular regular expression. For
+example, any clipboard contents starting with <quote>http://</quote> can
+be passed to &Netscape; or &konqueror; as &URL;s to open.</para>
+
+<para>To use this feature, just copy a &URL; or filename to the
+clipboard. If there is a matching regular expression in &klipper;'s
+list, a menu will appear showing you the options you have (&eg; Open
+&URL; in &konqueror;, open &URL; in &Netscape;). Use the mouse or
+keyboard to select the option you want, and &klipper; will run the
+program you have selected, opening the address pointed to by the
+clipboard contents.</para>
+
+<para>If you do not want to perform any actions on the clipboard
+contents, select <guimenuitem>Do Nothing</guimenuitem> on the pop-up menu
+to return to what you were doing before. If you leave the menu, it will
+disappear, leaving you to continue your work. You can change the time
+that the menu remains for in the <guilabel>Configure Klipper...</guilabel>
+dialog, with the option <guilabel>Timeout for action pop-ups</guilabel>
+under the <guilabel>General</guilabel> tab.</para>
+	  
+<para>Actions can be disabled completely by clicking on &klipper; and
+selecting <guimenuitem>Actions Enabled</guimenuitem>, or by pressing
+<keycombo action="simul">&Ctrl;&Alt;<keycap>X</keycap></keycombo>.</para>
+
+<para>Clipboard contents which match a regular expression can also be
+edited before performing an action on them. Select <guimenuitem>Edit contents...</guimenuitem> on the &klipper; pop-up menu, and you can
+change the clipboard contents in the dialog which appears, before
+clicking the <guibutton>OK</guibutton> button to run the appropriate
+action.</para>
+
+<para>Pressing <keycombo
+action="simul">&Ctrl;&Alt;<keycap>R</keycap></keycombo> shows the pop-up
+menu to repeat the last action which &klipper; performed.</para>
+
+</sect1>
+
+<sect1 id="clipboard-modes">
+<title>Clipboard/Selection Behavior</title>
+
+<sect2 id="clipboard-modes-general">
+<title>General</title>
+<para>
+&klipper; can be used to set the behavior of the clipboard and selection in
+&kde;. 
+</para>
+
+<note><para>The &X-Window; uses two separate clipboard buffers: the
+<quote>selection</quote> and the <quote>clipboard</quote>. Text is
+placed in the selection buffer by simply selecting it, and can be
+pasted with the middle mouse button. To place text in
+the clipboard buffer, select it and press
+<keycombo>&Ctrl;<keycap>X</keycap> </keycombo> or
+<keycombo>&Ctrl;<keycap>C</keycap> </keycombo>. Text from the
+clipboard buffer is pasted using <keycombo>&Ctrl;<keycap>V</keycap>
+</keycombo> or by selecting
+<menuchoice><guimenu>Edit</guimenu><guimenuitem>Paste</guimenuitem>
+</menuchoice>.</para>
+</note>
+
+<!-- &klipper; can be used to set the clipboard mode for the whole of &kde;. The
+first mode will be familiar to &Microsoft; &Windows; and &Mac; users: Text is
+inserted into the clipboard using an application's cut/copy (or generally
+<keycombo>&Ctrl;<keycap>X</keycap></keycombo> and
+<keycombo>&Ctrl;<keycap>C</keycap></keycombo> respectively)
+function, and the application's paste (or generally 
+<keycombo>&Ctrl;<keycap>V</keycap></keycombo>) function pastes the
+contents of this clipboard.
+</para>
+<para>
+The second mode will be more familiar to longtime &UNIX; users: Selected text
+is copied to this clipboard, and clicking the <mousebutton>middle</mousebutton> 
+mouse button pastes the
+contents of this clipboard.
+-->
+</sect2>
+
+<sect2 id="changing-clipboard-modes">
+<title>Changing Clipboard/Selection Behavior</title>
+<para>
+In order to change clipboard/selection behavior, select
+<guimenuitem>Configure Klipper...</guimenuitem> from the &klipper; pop-up menu,
+and in the dialog box that appears, select the
+<guilabel>General</guilabel> tab. Selecting <guilabel>Separate clipboard and
+selection</guilabel> makes the clipboard and selection function as completely
+separate buffers as described above. With this option set, the option
+<guilabel>Ignore selection</guilabel> will prevent &klipper; from
+including the contents of the selection in its clipboard history and from
+performing actions on the contents of the selection. Selecting
+<guilabel>Synchronize contents of the clipboard and the selection</guilabel>
+causes the clipboard and selection buffers to always be the same, meaning that
+text in the selection can be pasted with either the
+<mousebutton>middle</mousebutton> mouse button or the key combination <keycombo>&Ctrl;<keycap>V</keycap>
+</keycombo>, and similarly for text in the clipboard buffer.
+</para>
+
+ <!-- The
+<guilabel>Synchronize contents of the clipboard and the
+selection</guilabel> check box determines the clipboard mode. If the box is
+selected, the clipboard functions in the &UNIX; mode; if not, the
+&Windows;/&Mac; mode is used. -->
+
+</sect2>
+
+
+</sect1>
+
+</chapter>
+
+<chapter id="preferences">
+<title>Configuring Klipper</title>
+
+<sect1 id="viewing-options">
+
+<title>Viewing the Configuration Dialog</title>
+
+<para>To view or change &klipper;'s settings, open the &klipper;
+pop-up menu, and select <guimenuitem>Configure Klipper...</guimenuitem>. The &klipper;
+configuration dialog will appear. Its contents are described
+below.</para>
+
+</sect1>
+
+<sect1 id="general-tab">
+<title>General Options</title>
+
+<variablelist>
+
+<varlistentry>
+<term><guilabel>Popup menu at mouse-cursor position</guilabel></term>
+<listitem><para>Make the &klipper; pop-up menus appear at the position of
+the mouse cursor, instead of their default position (in the &kde; Panel).
+Useful if you use the mouse more than the keyboard.</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><guilabel>Save clipboard contents on
+exit</guilabel></term> <listitem><para>If this option is on, the clipboard
+history will be saved when &klipper; exits, allowing you to use it next time
+&klipper; starts.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Remove whitespace when executing actions</guilabel></term>
+<listitem><para>If selected, any whitespace (spaces, tabs, &etc;) at the
+beginning and end of the clipboard contents will be removed before passing the
+clipboard contents to an application. This is useful, for example, if the
+clipboard contains a &URL; with spaces which, if opened by a web browser, would
+cause an error.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Replay actions on an item selected from
+history</guilabel></term>
+<listitem><para>If this is switched on, selecting an item from the history
+causes &klipper; to display the actions pop-up on that item, if 
+appropriate.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Prevent empty clipboard</guilabel></term>
+<listitem><para>If selected, the clipboard will never be empty: &klipper; will
+insert the most recent item from the clipboard history into the clipboard
+instead of allowing it to be empty.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Ignore selection</guilabel></term>
+<listitem><para>Sets the clipboard mode. See <xref linkend="clipboard-modes"/>.
+</para>
+</listitem>
+</varlistentry> 
+
+
+<varlistentry>
+<term><guilabel>Synchronize contents of the clipboard and the
+selection</guilabel></term>
+<listitem><para>Sets the clipboard mode. See <xref linkend="clipboard-modes"/>.
+</para>
+</listitem>
+</varlistentry> 
+
+<varlistentry>
+<term><guilabel>Separate clipboard and selection</guilabel></term>
+<listitem><para>Sets the clipboard mode. See <xref linkend="clipboard-modes"/>.
+</para>
+</listitem>
+</varlistentry> 
+
+
+<varlistentry>
+<term><guilabel>Timeout for Action pop-ups</guilabel></term>
+<listitem><para>Set the time that a pop-up menu will remain for if you do
+nothing with it.</para></listitem>
+</varlistentry>
+
+<varlistentry><term><guilabel>Clipboard history
+size</guilabel></term>
+<listitem><para>Sets the number of items that are stored
+in the clipboard history.</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect1>
+
+<sect1 id="actions-tab">
+<title>Actions Options</title>
+
+<variablelist>
+<varlistentry>
+<term>Editing Expressions/Actions</term>
+<listitem><para>On the <guilabel>Actions</guilabel> tab, double-click
+the regular expression or action that you want to edit. An in-place text editing
+box will appear in which the text can be edited as you wish. Make sure you
+press <keysym>Enter</keysym> when you are done.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Adding Expressions/Actions</term>
+<listitem><para>Click the <guibutton>Add Action</guibutton> button
+to add a regular expression for &klipper; to match. &klipper; uses
+&Qt;'s <classname>QRegExp</classname>, which understands most regular
+expressions as you would use in <application>grep</application> or
+<application>egrep</application> for instance.</para>
+<para>You can add a description of the regular expression type (&eg;
+<quote>HTTP URL</quote>) by <mousebutton>left</mousebutton> clicking in the
+<guilabel>Description</guilabel> column.</para>   
+
+<note><para>You can find detailed information about the use of
+<classname>QRegExp</classname> regular expressions at <ulink
+url="http://doc.trolltech.com/qregexp.html#details">http://doc.trolltech.com/qregexp.html#details</ulink>.
+Note that &klipper; does not support the wildcard mode mentioned on this
+page.</para></note> 
+
+<para>Edit the regular expression as described above. To add a command
+to execute, <mousebutton>right</mousebutton> click, select
+<guimenuitem>Add Command</guimenuitem> and edit the command which
+appears in the tree under the regular expression.</para>
+
+<para>Note that <token>%s</token> in the command line is replaced with
+the clipboard contents, &eg; if your command definition is
+<userinput><command>kedit</command> <token>%s</token></userinput> and
+your clipboard contents are <filename>/home/phil/textfile</filename>,
+the command <userinput><command>kedit</command>
+<filename>/home/phil/textfile</filename></userinput> will be run. To
+include <token>%s</token> in the command line, escape it with a
+backslash, as so: <userinput>\%s</userinput>.</para></listitem>
+</varlistentry>
+
+<varlistentry><term><guibutton>Advanced...</guibutton></term>
+<listitem><para>Brings up the <guilabel>Disable Actions for windows of type
+WM_CLASS</guilabel> dialog.</para>
+<para>Some programs, such as &konqueror;,
+use the clipboard internally. If you get unwanted &klipper; pop-ups all the time
+when using a certain application, do the following:</para>
+
+<orderedlist>
+<listitem><para>Open the application.</para></listitem>
+<listitem><para>From a terminal, run <userinput><command>xprop</command>
+| <command>grep</command> <parameter>WM_CLASS</parameter></userinput>
+and then click on the window of the application you are
+running.</para></listitem> 
+<listitem><para>The first string after the equals sign is the one to
+enter.</para></listitem>
+</orderedlist>
+
+<para>Once the WM_CLASS is added, no more actions will be generated for
+windows of that application.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</sect1>
+
+<sect1 id="shortcuts-tab">
+<title>Shortcuts Options</title>
+
+<para>The shortcuts tab allows you to change the keyboard shortcuts
+which are used to access &klipper; functions. You can change the
+shortcut to one of three things:</para>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>None</guilabel></term>
+<listitem><para>The selected action cannot be accessed directly from the
+keyboard</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Default</guilabel></term>
+<listitem><para>The selected action uses &klipper;'s default key. These are the
+shortcuts referred to in this manual.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Custom</guilabel></term>
+<listitem><para>The selected action is assigned to the keys you choose.</para>
+<para>To choose a custom key for the action you have selected, click on the
+representation of a key in the lower right of the screen to activate it, and
+type the desired key combination on your keyboard, as in any &kde; application. 
+</para> </listitem>
+</varlistentry>
+</variablelist>
+
+</sect1>
+</chapter>
+
+<chapter id="credits">
+<title>Credits and License</title>
+
+<para>
+&klipper;
+</para>
+<para>
+Program copyright 1998 Andrew Stanley-Jones <email>asj@cban.com</email>
+</para>
+<para>
+Program copyright 1998-2000 &Carsten.Pfeiffer; &Carsten.Pfeiffer.mail;</para>
+<para>
+Currently maintained by Esben Mose Hansen. See <ulink
+url="http://mosehansen.dk/about">http://mosehansen.dk/about</ulink>
+for contact details.
+</para>
+
+<para>
+Documentation copyright 2000-2003, 2005 &Philip.Rodrigues;
+&Philip.Rodrigues.mail;</para>
+
+&underFDL;
+&underGPL;
+
+</chapter>
+
+<appendix id="installation">
+<title>Installation</title>
+
+<sect1 id="getting-klipper">
+<title>How to obtain &klipper;</title>
+
+&install.intro.documentation;
+
+</sect1>
+
+<sect1 id="compilation">
+<title>Compilation and Installation</title>
+<para>&klipper; should compile and install along with the kdebase
+package, and appear on your &kde; panel (&kicker;) when you run &kde;
+3. If it does not appear, you can start it by selecting
+<menuchoice><guimenu>Panel
+Menu</guimenu><guisubmenu>Add</guisubmenu><guisubmenu>Applet</guisubmenu><guimenuitem>Klipper</guimenuitem>
+</menuchoice>
+in any context menu in &kicker;, the &kde; Panel.</para> 
+
+<screenshot>
+<screeninfo>&klipper; icon</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="screenshot.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Screenshot</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+
+<!--
+<para>To remove &klipper; from your panel, select <guimenuitem>Remove
+Klipper</guimenuitem> from the context menu (accessed by left-clicking the
+small handle to the left of the &klipper; icon).</para>
+-->
+<!--
+<para>To disable this, simply remove the file 
+<filename>$<envar>KDEDIR</envar>/share/autostart/klipper.desktop</filename>
+or create a file <filename>$<envar>HOME</envar>/share/autostart/klipper.desktop</filename>
+with the following contents:
+
+<programlisting>
+[Desktop Entry]
+Hidden=true
+</programlisting>
+
+The latter will keep the system installation intact and only prevent
+&klipper; being started for you, without affecting other users.
+</para>
+-->
+</sect1>
+</appendix>
+
+&documentation.index; 
+
+</book>
+<!--
+Local Variables:
+mode: sgml
+sgml-minimize-attributes: nil
+sgml-general-insert-case: lower
+sgml-indent-step: 0
+End:
+-->
+
+
+
+
+
+
+
+
+
+
diff --git a/doc/klipper/screenshot.png b/doc/klipper/screenshot.png
new file mode 100644
index 000000000..2b1fbbafe
--- /dev/null
+++ b/doc/klipper/screenshot.png