		  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 (ONLY WORKS IF COMPILED WITH MAKE-OPTION DEBUG=1)
-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.

You can display only items which match specified name(s), date and/or permissions criteria, by setting filter(s) for the pane in question. Do that via dialogs initiated from a toolbar filters button. Directories can be included in the filtering. One or more filters can be used simultaneously. To filter items by name, you provide a string with one or more patterns, each with wildcard(s) "*" and/or "?", in general. (NOTE: there can be no '[...]' character ranges in a pattern, and "*" and "?" cannot be escaped to include them literally in a pattern). If more than one pattern is used, they must be separated by a ",". Any pattern(s) can have "!" prepended, which will cause a matched item to be excluded from the display. To include items whose name begins with "!", prepend "\" to that pattern.  As a convenience, the effect of every pattern in the string can be toggled, by checking the "inverted" box.

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.

The output pane is more than a simple terminal window, it is also intended to be a tool.

You may have as many different output text buffers (aka tabs) as desired. They can be added or removed using the output pane context menu. If more than one tab is in use, numerical tab-titles are shown, for selecting the tab of interest at any time.

Selected text in a tab can be saved, using the relevant context-menu item. The text can be edited, again using the relevant menu item. Not that editing per se is so important, but in particular the editor has the ability to find text, and save the whole buffer. See comments below on EDITING.

Text selected in a tab can be "activated" by a double-click. If that text names an item that conforms to a recognised filetype, that item will be opened just as if it had been in a filelist. Any filepath in the selection is handled.

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. Note that that window will intercept any "Enter" keypress (and the window will then close) so that if you wish to 'activate' the matched item by pressing Enter, you must wait (about 2 seconds) until the window closes, or otherwise, press Enter twice.

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.

TEXT FILE VIEWING

A simple text-file viewer is included in emelFM2. By default, the F3 key is bound to open that. Alernatively, a specified external viewer may be used, if the relevant config option is set.

The internal text file viewer handles several different protocols for line-ends (UNIX, DOS etc), and tries to interpret and convert various character-encodings. Even so, encoding may get the better of it, in which case, the file can't be viewed,or at least, it may contain un-recognizable content. An external encoding-converter can be used instead, if the relevant config option is set, and a converter command is provided there.

When the 'find' function is initiated, a bar of search-related options will be shown near the bottom of the window (and it can be dragged away from there). Of course the bar includes the a place to enter the text sought. That works incrementally, trying to match whatever is entered sofar. There are also options for searching backwards instead of forwards, for ignoring the case of the text sought, and for looping around from either end to the other end, if the search proceeds that far.

Finding can be initiated from the keyboard or a mouse button. The 'Enter' key has been given special privileges: by itself causes the next search, with <Control> it finds the first or (if searching backwards) the last match, and with <Shift> changes the search direction temporarily. Other than that, keys the same as the default button mnemonics may be used, with <Control> or <Alt>. As a special case, <Control>g or <Alt>g will perform a 'find'. The viewer supports the key bindings of a gtk textview widget, other than the ones relating to editing:
 Right  Move cursor one character towards end of file
 Left  Move cursor one character towards start of file
 <Control>Right  Move cursor one word towards end of file
 <Control>Left  Move cursor one word towards start of file
 Up  Move cursor up one line
 Down  Move cursor down one line
 <Control>Up  Move cursor one paragraph towards start of file
 <Control>Down Move cursor one paragrpah towards end of file
 Home   Move cursor to start of line
 End  Move cursor to end of line
 <Control>Home Move cursor to start of file
 <Control>End  Move cursor to end of line
 Page_Up  Move display up one "page"
 Page_Down  Move display down one "page"
 <Control>Page_Up  Move display left one "page"
 <Control>Page_Down  Move display rigth one "page"
 <Control>a   Select all
 <Control>/  Select all
 <Control>\   Unselect all
 <Control>c  Copy selected text to clipboard
 <Control>Insert  Copy selected text to clipboard
 <Control>Tab  Move focus forward
 <Shift><Control>Tab Move focus backard

There is a minimal context menu for changing default configuration.

When done with searching, the bar can be hidden again.

Entered search parameters are remembered for the duration of the current session, but not between sessions.

