		  emelFM2 help
		+---------------+

Note for translators: headings in this document that are surrounded by [] are search targets for context-specific help. The name inside the [] needs to match the translated name of the corresponding help-dialog page. Other headings here are simply capitalised.

INTRODUCTION

This document records advice, tips, answers to questions etc that might assist emelFM2 (e2) users. The content is work-in-progress. If you identify anything to usefully add here, mail tooar about it.

[usage]

STARTUP

Various command-line switches can be used, to determine aspects of the way an e2 session operates:
Program options:
-1,--one=DIR           set 1st pane's start directory to DIR
-2,--two=DIR           set 2nd pane's start directory to DIR
-c,--config=DIR        set config directory to DIR (default: ~/.emelfm2)
-d,--debug=[1-5]       set debug level from 1/error to 5/debug
-e,--encoding          set filesystem coding (include "ascii" or "ASCII" in this, to omit file path/name conversions) 
-f,--fallback-encoding set fallback encoding (default: ISO-8859-1)
-i,--ignore-problems   ignore encoding/locale problems (at your own risk!)
-l,--leave-alone       don't suppress gtk output on console
-n,--no-detach         don't detach from terminal
-r,--run-at-start      command to run immediatly after start
-s,--set-option        set one-line gui options in config file format
-t,--trash=DIR         set trash directory to DIR (default: ~/.emelfm2/Trash)
-x,--verbose           display time/location info on debug output
Help options:
-h,--help              show this help message
-u,--usage             display brief usage messsage
-v,--version           display version and build info

USER INTERFACE

The core elements of the UI are:
  lists showing information about the items in two directories
     (or one, if the pair show the same directory);
  a place where e2 messages, output from commands etc is shown; and
  four toolbars.

The directory lists and message area generally referred to here as "panes", and in particular, "file panes" or "output pane".

The file panes can be tiled side-by-side, or top-to-bottom. "Pane 1" is on the left, if the file panes are tiled side-by-side, or on the top, if the panes are tiled top-to-bottom. "Pane 2" is on the right, if the file panes are tiled side-by-side, or on the bottom, if the panes are tiled top-to-bottom.

At any time, one of the two file panes will be 'active' (have focus). The active pane is normally indicated by changed color of the column headers in the pane. However re-coloring does not work with some Gtk themes. If that applies to you, change the relevant setting on the 'panes' page of the configuration dialog (see the CONFIGURATION section, below), to enable bold column titles, as an alternative indicator.

The file panes can re-sized, or hidden, by dragging the separator or clicking a relevant toolbar button. The output pane can be resized, up to the full window size, or hidden, likewise by dragging or clicking.

You can change the order of columns displayed in either file pane. Press the mouse left-button while the mouse cursor is on the header of the column you want to move. Then drag it to where you want. Such change will be remembered between sessions.

You can change the width of any column by dragging the relevant column-separator. (There is a minimum size, related to the size of the column label.) You can hide any column by un-checking the corresponding column on the 'columns' page of the configuration dialog. Such changes will be remembered between sessions.

You can sort a file list according to the data in any column, by left-clicking on the column's header. Repeated clicks toggle the sort-order. The actual order that results depends on the user's locale settings. The result might be different from the  'traditional' way.

Right-clicking on a file pane or output pane will pop up a menu of things you may wish to do, there. For the file panes, a sub-menu can be opened by pressing a <shift> or <ctrl> button before right-clicking.

The toolbars are referred to as "pane1 bar", "pane2 bar", "task bar" and "command bar". The pane1 bar is by default at the top of pane 1. The pane2 bar is by default shown at the top of pane 2. The task bar is by default shown between the file panes. The command bar is by default shown near the bottom of the window.

Pane1 bar and pane2 bar typically have the same items in them, in mirrored order (more or less). Commands initiated by the items in those bars apply to the respective pane. Task bar items mostly relate to the active pane. (By default it includes a 'refresh' button which updates both panes.) Command bar items relate to the output pane, or other miscellaneous commands.

Both pane1 bar and pane2 bar typically have a combo box where the user can enter or select a directory to be shown in the corresponding pane (referred to a a "directory line"). In addition to normal choice, clicking the middle mouse button in a directory line, or pressing <Ctrl>Tab while a directory line is 'focused', will open a directory-selection dialog.

