Sophie: emelfm2-0.8.2-1.fc18 i686

emelfm2-0.8.2-1.fc18.i686.rpm

$Id: CONFIGURATION 2570 2012-07-17 23:13:23Z tpgww $
emelFM2 configuration 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 configuration-dialog page. Other headings here are simply capitalised.

INTRODUCTION
This document is still under development. Feel free to mail tooar a note about things that might usefully be added here.

Surrounding parentheses ' ' or " " are used in this document for clarity, they are not part of a string or character actually entered, unless so stated explicitly.

DIALOG BUTTONS
Configuration dialogs include 'commit', 'apply', and 'discard' buttons (among others). Clicking 'commit' applies any changes made in the dialog to the relevant parts (if any) of the application window, saves the updated configuration data onto disk in the 'config' file, and closes the configuration dialog. Clicking 'apply' differs from 'commit' in that the dialog window is not closed, and any changes are applied to the session, but not immediately saved to disk (though then-current configuration settings are always saved at the end of each session). Clicking 'discard' will revert any changes made since the last 'apply' (and of course those might not be all of the changes made) then close the dialog.

'TREE' OPTIONS - GENERAL
Click a tree row to focus it. Alternatively, move focus by pressing the Tab key, and within the treeview, by pressing a relevant a relevant arrow key. Click a field (cell) in a focused row to edit the cell, or edit a focused cell by pressing the space-bar. Editing a cell may invoke another dialog, if relevant (eg for an icon).

Where permitted, a selected tree line can be added, deleted, moved up or down by clicking the corresponding button at the foot of the page. Where permitted, tree rows can be dragged to another location in the tree. This takes some practice to get right !

Clicking the discard button will close the dialog without saving any changes made. Pressing escape-key will do the same.

In some instances (eg button labels, menu labels), text fields are for 'public' display. You are encouraged to include a mnemonic key (gtk expects a preceeding '_') and/or may include pango markup language, like <b>label</b>

Tree-option configuration pages have a context menu, displayed by a mouse right-click or a menu-key press. The menu replicates most of the buttons at the bottom of the page, but also allows cut/copy/paste and view collapse/expand.

Where an option involves doing/running something, the text of the function (meaning an e2 internal command a.k.a. action, or external command), may be typed directly into the relevant field, or action names can be selected from a drop-down (-up?) list. Any argument for the action is entered into the second field (to the right of the first). The entered command string can comprise: action(s) and/or external command(s), modifier(s), alias, argument(s), macro(s), variable(s). Multiple commands are joined with ';'. Refer to the separate USAGE document for more about such commands.

Note that for convenience when creating toolbars or menus, the actions list includes things that do not actually run anything directly. Part or all of their name is enclosed in <> - examples are 'command.<line>', '<submenu>', '<separator>'. These pseudo-actions may have argument(s) if appropriate.

[bookmarks]
The 'label' field holds the string that appears in the bookmarks menu. You may use a mnemonic key and/or markup in that field.

The 'tooltip' field hold the menu item tooltip.

The 'path' is the actual path to to bookmark. It may be '~' or start with '~/'. The '~' will be expanded to your home directory.

The 'tooltip' and/or 'path' field may include variable(s), like $VAR or ${VAR}. (or $[var], but why would you want an e2 option value, in this context?)

Bookmarks which are children of the first item are shown on the taskbar. Do not change the name of that first item, or else the bookmarks will not be shown.

[aliases]
The 'match' field contains a string that will be replaced, if it is found at the start of a command string which is about to be run. Extended regular expressions are allowed in the 'match' field. '^' is prepended to any match which does not have '^' at its start. (This causes pattern matching from the start of the string.)

If an alias has its associated 'stop' field set, alias-searching will end if that alias is matched. If the flag is not set for a matched item, the scan will continue down the aliases list, with the matched command now as the target. So the alias substitution is effectively chained.

The 'replace' field contains a string that will be put into a command instead of the corresponding 'match' field value. The 'replace' field is one of the "flexible" command fields - refer to the GENERAL section, above. The 'replace' field may contain '\1' and/or '\2'. If so, the 'replace' field value will be substituted for '\1', The part of the entered command, after the 'match' field and the following space(s) (effectively, the arguments), will be substituted for '\2'.

Refer also to the separate USAGE document.

The obscure-looking initial alias ensures that commands with pipes and/or redirections run in a separate shell. Otherwise, such commands won't work properly.

[filetypes]
The basic segmentation for stored filetype information is by 'category'. Each category may have as many filetypes as you wish (distinguished by the extension that is part of their name), and as many commands as you wish to execute on any file within the category.

