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

1 files changed, 521 insertions, 0 deletions

diff --git a/doc/kmenuedit/index.docbook b/doc/kmenuedit/index.docbook
new file mode 100644
index 000000000..73cb76ced
--- /dev/null
+++ b/doc/kmenuedit/index.docbook
@@ -0,0 +1,521 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" 
+"dtd/kdex.dtd" [
+  <!ENTITY package "kdebase">
+  <!ENTITY firefox "<application>Firefox</application>">
+  <!ENTITY % addindex "IGNORE">
+  <!ENTITY % English "INCLUDE" > <!-- change language only here -->
+]>
+
+<book lang="&language;">
+
+<bookinfo>
+
+<title>The &kmenuedit; Handbook</title>
+
+<authorgroup>
+<author>&Milos.Prudek; &Milos.Prudek.mail;</author>
+
+<othercredit role="reviewer">
+&Lauri.Watts; &Lauri.Watts.mail;
+<!-- <contrib>Reviewer</contrib> -->
+</othercredit>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+
+<copyright>
+<year>2000</year>
+<holder>&Milos.Prudek;</holder>
+</copyright>
+
+<legalnotice>&FDLNotice;</legalnotice>
+
+<date>2006-11-23</date>
+<releaseinfo>0.7 (&kde; 3.5.5)</releaseinfo>
+
+<abstract><para>&kmenuedit; allows editing of the &kde; &kmenu;. 
+</para></abstract>
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>KDE Menu Editor</keyword>
+<keyword>kmenuedit</keyword>
+<keyword>application</keyword>
+<keyword>program</keyword>
+<keyword>menu</keyword>
+<keyword>kicker</keyword>
+
+</keywordset>
+
+</bookinfo>
+
+<chapter id="introduction">
+<title>Introduction</title>
+
+<para>&kmenuedit; allows editing of &kde; &kmenu;.</para>
+
+<para>&kmenuedit; can be started either by &RMB; clicking the
+&kmenu; button on the panel and choosing
+<guimenuitem>Menu Editor</guimenuitem>, or by choosing
+<guimenuitem>Menu Editor</guimenuitem> from the
+<guisubmenu>Settings</guisubmenu> submenu of the &kmenu;.</para>
+
+<para>&kmenuedit; allows you to:</para>
+
+<itemizedlist>
+<listitem><para>View and edit the current &kmenu;</para></listitem>
+<listitem><para><guimenuitem>Cut</guimenuitem>, <guimenuitem>Copy</guimenuitem>
+and <guimenuitem>Paste</guimenuitem> menu items</para></listitem>
+<listitem><para>Create and delete submenus</para></listitem>
+</itemizedlist>
+
+</chapter>
+
+<chapter id="quickstart">
+<chapterinfo>
+<authorgroup>
+<author>&Virgil.J.Nisly; &Virgil.J.Nisly.mail;</author>
+</authorgroup>
+</chapterinfo>
+<title>A Quick Start Guide to Adding an Entry to the &kmenu;</title>
+
+  <para>In this example, we will add &firefox; to the <guisubmenu>Internet</guisubmenu> submenu. <note><para>Most applications can be added with &kappfinder;, &firefox; can usually be added that way, but was used for lack of a better example.</para></note></para>
+  <para>To start off, we need to open &kmenuedit;, so &RMB; on the &kmenu;, click <guimenuitem>Menu Editor</guimenuitem> to start &kmenuedit;. After &kmenuedit; has started, select <guisubmenu>Internet</guisubmenu> as shown in picture below. 
+<screenshot>
+<screeninfo>Select <guisubmenu>Internet</guisubmenu></screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="selectinternet.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>Select <guisubmenu>Internet</guisubmenu></phrase>
+</textobject>
+</mediaobject>
+</screenshot></para>
+  <para>
+    Once you have selected <guisubmenu>Internet</guisubmenu>, click on <menuchoice><guimenu>File</guimenu><guimenuitem>New Item...</guimenuitem></menuchoice>, opening the <guilabel>New Item</guilabel> dialog, as shown below. Type the name of the program you want to add, in this case, type <userinput>firefox</userinput>. 
+<screenshot>
+<screeninfo><guilabel>New Item</guilabel> dialog</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="itemname.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>The <guilabel>New Item</guilabel> dialog.</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+</para>
+<para>
+Press return, and you should see something like the picture below in the main window.
+<screenshot>
+<screeninfo>New Item</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="new.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>The new item created.</phrase>
+</textobject>
+</mediaobject>
+</screenshot></para>
+  
+<para>
+    Now lets fill in the <guilabel>Description:</guilabel>, in this case type <userinput>Web Browser</userinput>. <note><para>The description and name will be displayed on the &kmenu; as <quote>Web Browser (Firefox)</quote>.</para></note> We will need to fill in the executable name in the <guilabel>Command:</guilabel> field, in this instance we will type <userinput><command>firefox</command></userinput>.</para>
+<note><para>Following the command, you can have several place holders which will be replaced with actual values when the program is run:
+<simplelist>
+<member>%f - a single file name</member>
+<member>%F - a list of files; use for applications that can open several local files at once</member>
+<member>%u - a single &URL;</member>
+<member>%U - a list of &URL;s</member>
+<member>%d - the folder of a file to open</member>
+<member>%D - a list of folders</member>
+<member>%i - the icon</member>
+<member>%m - the mini icon</member>
+<member>%c - the caption</member>
+</simplelist></para>
+<informalexample><para>For example: if you want to firefox to start your web browsing at www.kde.org - instead of <command>firefox</command> you would type <command>firefox %u www.kde.org</command>.</para></informalexample></note>
+<para>We would like to have a more creative icon, so we will click the generic icon sitting beside <guilabel>Name:</guilabel>. It will bring the <guilabel>Select Icon</guilabel> dialog which will let us choose the new icon, as shown below.
+<screenshot>
+<screeninfo><guilabel>Select Icon</guilabel> dialog</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="selecticon.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>The <guilabel>Select Icon</guilabel> dialog.</phrase>
+</textobject>
+</mediaobject>
+</screenshot></para>
+
+  <para>We choose the firefox icon from the list, and press return. Your finished screen should probably look something like the screenshot below. 
+<screenshot>
+<screeninfo>Done screenshot</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="done.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>This is what the completed menu item should looks like.</phrase>
+</textobject>
+</mediaobject>
+</screenshot></para>
+
+<para>Click <menuchoice><guimenu>File</guimenu><guimenuitem>Save</guimenuitem></menuchoice>, wait for the <guilabel>Updating System Configuration</guilabel> dialog to get finished, you should find &firefox; in the &kmenu; <guisubmenu>Internet</guisubmenu> submenu!</para>
+
+
+
+</chapter>
+
+<chapter id="using-kmenuedit">
+<title>Using &kmenuedit;</title>
+
+<para>The left application panel shows the &kmenu; structure. When
+you browse items in the left panel, the right panel shows detailed
+information for the highlighted menu item.</para>
+
+<sect1 id="details-general">
+<title>General program information</title>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Name:</guilabel></term>
+<listitem><para>This is the name of your program as it appears in the
+&kmenu; menu. It can be different from the real executable
+name. For instance the name of <command>mc</command> executable is
+"<application>Midnight Commander</application>".</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Description:</guilabel></term>
+<listitem><para>The description will be displayed together with the name in the &kmenu;. This is
+entirely optional.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Comment:</guilabel></term>
+<listitem><para>Describe the program in greater detail in this field. This is
+entirely optional.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Command:</guilabel></term>
+<listitem><para>This is the name of the executable program. Make sure that you
+have permission to run the program.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Enable launch feedback</guilabel></term>
+<listitem><para>If this box is checked, this will display feedback when an application is started
+</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Place in system tray</guilabel></term>
+<listitem><para>When checked, the application's icon will show up in the panel system tray.
+You will then be able to hide or show the application by clicking on the system
+tray icon. Clicking on it using the &RMB; will allow also you to undock, or quit the
+application.
+</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guiicon>Icon List</guiicon></term>
+<listitem><para>Click
+this icon to display a choice of icons. Choose an icon for your
+program.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Work path:</guilabel></term>
+<listitem><para>Specify the work path of the program. This will be the current
+path when the program launches. It does not need to be the same as the
+executable location.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Run in terminal</guilabel></term>
+<listitem><para>You must check this if your program requires terminal emulator
+in order to run. This mainly applies to <link
+linkend="gloss-console-application">console 
+applications</link>.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Terminal options:</guilabel></term>
+<listitem><para>Put all terminal options in this field.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Run as a different user</guilabel></term>
+<listitem><para>If you want to run this program as a different user (not you),
+check this checkbox, and provide the username in the
+<guilabel>Username:</guilabel> field.</para></listitem>
+</varlistentry>
+</variablelist>
+
+<para>You can assign a special keyboard shortcut to launch your program.</para>
+
+<para>Click the <guibutton>None</guibutton> button to the right of the <guilabel>Current
+shortcut key:</guilabel> checkbox.</para>
+
+<para>A dialog box will pop up, allowing you to assign a <guilabel>Primary shortcut:</guilabel>
+by pressing the key combination on your keyboard that you want to be assigned to your program.
+It might be useful to assign a second
+keybinding to the same item by checking the
+<guilabel>Alternate shortcut:</guilabel> button, for
+example, if you often switch keyboard maps, and some shortcuts are not
+as convenient to type at all times.</para>
+
+<para>Click the <guiicon>x</guiicon> to clear the shortcut, if you
+made a mistake.  Check the <guilabel>Multi-key mode</guilabel> box if you
+want to assign a shortcut that uses more than one key.</para>
+
+<para>The dialog will close when you have selected a keybinding.
+</para>
+
+</sect1> 
+
+</chapter>
+
+<chapter id="menu-reference">
+<title>Menu Reference</title>
+
+<variablelist>
+<varlistentry id="file-new-item">
+<term><menuchoice> 
+<shortcut><keycombo
+action="simul">&Ctrl;<keycap>N</keycap></keycombo></shortcut>
+<guimenu>File</guimenu> <guimenuitem>New Item...</guimenuitem>
+</menuchoice></term> <listitem><para><action>Adds new menu
+item.</action></para></listitem>
+</varlistentry>
+
+<varlistentry id="file-new-submenu">
+<term><menuchoice>
+<guimenu>File</guimenu>
+<guimenuitem>New Submenu...</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Adds new submenu.</action></para></listitem>
+</varlistentry>
+
+<varlistentry id="file-new-separator">
+<term><menuchoice><guimenu>File</guimenu><guimenuitem>New
+Separator</guimenuitem></menuchoice></term>
+<listitem>
+<para><action>Adds a new separator to the menu.</action></para>
+</listitem>
+</varlistentry>
+
+<varlistentry id="file-save">
+<term><menuchoice>
+<shortcut><keycombo
+action="simul">&Ctrl;<keycap>S</keycap></keycombo></shortcut>
+<guimenu>File</guimenu><guimenuitem>Save</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>Saves the menu</action></para>
+</listitem>
+</varlistentry>
+
+<varlistentry id="file-quit">
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Quit</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Quits</action> &kmenuedit;.</para></listitem>
+</varlistentry>
+
+<varlistentry id="edit-cut">
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>X</keycap></keycombo>
+</shortcut>
+<guimenu>
+Edit</guimenu> <guimenuitem>Cut</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Cuts the current menu item to the clipboard.</action> If
+you want to move menu item, you should first cut it to the clipboard, move to
+the destination place using the left panel, and use the
+<guimenuitem>Paste</guimenuitem> function to paste the menu item from the
+clipboard.</para></listitem> 
+</varlistentry>
+
+<varlistentry id="edit-copy">
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo>
+</shortcut>
+<guimenu>
+Edit</guimenu> <guimenuitem>Copy</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Copies the current menu item to the
+clipboard</action>. You can later use the <guimenuitem>Paste</guimenuitem>
+function to paste the copied menu itemfrom the clipboard to its destination. You
+can paste the same item many times.</para></listitem>
+</varlistentry>
+
+<varlistentry id="edit-paste">
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>V</keycap></keycombo>
+</shortcut>
+<guimenu>Edit</guimenu>
+<guimenuitem>Paste</guimenuitem> </menuchoice></term>
+<listitem><para><action>Paste menu item from the clipboard</action> to currently
+selected place in the <guimenu>Main</guimenu> menu. You must first use
+<guimenuitem>Cut</guimenuitem> or <guimenuitem>Copy</guimenuitem> before you can
+<guimenuitem>Paste</guimenuitem>.</para></listitem>
+</varlistentry>
+
+<varlistentry id="edit-delete">
+<term><menuchoice>
+<shortcut><keycap>Delete</keycap></shortcut>
+<guimenu>Edit</guimenu> <guimenuitem>Delete</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Deletes currently selected menu
+item.</action></para></listitem>
+</varlistentry>
+
+<varlistentry id="settings-hide-toolbar">
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Show/Hide Toolbar</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Show or hide the toolbar</action></para></listitem>
+</varlistentry>
+
+<varlistentry id="settings-configure-shortcuts">
+<term><menuchoice>
+<guimenu>Settings</guimenu><guimenuitem>Configure
+Shortcuts...</guimenuitem></menuchoice></term>
+<listitem>
+<para><action>Customize the keyboard shortcuts</action></para>
+</listitem>
+</varlistentry>
+
+<varlistentry id="settings-configure-toolbars">
+<term><menuchoice>
+<guimenu>Settings</guimenu><guimenuitem>Configure
+Toolbars...</guimenuitem></menuchoice></term>
+<listitem>
+<para><action>Customize the toolbar icons.</action></para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+&help.menu.documentation;
+
+</chapter>
+
+<chapter id="credits">
+
+<title>Credits and License</title>
+
+<para>
+&kmenuedit;
+</para>
+<para>Program copyright &copy; 2002, &Raffaele.Sandrini;</para>
+
+<para>Contributors:</para>
+<itemizedlist>
+<listitem><para>&Matthias.Elter; &Matthias.Elter.mail; - Original
+Author</para> 
+</listitem>
+<listitem><para>&Matthias.Ettrich; &Matthias.Ettrich.mail;</para>
+</listitem>
+<listitem><para>&Daniel.M.Duley; &Daniel.M.Duley.mail;</para>
+</listitem>
+<listitem><para>&Preston.Brown; &Preston.Brown.mail;</para>
+</listitem>
+</itemizedlist>
+
+<para>Documentation copyright &copy; 2000 &Milos.Prudek;</para>
+
+<para>Updated for &kde; 3.0 by &Lauri.Watts; &Lauri.Watts.mail;
+2002</para>
+
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+
+&underFDL;
+&underGPL;
+
+</chapter>
+
+<glossary id="glossary">
+<title>Glossary</title> 
+
+<glossentry id="gloss-terminal-emulator">
+<glossterm>Terminal emulator</glossterm>
+<glossdef>
+<para>Terminal emulator is simply a windowed shell; this is known as
+<quote>command line window</quote> in some other environments. If you
+want to use the shell, you should know at least a few of the
+system-level commands for your operating system.</para>
+</glossdef>
+</glossentry>
+
+<glossentry id="gloss-applet">
+<glossterm>Applet</glossterm>
+<glossdef><para>A small application that occupies very little memory
+and screen space, and at the same time gives you some useful
+information or provides a control shortcut. For instance the
+<application>Clock</application> applet shows current time and date
+(and even a month diary if you click it), and <application>System
+Monitor</application> applet shows how busy your machine currently is
+in real-time.</para> </glossdef> 
+</glossentry>
+
+<glossentry id="gloss-legacy-application">
+<glossterm>Legacy Application</glossterm>
+<glossdef>
+
+<para>An X-window application which was not written with &kde; in
+mind. Such applications run fine in &kde;. However, they are not
+warned automatically when you shut down your &kde; session. You
+therefore must not forget to save documents open in these applications
+before you log out from &kde;. </para> <para>Additionally, many of
+these applications do not support copying and pasting from
+&kde; compliant applications. &Netscape; 4.x browser is a prominent
+example of such application <footnote><para>Some <ulink
+url="http://www.gnome.org">GNOME</ulink> applications may provide
+limited interoperability with the &kde;.</para></footnote>.</para>
+</glossdef>
+</glossentry>
+
+<glossentry id="gloss-console-application">
+<glossterm>Console Application</glossterm>
+<glossdef>
+
+<para>Application originally written for non-graphic, text oriented
+environment. Such applications run fine in &kde;. They must run within
+console emulator, like &konsole;. They are not warned automatically
+when you shut down your &kde; session. You therefore must not forget
+to save documents open in these applications before you log out from
+the &kde;.</para>
+
+<para>Console applications support copying and pasting from
+&kde;-compliant applications.Simply mark the text in the console
+application with your mouse, switch to the &kde;-compliant application
+and press <keycombo action="simul">&Ctrl;
+<keycap>V</keycap></keycombo> to paste the text. If you want to copy
+from &kde; application to a console application, first mark the text
+with your mouse, press <keycombo action="simul">&Ctrl;
+<keycap>C</keycap></keycombo>, switch to the console application and
+press the middle button on your mouse<footnote><para>If your mouse
+does not have a middle button, you must press
+<mousebutton>left</mousebutton> and <mousebutton>right</mousebutton>
+button at the same time. This is called <quote>middle button
+emulation</quote> and it must be supported by your operating system to
+work.</para></footnote>.</para>
+
+</glossdef>
+</glossentry>
+
+</glossary>
+
+&documentation.index; 
+
+</book>
+<!--
+Local Variables:
+mode: sgml
+sgml-minimize-attributes: nil
+sgml-general-insert-case: lower
+End:
+-->
+