By default, toolbar buttons will show tooltips, for those of us less familiar with the icons. You can change the button style to include labels, if you wish. Right-click on a toolbar to see its context menu, which includes settings which can be changed. Or open the configuration dialog, and on the relevant bar's 'options' page, change the 'button-style' option.

FINDING ITEMS

Typing, while a filepane is focussed, will select the first item whose name begins with the typed characters (not case sensitive). That item might be before or after the current position. A small window pops open near the bottom of the pane, showing the characters typed sofar.

By default the keys <Ctrl>f & F3, and a button on the command bar, will allow you to find an item in the active pane by entering into a dialog any part of the item's name. Wildcards may be entered. When scanning, this action loops round from either end of the filelist to the other end.

A find plugin allows heavy-duty searching, with that you can find item(s) anywhere, and by many attributes.

ENTRY COMPLETION

By default, the Tab key is bound to an action (see KEY BINDINGS section, below) which "completes" entries in directory lines or the command line, as follows.

When entering a path into a directory line, pressing the Tab key will complete that entry, if there is only one valid completion. If there is more than one such completion, they will be listed in the output pane. (Note also that pressing <Ctrl>Tab will open a directory-selection dialog.)

In general, when entering text into the command line, pressing the Tab key will complete the "word" that is being entered. If the entered string starts with "./", the word will be completed using the matching item-name from the active pane. If the entered string does not start with "./", the word will be completed using the matching item-name from all directories specified in the $PATH environment variable. If there is more than 1 item which could validly complete the word, those items will be listed in the output pane.

The exception to the previous paragraph is when the entered command is "mount" or "umount". A "mount" command will be completed with a valid mount point, a "umount" command will be completed with a valid unmountable partition. Again, if there is more than one possible completion, they will be listed in the output pane. Note that this form of completion is permission-depenant, so in many instances, there will be nothing valis to show. 

KEY BINDINGS

Various keys are assigned specific tasks within e2.

To get a listing of the current e2 key bindings, enter the command 'keys' on the command line. You can also type 'keys panes', 'keys command line' or 'keys directory lines' to see the subset of bindings relevant to those places.  (Note 'keys' in this context is a default alias, and should be translated, and may be changed by the user.)

Any key can be assigned to more than one thing, by including the key in a binding more than once.

Pressing any 'unbound' key while the focus is on a file pane opens a small  window in which you can continue typing a name, and an item whose name matches what you type will be selected.

SELECTION

In general, things may be selected in accordance with gtk's normal method for doing so. For example, selecting items in a file-pane is done by combinations of left-burron-clicks, ctrl-key+left-clicks (which toggle selection-state of the clicked item) and shift-key+left-click (which select the range from previously-selected item to the clicked item).

