		  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: ~/.config/emelfm2)
-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,--log-all           maximise scope of error logging (relevant only when built without debugging-support)

If the program has not been built with debugging-support enabled (compiled without make-option DEBUG=1):
(note that this option must be used if you wish emelFM2 to nicely respond to shutdown, save-yourself etc requests by your desktop session-manager)
-m,--daemon         detach emelfm2 session from its controlling terminal, and run as a daemon

-r,--run-at-start      command to run immediatly after start
-s,--set-option        set configuration parameter (one-line argument in config file format)
-t,--trash=DIR         set trash directory to DIR (default: ~/.local/share/Trash/files)
Help options:
-h,--help              show this help message
-u,--usage             display brief usage messsage
-v,--version           display version and build info

If the program has been built with debugging-support enabled (compiled with make-option DEBUG=1):
-d,--debug=[1-5]       set debug messages level from 1 (lowest) to 5 (highest)
-x,--verbose           display time/location info in debug messages

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.

A "navigation" window for the active pane can be displayed, and used to select the directory to show in the corresponding file pane. By default, <Shift>F9 will open this window. Activating (by mouse double-click or <Enter> keypress) any of the listed directories will cause that directory to be opened. Directories which cannot be accessed are shown in the 'negative' text color (typically, red).

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 or a <Ctrl>-click, if that text names an item that belongs to a recognised filetype. The named item will be opened just as if it had been in a filelist. Any filepath in the selection is handled, or if there is no filepath, the directory displayed in the active file pane will be assumed.

If selected text describes a recognised filetype, and the output pane context-menu is opened by a right-click on the selection, then menu will include a sub-menu of operations for that filetype, the same menu as for a selected item of that type in a file-list context-menu.

A <Ctrl>-click, or right-click to open a context-menu, will also operate on non-selected text in the output pane, as described above. As there is no selection, space characters define the text that is used.

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.

The "comboboxes" (entry fields with drop-down history list) used throughout the application have hard-coded key bindings <Shift><Delete> which clears the contents of the entry from the cursor position to the end, <Alt><Delete> which clears the current entry and any matching history entry(ies), and <Shift><Alt><Delete> which clears the entire history.

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 FILES AND 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.

Most such operations are added to a queue, and performed when they reach the head of that queue. This allows such operations to be initiated and performed without blocking the user-interface, when the operation takes some time to complete. Some operations - info, view, view again, edit, edit again, open, open with - are performed independently of the queue.

Actions and keybindings are provided to respectively list the finished, active, and waiting members of that queue.

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. Such command must convert text to UTF-8 and send that converted text to stdout, and the text will be read by emelFM2 directly into memory. If the converter-command requires that the file encoding be specified, then obviously you will need to discover that before opening the file. Some european candidates are:
belarussian: CP1251 IBM866 ISO-8859-5 KOI8-UNI maccyr IBM855
bulgarian: CP1251 ISO-8859-5 IBM855 maccyr ECMA-113
czech: ISO-8859-2 CP1250 IBM852 KEYBCS2 macce KOI-8_CS_2 CORK
estonian: ISO-8859-4 CP1257 IBM775 ISO-8859-13 macce baltic
croatian: CP1250 ISO-8859-2 IBM852 macce CORK
hungarian: ISO-8859-2 CP1250 IBM852 macce CORK
lithuanian: CP1257 ISO-8859-4 IBM775 ISO-8859-13 macce baltic
latvian: CP1257 ISO-8859-4 IBM775 ISO-8859-13 macce baltic
polish: ISO-8859-2 CP1250 IBM852 macce ISO-8859-13 ISO-8859-16 baltic CORK
russian: KOI8-R CP1251 ISO-8859-5 IBM866 maccyr
slovak: CP1250 ISO-8859-2 IBM852 KEYBCS2 macce KOI-8_CS_2 CORK
slovene: ISO-8859-2 CP1250 IBM852 macce CORK
ukrainian: CP1251 IBM855 ISO-8859-5 CP1125 KOI8-U maccyr

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"
 BackSpace  Delete character before cursor
 <Control>BackSpace Delete word before cursor
 <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 and text-entry strings 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.

History lists for text-entry strings can be cleared by pressing <Alt>Delete when the entry in question is focused.

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

NOTE the action-name for this plugin is (in english) file.foreach. If this action is run from the command line, it needs to have a "!" prepended e.g. !file.foreach echo %f. (This is to prevent any %f or %p macro in the command from being expanded by the command-interpreter. Such expansion needs to be performed by the plugin, instead.)

[glob plugin]

Selects items whose name matches specified pattern(s). The selection criteria are the same as filelist filtering criteria.