So the tree layout for each category is as follows:
category name (eg image files)
|____ extensions [optional color name e.g. #AB12CA or orange]
| extension in this category (eg jpg) [optional color name]
| another extension (if desired) [optional color name]
| and so on ...
|
|____ commands
default command for this category (see below)
another command (if desired)
and so on ...

Extensions are assumed to be the part of the filename after a ".", usually the first one in the name. Examples are 'tar', 'gz', 'tar.gz'. Pseudo-extensions '<none>', '<directory>', '<executable>' are recognised, and would typically be included.

As of version 0.1.6, there is experimental support for setting foreground text color, for any or all categories and/or extensions. The various pseudo-filetypes (enclosed in < >, e.g. <none>) are not affected by any custom color. Nor are the various item-types (directories, links, sockets etc) whose colors are set on other config dialog pages. Any extension color will override the corresponding category color, if any. If no color is provided, the theme-default text color will be used, as before.

Color names are stored in the 3rd column of the view, ajacent to an "extensions" heading, and/or adjacent to any specific exension under that heading. Any specific extension color wlll override any color for all extensions in the category. Color names can be keyed in manually or pasted, but to select a new color it is best to select the row in question, then click on the "Color" button near the bottom of the window. To delete a color, select the cell in question, and delete the string.

Each command item has 2 adjacent fields on a single line in the tree:
The left-most field (under the 'commands' field) stores a label string that will appear in the file-pane context menu. That string may include a mnemonic key and/or pango markup language. Sometimes it is convenient to simply use the name of the command.

The adjacent field to the right has the command string itself. This is one of the "flexible" command fields (see GENERAL section above).

The first command in each category is the default for that category, executed when an item in the category is double-clicked.

You may add categories, provided that they each conform to this structure. The easiest way to add a category is to copy/paste an existing category and then edit the pasted lines (except the heading lines with 'extensions' and 'commands', of course).

[plugins]
The 'loaded' field is TRUE if the plugin is to be loaded into memory (i.e. made usable). (Plugins are loaded at session-start or after a change to the plugin config data.)

The 'menu' field is TRUE if the plugin is to appear in the plugins context menu. (A loaded plugin may be used only for keybindings, say, and so need not be on the plugins menu.)

The 'label' field holds the label that appears in the plugins context menu. You may use a mnemonic key and/or markup in that field.

The 'filename' field is for the actual file name, typically e2p<something>.so. It does not include a path.

The 'location' field is for a path to a directory containing the named file, or it may be left empty if the the default plugins directory is to be used.

To add one or more extra plugins it's easiest to select the corresponding file(s). Position the cursor where you want the addition(s) to be located, then click on the "Select" button near the bottom of the window. In the opened selector-dialog, select as many plugin-files as you want, then click the 'Open' button. Re-loading of plugins already in place is automatically blocked.

[key bindings]
Keybindings are arranged in a context-specific hierarchical manner. The tree layout is as follows:

Any keybinding will pre-empt the same binding assigned to an 'ancestor' context (higher level in the same branch of the tree hierarchicy). Bindings in the 'general' category apply everywhere within e2 (unless pre-empted).

Each key binding has 4 adjacent fields on a single line in the tree:
The left-most field is populated automatically by pressing the desired key and any modifier(s) (<Ctrl> etc) after the field has been selected.

The second field is a 'continue' flag. Any key can be assigned to more than one action, by including the key in more than one binding. In order that the keypress interpreter does not stop at the first match, all but the last instance must have their 'continue' flag set.

The third field 'action' and fourth field 'argument' are selectable from the actions list. The 'action' can be a simple action name, or an external command, or a ';' separated series of commands and/or actions with or without respective argument(s). The 'argument' can contain one or more arguments appropriate for the only or last element of the 'action' field. If desired (DEPRECATED), for a more-complex/external operation, 'action' may be set to <custom command> and 'argument' set to the entire series of actions/commands/arguments as just described in relation to the 'action' field. Refer also to the USAGE document.

Sequences of keys can be implemented. Any bound key may have 'child' key(s), and they may have child(ren), and so on. If so, each 'parent' is treated much like a modifier (ie like Shift, Ctrl, Alt) for each child. You might think of the sequence as forming a compound key, activated by pressing the parent, then shortly after, the child, then the grandchild, and so on. (The allowed time interval for recognising a child is set at another option, by default it is 2 seconds.) Unlike standard modifier keys, each key in the sequence can be bound to its own command.

Users are prevented from changing category names, or adding, removing categories. You can of course add remove or move actual keybindings.

[pointer buttons]
Button bindings are arranged in a context-specific hierarchical manner. The tree layout is as follows:

Any button-binding will pre-empt the same binding assigned to an 'ancestor' context (higher level in the same branch of the tree hierarchicy). Bindings in the 'general' category apply everywhere within e2 (unless pre-empted).

Each button binding has 5 adjacent fields on a single line in the tree:
The left-most field is populated automatically by pressing the desired button(s) and any modifier key(s) (<Ctrl> etc), after the field has been selected.

The second field is a 'double-click' flag. The third field is a 'triple-click' flag. Sadly, it's not possible to set these flags automatically by multi-click in tne name field. There's no check for both of these flags being set. However in that case it will be assumed that a double- is intended.

The fourth field 'action' and fifth field 'argument' are selectable from the actions list. The 'action' can be a simple action name, or an external command, or a ';' separated series of commands and/or actions with or without respective argument(s). The 'argument' can contain one or more arguments appropriate for the only or last element of the 'action' field. Refer also to the USAGE document.

Users are prevented from changing category names, or adding, removing categories. You can of course add remove or move actual button bindings. Changing button 1 or 3 is generally not wise, it will probably interfere with basic operations like selection or context-menus. Duplicates are checked after the button field is changed, so it may help to set that field last.

[pointer gestures]
Gesture bindings are arranged in a context-specific hierarchical manner. The tree layout is as follows:

Any gesture-binding will pre-empt the same binding assigned to an 'ancestor' context (higher level in the same branch of the tree hierarchicy). Bindings in the 'general' category apply everywhere within e2 (unless pre-empted).

Each gesture binding has 4 adjacent fields on a single line in the tree:
The left-most field is populated automatically by pressing the desired button(s) and any modifier key(s) (<Ctrl> etc), after the field has been selected. You can nominate as many buttons and keys as you like, for any given binding.

The second field is an optional identifier. It's not actually used for processing, but is merely for a guide or hint about the nature of the actual gesture involved.

The third field is a representation of the gesture. It's a comma-separated sequence of numbers, each 1 .. 9. The underlying representation is a 3X3 grid, numbered 1 at top-left, 3 at top-right, and so on to 9 at bottom-right. Recorded gestures have the grid-numbers of start, end, and _vertices_ of the pointer movement e.g. a V-shape is 1,8,3 and an L-shape is 1,7,9. Clicking on a gesture field will open a dialog where new gestures can be drawn and/or manually edited, and where there's a 'clear' button which can be combined with 'commit' to clear an existing gesture (though there's no sense in having an empty binding). Gestures are automatically scaled to use as much of the grid as possible. Tall-thin gestures and short-wide gestures are automatically centred. Gestures are 'cleaned' as much as possible to help ensure successful matching.

[bar]
The pane1 bar is the toolbar which by default is shown at the top of pane 1. 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.

By default, this toolbar includes a pseudo-action 'pane1.<line>'. That needs to have the argument ',expand' for it to work properly. You may add a minimum size, if you want that to be bigger than the default, by making the argument 'size,expand' where 'size' is an integer like '100'.

The pane2 bar is the toolbar which by default is shown at the top of pane 2. 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.

By default, this toolbar includes a pseudo-action 'pane2.<line>'. That needs to have the argument ',expand' for it to work properly. You may add a minimum size, if you want that to be bigger than the default, by making the argument 'size,expand' where 'size' is an integer like '100'.

Clicking the 'replicate' button replaces all the current data with data from the other toolbar, then simply adjusts any "pane1" or "pane2" (depending on which one you're working on) in an action-name, and any "1" or "2" in the arguments. NOTE that the latter is quite crude, and may change numbers you don't intend, so DO CHECK THE RESULTS before committing. You may choose to adjust anything else, of course.

See the section ALL TOOLBARS, below.

[task bar]
This is the toolbar which by default is shown between the file panes. (Actually, it is stored at the end of pane 1).

By default, this toolbar includes a pseudo-action 'bookmark.<list>'. That needs to have the argument 'task bar', for it to work properly.

See the section ALL TOOLBARS, below.

[command bar]
This is the toolbar which by default is shown near the bottom of the window.

By default, this toolbar includes a pseudo-action 'command.<line>'. That needs to have the argument ',expand' for it to work properly. You may add a minimum size, if you want that to be bigger than the default, by making the argument 'size,expand' where 'size' is an integer like '200'.

See the section ALL TOOLBARS, below.

ALL TOOLBARS
The 'Label' field has the label shown for each bar item if the bar's 'style' option is set accordingly. You may use a mnemonic key and/or markup in that field.

Some items (eg command line, separator, submenu) never display their label and so it doesn't matter what the field contains. Typically the label for those items will be empty.

The 'tooltip' and/or 'argument' field may include $<something> variable(s).

emelFM2 toolbars support a special kind of toggle button. The configuration data for such a button comprises a pair of standard button entries. Each pair has one each of the action types "toggle.on" and "toggle.off" (or translated forms of those names). The pair do need to be adjacent in the bar configuration data. The first one of each pair sets the toggle-state at session start (unless over-ridden by a saved value). The members of the pair can have different labels, icons, tooltips, and functions. Here, "function" refers to an (internal) action or (external) command, with any appropriate argument(s).

The 'action' field value is one of the 'selectable' form - refer to the GENERAL section above. Use the pseudo-actions <separator> or <submenu> as appropriate.. Refer to the ACTIONS document for information about pseudo-actions. For toolbars, submenu items must be defined in a custom menu, on the "custom menus" config page. The name of that custom menu must be provided in the action field of the toolbar's sub-menu item. Refer to the "custom menus" section below.

[context menu]
This page deals with the content of the file-pane context menu only (other context menus cannot be altered by the user).

You may use a mnemonic key and/or markup in the 'Label' field, which is what appears in the context menu. Some items (eg separator, submenu) never display their label, and so it doesn't matter what the field contains.

Toggles can be used, by adding adjacent pairs of items, with actions toggle.off and toggle.on, and argument(s) which are the actual things to run.

A subset of the norrnal context menu may be shown, if a <Shift> key or a <Control> key is pressed when the menu is activated. Only the menu items with the 'shift' field set will be used when a Shift key is pressed. Similarly for the 'ctrl' field.

The 'action' field value is one of the 'selectable' form - refer to the GENERAL section above. Use the pseudo-actions <separator>, <submenu> for those types of items. Refer to the ACTIONS document for information about pseudo-actions. Submenu items are created as children of the <submenu> item, or a separate custom sub-menu may be specified. In the latter case, the name of that custom menu must be provided in the action field of the sub-menu item, and the menu's contents defined on the "custom menus" config page. Refer to the "custom menus" section below.

[custom menus]

The "Menu" column stores the name used to identify the menu. That name does not appear in the user interface, other than in this page of the configuration dialog. It need not be translated, but must be unique for the menu-creation process to work properly.

"Child" entries for each "Menu" hold data for the actual menu items in that menu. The columns - icon, label, tip and command - have the same meaning as for other menus. Entries in these columns are optional, but presumably you will want at least a label and command. The command may be <separator> (suitably translated), or any action(s) or external command(s), or combination of those. There is no separate column for action/command parameters - any such must be put into the same column as the command.

Menu child-entries may in turn have children, which will be shown as a sub-menu. So, the menu can be as complex as you need.

To display a custom menu, at the relevant place in configuration data for a toolbar or the main context menu, insert a <submenu> item, and set the argument for the inserted <submenu> to the name of the custom menu. If it's in a toolbar that's showing icons, you should also specify an icon for the <submenu>, perhaps gtk's stock "index" icon if you have no better alternative.

'NON-TREE' OPTIONS - GENERAL

The respective tooltips give reasonable guidance about the application of those options.

[interface]

The 'columns' page allows the various columns in file-panes 1 or 2 to be (un)hidden. It always shows the columns in the default order. To change the displayed column-order, in the relevant file-pane, drag the relevant column header to the desired place. To change the width of a column, drag the relevant column header separator to the desired width. There is a minimum size, related to the width of the header label.

[icons]
Icons used in toolbar buttons, dialog buttons, menu items etc can be gtk "stock" icons or custom icons. A number of the latter are supplied with the application.

By default, custom icons are expected to be in the default icons directory, usually something like
/usr/share/pixmaps/emelfm2
(in this example, assuming the installation 'prefix' was /usr)

The icons directory can be changed, by specifying another directory in the advanced configuration dialog. Go to the 'interface' page.

This provides a mechanism to implement different sets of icons. It may be convenient, for example, to create various sub-directories in your config directory (~./emlefm2) and store there icons which are compatible with various gtk themes.

Even finer tuning is also possible. In the configuration dialog, any icon can be specified to be a file with a full (absolute) path. In that case, the path will over-ride any directory (default or otherwise) that would otherwise apply.

[text encoding]
When opening text files for viewing or editing, the character-encoding of the file in question must be recognisable to the application doing the viewing or editing. Many, but not all, such applications can deal with various encodings. Sometimes it is necessary to convert the encoding before sending the text to the application.

EmelFM2 has basic encoding conversion capability which is applied when appropriate to files opened with the internal viewer or editor. There is also a configuration option to specify an external command to perform encoding conversion. If enabled, that command will be applied in preference to the internal conversion, for files opened in the internal viewer or editor. Any such external command must send the converted text to stdout. The command may contain any of the macros %f, %%f, %p, %%p. Otherwise, the current filename, surrounded by '', will be appended to the command string.

EmelFM2 has configuration options to use an external text-file viewer and/or editor, with corresponding commands. If those applications require the text encoding to be altered, custom command-string(s) can be crafted accordingly. If it's appropriate to use the default external encoder command, then prepending "$[command-encoder] |" to the viwer/editor command will achieve that (e.g. $[command-encoder] | leafpad).