An action is bound to the key <Shift>F3 to view a file again (re-view), starting at the last-viewed spot in that file. This appies only to the internal viewer.

TEXT FILE EDITING

A "tiny" text-editor is available. By default, the F4 key is bound to open that. Alernatively, a specified external editor may be used, if the relevant config option is set.

The internal editor is quite basic, intended for those little jobs that are hardly worth loading another application. Functions are: find, replace, cut/copy/paste, undo, save, save as, save selection. Selected text can be dragged to another spot. No printing.

Most of these functions can be initiated from the keyboard, and the rest of them from the context menu and/or by button-click. Keyboard bindings set by emelFM2 are the same as the respective mnemonics for buttons and/or context-menu items. As a special case, <Control>z will perform an 'undo'.  The editor also supports the key bindings of a gtk textview widget:
 Those listed above under TEXT FILE VIEWING
 Delete  Delete character at the cursor position
 BackSpace  Delete character before the cursor position
 <Shift>BackSpace  Same as Backspace, to help with mis-typing
 <Control>Delete  Delete characters from cursor position to end of word
 <Control>BackSpace  Delete characters from before cursor position to start of word
 <Control>x  Cut selected text to clipboard
 <Control>v  Paste from clipboard to cursor position
 <Shift>Delete  Cut selected text to clipboard
 <Shift>Insert  Paste from clipboard to cursor position
 Insert  Toggle insert-overwrite mode

See comments above about searching. Replacement choices are made via a similar interface. When active, the bar is stacked below the search options bar.

See comments above about character encoding. The same applies to the editor.

An action is bound to the key <Shift>F4 to re-edit a file, starting at the last-viewed spot in that file. This appies only to the internal editor.

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 !

Now, some specific notes:

[clone plugin]

Copies selected item(s), each with new name as entered by the user, to the current directory.

[copy plugin]

This offers the possibiitiy of pausing the copy process. Any such pause begins at the completion of the item currently being copied. If that's a directory, all its decendants will be competed before the pause.

[disk usage plugin]

Calculates the 'apparent' disk usage of selected item(s). 'Apparent' in the sense that any 'holes' in the file data which are artefacts of the filesystem are not counted in the size, even though they're not avaiable for other purposes.

[directory compare plugin]

Selects items which match items in the other pane. Where relevant, md5 sums are used for the comparison. After selection, items can of course be moved, copied etc, or their names copied, using that plugin. As always, selections can be inverted by pressing Ctrl-i, before processing.

[find plugin]

The choices made for the various buttons shown in this dialog are remembered for at least the duration of the current emelFM2 session. If the plugin is still loaded at the end of a session, then the choices will be saved, and available to be re-loaded next time. However, the various text-entry values are not (yet?) saved.

[find by name]
Here you can enter the name of the file you want to match. The e2 macros %f or %F can be used instead of explicit name(s).

If the "is" option is selected, the find will match any file of that name, which may include wildcard characters:
	* will match any or no characters. For example, the pattern "*.txt" will match files named foo.txt and .txt, but not foo.text.
	? will match any one character.  For example, "wibble.?" will match files named wibble.c and wibble.s, but not wibble. or foo.c.
The "is like" option will match any file whose name contains the string you enter.  For example, the string ".txt" will match the files foo.txt and bar.txt, but not the file baz.text. Again, wildcard characters can be used. 
If the "regular expression" button is selected, all of the regex capabilities of the shell "find" command may be used. In this case, don't search for %f or %F if more than one item is selected.

[find by content]
You may enter a string of characters to search for in files to be matched. For example, to match all files containing "linux" you could either select the "this" option and enter "linux", or select the "like this" option and enter the pattern "*linux*". Regular expression searching is conducted by the shell \"grep\" command, for which there is extensive documentation elsewhere.

[find by mime]
You may enter a string of characters which are all or part of the string representing the mimetype of files to be matched. For example, "pdf" or "application/pdf" would match files in Adobe's PDF format. The string is case-sensitive.

[find by mtime]
These options allow you to find files according to their modification time. That is the last time that the file was saved to disk storage. You can choose whether you want to match files with times earlier than, equal to, <b>and/or</b> later than the time you have entered.

