Added old KDE3 version of Krusader

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

1 files changed, 644 insertions, 0 deletions

diff --git a/doc/en/useractions.docbook b/doc/en/useractions.docbook
new file mode 100644
index 0000000..2c3b5fd
--- /dev/null
+++ b/doc/en/useractions.docbook
@@ -0,0 +1,644 @@
+<sect1 id="useractions">
+  <!-- **********************************************************************
+                            useractions.docbook
+                          ++++++++++++++++++++++++++
+ (C)opyright            : (C) 2000 - 2008
+  All Rights Reserved     Rafi Yanai, Shie Erlich, Frank Schoolmeesters
+                          & the Krusader Krew
+  e-mail                : krusader@users.sourceforge.net
+  web site              : http://www.krusader.org
+  description           : a Krusader Documentation File
+
+***************************************************************************
+* Permission is granted to copy, distribute and/or modify this            *
+* document under the terms of the GNU Free Documentation License,         *
+* Version 1.1 or any later version published by the Free Software         *
+* Foundation; with no Invariant Sections, no Front-Cover Texts and        *
+* no Back-Cover Texts.  A copy of the license is available on the         *
+* GNU site http://www.gnu.org/licenses/fdl.html or by writing to:         *
+* Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,    *
+* MA 02110-1301, USA.                                                     *
+*********************************************************************** -->
+  <title>UserActions</title>
+  <indexterm>
+    <primary>UserActions</primary>
+  </indexterm>
+  <!-- Thanks to Jonas Bar -->
+  <para>With ActionMan you can set up, configure and manage
+  UserActions. Some general settings are configured with 
+  <link linkend="konfig-useractions">Konfigurator</link>. With
+  UserActions you can perform actions on files in the panel or to
+  access &krusader; internal functions with parameters
+  directly using placeholders. The actions integrate seamlessly
+  into &kde;'s action system, which means that the
+  standard Edit Toolbar and Edit Shortcut dialogs will show
+  UserActions, too. The UserActions are stored in 
+  <filename>
+  ~/.kde/share/apps/krusader/useraction.xml</filename> (the file
+  structure is documentated in doxygen headers of UserActionXML).
+  Several 
+  <link linkend="useraction-xml">examples</link> are included in the
+  documentation. UserActions can be edited / added / imported /
+  exported by using ActionMan. The default UserActions are stored
+  in 
+  <filename>
+  ~/.kde/share/apps/krusader/useraction-examples.xml</filename>.
+  UserActions can appear nearly everywhere where "normal" KActions
+  can be placed. The actions integrate seamlessly into
+  &kde; action system, which means that the standard
+  Edit Toolbar and Edit Shortcut dialogs will show UserActions,
+  too. They can even be placed in the menu bar, but for that the 
+  <filename>krusaderui.rc</filename> file must be edited. A few
+  examples: 
+  <itemizedlist>
+    <listitem>
+      <para>
+        <link linkend="useractions-menu">Useractions Menu</link>
+      </para>
+    </listitem>
+    <listitem>
+      <para>&usermenu-lnk;</para>
+    </listitem>
+    <listitem>
+      <para>&actions-toolbar-lnk;</para>
+    </listitem>
+    <listitem>
+      <para>right click menus</para>
+    </listitem>
+    <listitem>
+      <para>&etc;</para>
+    </listitem>
+  </itemizedlist>&krusader;'s UserActions tool is very
+  powerful and customizable if you are familiar with writing
+  UserActions in general.</para>
+  <tip>
+    <para>Several UserActions are provided by default. Please 
+    <link linkend="help_krusader">upload your favorite
+    UserActions</link> so that they become available for the
+    &krusader; community. Thanks! We provide also an
+    &useractionsforum-url;.</para>
+  </tip>
+  <figure id="screenshot-actionman" float="1">
+    <title>ActionMan</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="actionman.png"></imagedata>
+      </imageobject>
+      <textobject>
+        <phrase>ActionMan</phrase>
+      </textobject>
+    </mediaobject>
+  </figure>
+  <para>Basically, UserActions are a method to call external
+  programs with variable parameters. For example, you could have a
+  UserAction with the following 
+  <command>xmms 
+  <option>--enqueue %aList("Selected")%</option></command> to
+  enqueue all selected items of the active panel to the current
+  instance of xmms. Additionally, there is limited access to
+  &krusader; internal functions requiring parameters.
+  For example, 
+  <command>%aPanelSize("80")%</command> will set the width of the
+  active panel to 80% of the &krusader; mainwindow.
+  Since the parameter of placeholders can contain other
+  placeholders, few scripts are possible. However, scripting can be
+  done with the &javascript-console-lnk;.</para>
+  <para>
+    <emphasis role="bold">Managing UserActions</emphasis>
+  </para>
+  <para>Open Konfigurator and choose "UserActions -&gt;
+  ActionMan", in which you can add, edit, remove, import and export
+  UserActions. 
+  <itemizedlist>
+    <listitem>
+      <para>
+      <guimenuitem>Add Action</guimenuitem>: If you add an new
+      action, you get an empty input mask where you can enter all
+      the properties you desire. The action will be added as soon
+      as you press 
+      <guimenuitem>Ok</guimenuitem>. Afterwards, the name is shown
+      in the list on the left.</para>
+    </listitem>
+    <listitem>
+      <para>To edit a UserAction: Select the UserAction on the
+      left. Then choose it if you want to edit its properties. The
+      changes will only take effect when you press 
+      <guimenuitem>OK</guimenuitem>.</para>
+    </listitem>
+    <listitem>
+      <para>
+      <guimenuitem>To remove a UserAction</guimenuitem>: Select the
+      UserAction on the left and click the remove button.</para>
+    </listitem>
+    <listitem>
+      <para>
+      <guimenuitem>To import a UserAction</guimenuitem>: If you
+      import some actions, they will be automatically added to your
+      list. If there are name conflicts (the names have to be
+      unique because these are the ID for &kde;'s action
+      system), you are asked to resolve them. For this, the list on
+      the left will only show the actions where conflicts exist.
+      You can now give them new names or remove them.</para>
+    </listitem>
+    <listitem>
+      <para>
+      <guimenuitem>Export Action</guimenuitem>: If you export a
+      UserAction you have to give a filename in which to store it.
+      If it does not exist, it will be created. If the file already
+      contains UserActions, the action you are exporting will be
+      added to that file.</para>
+    </listitem>
+  </itemizedlist>All actions you have defined are now shown in the
+  user menu and in &kde; dialogs for changing shortcuts
+  and managing the toolbar. In addition, all actions available for
+  the current item will also show up in the right click
+  menu.</para>
+  <para>
+    <emphasis role="bold">
+      <guimenuitem>Basic Properties</guimenuitem>
+    </emphasis>
+  </para>
+  <para>
+  <guimenuitem>"Distinct Name", "Title" and "Command
+  line"</guimenuitem>are always required, all the other properties
+  are optional. 
+  <itemizedlist>
+    <listitem>
+      <para>
+      <guimenuitem>"Distinct Name"</guimenuitem>: A unique name of
+      the UserAction, used to identify it for &kde;'s
+      action system.</para>
+    </listitem>
+    <listitem>
+      <para>
+      <guimenuitem>"Icon button"</guimenuitem>: The icon for your
+      UserAction.</para>
+    </listitem>
+    <listitem>
+      <para>
+      <guimenuitem>"Category"</guimenuitem>: Adds a category for a
+      better overview. NOTE: This property is not used yet. It is
+      planned to be used, but has not implemented yet.</para>
+    </listitem>
+    <listitem>
+      <para>
+      <guimenuitem>"Title"</guimenuitem>: The title displayed in
+      the menus or dialogs.</para>
+    </listitem>
+    <listitem>
+      <para>
+      <guimenuitem>"Tooltip"</guimenuitem>: A tooltip for your
+      UserAction, &eg; displayed in the toolbar on
+      mouseover.</para>
+    </listitem>
+    <listitem>
+      <para>
+      <guimenuitem>"Description"</guimenuitem>: A description of
+      what the UserAction does. This is also displayed as 
+      <guimenuitem>"What's This"</guimenuitem> if you 
+      <keycombo action="simul">&Shift;
+      <keycap>F1</keycap></keycombo> click on your
+      UserAction.</para>
+    </listitem>
+    <listitem>
+      <para>
+      <guimenuitem>"Use Tooltip checkbox"</guimenuitem>: Uses the
+      tooltip as description.</para>
+    </listitem>
+    <listitem>
+      <para>
+      <guimenuitem>"Command line"</guimenuitem>: The command which
+      will be executed. You can add placeholder using a GUI with
+      the 
+      <guibutton>add</guibutton> button.</para>
+    </listitem>
+    <listitem>
+      <para>
+      <guimenuitem>"Startpath"</guimenuitem>: The working directory
+      for the command which will be executed.</para>
+    </listitem>
+    <listitem>
+      <para>
+      <guimenuitem>"Execution mode"</guimenuitem>:</para>
+      <itemizedlist>
+        <listitem>
+          <para>
+          <guimenuitem>"Normal"</guimenuitem>: Normal execution
+          mode.</para>
+        </listitem>
+        <listitem>
+          <para>
+          <guimenuitem>"Run in terminal"</guimenuitem>: Runs the
+          command in the terminal.</para>
+        </listitem>
+        <listitem>
+          <para>
+          <guimenuitem>"Collect output"</guimenuitem>: Collects the
+          output of the executed program in a &GUI;
+          window.</para>
+        </listitem>
+        <listitem>
+          <para>
+          <guimenuitem>"Separate standard error"</guimenuitem>:
+          When "Collect output" is used the stdout and stderr are
+          separately collected.</para>
+        </listitem>
+      </itemizedlist>
+    </listitem>
+    <listitem>
+      <para>
+      <guimenuitem>"Command accepts"</guimenuitem>:</para>
+      <itemizedlist>
+        <listitem>
+          <para>
+          <guimenuitem>"Local files (no URLs)"</guimenuitem>: Tells
+          the placeholder it should return local addresses.</para>
+        </listitem>
+        <listitem>
+          <para>
+          <guimenuitem>"URLs (local and remote)"</guimenuitem>:
+          Tells the placeholder it should return
+          &URL;s.</para>
+        </listitem>
+      </itemizedlist>
+    </listitem>
+    <!--    Not yet implemented, but will be after 1.50 stable is released
+        <listitem><para><guimenuitem>"On multiple selection"</guimenuitem>:  </para>
+        <itemizedlist>
+   <listitem><para><guimenuitem>"separate call for each file"</guimenuitem>: executes the command for each selected file.
+             </para></listitem>
+         </itemizedlist>
+      </listitem> -->
+    <listitem>
+      <para>
+      <guimenuitem>"Shortcut button"</guimenuitem>: Configures a
+      shortcut for the UserAction.</para>
+    </listitem>
+  </itemizedlist></para>
+  <para>
+    <emphasis role="bold">Command-line syntax:</emphasis>
+  </para>
+  <para>Basically, everything you type in the command line will get
+  executed (if you type "ls -l", "ls -l" gets executed). You have
+  the possiblity to get a character string from
+  &krusader; which represents the current state of the
+  panel. This is done using placeholders. A placeholder begins with
+  a percent-sign ('%') and is followed by a panel indicator ('a'
+  for the active, 'o' for the other, 'l' for the left and 'r' for
+  the right panel. If the placeholder doesn't need a panel to
+  operate on, you have to indicate this by an underscore ('_')).
+  Then comes the name of the placeholder (see the list below),
+  which may get some parameters enclosed in quotes. Finally, again
+  the percent sign.</para>
+  <para>This sounds very complicated, so let's make an example:
+  '%aList("Selected")%' is replaced by a list of all selected items
+  in the active panel. So a command like 'xmms --enqueue
+  %aList("All", " ", "", "*.mp3")%' will execute xmms with a list
+  of all .mp3s in the current panel, separated by a single
+  blank.</para>
+  <para>Currently, these placeholders are implemented: 
+  <itemizedlist>
+    <listitem>
+      <para>
+      <userinput>Path</userinput> - replaced by the panels
+      path</para>
+      <orderedlist>
+        <listitem>
+          <para>&useraction-optional-parameter;
+          Automatic escape spaces. &useraction-default;
+          yes</para>
+        </listitem>
+      </orderedlist>
+    </listitem>
+    <listitem>
+      <para>
+      <userinput>Count</userinput> - replaced by the number of
+      &lt;first parameter&gt;</para>
+      <orderedlist>
+        <listitem>
+          <para>&useraction-parameter; Which items;
+          either "All", "Selected", "Files" or "Dirs"</para>
+        </listitem>
+      </orderedlist>
+    </listitem>
+    <listitem>
+      <para>
+      <userinput>Filter</userinput> - replaced by the panel's filter
+      mask</para>
+    </listitem>
+    <listitem>
+      <para>
+      <userinput>Current</userinput> - replaced by the current
+      item</para>
+      <orderedlist>
+        <listitem>
+          <para>&useraction-optional-parameter; Omit the
+          current path. &useraction-default; no</para>
+        </listitem>
+        <listitem>
+          <para>&useraction-optional-parameter;
+          Automatic escape spaces. &useraction-default;
+          yes</para>
+        </listitem>
+      </orderedlist>
+    </listitem>
+    <listitem>
+      <para>
+      <userinput>List</userinput> - replaced by a list of all
+      &lt;first parameter&gt;</para>
+      <orderedlist>
+        <listitem>
+          <para>&useraction-parameter; Which items;
+          either "All", "Selected", "Files" or "Dirs"</para>
+        </listitem>
+        <listitem>
+          <para>&useraction-optional-parameter;
+          Separator between the items.
+          &useraction-default;
+          "&nbsp;"</para>
+        </listitem>
+        <listitem>
+          <para>&useraction-optional-parameter; Omit the
+          current path. &useraction-default; no</para>
+        </listitem>
+        <listitem>
+          <para>&useraction-optional-parameter;
+          Filtermask (for all but "Selected").
+          &useraction-default; *</para>
+        </listitem>
+        <listitem>
+          <para>&useraction-optional-parameter;
+          Automatic escape spaces. &useraction-default;
+          yes</para>
+        </listitem>
+      </orderedlist>
+    </listitem>
+    <listitem>
+      <para>
+      <userinput>Select</userinput> - manipulates the selection in a
+      panel</para>
+      <orderedlist>
+        <listitem>
+          <para>&useraction-parameter; Filtermask</para>
+        </listitem>
+        <listitem>
+          <para>&useraction-optional-parameter;
+          manipulate in which way; either "Set", "Add" or "Remove".
+          &useraction-default; "Set"</para>
+        </listitem>
+      </orderedlist>
+    </listitem>
+    <listitem>
+      <para>
+      <userinput>Goto</userinput> - changes the panels' path to
+      &lt;first parameter&gt;</para>
+      <orderedlist>
+        <listitem>
+          <para>&useraction-parameter; A relative or
+          absolute path, or an URL</para>
+        </listitem>
+        <listitem>
+          <para>&useraction-optional-parameter; Open the
+          location in a new tab. &useraction-default;
+          no</para>
+        </listitem>
+      </orderedlist>
+    </listitem>
+    <listitem>
+      <para>
+      <userinput>Ask</userinput> - asks the user for some text and
+      is replaced by the answer</para>
+      <orderedlist>
+        <listitem>
+          <para>&useraction-parameter; The
+          Question</para>
+        </listitem>
+        <listitem>
+          <para>&useraction-optional-parameter; A
+          default answer</para>
+        </listitem>
+        <listitem>
+          <para>&useraction-optional-parameter; A
+          caption for the question box</para>
+        </listitem>
+      </orderedlist>
+    </listitem>
+    <listitem>
+      <para>
+      <userinput>Clipboard</userinput> - manipulates the
+      clipboard</para>
+      <orderedlist>
+        <listitem>
+          <para>&useraction-parameter; The text that
+          should go to the clipboard (you may want to use
+          "%aCurrent%" here)</para>
+        </listitem>
+        <listitem>
+          <para>&useraction-optional-parameter; Append
+          the text to the current content of the clipboard with
+          this separator</para>
+        </listitem>
+      </orderedlist>
+    </listitem>
+    <listitem>
+      <para>
+      <userinput>Copy</userinput> - copies a file, useful for quick,
+      local backups</para>
+      <orderedlist>
+        <listitem>
+          <para>&useraction-parameter; What should be
+          copied</para>
+        </listitem>
+        <listitem>
+          <para>&useraction-parameter; Where it should
+          be copied</para>
+        </listitem>
+      </orderedlist>
+    </listitem>
+    <listitem>
+      <para>
+      <userinput>Sync</userinput> - opens the Synchronizer with a
+      given profile</para>
+      <orderedlist>
+        <listitem>
+          <para>&useraction-parameter; A profile for the
+          Synchronizer</para>
+        </listitem>
+      </orderedlist>
+    </listitem>
+    <listitem>
+      <para>
+      <userinput>NewSearch</userinput> - opens the search windows
+      with a given profile</para>
+      <orderedlist>
+        <listitem>
+          <para>&useraction-parameter; A profile for the
+          search module</para>
+        </listitem>
+      </orderedlist>
+    </listitem>
+    <listitem>
+      <para>
+      <userinput>Profile</userinput> - loads a given panel
+      profile</para>
+      <orderedlist>
+        <listitem>
+          <para>&useraction-parameter; A panel
+          profile</para>
+        </listitem>
+      </orderedlist>
+    </listitem>
+    <listitem>
+      <para>
+      <userinput>Each</userinput> - splits the commandline into a
+      list. These commands are executed one after another.</para>
+      <orderedlist>
+        <listitem>
+          <para>&useraction-parameter; A list item (all,
+          all files, all dirs, all selected).</para>
+        </listitem>
+      </orderedlist>
+    </listitem>
+    <listitem>
+      <para>
+      <userinput>Move</userinput> - move from source to
+      destination.</para>
+      <orderedlist>
+        <listitem>
+          <para>&useraction-parameter; A source</para>
+        </listitem>
+        <listitem>
+          <para>&useraction-parameter; A
+          destination</para>
+        </listitem>
+      </orderedlist>
+    </listitem>
+    <listitem>
+      <para>
+      <userinput>PanelSize</userinput> - change the ratio between
+      the two panels.</para>
+      <orderedlist>
+        <listitem>
+          <para>&useraction-optional-parameter; A
+          integer value, e.g., 80 makes the active panel use 80% of
+          &krusader;'s width (height in vertical mode),
+          omitting the parameter means 50%.</para>
+        </listitem>
+      </orderedlist>
+    </listitem>
+    <listitem>
+      <para>
+      <userinput>Ask</userinput> - cancel the execution.</para>
+      <orderedlist>
+        <listitem>
+          <para>&useraction-optional-parameter; A string
+          for the cancel question.</para>
+        </listitem>
+      </orderedlist>
+    </listitem>
+    <listitem>
+      <para>
+      <userinput>Script</userinput> - executes an external 
+      <link linkend="javascript_console">
+      Javascript</link> file.</para>
+      <para>NOTE: This is still experimental and the interface may
+      change, feedback is always welcome.</para>
+      <orderedlist>
+        <listitem>
+          <para>&useraction-parameter; path to the
+          external foo.js file, absolute path or relative to 
+          <filename>
+          &lt;kde-app-data&gt;/krusader/js/</filename>.
+          &lt;kde-app-data&gt; is 
+          <filename>$(kde-config
+          --localprefix)/share/apps/</filename> or 
+          <filename>$(kde-config --prefix)/share/apps/</filename>,
+          for those who don't know where to copy the
+          scripts/extensions. If all the needed files (normally 
+          <filename>.js</filename> and maybe 
+          <filename>.ui</filename>) are in one of these dirs it's
+          sufficient to give the file name only as 1.
+          parameter.</para>
+        </listitem>
+        <listitem>
+          <para>&useraction-optional-parameter; a list
+          of variables which should be set, like "return=cmd;
+          a=lalala; b='%_Ask(..)'" so that the placeholder is
+          replaced be the content of the variable cmd and the other
+          two have already these values when the script
+          starts.</para>
+        </listitem>
+      </orderedlist>
+    </listitem>
+    <listitem>
+      <para>
+      <userinput>ListFile</userinput> - is replaced by path/file name
+      of a temporary file containing a list of items</para>
+      <orderedlist>
+        <listitem>
+          <para>&useraction-parameter;
+          path/filename</para>
+        </listitem>
+      </orderedlist>
+    </listitem>
+    <listitem>
+      <para>
+      <userinput>ColSort</userinput> - set the sorting on a column
+      of a specific panel.</para>
+      <orderedlist>
+        <listitem>
+          <para>&useraction-parameter; Column: Either
+          "Name", "Ext", "Type", "Size", "Modified", "Perms",
+          "rwx", "Owner" and "Group"</para>
+        </listitem>
+        <listitem>
+          <para>&useraction-parameter; Sort sequence:
+          Either "Toggle", "Asc", "Desc"</para>
+        </listitem>
+      </orderedlist>
+    </listitem>
+    <listitem>
+      <para>
+      <userinput>View</userinput> - set the view mode.</para>
+      <orderedlist>
+        <listitem>
+          <para>&useraction-parameter; View mode: Either
+          "generic", "text", "hex"</para>
+        </listitem>
+        <listitem>
+          <para>&useraction-parameter; Window Mode:
+          Either "tab", "window"</para>
+        </listitem>
+      </orderedlist>
+    </listitem>
+  </itemizedlist>A GUI-based helper for placeholder adding is
+  provided. Spaces In Path, Current and List are by default,
+  automatically escaped. There is one more important thing to know:
+  All placeholders that interact with &krusader;
+  internal functions are called at expand time (meaning directly
+  when the placeholders are replaced). External programs are
+  called at execution time (meaning after all placeholders are
+  replaced).</para>
+  <para>
+    <emphasis role="bold">
+      <guimenuitem>Advanced Properties</guimenuitem>
+    </emphasis>
+  </para>
+  <para>Here you can configure where your command should be visible
+  (for the right click menu) In addition, it is possible to change
+  the command executed and confirm it separately. You can also set
+  a user under which the command should be executed. 
+  <itemizedlist>
+    <listitem>
+      <para>Configures if the action is valid for a Protocol, Path,
+      Mime type or File name.</para>
+    </listitem>
+    <listitem>
+      <para>Tweaking the command line before being executed.</para>
+    </listitem>
+    <listitem>
+      <para>Set a different user for the execution (this has no
+      effect in &krusader; internal functions)</para>
+    </listitem>
+  </itemizedlist></para>
+</sect1>