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) DIR should end with "Trash"
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. When filtering by date, as well as entering a d,M,Y string in the normal format for your locale, you can also specifiy a relative period, by entering things like "past 2 hours" (translated as appropriate). The syntax parsing is crude, it just looks for locale-specific strings "hour" "day" "month" or "year", and any decimal number. A negative number is ok.
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"). Double-clicking in a 'focused' directory line has the same effect as pressing <Enter>. In addition to normal choice, pressing <Ctrl>Tab while a directory line is focused, or clicking the middle mouse button in a directory line at the same time as <Ctrl> is pressed, will open a directory-selection dialog. The dropdown histories for these comboboxes function as semi-permanent bookmarks. Directories are added to a history only when the respective entry is manually activated (by <Enter> press or pointer-device double-click). Directories can be removed from a history by pressing <Alt><Delete> when the relevant directory is shown in the entry. As a visual cue, the entries show their path in coloured text (using the 'positive color' recorded in configuration data) if the directory is in the history.
By default, the pane toolbars include go-forward and go-back buttons. In addition to their regular use, they
can show respective menus of directories present in the forward/backward history. Such menus can be popped up
by a <Ctrl>left-click or right-click on the button, or by hovering the pointer over the button for about half a second. A menu of all such directories (i.e. not partitioned into forward and backward) is available in the
default context menu for each filelist.
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). Note that the content of such windows is not refreshed dynamically. A context-menu includes capability to manually refresh, among other things.
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 some hard-coded key bindings which are specific to emelFM2:
<Control><Down> displays all the history items (the same effect as clicking on the expander button),
<Shift><Delete> clears the contents of the entry from the cursor position to the end,
<Alt><Delete> clears the current entry and any matching history item(s),
<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
e2 manages trash largely in accord with the freedesktop.org trash specification. The preferred trash folder will be on the same device/partition as the item being trashed. This may be in a hidden dir in the top-level directory of that device/partition, either ".Trash" or ".Trash-UID" where UID is the number assigned to the current user. For the device/partition where the user's home directory is mounted, and in all cases where neither of the top-level dirs is present in other relevant places, the trash dir will be ".local/share/Trash" in the user's home directory. The last of these will be created if it didn't exist already. Trashed items are put into a sub-dir "files" in the relevant Trash, and a related info file is put into sub-dir "info" in that Trash.
Deleting, renaming or moving an item in ".../Trash/files" will trigger a suitable change to any corresponding info file.
There is no overt over-write checking for trashed items. However, if an item with the same name is already in the relevant "...Trash/files", the name of the newly-trashed item and its info file will be modified to something unique.
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.
You can directly rename any allowed item by clicking on its name in a filelist, when the item's row is not selected. In this case, the rename action is not queued.
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:
[access control list plugin]
ACL's enable application of a superset of most of the "normal" permissions, to an item in a filesystem. Fine-tuning of *NIX read (r), write (w) and/or traverse|execute (x) permission is possible for particular users and/or particular groups. As such, ACL's are mainly relevant in contexts where there are various users, such as corporate systems.
Not all *NIX operating systems and file systems support ACL's. If support is present, not all items (or none at all) in the filesystem need actually have an ACL. Any item in a supporting filesystem may have an "access-ACL" that determines the effective r, w, and/or x permission(s) of the item. On a system where _POSIX_ACL_EXTENDED is defined, any directory may also or instead have a "default-ACL" that governs the initial access-ACL for items created within that directory.
Two standard formats are used for human-readable ACL display.
This is an example of one ACL in the long text form:
user::rw-
user:lisa:rw- #effective:r--
group::r--
group:444:rw- #effective:r--
mask::r--
other::r--
These are two examples of the short text form:
u::rw-,u:lisa:rw-,g::r--,g:444:rw-,m::r--,o::r--
g:444:rw,u:lisa:rw,u::wr,g::r,o::r,m::r
An ACL consists of a series of ACL-entries. In the above examples, each line (in the long-form) and each comma-separated block (in the short-form) represents an ACL-entry. An ACL-entry contains
* an entry tag type, largely represented by the first part of the entry (user, g, mask, o etc) (see below for a description of these types),
* for two types of entry tag, a "qualifier", represented by the second part of the entry (a UID or GID - lisa, 444), and
* a set of permissions represented by the third part of the entry (r w x).
There are 6 types of enties, as described below. If an ACL exists, 3 of the 6 will always be present - these correspond to the usual user/group/other permissions which apply generally. The other 3 types provide the extra flexibility which justifies using an ACL. There are rules about how these may be used, of course.
The ACL_USER_OBJ entry denotes access rights for the item's owner. A valid ACL contains exactly one such entry. Typically, the "normal" rwx permissions defined for the item's owner would be used for the permissions of the ACL_USER_OBJ entry.
The ACL_GROUP_OBJ entry denotes default access rights for members of the item's group. A valid ACL contains exactly one such entry. Typically, the "normal" rwx permissions defined for the item's group would be used for the permissions of the ACL_GROUP_OBJ entry. If the ACL has no ACL_MASK entry, then the permissions defined for the item's group correspond to the permissions of the ACL_GROUP_OBJ entry. If the ACL does have an ACL_MASK entry, then the permissions defined for the item's group correspond to the permissions of the [ACL_GROUP_OBJ entry masked by (and'ed with) that?] ACL_MASK entry.
The ACL_OTHER entry denotes access rights for processes that do not match any other entry in the ACL. The "normal" "other" rwx permissions defined for the item would typically be used for the permissions of the ACL_OTHER entry. A valid ACL contains exactly one such entry.
ACL_USER entries denote the maximum access rights for the user identified by the entry's qualifier. This type of entry may appear zero or more times in an ACL. This type of entry has a qualifier denoting the identifier of a user (UID as a name or number). The actual permissions defined for the user correspond to the permissions of the ACL_USER entry masked by (and'ed with) the ACL_MASK entry.
ACL_GROUP entries denote access the maximum rights for groups identified by the entry's qualifier. This type of entry may appear zero or more times in an ACL. This type of entry has a qualifier denoting the identifier of a group (GID as a name or number). The actual permissions defined for the group correspond to the permissions of the ACL_GROUP entry masked by (and'ed with) the ACL_MASK entry.
An ACL_MASK entry denotes the maximum access rights that can be granted by entries of type ACL_USER, ACL_GROUP_OBJ, or ACL_GROUP. An ACL that contains entry(ies) of ACL_USER or ACL_GROUP tag types must contain exactly one entry of the ACL_MASK tag type. If an ACL contains no entries of ACL_USER or ACL_GROUP tag types, then an ACL_MASK entry is optional.
A qualifier denotes the identifier of a user or a group (UID or GID as a name or number), for entries with tag types of ACL_USER or ACL_GROUP, respectively. All user-ID qualifiers must be unique among all entries of ACL_USER tag type, and all group-ID qualifiers must be unique among all entries of ACL_GROUP tag type. Entries with tag types other than ACL_USER or ACL_GROUP have no defined qualifiers, and in human-readable form, their respective qualifiers are empty or blank.
You might get some further useful insight from the likes of:
www.vanemery.com/Linux/ACL/linux-acl.html
rofi.roger-ferrer.org/eiciel/doc
Whew !!!
First, a caveat. Not all operating systems (or more particularly their libraries used to manage ACL's) support the same level of functionality. This plugin assumes reasonably-full functionality, more-or-less the full capability of the aborted POSIX standard for ACL's. Linux meets this requirement, others will just have to experiment.
There is a lot of ways that changes can be made using this plugin. You can add ACL(s) to any item that has none, and change any existing ACL in many ways, but (because the file system doesn't allow it) you can't entirely remove an existing ACL from an item. You can't add and remove things at the same time - you'd need to run the process twice to achieve that effect.
ACL entries for the current item are represented on separate lines in the dialog. Entries can be added or removed using the buttons at the bottom of the dialog, and can be edited in place.
What is the whole-flag for? In some cases (ACL_USER, ACL_GROUP, ACL_MASK) you can add that entire entry to, or remove that entire entry from, the ACL, or (if the entry exists already for an item being processed) you can just add to or remove from that entry's permissions. So we need to distinguish what is intended. If the entry's WHOLE setting is in effect, then as you'd expect, the specified change(s) for that entry apply to it as a whole, not just to its permissions. For other types of entries, the whole-flag is ignored, when setting or adding at least. A global whole-flag (below the displayed ACL), if set, has the same effect as setting each relevant whole-flag for all the entries in the ACL (at implementation-time, and whether or not the individual entries' whole-flags are set).
Among other things, this arrangement means you will want to set the whole-flag for entries being added to an ACL.
A common error when first adding ACL_USER or ACL_GROUP entry(ies) - a ACL_MASK entry must also be added.
If the item currently being processed is a directory, you may choose to apply changes recursively. In that case, you may choose to apply changes to directories or to non-directories or to everything. Any changes to a directory (whether or not recursion is in effect) may be to its access-ACL and/or to its default-ACL, or to neither of those ACL's, depending on what has been selected. Remember - to apply changes to directories, you need to activate _all_ the relevant options.
This is how the change-process works in the plugin:
Each entry in the proposed new ACL is processed in turn. A WHOLE setting is deternined by whether the global whole-flag is set, or othewise, whether a whole-flag is set for the specific entry.
After all WHOLE settings are known, the ACL (if any) of the item being updated is interrogated.
If the chosen action is SET:
* if a WHOLE setting is in effect:
- if a matching existing entry is found, replace its permissions
- if no matching existing entry is found, and if valid to do so, add this entry and its permissions
- if no matching existing entry found, and not valid to add it, continue
* if a WHOLE setting is NOT in effect:
- if a matching existing entryis found, replace its permissions
- if no matching existing entry is found, continue
If the chosen action is ADD:
* if a WHOLE setting is in effect:
- if matching existing entry is found, add specified permissions to it
- if no matching existing entry is found, and if valid to do so, add this entry and its permissions
- if no matching existing entry is found, and not valid to add it, continue
* if a WHOLE setting is NOT in effect:
- if matching existing entry is found, add permissions to it
- if no matching existing entry is found, continue
If the chosen action is REMOVE:
* if a WHOLE setting is in effect:
- if matching existing entry is found, and if valid to do so, remove it
- if matching existing entry is found, and if not valid to remove it entirely, remove specified permissions
- if no matching existing entry is found, continue
* if a WHOLE setting is NOT in effect:
- if matching existing entry is found, remove specified permissions from it
- if no matching existing entry is found, continue
[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.
[crypt plugin]
Encrypt or decrypts selected files. Encryption is performed using the Salsa20 algorithm (see www.ecrypt.eu.org/stream/salsa20pf.html). Recursion into directories is possible, if the corresponding option is selected.
The files may optionally be compressed too, as part of the encryption process (compression of a small file might make it a bit larger). For compression, the plugin uses an external library, in accord with configuration option. The supported libraries are lzo (which has less compression but is fastest) or zlib, or bzip2 (most compression, but slowest). The chosen library needs to be present, of course, and dynamically linked (so that it can be interrogated by dlopen() function). When decrypting, decompression will be performed automatically, provided the corresponding compression library is still available.
The conversion process requires that the file being processed fits entirely into available memory, and [de]compression roughly doubles that memory-space requirement. So this plugin is not suitable for large files.
The contents of password entry(ies) may be rendered visible (by pressing <Ctrl>p in an entry) or re-hidden (by <Ctrl>h) or (for gtk >= 2.10) partially and temporarily visible (by <Ctrl>t).
Several file naming options are provided, anything more complex will need to be done in the rename plugin afterwards. Existing properties of an encrypted file can optionally be stored in the file, and then optionally re-applied after de-cryption.
Each processed file can be retained as is after processing, if so desired. This is probably wise, until you are comfortable with the way the plugin is operating. Any unencrypted file that's not retained will be thoroughly wiped, not just deleted.
There is an option to include validation data in the encrypted file. That data allows some extra checks when decrypting, before overwriting anything at that stage, and as such may provide an extra safety-factor for normal usage. However it also provides a mechanism to automate a brute-force attack on the file, so if highest security is important, do not use validation.
[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, or within a specified recent interval.
[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, or within a specified recent interval.
[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, or within a specified recent interval.
[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, .tgz
.tar.bz2, .tbz2
.tar.lzma, .tlz
.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).
[thumbnails plugin]
This opens a dialog window showing thumbnails of all recognised images in the active-pane directory. More than one such dialog may be opened, for either or both filepanes.
Images whose maximum dimension is less than 32 pixels are scaled up. Images whose maximum dimension is more than 128 pixels are scaled down.
No file operations (copy, delete etc) may be performed directly on items in this dialog. However, selections are normally echoed back to the associated filelist, and operations may be performed from there. Sorting of the images using the normal fields is possible via a menu opened when the Sort button is clicked.
The dialog has a context-menu which enables manual refreshes of the view contents, un-selecting all items in the view, rotating or flipping the selected items, and changing whether to replicate all [de]selections in the dialog back to the associated filelist. Any rotation or flip is for display only, the original file is not altered.
This plugin uses functions in libgimpthumb to manage thumbnail-cacheing in accordance with freedesktop.org specification.
[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, .tgz
.tar.bz2, .tbz2
.tar.lzma, .tlz
.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.
Shell environmental variables may be stored by a command of the form 'set NAME VALUE' or 'set NAME=VALUE', retrieved by '$NAME', and cleared by 'set NAME' or 'set NAME='.
Much like shell environment variables, internal variables may be defined and used e.g. for communication between actions or commands. Similar to 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 internal 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
%t = substitute absolute path of a unique sub-directory in the default temp directory
%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
%{"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 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).
%!... = substitute part or all of a prior command (not action) in a manner similar to !... history expansion by shells like bash, csh. Supported syntaxes for the !... are:
![-]n nth-previous command (all values are 'backward' in history)
!! same as !1 or !-1
!beginswith most-recent command beginning with the series of characters beginswith
Any of the above may be immediately followed by a 'word(s)' specifier:
:n 0 is the command, 1 ... are the arguments
:n-m a range of words
:-m same as :0-m
:n-$ same as :n-last
:-$ same as :0-last
:^ same as :1 i.e. first argument
:$ same as last
:* same as :1-$ i.e. all arguments
Shortforms for using immediately-prior command
!^
!$
!*
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'.