[find by atime]
These options allow you to find files according to their access time. That is the last time that the file was read or executed. You can choose whether you want to match files with times earlier than, equal to, <b>and/or</b> later than the time you have entered."

[find by ctime]
These options allow you to find files according to their inode time. That time is updated whenever a linux file is created, when its atime or mtime is changed, when its mode is changed, and other times too. You can choose whether you want to match files with times earlier than, equal to, and/or later than the time you have entered.

[find by size]
You may enter the size (in bytes, kilobytes or megabytes) of files to be matched. For kb or MB, the size may be like "1.23". You can choose whether you want to match files sized smaller than, equal to, and/or bigger than the size you have entered.

[find by permission]
These options allow you to find files according to their permissions (a.k.a "mode"). You can match against multiple permissions. The ones selected need not be the only ones that apply to matched files.

[find by owner]
These options allow matching files according to their owner and/or group. You can choose to match against the name/group of the logged-in user and/or another specified user or group, or to ignore the user/group. You can also match files without a known user or group by selecting the "Match unknown users" or "Match unknown groups" toggle buttons.

[find by type]
These options allow you to find files according to their type. You can match against multiple types.

[foreach plugin]

Executes an entered command on each selected item separately.

[glob plugin]

Selects items whose name matches a specified pattern.
This is now redundant, equivalent funtionality has been moved into the main application.

[move plugin]

This offers the possibiitiy of pausing the move process. Any such pause begins at the completion of the item currently being moved. If that's a directory, all its decendants will be competed before the pause.

[names copy plugin]

This normally copies the name(s) of selected item(s) to the clipboard.
If a <Shift> key is pressed when the plugin is activated, the full path of each item will be copied, instead of just its name.

[pack plugin]

Archives of these sorts are supported:
    .tar.gz
    .tar.bz2
    .tar
    .zip
    .rar
    .arj

[rename plugin]

Full documentation on regular expressions can be found by running the shell command "man grep", and many other places.

In brief: these are the special characters:
^ match the beginning of the line
$ match the end of line
\ ignore the special meaning of the next character
\\ a literal "\"
- indicates a range when not in the first/last position when specifying ranges with "[" and "]" (see below about LISTs)
| union of regular expressions
[LIST] match a single character specified inside the brackets e.g. [a-z]
[^LIST] do not match a single character specified in the brackets e.g. [^0-9]
. match any single character (including non-printable ones)
* repeat the previous regular expression 0 or more times
+ repeat the previous regular expression 1 or more times
? repeat the previous regular expression 0 or 1 times
(EXP) groups the expression inside the brackets

This means, for example, that ".*" is needed where a wildcard "*" might have been used, and "\." for a literal "."
Your installed software may only support 'basic' regular expressions, in which case any ? + {  |   (  ) needs to be preceded by a  "\".

Groups like (EXP) may be referred to in the replacement name \1, \2 ... in order of their occurrence.

[sort-by-extension plugin]

[timeset plugin]

Ony the privileged user ('root') able to vary the 'ctime' (inode change time) of any item(s). Changing ctime requires temporary changes to the system clock. That is normally unwise, as typically, other things rely on system time.

[unpack plugin]

Archives of these sorts are supported:
    .tar.gz
    .tar.bz2
    .tar
    .zip
    .rar
    .arj

Compressed single-items (i.e. no tar, and usually named like "somename.ext.bz2" or "othername.ext.gz") are not supported. They can be readily unpacked by a simple command like 'bzip2 -d %f' or 'unzip %f'

[view plugin]

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 action name. You may add argument(s) for an action, with whitespace 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
%p = substitute (space-separated series of) quoted pathname(s),
         corresponding to (each) selected item in the active pane
%P = same as %F, for convenience

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

%$prefix$ = prepend the string between the $$ to anything that follows e.g. %$file://$%%p will result in a series of absolute path strings, each preceded by "file://"

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

'$$' will be replaced by the path of the active directory, very much like %d, except that in this case there is no trailing "/". Sometimes needed for path comparisons.

'$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.

Any un-escaped '*' or '?' in a command argument will be assumed to be part of a wildcard filename, and the argument in question will be expanded into a series of matching filenames (if any)

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'.
