[kde-doc-english] [kde-workspace] doc/kmenuedit: KMenuedit documentation - improve introduction chapter and add use case section
Burkhard Lück
lueck at hube-lueck.de
Mon Sep 23 19:18:40 UTC 2013
Git commit 8d526e154d45c001010576f5c671bcbc5eb22bbf by Burkhard Lück.
Committed on 23/09/2013 at 19:18.
Pushed by lueck into branch 'master'.
KMenuedit documentation - improve introduction chapter and add use case section
M +148 -11 doc/kmenuedit/index.docbook
http://commits.kde.org/kde-workspace/8d526e154d45c001010576f5c671bcbc5eb22bbf
diff --git a/doc/kmenuedit/index.docbook b/doc/kmenuedit/index.docbook
index f62b55a..c15f1db 100644
--- a/doc/kmenuedit/index.docbook
+++ b/doc/kmenuedit/index.docbook
@@ -35,7 +35,7 @@
<legalnotice>&FDLNotice;</legalnotice>
-<date>2013-06-19</date>
+<date>2013-09-07</date>
<releaseinfo>0.9 (&kde; 4.11)</releaseinfo>
<abstract><para>&kmenuedit; allows editing one of the &kde; application launchers: &kickoff;, the classic &kmenu; or Lancelot Launcher.
@@ -56,7 +56,7 @@
<chapter id="introduction">
<title>Introduction</title>
-<para>&kmenuedit; allows editing of &kde; application launchers: &kickoff;, classic &kmenu; or Lancelot Launcher.</para>
+<para>&kmenuedit; allows editing the menu of &kde; application launchers: &kickoff;, classic &kmenu; or Lancelot Launcher.</para>
<para>&kmenuedit; can be started either by &RMB; clicking the application launcher
button on the panel and choosing <guimenuitem>Edit
@@ -66,12 +66,136 @@ by typing <userinput>kmenuedit</userinput> in the &krunner; line.</para>
<para>&kmenuedit; allows you to:</para>
<itemizedlist>
-<listitem><para>View and edit the current application launcher (&kickoff;, classic menu or Lancelot Launcher)</para></listitem>
+<listitem><para>View and edit the menu used by the current application launcher (&kickoff;, classic menu or Lancelot Launcher)</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>
+and <guimenuitem>Paste</guimenuitem> submenus and items</para></listitem>
+<listitem><para>Create and delete submenus and items</para></listitem>
+<listitem><para>Change the order of submenus and items</para></listitem>
+<listitem><para>Hide items and add new submenus and items</para></listitem>
</itemizedlist>
+<para>By default all applications installed on the computer appear in the application launchers menu of all users.
+Applications may appear more than once in several different menus.
+Empty submenu categories defined in the desktop menu specification will show up as well,
+but are not visible in application launchers unless you install applications belonging to these categories.
+</para>
+
+<para>The tree view has three different entry types:</para>
+<itemizedlist>
+<listitem><para>Submenu: Only <guilabel>Name</guilabel>, <guilabel>Comment</guilabel> and
+<guilabel>Description</guilabel> fields and the button to select an icon
+are enabled, the <guilabel>Advanced</guilabel> tab is disabled.
+Any submenu can hold additional submenus and/or items.
+</para></listitem>
+<listitem><para>Items: Use this entry to enter the data for the application you want to add.
+For detailed information see <link linkend="using-kmenuedit">Using &kmenuedit;</link>.
+</para></listitem>
+<listitem><para>Separator: A visual entry to structure the menu. It cannot be modified
+and all editing actions are disabled.
+</para></listitem>
+</itemizedlist>
+
+<para>&kmenuedit; has two tree view modes - normal and with hidden entries. To see the latter check the option
+<guilabel>Show hidden entries</guilabel> in the configuration dialog on the <guilabel>General options</guilabel> page.
+</para>
+<para>Many additional entries appear in hidden view mode in the tree. Several hidden entries seem to be just duplicates
+but have different command options. Usually you should never change these hidden entries or you risk to break some
+functionality of the system.
+</para>
+<para>In hidden mode you will have a special submenu <guilabel>.hidden [Hidden]</guilabel> as top level
+item in the tree. This special submenu is not editable. In this submenu all deleted items will be shown at the next
+start of &kmenuedit;.</para>
+<para>It is not possible to delete entries using the &GUI; in this special submenu. They will reappear at the
+next start of &kmenuedit;.
+</para>
+
+<sect1 id="use-cases">
+<title>Use Cases</title>
+
+<sect2 id="use-cases-adapt">
+<title>Adapt the Menu for a User</title>
+
+<sect3 id="use-cases-adapt-order">
+<title>Reorder Items</title>
+
+<para>This should be done in hidden view mode where only the submenus and items visible in the application
+launcher menu are displayed.
+</para>
+<para>By default the menu is sorted alphabetically using the English names or descriptions. Using another language
+than English some submenus and items therefor will appear in an unsorted order.
+</para>
+<para>Use the options in <menuchoice><guimenu>Edit</guimenu><guimenuitem>Sort</guimenuitem></menuchoice>
+to sort either by name or description. If you use the classic application launcher you have to select the
+corresponding <guilabel>Format</guilabel> option in the settings dialog. In the &kickoff; launcher check
+<guilabel>Show applications by name</guilabel> if you sort them by name here.
+</para>
+<para>Grouping your frequently used submenus or items together ⪚ at the top of the menu makes selecting them easier.
+To change the order of single items or submenus in the tree use the <guibutton>Move Up</guibutton> or
+<guibutton>Move Down</guibutton> button in the toolbar or these actions in the menu.
+</para>
+<para>All application launchers will use the order of submenus defined in &kmenuedit;.
+</para>
+</sect3>
+
+<sect3 id="use-cases-adapt-hide">
+<title>Remove Items from the Menu View</title>
+
+<para>Having all applications installed on a computer may be confusing for some users so you may
+want to hide some less frequently used items or submenus. There are two different ways to do that:
+</para>
+
+<para>Switch to normal view mode without hidden entries. If you delete items they are moved to the
+<guilabel>.hidden [Hidden]</guilabel> submenu. You can move them back into the tree to have them in the menu again.
+</para>
+<para>If you delete a submenu it will be really deleted with all its submenus and items.
+To recreate them you can use <menuchoice><guimenu>Edit</guimenu><guimenuitem>Restore to System
+Settings</guimenuitem></menuchoice>, but this will remove all your custom submenus and items
+and the corresponding <filename class="extension">.desktop</filename> files are deleted too. This action cannot be reverted.
+</para>
+
+<para>The preferred way to remove submenus and items in the menu of an application launcher is to check <guilabel>Hide
+entry</guilabel> on the <guilabel>General</guilabel> tab and switch to the hidden view mode.
+In this mode it is easy to revert changes without destroying the menu structure.
+The only drawback is that you have to hide all entries in a submenu manually to
+hide the whole submenu from the view.
+</para>
+</sect3>
+
+</sect2>
+
+<sect2 id="use-cases-additems">
+<title>Adding Custom Items</title>
+
+<para>To add custom items (submenu, item or separator) use the actions in the menu or toolbar.
+Items need a Name and a Command, without a command entry an item will not be saved and your addition gets lost.
+</para>
+<para>If you add an entry it is inserted as sub entry at the actual highlighted position in the tree.
+Move an entry by dragging it with the mouse or using the <guibutton>Move Down</guibutton> button
+to the bottom of the tree to make it a top level entry.
+</para>
+
+</sect2>
+
+<sect2 id="use-cases-transfer">
+<title>Transfer application launcher settings</title>
+
+<para>There is no way to transfer menu settings using the &GUI;, you have to do that manually
+and copy the following files to the target user:</para>
+<para>&kmenuedit; stores the menu hierarchy in
+<filename class="directory">$<envar>HOME</envar>/.config/menus/applications-kmenuedit.menu</filename>
+and <filename class="directory">$<envar>HOME</envar>/.local/share/desktop-directories</filename>
+contains desktop files for submenus you created.
+In <filename class="directory">$<envar>HOME</envar>/.local/share/applications/</filename> you
+find the desktop files for the custom items you created.
+</para>
+<para>The shortcuts for each application are stored in <filename>~/.kde/share/config/kglobalshortcutsrc</filename>,
+but export/import does not work because the UUIDs of the shortcuts do not match up between systems, even though the
+<filename class="extension">.desktop</filename> files are the same. You have to assign all shortcuts manually again.
+</para>
+
+</sect2>
+
+</sect1>
</chapter>
<chapter id="quickstart">
@@ -126,7 +250,14 @@ Press return, and you should see something like the picture below in the main wi
</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 application launcher 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>
+Now lets fill in the <guilabel>Description:</guilabel>, in this case type <userinput>Web Browser</userinput>.
+<note><para>The appearance how description and name will be displayed depends on the settings in the application
+launcher ⪚ <quote>Web Browser (Firefox)</quote> or <quote>Firefox (Web Browser)</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>
+<para>The command has to be in your <envar>PATH</envar> variable or you have to specify the full path to the executable.
+If you do not know the executable name of an application use the <userinput><command>locate</command></userinput>
+command to search for the desktop file and enter the string from the Exec line as command here.
+</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>
@@ -168,11 +299,10 @@ To see all options for an application launch <userinput><command><replaceable>ap
</mediaobject>
</screenshot></para>
-<para>The place of the new menu item can now be changed using <guibutton>Move Up</guibutton> and <guibutton>Move Down</guibutton> buttons on the &kmenuedit; toolbar.</para>
-
+<para>The place of the new menu item can now be changed using <guibutton>Move Up</guibutton> and <guibutton>Move Down</guibutton> buttons on the &kmenuedit; toolbar or by dragging with the mouse.</para>
<para>The submenu items can be sorted using <guibutton>Sort</guibutton> button on the &kmenuedit; toolbar or <menuchoice><guimenu>Edit</guimenu><guisubmenu>Sort</guisubmenu></menuchoice> submenu items.</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 application launcher <guisubmenu>Internet</guisubmenu> submenu!</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 application launcher <guisubmenu>Internet</guisubmenu> submenu.</para>
</chapter>
@@ -226,6 +356,10 @@ application.
<listitem><para>When checked, the application entry will only be visible in all &kde; application launchers but not in other desktops environments.
</para></listitem>
</varlistentry>
+<varlistentry>
+<term><guilabel>Hidden entry</guilabel></term>
+<listitem><para>Remove an entry from the menu view in the application launcher. </para></listitem>
+</varlistentry>
</variablelist>
</sect1>
@@ -285,6 +419,9 @@ fileref="reset.png" format="PNG"/></imageobject></inlinemediaobject>.
<chapter id="menu-reference">
<title>Menu Reference</title>
+<para>Most actions in the menubar are also available in the context menu opened with a &RMB;
+click on an item in the tree view.</para>
+
<variablelist>
<varlistentry id="file-new-item">
<term><menuchoice>
@@ -375,7 +512,7 @@ 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
+function to paste the copied menu item from the clipboard to its destination. You
can paste the same item many times.</para></listitem>
</varlistentry>
@@ -387,7 +524,7 @@ can paste the same item many times.</para></listitem>
<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
+selected place in the main menu. You must first use
<guimenuitem>Cut</guimenuitem> or <guimenuitem>Copy</guimenuitem> before you can
<guimenuitem>Paste</guimenuitem>.</para></listitem>
</varlistentry>
More information about the kde-doc-english
mailing list