As a special case, e2 (except 0.1.0 to 0.1.2) also supports selection of file-pane items by dragging. The protocol for this is: press left mouse button when the cursor is on an item, then press a control key, then drag the mouse cursor over item(s) to be selected. (A bit complex, so as to not interfere with gtk's normal selection and DnD processes.)

DRAG & DROP

Drag and drop can be performed in the standard gtk fashion, i.e. by selecting the item(s) you want to process (see SELECTION above), then dragging to a location in either of the file lists, or to any other compatible application. When dragging by left-button, the default operation is to copy the selected item(s) to the drop-target but the action will be different if 'modifer' key(s) are pressed at the time of the drop. As usual, if the Shift key is presssed while dropping, the selection will be moved; or if both Shift and Control are pressed, the selection will be linked; or if the Alt key is pressed, a menu will prompt you for the operation you want to perform (the menu allows copy/move/link/cancel). To prevent gtk from treating the process as something other than a drag, the modifier key(s) need to be pressed after the drag has started.

You may instead perform a drag with the middle-button, which behaves the same as left-plus-Alt i.e. always pops up that action menu. Note that there is an option to make middle-button clicks open the parent directory of the one where the click occurred, and it that option is in force, it may interfere with dragging by middle-button.

If you drop ONto a directory (other than one that's part of the selection being dropped), the selected item(s) will be copied/moved/linked INto that directory. This means you can copy/move/link any item into a subdirectory without opening that directory in the other pane.

If you don't drop onto a directory, the item(s) will be copied/moved/linked to the directory whose contents are displayed in that pane (if it's not the same as the source directory, of course)

It is also possible to drag and drop between different instances of emelFM2 and between emelFM2 and some other gtk-based applications like nautilus, Gnome Midnight Commander and GQView. In some cases it might work in only one direction.

TRASH

When e2 puts something into trash, it will first try to use a folder named '.Trash' in the directory the item(s) come from i.e. the one shown in the active pane. If such a folder doesn't exist, fallback choices are: '.Trash' in the user's home directory, then finally, '.emelfm2/Trash' in the user's  home directory. The last of these will be created if it didn't exist already.

There is no over-write checking for trashed items. Any item with the same name, already in the trash, will simply be erased.

OPERATIONS ON DIRECTORIES

Operations (copy, move etc) on item(s) in the active file pane are performed on the selected items, as would be expected. If a selected item is a directory, the operation applies to the directory as a whole (with its contents), NOT just to the contents of the directory. This means that if, say, a directory is moved, and in so doing over-writes another directory of the same name (usually after the user's confirmation), then the destination directory and all its contents will be replaced by the source directory and all its contents. The effect of this is that all of the contents of the destination directory are lost. Just like all the contents of a file are lost if it is over-written.

If you want to operate only on the contents of a directory, you must open the directory and select the contents explicitly.

BOOKMARKS

As you would expect, these are a mechanism for opening a particular directory with minimal effort.

By default, the pane1 bar and pane2 bar, and the file pane context menu, include a bookmarks sub-menu. Actually, they are a bit more complex than a standard sub-menu - each includes its own context menu (yes, we know, peculiar UI design ..)  with items for adding the currently-displayed to, or removing it from, the recorded bookmarks. This is a quick alternative to opening the configuration dialog to re-arrange bookmarks.

Though accessible by these several menus, there is only one bookmarks list, which applies to both panes.

PLUGINS

These are effectively chunks of code that provide optional, additional capability for e2. Any of them may be cofigured to load (i.e. be ready to run) or not, depending on the user's expected need for it. (With a big, fast computer, just load them all and get on with life ...) Descriptions of the current plugins are provided in the respecitive tooltips, which can be displayed in the plugins context-sub-menu, or the plugins page of the configuration dialog. The view plugin always runs the internal viewer for text files, and so it is useful only if your default file viewer is set to be some external viewer.

Any plugin might only be needed for a key binding, or a toolbar button action, for example. So a loaded plugin may be configured to appear in the plugins context menu, or not. Plugin configuration settings are preserved until changed by the user.

If all goes according to plan, more plugins are coming !

CONFIGURATION

Most things about the e2 user-interface can be changed, if you wish. Hopefully the default settings are such that changes, if any, will be rare.

Settings can be viewed or changed in the configuration dialog. Open that by clicking the relevant button near the right-end of the command bar, or by pressing the F11 key (unless you've already changed the configuration of those things ..)

A separate document titled CONFIGURATION gives more specific guidance about e2 settings and how to change them.

e2 configuration data are saved, between sessions, in 2 files: one ('cache') stores data related to run-time detals the user did not  specifically set e.g. window size, history lists for visited directories. The other ('config') stores the various parameters set in the configuration dialog. Both those files are by default saved in the directory ~/.emelfm2. If either or both is deleted, e2 will simply revert to default settings for the missing data.

Note that emelfm2 can (and by default does) watch for and respond to changes to the file 'config'. Some file-alteration-monitors that may be in use do not (or at least assert that they do not) follow links, so it is bad practice to make 'config' a link to some other file.

[commands]

Commands used in the emelFM2 (e2) command-line, or associated with a key binding, filetype, alias, are normal shell commands except as set out here.

Multiple commands may be joined by ';', as for normal shells.

In the following, surrounding parentheses ' ' are not part of the actual command.

INTERNAL COMMANDS

Names of e2 internal commands (a.k.a. actions) are of the form 'string1.string2', e.g. 'file.copy'.

Actions may be executed just like an external command, by entering the command name with a '<' in front. You may add argument(s) for an action, with space character(s) between the action name and the first argument, e.g.'<file.view mydocument'.

A detailed description of actions and their arguments is provided in the document ACTIONS. A list of the actions can be found in the configuration dialog, e.g. by clicking on the action column on the 'key bindings' page.

COMMAND MODIFIERS

There are several ways to influence how e2 runs a command (action or external command). One or more of the following may be applied:

* adding '>' to the beginning of an external command will run it in a
   new shell. (NOTE, in particular, this is necessary for commands that
   include any pipe and/or re-direction, and there is an alias to make
   that happen if you forget.)

* adding '|' to the beginning of the command will cause it to 'block'.
   This means nothing else will happen until the command is completed.
   (For commands applied to selected items, any '|' will be ignored, as
   a configuration setting takes precedence)

* adding '!' to the beginning of the command will suppress macro
   expansion. (See below for macros description). This means things
   like '%f' will be treated literally.

* adding '&' to the end of the command will run it in the background,
   and all output other than standard error is suppressed.
   (For commands applied to selected items, any '&' will be ignored, as
   a configuration setting takes precedence)

MACROS

%f = substitute (space-separated series of) quoted itemname(s),
         corresponding to (each) selected item in the active pane
%F = substitute (space-separated series of) quoted pathname(s),
         corresponding to (each) selected item in the inactive pane
%d = substitute the active directory path, quoted
%D = substitute the inactive directory path, quoted

Prepending an extra '%' to the above produces the same result but without quotes

%{"Prompt:"} = open a dialog seeking user input, with 
prompt 'Prompt:', and substitute the entered string

Any other '%' inside a command is simply passed to the application in question.

ALIASES

e2 aliases are a mechanism for replacing part or all of a command string entered into the main command line. The process works pretty much like aliases for command line interfaces generally. Before any command is executed by e2, the recorded aliases are scanned and if a match is found, it will be substituted.

As many command aliases as you wish may be recorded in the e2 configuration  data. By default 'x' will run the default terminal application, and 'keys' will list in the output pane the current key bindings. The full list can be reviewed on the 'aliases' page of the configuration dialog.

An alias can only be matched at the start of the entered command.

Alias strings may include posix extended regular expressions.

A replacement string for an alias may contain \1 or \2. The alias itself will be substituted for \1. The part of the entered command after the alias will be substituted for \2. This means you can, for example, enter a command like 'do this' and have it actually run something like 'do-the-real-command more options that always apply this', or like 'do this and that'.

OTHER SUBSITITUTION

'$VAR' or '${VAR}' will be replaced by the value of the environment variable 'VAR', if that exists. However such replacement will NOT happen if the $VAR or ${VAR} is part or all of a string inside parentheses, e.g. 'string with $VAR' (here, the ' ' are actually part of the string). If the variable is part of a longer string, the ${} form should be used.

'$[OPT]' will be replaced by the current value of the e2 configuration option 'OPT' if it exists. The various option names can be found in the 'config'  file, in lines like 'list-font=Sans 10', where 'OPT' is 'list-font'

Any '~' that is at the start of a command or command-argument, and is followed by a '/', or which is the only content of an argument, will be replaced with the current user's home directory.

COMMUNICATION WITH CHILD PROCESSES

A command of the form 'pid:message' will pipe 'message' to the process with process id 'pid' (the process has to be a child of e2). The piped message will be encoded as utf-8.

You can set 'pid' to 0 to send 'message' to the last-started child. This provides a mechanism to pass input to an application which has been started from the command line, and is waiting for input from the user.

There is no path for getting messages back from child processes, other than for display in the output pane.

EXAMPLES

  diff -c %f %F > %{Filename for patch:}

This runs the diff command to create a patch between the selected files, prompting for the filename for the patch.

  tar xzvf %f -C %D &

This unpacks a selected tarball from the active directory into the inactive directory. Because of the '&' at the end, e2 will not list the output.

  su rpm -Uvh %f

This opens the default terminal application and su's to root, prompting for the root password. Then it executes the RPM update command.

  >rpm -qlip %f | less

This executes an rpm query command and pipes the output to 'less'.