[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.
If a <Control> key is pressed when the plugin is activated, copied item paths or names will be separated by a "newline" character, instead of a space.

[pack plugin]

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

[rename plugin]

Items to be processed can be located in any specified filesystem directory, and optionally, in any descendant directory of the starting point.

Items to be processed can be those selected (in either displayed filelist), or all items which match a specific name, or match a name-pattern with wildcard character(s) "?" and/or "*", or a match a name-pattern with regular-expression syntax. Note that internally, regular-expression matching is always used. Regular expressions are "greedy" and this can produce unexpected results. For example, using a wildcard pattern "*-*", when renaming an item "12-34-56", the first "*" will match "12-34", not "12".

Replacement names can be made all lower-case or all upper-case, and/or a pattern which contains wildcard characters, or "back-reference(s)" to regular-expression-group(s) in the search pattern.

Documentation on regular expressions can be found by running the shell command "man 7 regex" or "man grep" or from www.regular-expressions.info/reference.html, or 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 a replacement name-pattern by \1, \2 ... in order of their occurrence.

The whole of any matching item name may be referred to in a replacement name-pattern by \0 (This is an emelFM2 extension, not standard regular expresssion syntax.)

The replacement name-pattern may include up to 4 counter macros (see macros section below, for details). In this context, initial value defaults to 1 if not explicitly provided. If more than one counter is included, the respective i and w parameters are independent of those in the other counters. A normal "%c" in the name-pattern must be escaped as "\%c".

It is generally wise to apply the confirmation option, so that each replacement name can be checked before it is applied.

[sort-by-extension plugin]

This is now effectively redundant, as the same functionality is available by clicking the filename column header when a <Control> key is pressed.

When extension sorting is active, the column-header arrow changes to point right (for ascending order) or left (for descending order).

[timeset plugin]

Replacement date(s) and/or time(s) may be separately set. If a new date or time is not provided, then the current value will be used. Formats of entered strings should be appropriate for the user's locale.

By way of confirmation, the corresponding 'set' box must be checked, to implement the change.

Ony the privileged user ('root') is 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.

Any replacement date/time can be applied recursively if the item is a directory. If multiple selected items are being processed, the replacement date/time can be applied to all remaining unprocessed items. All selected items can be conformed by simply checking a 'set' box and applying the change to all.

[tracker plugin]

At least until the tracker (a.k.a metatracker) information-indexer (see www.gnome.org/~jamiemcc/tracker) is further developed and better-documented, this plugin merely provides a simple listing of indexed items which match specified criteria.

Tracker (currently) works with a small number of categories of item (in tracker terms, "services") e.g. documents, videos, music, or it works with mimetypes (sometimes fake mimetypes like 'system-file-manager'?). When searching by service, it's possible to also specify some content. (NOTE not yet sure how this content works - probably the specified words are AND'ed.)

Tracker can also run pre-defined queries (called "rdf queries", expressed in small XML-ish files with ".rdf" extension). Rdf started as a standard on top of XML for encoding metadata and has evolved into a means for encoding information about, and relations between, things. See, for example, www.w3.org/RDF and www.xml.com/pub/a/2001/01/24/rdf.html.

To find items by service, select the corresponding radio button, and the service type. Any desired content may be added in the entry field at the bottom.

To find items by mimetype, select the corresponding radio button, and add one or more mimetypes into the entry field at the bottom. If more than one type, separate them with a space character.

To use an rdf query, select the corresponding radio button, and enter or choose the path of the query file.

The tracker package includes utilities "tracker-files", "tracker-search" and "tracker-query". The plugin expects those to be executable by name-only (i.e. located somewhere in the search-path). Tracker itself does not have any gnome dependency, but it may be built with a simple GUI that does rely on gnome.

[unpack plugin]

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

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]

This opens the first selected item with the internal text-file viewer. It is intended to be used when the default view action is configured to use an external viewer.

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.

Much like shell environment variables, internal variables may be defined and used e.g. for communication between actions or commands. As in the case of an environment variable, an internal variable can be stored by a command of the form 'NAME=VALUE', retrieved by '$NAME', and cleared by 'NAME='. In addition, a command '=VALUE' will list the name of any variable with that value, and just '=' will list all internal variables with their values. Whitespace surrounding the "=" in any variable-related command is ignored.

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 cause it to run in a separate shell, i.e. bash, zsh, korn, sh etc. This is necessary if you want extra functionality like pipes, re-direction, fancy variable processing. Commands which include any of '|<>' are automatically run in a separate shell.

* adding '>>' to the beginning of a "joined" external command will cause it to run as a single command in a separate shell, i.e. bash, zsh, korn, sh etc. This is necessary if you do not want the individual components of the joined command to be indivually sent to the shell.

* adding '|' to the beginning of a 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 a command will suppress macro expansion. (See below for macros description). This means things like '%f' will be treated literally.

* adding '&' to the end of a 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

%c[i][,w] = substitute decimal number string. i and w are optional numbers >= 0. If present, i will set the value to be shown in the counter, or if not present, the (last-used counter-macro-value + 1) will be used. If present, w must be  preceded by a ',' and sets the minimum width of the counter field, which will be padded with leading 0's as required. No spaces are allowed surrounding the ','. Width defaults to 1 if not explicitly provided.  Examples: %c  %c0 %c10,2 %c,3

%t = substitute absolute path of a unique sub-directory in the default temp directory

%{"Prompt:"} = open a dialog seeking user input, with prompt 'Prompt:', and substitute the entered string
%{(cachename)@"Prompt:"} = open a dialog seeking user input, with prompt 'Prompt:' and history list that ws cached as "cachename", and substitute the entered string
%{*@"Prompt:"} = open a dialog seeking a password, with prompt 'Prompt:', and substitute the entered string
(If there is no "(cachename)@" or "*@" in a %{} macro, and the prompt is to include "@", any such character must be escaped as "\@" in the prompt string.) Any string enterted via the dialog may contain other macro(s).

%$prefix$ = prepend the string between the $$'s to anything that follows e.g. %$file://$%%p will result in a series of absolute unquoted path strings, each preceded by "file://". The string between the $$'s may contain other macro(s).

Any other '%' inside a command is simply treated as part of the command.

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 mechanism to send a message to a child of a command which is running in a separate shell ("grand-child"?).

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