FileMangler User’s Guide

Table of Contents

Next: , Up: (top)   [Contents][Index]

FileMangler (fmg)

Copyright © 2005 - 2017
              Mahlon R. Smith, The Software Samurai


This manual describes version 0.0.35 of FileMangler.


  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.3
  or any later version published by the Free Software Foundation;
  with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
  Texts.  A copy of the license is included in the section entitled 
  "GNU Free Documentation License".





Next: , Previous: , Up: Top   [Contents][Index]

Introduction

What FileMangler Is

Welcome to FileMangler (fmg), a compact, fast and flexible tool for handling all your file management needs.

FileMangler is a console-based file management utility based on the 'ncurses' engine, providing an intuitive and easy to learn dialog-based user interface which will run smoothly in almost any Linux/UNIX terminal environment.

What FileMangler Does

The FileMangler application is a simple tool, dedicated to doing only one thing: giving you control over your own data.


User Interface

Control of the application’s functionality is provided through two mechanisms:

  1. selection of tasks through the Menu System Interface
    (see Menu System Interface)
  2. selection of tasks through the Command Interface
    (see Command Interface)

The functionality available through these two interface systems is roughly equivalent; however, there are minor differences. A bit of experimentation will quickly reveal what combination of these interfaces will work best with your daily activities.


"With great power, comes great responsibility."
Old Uncle Ben

FileMangler provides immense control over the contents of your local 
filesystems, especially if you are acting as the ’SUPERUSER’ (’root’ user).
It’s equally possible that you could use this power to rid the world of 
supervillians -OR- to destroy your installation. If you are not 
comfortable with all this power, use a less-capable application.
You have been warned!



Next: , Previous: , Up: Top   [Contents][Index]

Operational Overview

Three display modes are available. Within the application, you may switch among these views at any time. Please see FileMangler invocation instructions (Invoking) and configuration options (Configuration) for selecting the initial display mode.



Next: , Up: Operational Overview   [Contents][Index]

Single-window Mode

In Single-window Mode, a single Directory Window is displayed.
All file operations occur on the files displayed in this window.

Please note that the 'info' reader cannot display the lovely, multi-colored text, underlining and other text attributes used by FileMangler. Nor can it squeeze more than 80 text columns into the width of this document. Some diagrams used in this document have been modified slightly to overcome limitations in the documentation engine. The HTML-format documentation is a more accurate representation of the application’s appearance.


Screen Shot of Single-window Mode

┌───────┤ FileMangler - v:0.0.33 (c)2005-2015 [Press F2 for Menu] ├───────┐ │Status: Ctrl+Q=Quit, Shift+F1=Help, F2=Menu ├────────────────────────────────────────────────────────────────────────────┤ /home/sam/SoftwareDesign/XClip ├────────────────────────────────────────────────────────────────────────────┤
375 22-Aug-2013 09:59:33 Makefile 8,077 15-Apr-2014 08:44:56 XClip.cpp 6,252 15-Apr-2014 08:45:25 XClip.o 156,386 10-Jan-2014 08:49:45 gString.cpp 36,884 10-Jan-2014 08:50:00 gString.hpp 37,368 15-Apr-2014 01:43:38 gString.o 43,425 15-Apr-2014 08:45:26 xclip ├────────────────────────────────────────────────────────────────────────────┤ 7 files 288,767 bytes └────────────────────────────────────────────────────────────────────────────┘

  1. Single-window Mode is based on one Directory Window. All file operations occur on the files displayed in this window.
  2. The width of the Single-window Mode dialog is fixed at 80 text columns to fit within a standard, 80-column dumb-terminal screen.
  3. The height of the Single-window Mode dialog will be at least 25 text rows, and on startup or during Mode switching will automatically expand to fill any additional text rows available in the terminal window.
  4. The terminal window must be at least 80 columns by 25 rows, otherwise the application will not be able to open, and an error message will be displayed.

    Note that the application dialog will not be dynamically resized as the terminal window is resized because this requires closing and re-opening the dialog which would cancel any pending, or in-progress file operations. Dialog sizing occurs only on application startup, when switching between Single-window and Dual-window modes, (see View Mode Selection), or explicity through the “Resize Dialog” option in the View Menu.

    Note also that re-sizing the terminal window while the application is running may corrupt the dialog display (although any file operations in progress will complete normally).

  5. The dialog features and controls within this view are:
    1. Application’s title line
    2. Status control window (read-only textbox control)
      Displays status messages, error messages, or a Quick-help message.
    3. Path-display control window (read-only textbox control)
      Displays the full path of the currently-displayed directory. Note that if the path name is too long to fit in the window, then one or more subdirectory names in the path will be replaced by ellipses.
      Examples:  /home/Fred/Documents/Homework/Fall Semester/Poetry
                 /home/Fred/Documents/.../Poetry
      
    4. Directory Window (interactive scrolling control)
      User commands are captured and interpreted by this control.
      See Command-key Introduction.
      The exception is when the Menu Bar is active, in which case the Directory Window become inactive, and user input will be interpreted by the menuing system.
    5. Statistics control window (read-only textbox control)
      This control displays the number of top-level file and directory names in the Directory Window as well as the combined size (in bytes) of these files.

      If individual filenames or directory trees in the Directory Window have been ’selected’, then statistics on the number of ’selected’ individual filenames, directory names AND the the contents of the selected directories, as well as the combined size of all these files will also be displayed.

      Note that messages regarding certain minor processing errors may also briefly appear in this control.

    6. Menu Bar (a group of drop-down menus and sub-menus)
      The Menu Bar is initially inactive and invisible, and occupies the same space as the application title. The Menu Bar becomes visible and active when one of the menu-invocation keys is detected.

      ┌───────┤ File Edit View Util Help ├───────┐ │Status: E┌────────────────┐ exits menu--ESC exits menu--ESC exits menu ├──────────│File Commands >│────────────────────────────────────────────────┤ /home/samSort Options c+Slip ├──────────│Favorites... c+O│────────────────────────────────────────────────┤
      375View File >59:33 Makefile 8,077Find Files...c+F44:56 XClip.cpp 6,252Mount... c+Y45:25 XClip.o 156,386Refresh c+U49:45 gString.cpp 36,884Set Alt Cwd a+'50:00 gString.hpp 37,368Cmd Shell as+Z43:38 gString.o 43,425Exit c+Q (a+Q)45:26 xclip └────────────────┘ ├────────────────────────────────────────────────────────────────────────────┤ 7 files 288,767 bytes └────────────────────────────────────────────────────────────────────────────┘

      See Accessing the Menu System, to activate the Menu Bar.
      See Configuration, to lock the Menu Bar in the visible state.

    7. Super-user Indicator
      If you invoke FileMangler as the ’SUPERUSER’ (root user), then a status indicator will be displayed near the upper-left-hand corner of the application as a reminder that you are able to inflict maximum damage.

      ┌───────┤ FileMangler - v:0.0.33 (c)2005-2015 [Press F2 for Menu] ├───────┐ │Status: Ctrl+Q=Quit, Shift+F1=Help, F2=Menu [SUPERUSER]─────────────────────────────────────────────────────────────────┤ /home/sam/SoftwareDesign/XClip ├────────────────────────────────────────────────────────────────────────────┤
      375 22-Aug-2013 09:59:33 Makefile 8,077 15-Apr-2014 08:44:56 XClip.cpp 6,252 15-Apr-2014 08:45:25 XClip.o

      Please see invoking as superuser for more information.

  6. Switching between Single-window Mode and Dual-window mode is done through the 'ALT+w' command.

    Please see View Mode Selection for more information.





Next: , Previous: , Up: Operational Overview   [Contents][Index]

Dual-window Mode

In Dual-window Mode, two Directory Windows are displayed side-by-side.

Screen Shot of Dual-window Mode

┌───────┤ FileMangler - v:0.0.33 (c)2005-2015 [Press F2 for Menu] ├───────────────────────────────────┐ │Status: Ctrl+Q=Quit, Shift+F1=Help, F2=Menu ├────────────────────────────────────────────────────────────────────────────────────────────────────────┤ /home/sam/SoftwareDesign/XClip /home/sam/SoftwareDesign/DynaMo ├───────────────────────────────────────────────────┐┌───────────────────────────────────────────────────┤
375 22-Aug-2013 09:59:33 Makefile ││ 4,096 21-Aug-2012 11:31:28 2010_Aug17 8,077 15-Apr-2014 08:44:56 XClip.cpp ││ 18,490 17-Aug-2010 20:32:02 DynaMo 6,252 15-Apr-2014 08:45:25 XClip.o ││ 33,128 17-Aug-2010 20:32:00 DynaMo.cpp 156,386 10-Jan-2014 08:49:45 gString.cpp ││ 393 26-Jul-2010 12:27:52 Makefile 36,884 10-Jan-2014 08:50:00 gString.hpp ││ 194 17-Aug-2010 12:40:02 dy 37,368 15-Apr-2014 01:43:38 gString.o ││ 178 30-Apr-2014 10:39:40 output 43,425 15-Apr-2014 08:45:26 xclip ││ ││ ││ ││ ││ ││ ││ ││ ││ ││ ├───────────────────────────────────────────────────┘└───────────────────────────────────────────────────┤ 7 files 288,767 bytes 6 files 56,479 bytes └────────────────────────────────────────────────────────────────────────────────────────────────────────┘
            Note: This screenshot has been compressed to fit the document width.
  1. Dual-window Mode is based on two Directory Windows, side-by-side. File operations may occur within either window or from one window to the other.
  2. The width of the Dual-window Mode dialog will be at least 118 text columns, and on startup or during Mode switching will automatically expand to fill any additional text columns available in the terminal window (up to 160 columns) with the available columns divided evenly between the two Directory Windows.
  3. The height of the Dual-window Mode dialog will be at least 25 text rows, and on startup or during Mode switching will automatically expand to fill any additional text rows available in the terminal window.
  4. The terminal window must be at least 118 columns by 25 rows for the application to open in (or switch to) Dual-window Mode. If the terminal window is smaller, then the application will open in Single-window Mode if space is available (see Single-window Mode). Otherwise the application will not be able to open, and an error message will be displayed.

    Note that the application dialog will not be dynamically resized as the terminal window is resized because this requires closing and re-opening the dialog which would cancel any pending, or in-progress file operations. Dialog sizing occurs only on application startup, when switching between Single-window and Dual-window modes, (see View Mode Selection), or explicity through the “Resize Dialog” option in the View Menu.

    Note also that re-sizing the terminal window while the application is running may corrupt the dialog display (although any file operations in progress will complete normally).

  5. Note that the following operations REQUIRE Dual-window Mode.
      ’Backup’ (see Backup Your Data)
        and
      ’Synchronize’ (see Synchronize Directories)
  6. The dialog features and controls within this view are:
    1. Application’s title line
    2. Status control window (read-only textbox control)
      Displays status messages, error messages, or a Quick-help message.
    3. Path-display control windows (2) (read-only textbox control)
      There are separate Path-display controls for each Directory Window.
      Displays the full path of the currently-displayed directory. Note that if the path name is too long to fit in the window, then one or more subdirectory names in the path will be replaced by ellipses.
      Examples:  /home/Fred/Documents/Homework/Fall Semester/Poetry
                 /home/Fred/Documents/.../Poetry
      
    4. Directory Windows (2) side-by-side (interactive scrolling control)
      User commands are captured and interpreted by this control.
      The exception is when the Menu Bar is active, in which case the Directory Window become inactive, user input will be interpreted by the menuing system.
    5. Statistics control windows (2) (read-only textbox control)
      There are separate Statistics controls for each Directory Window.
      This control displays the number of top-level file and directory names in the Directory Window as well as the combined size (in bytes) of these files.

      If individual filenames or directory trees in the Directory Window have been ’selected’, then statistics on the number of ’selected’ individual filenames, directory names AND the the contents of the selected directories, as well as the combined size of all these files will also be displayed.

      Note that messages regarding certain minor processing errors may also briefly appear in this control.

    6. Menu Bar (a group of drop-down menus and sub-menus)
      The Menu Bar is initially inactive and invisible, and occupies the same space as the application title. The Menu Bar becomes visible and active when one of the menu-invocation keys is detected.

      Please see Single-window Mode for a screenshot.
      Please see Accessing the Menu System to activate the Menu Bar.
      Please see Configuration to lock the Menu Bar in the visible state.

    7. Super-user Indicator
      If you invoke FileMangler as the ’SUPERUSER’ (root user), then a status indicator will be displayed near the upper-left-hand corner of the application as a reminder that you are able to inflict maximum damage.

      Please see Single-window Mode for a screenshot.
      Please see invoking as superuser for more information.

  7. Switching between Single-window Mode and Dual-window mode is done through the 'ALT+w' command.

    Please see View Mode Selection for more information.





Next: , Previous: , Up: Operational Overview   [Contents][Index]

Tree-view Mode

Tree-view Mode is a temporary mode for quick navigation through the filesystem’s directory tree. No file operations take place in Tree-view Mode. It is only for traveling up and down through the directory-tree hierarchy.
When invoked, Tree-view Mode expands to the full width of the application for maximum viewing area.

┌───────┤ FileMangler - v:0.0.33 (c)2005-2015 [Press F2 for Menu] ├───────┐ ├────────────────────────────────────────────────────────────────────────────┤ /usr/local ├────────────────────────────────────────────────────────────────────────────┤ │ Navigate using cursor keys. BKSP (or ALT+UpArrow) to parent directory. │ │ CTRL+F / CTRL+G = Search, ENTER (or ALT+Q) = new CWD, CTRL+Q to Return. │ ├────────────────────────────────────────────────────────────────────────────┤
.. (parent dir) local bin etc games include lib pkgconfig python2.7 site-packages xcbgen lib64 libexec sbin share applications info locale cs └────────────────────────────────────────────────────────────────────────────┘

                                            Screen Shot of Tree-view Mode

Base directory for Tree-view Mode

The base directory for the initial Tree-view display will be the directory currently displayed in the active File-view window from which Tree-view Mode was invoked. In the example above, the base directory is '/usr/local' as shown in the 'Path' area, and the directory names in the leftmost column (top node) of the Tree-view are 'local' and '..' i.e. the parent directory.

When you exit Tree-view Mode, the directory displayed in the active File-view window will be either the directory from which Tree-view was invoked OR the new current working directory (CWD) which you have selected. See below for details.

Tree-view Mode may be invoked in one of three ways:

  1. If invoked as a command-line option
      (see 't' option)
    then the subdirectory tree is displayed immediately after start-up. This is useful if you intend to immediately navigate to a different directory before performing any file-oriented operations.
  2. Through the menu interface
      (see View Menu)
    open the application’s View menu and select the Tree View item.
  3. Through the command-key interface
      (see View Mode Selection)
    use the 'CTRL+T' command-key sequence.

Navigation within Tree-view Mode:

Some Important Notes

  1. If there are a significant number of subdirectories below the current working directory, then depending on the access speed of the storage medium, it may take several seconds to scan and display them. Please be patient.
  2. All directory names including 'hidden' directories will be read regardless of whether you have specified display of hidden files. This is necessary to avoid gaps in the directory tree.
    Please see Sorting the File List for more information on 'hidden' files.
  3. If the tree scan encounters a subdirectory which contains a mounted, external filesystem i.e. a network drive or removable filesystem, then the contents of the external filesystem IS NOT scanned. A message will be appended to an unscanned subdirectory name indicating that its contents were not scanned.
    Examples:
        /home/Fred/Smb4k(extfs)
        /run/media/Fred/TravelDrive16(extfs)
    

    To view the directory tree of an external filesystem, highlight the directory name and press the ENTER(RET) key. OR to display the full contents of the highlighted filesystem, exit Tree-view via ALT+q.

  4. Certain system subdirectories are not accessible to user accounts; therefore, if such a subdirectory is found within the display path, its contents cannot be read or displayed, but a message will be appended to the directory name indicating that its contents are inaccessible.
    Example:
        /home/lost+found(rdacc)
    




Next: , Previous: , Up: Operational Overview   [Contents][Index]

Special File Types

Certain special handling takes place based upon the ’file-type’ of the file being manipulated. There are seven basic file types, Regular Files, Directories, Symbolic Links, Character Devices, Block Devices, FIFOs and Sockets.

Certain system-specific file types also exist. FileMangler labels
those unusual file types as Other Type or Unknown Type, and
in most cases, will refuse to modify those files.

Most operations take place on ’Regular’ files, so the descriptions of file operations are geared primarily toward those Regular files. Processing for other file types are noted as exceptions to the more general descriptions of the file operations described in the following sections.

Exception #1: Symbolic Links

FileMangler supports display, creation, deletion moving and renaming of Symbolic Links, but does not allow Symbolic Link files to overwrite other (non-link) files. This restriction is implemented to prevent the accidental over-write of useful data by a mere link.

Also, Linux and other UNIX-like systems support two modes for copying of Symbolic Links. The Copy command can either copy the link itself, or copy the file the link points to.

Note that for the cut-and-paste sequence (move files), the link file itself, is always written to the target directory. See the discussion of the ’Paste Special’ command for additional information.
See Copying and Moving Files.

Note to novice users: For users of that other operating system, Symbolic Links are analogus to shortcut files.

Exception #2: FIFOs (First-In-First-Out aka ’Named Pipes’)

Manipulation of FIFOs is a difficult design decision in that a FIFO is very much like a Regular file but has some of the characteristics of a Character Device, meaning that ill-advised changes to or deletion of a FIFO could have serious consequences for your system. FileMangler allows all operations available for Regular files to be used on FIFOs, but displays the names of FIFO files in a distinctive color to encourage thoughtfulness and caution when manipulating files of this type.

Exception #3: Character/Block Devices and Sockets

FileMangler displays (in distinctive colors) but restricts operations on Character Devices, Block Devices, and Sockets. Copying, moving, deleting or renaming files of these types can have serious consequences regarding the performance and functionality of your system. FileMangler always presents a warning message before any modification to these file types is carried out.

Also note that these files are generally owned by the ’root’ user, so it will usually be necessary to log in as the ’SUPERUSER’ before using FileMangler to modify these files. Files of these types should be modified only by a fully-qualified systems administrator. Please see invoking as superuser for more information.

Exception #4: Directories and Directory Trees

Manipulating directories and directory trees offer a special challenge. Although empty directories are handled as if they were regular files, manipulation of directory trees (directories that contain other directories and/or files) provides vast opportunities for creating chaos and destruction.

For safety, we have implemented FileMangler to prompt for confirmation on all operations involving modification of non-empty directory trees. If the name of a non-empty directory has been selected for an operation that will potentially cause a loss of data, a dialog window will ask you to confirm that you really want to perform the operation on an entire directory tree.


Color Coding of Filenames by File Type

Filenames displayed in the directory window are color coded according to file type. The following table describes this color-coding.

 File Type   Display Color
 Regular files Black on White
 Directories Cyan on White
 Symbolic links Blue on White
 FIFO files Brown on White
 Character Devices Magenta on White
 Block Devices Magenta on White
 Unknown or system
  specific types
 Black on White

Note that black on near white is assumed to be the default color for the terminal window. If not, then this color coding will be adjusted accordingly.





Next: , Previous: , Up: Operational Overview   [Contents][Index]

Dialog Controls

FileMangler’s user interface is dialog-based. The main application dialog and various sub-dialogs allow you to interact with the application to issue commands and to retrieve information.

These dialogs use various standard dialog controls such as menus, lists, text-input controls, pushbuttons, radio buttons (on/off switches), spinners and other controls.

Using these controls is straightforward and intuitive, but a brief introduction to each control type may be helpful. The descriptions that follow describe using the keyboard with these controls, but also see Mouse Support for accessing the controls using a mouse.


Menu Controls and Lists

Menu controls and List controls are small windows containing a list of items from which you may choose one item.

The ’Sort By...’ context menu is a typical example of a Menu control.
It provides a list of options for sorting the displayed filenames, and you may choose any one item in the list, either by scrolling the highlight to that item and pressing the ENTER(RET) key or by pressing the ’hotkey’ associated with that item. The ’hotkey’ for the item (if defined) is indicated by the underlined character. For instance, the 'E' character in the word 'Extension' is the hotkey for that menu item.

Pressing the ’E’ or ’e’ key will select the corresponding item in the list, just as if you had moved the highlight to that item and pressed the ENTER(RET) key. The control will be closed, and the files will be sorted according to the filename extension.

┌─────────────────┐ Name Name Reverse Date Date Reverse Size Size Reverse Extension Extension Reverse File Type FileType Reverse No Sort └─────────────────┘

For additional information, See Menu System Interface.


The ‘File-sort Option’ list in the ‘Modify Sort Option’ sub-dialog is an example of a non-menu list. For non-menu lists, the highlighted item is the ‘selected’ item.

As with Menu controls you may select an item by scrolling the highlight to that item and pressing the ENTER(RET) key.

Unlike the Menu controls, you may select an item by placing the hilight on that item and then moving the focus to the next/previous control.
Again: When the input focus leaves the control, the control’s highlighted item is the ‘selected’ item.

To leave a list control without making a selection, press the ESCAPE key. The highlight will return to its original position, the focus will be moved to the next control.

┌───────────────┤ Modify Sort Options ├───────────────┐ │ │ ┌┤ File-sort Option ├┐ < > Reverse sort order │ File Name Modification Date < ◆ > Case-sensitive sort │ File Size Filename Extension < > Show hidden files │ File Type No Sort └────────────────────┘ │ │ │ │ OK CANCEL └───────────────────────────────────────────────────────┘

Special Keys

— ENTER(RET) key or ’hotkey’ (if defined for the item) 'selects' the item
— TAB or SHIFT+TAB key moves to the next/previous control.
— For non-menu lists, the highlighted item is 'selected' implicitly.
— For menu lists, no selection is made by moving to another control.
— Escape key (ESC) leaves the control without making a selection.


Text-input Controls

Text-input controls are used to collect text that you type on the keyboard or to display messages. All Text-input controls have a similar appearance although the text input may be filtered according to the type of information needed.
For instance, some of the text-input filters that may be applied are:
 a) valid filename characters
 b) valid path name characters
 c) valid characters for a URL
 d) alphanumeric data
 e) numeric values
Many other filters may be assigned for specific purposes.

If you enter a character but it does not appear, it is a good indication that the character is not allowed in the current context. Most Textbox controls are also configured to generate an audible alert if an invalid character is entered. Note that only printing characters (visible characters) may be entered into a Text-input control. Control characters and metacharacters are not allowed.

Special Keys

— Scroll keys (LEFT, RIGHT, HOME, END) move the visible cursor.
   Note that the mouse (if enabled) may also be used to position the cursor.
— ENTER(RET) key ends the edit and moves focus to next control.
— TAB key ends the edit and moves to focus to next control.
— SHIFT+TAB key ends the edit and moves to focus to previous control.
— ESCAPE key aborts edit and restores the previous contents.
— INSERT key toggles Insert/Overstrike input mode.
— SHIFT+RIGHT_ARROW selects text toward the right
— SHIFT+LEFT_ARROW selects text toward the left
   Note that the mouse (if enabled) may also be used to select text.
— CTRL+C copies ‘selected’ text to the clipboard
— CTRL+V pastes text from the clipboard at the cursor position

Text may be entered directly from the keyboard or through an Input Method Engine (IME), also known as an Input Method Editor or similar names.

Depending on the type of data displayed and the language for which the application is configured (LTR or RTL), input is either left-justified or right-justified. Also, in general, Text-input controls will accept more data than can be simultaneously displayed within the control. The data you enter is still present even if you cannot see all of it at the same time.

The example below shows the use of a Textbox control for renaming a file.

┌─────────────────────┤ Specify Target Filename ├──────────────────────┐ │ Source Name: FileMangler.cfg │ │ Target Name: │ FileManglerSU.cfg▒ │ ('Insert' toggles Ins/Overstrike mode) INSERT:<◆> │ │ │ OK CANCEL └────────────────────────────────────────────────────────────────────────┘

Pushbutton Controls

As the name implies, a Pushbutton control functions like any button in the physical world, such as the ’Balance Inquiry’ button on a bank machine or the ’Up’ button at an elevator. ’Pushing’ the button activates the functionality associated with that control.

Special Keys

— Enter(RET) or SPACE key activates the control.
— TAB key (or ESC) moves focus to next control.
— SHIFT+TAB key moves focus to previous control.

See the 'OK' and 'CANCEL' Pushbutton controls in the diagram above.


Radio-button Controls

Radio Button controls are so-named because of the array of channel-selection preset buttons often found on car radios. Selecting and de-selecting a Radio Button control is like turning a light switch on or off. For a Radio Button which has the input focus, toggle its on/off state by pressing the SPACE key. (The ’on’ state (but not the ’off’ state) may also be set via the ENTER(RET) key.)

There are two varieties of Radio Button, and each has its uses.

  1. Independent Radio Button
    An independent Radio Button is not associated with any other
    button, and is toggled on or off as described above.
  2. Radio Button Group
    A Radio Button group consists of two or more Radio Buttons logically linked together to form what programmers and math geeks call an ’exclusive-OR’ set.

    One, and only one of the buttons in a Radio Button group may be selected at any given time. If any button in the group is selected (set to the ’on’ state), then all other buttons in the group are reset (to the ’off’ state).

    To put it another way, exactly one group member must be in the ’on’ state at all times. This is similar to the channel-selection buttons on your car radio: you can listen to station A or to station B, but you cannot listen to two stations at once, AND you cannot listen to no station at all (unless you turn off the radio).

There are many visual ’styles’ for Radiobutton controls, but the functionality is the same for all. The ’standard styles’ are shown below.

┌────────────────────────────────────┐ │ │ Standard, 1 columns wide │ │ <> Standard, 3 columns wide │ │ [] Standard, 3 columns wide │ │ () Standard, 3 columns wide │ │ < > Standard, 5 columns wide │ │ [ ] Standard, 5 columns wide │ │ ( ) Standard, 5 columns wide │ │ │ └────────────────────────────────────┘

For additional examples of Radiobutton controls, please see the diagram of the 'Modify Sort  Options' dialog above.


Spinner Controls

A Spinner control provides for selecting a numeric value within a predetermined range. The UpArrow key and DownArrow key are used to cycle through the available values. Moving the input focus to another control sets the control’s value.


Special Keys

Because the range of values may be anywhere between a few integer values to thousands of decimal values, additional key combinations are defined to facilitate efficient selection of the desired value.

Adjusting spinner-control values:

— increment/decrement by 1   : up/down keys (or plus/minus keys)
— increment/decrement by 10  : Shift + up/down keys
— increment/decrement by 100 : Control + up/down keys
— increment/decrement by 1000: Alt + up/down keys
— increment/decrement by 10% : PageUp/PageDown keys
— maximum/minimum value      : Home/End keys
— if enabled, the mouse ScrollWheel can also be used for value
  increment/decrement. See Mouse Support, for more information.
— ENTER(RET) or TAB or SHIFT+TAB key sets the control value.
— Escape key (ESC) returns the control to its previous value.

The example below shows two Spinner controls which are used as 'Width' and 'InitVal' controls for batch rename of files using sequential numerical filenames.

┌──────────────────────┤ Construct Rename Pattern ├──────────────────────┐ │ For automated rename of selected files: select desired option(s), enter │ │ necessary text data, and view a sample of the resulting pattern below. │ │ Sample: Bangkok_Trip-001.fext Before:< > Add text to Beginning of filename. │ │ Insert:< > Insert text before filename extension. │ After :< > Add text to end of filename. │ Replace:< ◆ > Bangkok_Trip- 3± 1± │ Replace base name with text+sequence number, Width InitVal │ │ or if Width=0 replace extension with text. │ Date :< >(yyyymmddhhmmss) OK CANCEL CLEAR HELP └──────────────────────────────────────────────────────────────────────────┘

For an additional example of using Spinner controls, see scheduled backup for setting the delay for a scheduled backup or directory synch operation.


For Additional Information

FileMangler’s dialog-based display and user interface are based on the NcDialog link library which was designed by the same author. For a more detailed description of the dialog window and its controls, please refer to the NcDialog documentation.
See by the same author.





Mouse Support

FileMangler mouse support is available through the 'Enable Mouse' configuration option (see Configuration), or may be enable/disabled for the current session through the 'Mouse Support' item in the 'Utility' menu (see Util Menu).

FileMangler uses the NcDialog API’s ‘Stable Mouse’ implementation. Mouse events which are associated with dialog controls are converted into the equivalent keycode. Any mouse event which is not associated with a user interface control object will be silently ignored.

Important Note: Your mouse must have at least one button and a ScrollWheel in order to use FileMangler’s mouse interface. (ScrollWheel emulation is available through some touchpads and other mouse-like hardware.)

  1. Types of mouse events available to FileMangler

    • Left-button Single Click
    • Left-button Double Click
    • ScrollWheel Events

    Note that left-handed users often swap mouse Button #1 and Button #3. This swap takes place at the mouse-driver level, so that for purposes of this discussion, the ’left’ mouse button is whatever button you have assigned as the primary button during system configuration.

  2. Modifier Keys

    • CTRL (Control) key
    • ALT aka META (Alt) key
    • SHIFT (Shift) key

    Mouse events may be interpreted according to the combination of modifier keys which arrive with the event. Most SHIFT+event combinations are eaten by the system or by the XTerm mouse driver; however, most CTRL+event and ALT+event modifiers are passed through to terminal applications.

  3. File-display Window

    • Single-click:
      Select or de-select the item under the mouse pointer.

    • Click + ALT key:
      Open the 'ViewFile' context menu for viewing information about the target item.

    • Double-click:
    • Single-click + CTRL key:

      If the target item is a directory name, then enter that directory and display the files it contains.

      If the target item is not a directory name, then this is the same as the 'Click + ALT key' above.


    • ScrollWheel
      Move the highlight upward and downward through the list.
      Note: You may also scroll through the data using only the left mouse button:
      — Click in the top border of the window to scroll upward.
      — Click in the bottom border of the window to scroll downward.
      
  4. Path-display Window

    To navigate to the parent of the currently-displayed directory, click on the Path-display window, located just above the File-display Window

  5. Dual-window Mode

    When in Dual-window Mode, click anywhere within the inactive file-display window to make it the active window.

  6. Menus
    The MenuBar is located in the application’s top border, and is invisible by default to save space on the screen. To access the MenuBar using the mouse, click anywhere in the top border, and the menus will become visible.

    The MenuBar remains open until you have made a selection. To close the MenuBar without making a selection, click the mouse anywhere in the application that is not part of a menu.

    • Menu-item Selection
      A single-click or double-click, with or without modifier keys will select the menu item under the mouse pointer.
    • ScrollWheel
      Use the ScrollWheel to move upward and downward through the menu items. Note that the highlight will wrap around from bottom to top, or from top to bottom.
  7. Sub-dialog Windows
    Sub-dialogs may contain multiple types of controls: lists, radiobuttons, pushbuttons, spinners, text-input controls and others.

    In general, using the mouse to access these controls is straightforward and intuitive. A few special cases exist.

    • Radiobutton Controls
      Set/reset the target Radiobutton. For Radionbuttons which are part of an exclusive-OR Radiobutton group, only one button of the group may be in the ’set’ state.
    • Textbox Controls
      For Textbox controls, use the ScrollWheel to move the insertion point (visible cursor) right or left through the text.

      The ScrollWheel in combination with the SHIFT modifier key ’selects’ the text under the cursor for copying to the clipboard.

    • Spinner Controls
      Use the ScrollWheel to increase or decrease the displayed value.
      The SHIFT, CTRL and ALT modifier keys multiply the speed of the increase/decrease by 10, 100 or 1000, respectively.
    • Controls that Display Lists of Items
      Like simpler versions of the main File-display windows discussed above, list controls allow scrolling through the data using the ScrollWheel, and an item is ‘selected’ by clicking the mouse on the desired item.


 Please see Dialog Controls for more information on the
 user-interface controls.

 Please see the documentation for the NcDialog API for technical
 details on how each user-input control responds to mouse input.


Author’s Note: Capturing stable and reliable text-based mouse events presents many technical challenges. First, the X-windows mouse is filtered through layers of complexity before the terminal even sees it. Then, the XTerm mouse interface is, (for lack of a better word), ‘hijacked’ by the 'ncurses' C-language library. While ncurses does what it can to provide baseline mouse support across multiple platforms—the result is not impresive. The author’s NcDialog API, on which the FileMangler application is based, works hard to overcome most of these deficiencies, but please do not expect miracles.
Software Sam




Invoking

Summary of Options

  OPTION  DESCRIPTION
  'w' option Operating Mode  (single or dual window)
  's' option Sort Order  (file sorting option)
  'a' option Alternate Locale  (non-default locale)
  'f' option Specify an alternate configuration file
  'd' option Specify the start-up directory       (first directory to view)
  'b' option Specify a Backup or Synch operation  definition file
  't' option Start in Tree-view Mode
  'm' option Enable Mouse Support
  'c' option Color Scheme (application colors)
  'C' option Configure FileMangler            (interactive configuration)
  'h' option Display command-line Help          (short form help option)
  'p' option Pause for diagnostic data          (debug option)
  'version' option Display application version and  copyright information
  'help' option Display command-line Help        (summary of options)

Usage

    fmg [OPTIONS]
  1. Options may be specified in any order.
  2. Each option must be preceeded by the dash/minus (’-’) character and must be immediately followed by its argument (if any).

    Example: fmg -wt -sd -t -d=Documents

    Exceptions:
    Options without arguments, and options with single-character arguments may be concatenated (in any order) into a single token.

    Example: fmg -tpwdsD

    An option with a multi-character argument (e.g. a filename) may also be concatenated; however, it must be the last option in the sequence.

    Example: fmg -wsd=Documents

  3. For options that require a pathname, filename or other multi-character argument, the argument may be specified in either of two ways:
    • The option is immediately followed by the '=' (equals) character, which must be immediately followed by the argument.
    • The option is followed by whitespace (one or more space characters) and the argument must be the next token on the command line.

    If the argument contains space characters, then enclose the argument within quotation marks to indicate that it is a single token.

    Examples:
        fmg -c=blue
        fmg -d=/usr/local/lib
        fmg -d '~/Downloads/game patches'
        fmg -f ../special.cfg
    
  4. Unless otherwise noted, options and their arguments are not case sensitive; however, if you are writing scripts, it is recommended that you use the documented uppercase/lowercase version because additional options may be added in a later FileMangler release. The following are equivalent:
        fmg -wd -sd -P
        fmg -WD -Sd -p
    
    1. Note that '-c' (Color Scheme) and '-C' (Configure ) are different options.
    2. Note that the arguments of the '-s' (Sort) option are case sensitive.
    3. Filename and pathname arguments are, of course, case sensitive.
  5. If a given option is specified more than once (not recommended), then the last occurrance of the option on the command line will be recognized.
  6. All options are optional, so for any option that is left unspecified, its setting will be determined by the value specified in the configuration file. See Configuration.
  7. If an invalid command-line option or argument is detected, then a list of valid options (command-line Help) will be displayed and the application will exit.
  8. Note that '--help' ('-h') overrides all command options, and that '--version' overrides all other options.

Invocation Mechanism

  1. FileMangler is invoked through the memory-resident function: 'fmg'. This function is created during the installation process, and by default is located in the file '$HOME/.bashrc'
  2. If the 'fmg' function is not found, then FileMangler is invoked through the shell script 'fmg' or 'fmg.sh' located in a directory on your executable path (see $PATH environment variable). Note, however, that some functionality is lost if the memory-resident function is not used.
  3. Direct invocation of FileMangler through the 'FileMangler' executable binary is not recommended because some functionality may be lost and/or the application may not be able to find its configuration file.
  4. Please refer to
      See Configuration, or to
      See Manual Installation,
    for detailed information on the invocation mechanism.

Invoking as SuperUser

Invoking FileMangler when operating as the 'SUPERUSER' (’root’ user) requires a slightly different procedure. The reason for this is that the SuperUser generally does not have a '$HOME' directory in the same sense as a regular user account, (where applications are installed), and the login scripts for the ’root’ user are often inaccessible. For these reasons, please keep the following in mind.

  1. By default, the SuperUser’s '$HOME' directory is '/root' which is an inappropriate location for installing an application.

    Thus, the location of the binary executable, configuration file and other support files for the SuperUser must be explicitly indicated, either directly on the command line or through a shell script.

  2. When working in a terminal window, there are two primary mechanisms for invoking an application as the SuperUser.

    1. Log in as the SuperUser and then invoke the application.
      [Fred]$ su
              password4root
      [root]# fmg
      
    2. Invoke the application with root privilege using the 'sudo' command.
      [Fred]$ sudo fmg
              password4Fred
      
  3. Invocation of FileMangler when operating as the SuperUser should always specify an alternatate configuration file which describes the SuperUser’s working environment.
    Example when logged in as 'root':
       fmg -f=/home/admins/Apps/FileMangler/FileMangler.cfg
       
    Example when executing a single command with 'root' privilege:
       sudo fmg -f=/home/admins/Apps/FileMangler/FileMangler.cfg
    

    Note that for these examples, the SuperUser’s copy of the configuration file (and other support files) is in a user-space directory, '/home/admins/Apps/FileMangler'.
    Please see Configuration for additional details.

  4. The 'sudo' command.
    The 'sudo' command is a security protocol which allows an ordinary user to execute a command or an application with administrative privilege. While this is an excellent security device, it has its problems.

    1. Note that to use the 'sudo' command, your user ID must list you as a member of the 'wheel group'. To determine whether your user account is part the wheel group, use the 'id' command.
      Example for user 'Fred':
      
         id -Gn
         Fred sys lp klingon wheel
      

      If you are not a member of the 'wheel group', then as SuperUser, you will need to add yourself.
      (See the 'usermod' system-maintenance command for details).

    2. In addition, the '$PATH' environment variable for the 'sudo' command may not include all the same search directories that are available when logged in as the SuperUser; therefore, a copy of the 'fmg' and 'fmg.sh' shell scripts should be placed where the 'sudo' command can find them. To determine the available path locations, use:
      [Fred]$ sudo echo $PATH
              password4Fred
      
    3. The 'sudo' command cannot easily be made to see a memory-resident function, so the exit-to-CWD command, 'ALT+q' will probably not work under 'sudo', (see next item).
  5. Finally, neither the SuperUser’s environment nor the 'sudo' command’s environment will have the memory-resident function needed for the application to exit into the current-working directory.
    Please See Exit the Application.

    An appropriate memory-resident function can be added to the SuperUser’s 'bashrc' (or equivalent) login script; however, as mentioned, the 'sudo' command will not have the equivalent function.

  6. The special requirements for a SuperUser installation are discussed in more detail at see Multi-user Installation.
  The next chapter describes each command-line option in detail.
 



Up: Invoking   [Contents][Index]

Invocation Options

This chapter describes each command-line option in detail. Please see the previous chapter (see Invoking), for an overview of FileMangler invocation.

–w Select FileMangler's operating mode.

The Operating Mode specifies the way the file data will be initially displayed, either all data are displayed in a single window, or data are displayed in two independent windows. The Operating Mode may be toggled between these two modes during operation.

The '-w' option take one argument as shown:

    fmg -ws       Single-window Mode
    fmg -wd       Dual-window Mode
    fmg -wt       Terminal width determines operating mode (default)

Single-window Mode

As the name implies, Single-window Mode will display the files of the current directory in a single view. Navigation among parent and child directories and operations on the displayed files are handled within this view.
See Single-window Mode.

Please note that the minimum terminal window size required for FileMangler invocation is 80 columns x 25 rows, Therefore Single-window Mode will be necessary for terminal windows that are limited to the basic 80-column width.

Dual-window Mode

This mode is available for terminal windows that can be expanded to at least 118 columns x 25 rows. On start-up, the files of the current directory are displayed in two, independent views, and each view may be changed to different parent and/or child directories. Operations on the displayed files may occur within either view or from one view to the other.
See Dual-window Mode.

If Dual-window Mode is specified, but the terminal window is too small, then a warning message will be displayed, and then the application will start in Single-window Mode instead.

Automatic Operating-Mode Selection

The automatic-selection option allows the Operating Mode to be determined by the width of the terminal window. If the terminal window is large enough, FileMangler will open in Dual-window Mode, else in Single-window mode.

Default Setting

  • If no Operating Mode is specified on the command line, then the mode is taken from the configuration file.
  • If no Operating Mode is specified on the command line AND if the configuration file contains no setting for the Operating Mode, or if no configuration file was found, then 'Automatic Operating Mode Selection' is the default.
  • NOTE: On start-up, FileMangler will always expand to the full height of the terminal window, regardless of which Operating Mode is selected.

Please also see 't' option, below for starting FileMangler in Tree-view Mode.



–s Sort order for filenames.

The Sort Order option, followed by one of the listed arguments, specifies the initial sort order for the entries listed in the display window(s). Entries may be sorted by:

  • Filename
  • Modification Date
  • File Size
  • Filename Extension
  • File Type
  • No Sort
Each of these options may be ordered:
   low-to-high (ascending)
     Example (by file size ascending) :  fmg -ss
   high-to-low (descending)
     Example (by file size descending):  fmg -sS

Arguments for the Sort Order option
(these arguments ARE case sensitive):

  • n : by filename, ascending (default)
  • N : by filename, descending
  • d : by file-modification date, ascending
  • D : by file-modification date, descending
  • s : by file size, ascending
  • S : by file size, descending
  • t : by file type (regular, FIFO, SymLink, Socket, etc.)
  • T : by file type, descending
  • e : by filename extension (.odt, .hpp, .jpg, etc.)
  • E : by filename extension, descending
  • u : No Sort - display the entries in the same order
        they are stored in the directory).

Note that subdirectory names are grouped at the top of the list except for sub-options 'T' and 'u'.

Default Setting

  • If no Sort Order is specified on the command line, then the initial order is taken from the configuration file.
  • If no Sort Order is specified on the command line AND if the configuration file contains no setting for the Sort Order, or if no configuration file was found, then '-sn' (by filename, ascending) is the default.


–a Specify an alternate locale.

The 'locale' is the set of rules provided by your operating system for language-specific or region-specific character interpretation and display on your local system.

By default, the locale is taken from the terminal environment, and this is usually the correct setting for your system; however, this can be overridden by specifying an alternate locale on the command line.

Example:
    fmg -a=yue_HK.utf8

Any locale supported by your system may be specified PROVIDED that it supports UTF-8 encoding. Note that UTF-8 encoding is the default for GNU Linux and most other modern implementations.

For a complete listing of locales supported by your system, at the command prompt, type: 'locale -a'

Default Setting

  • If no Locale is specified on the command line, then the locale setting is taken from the terminal’s environment.
  • If your system is properly configured, a locale setting will be included as part of the terminal environment; however, if no locale is specified by the terminal environment, or if the locale specified does not support UTF-8 character encoding, then a warning message will be displayed and the default C-language (ASCII English) locale will be used. If this happens, then filenames containing non-ASCII characters may not be displayed properly.


–f Specify location of the configuration file.

By default, the FileMangler start-up sequence reads configuration data from the default configuration file, 'FileMangler.cfg'. This file is located in the directory where the 'FileMangler' executable binary file is installed.

For normal operation, this is the appropriate action; however, if there are multiple users accessing a shared binary (executable) file or if you have special operations to perform at different times, then an alternate configuration file may be specified for each user or special operation.

FileMangler.cfg is a plain-text, fully self-documented configuration file which may be edited manually, OR may be modified through FileMangler’s configuration utility (see 'C' option).

Simply make a copy of FileMangler.cfg and modify the copy for your needs. Then invoke the application with the name of your customized configuration file.

Examples:
    fmg -f=custom.cfg
    fmg -f '~/Apps/cfg/fmg_saturday_backup.cfg'

Please see Configuration, for complete details.



–d Specify the directory path for initial view.

By default, FileMangler opens with a display of the terminal window’s current working directory (CWD); however, an alternate initial-directory path may be specified so explicit navigation to that directory is not needed.

Example (absolute path):
    fmg -d=/run/media/sam/TravelDrive8GB

Example (relative path):
    fmg -d=../Photos

Example (path which includes environemnt variables):
    fmg -d=$HOME/Downloads

Note that on exit, FileMangler returns to the original CWD unless you specify an exit to the currently-displayed directory.
Please see Exit the Application for more information.



–b Backup or Synch definition file.

Specify a definition for a Backup or Synchronization operation to be launched at startup.

Example (absolute path):
    fmg -b=~/Apps/FileMangler/Backup_Def.txt

Example (relative path):
    fmg -b=./Backup_Def.txt

The definition file is is a plain text file which optionally specifies:

  • the type of operation: Backup, Synch, or Archive
  • source-data path
  • target path
  • the time at which to begin the operation
  • filename of optional archive file
  • categories of files to be excluded from operation

Please see Backup Your Data, or
see Synchronize Directories for more information.



–t Start FileMangler in Tree-view Mode.

Immediately after completion of the application’s start-up sequence, switch to Tree-view Mode which displays the contents of the filesystem as a directory-tree strucure starting from the current working directory (CWD) and and continuing through all lower-level subdirectories.

Note that only directory names are displayed in this view.

Example:
    fmg -t

Please see see Tree-view Mode, for more information.



–m Enable Mouse Support.

Enable the mouse interface. The mouse can be used to scroll through display data, select files and subdirectory trees for processing, to access the Menu Bar and to interact with the various application sub-dialogs.

The mouse interface is an operational convenience only and is not necessary for access to FileMangler’s full functionality.

Example:
    fmg -m

Please see see Mouse Support, for more information.



–c Set the application's Color Scheme.

Specify the Color Scheme for the FileMangler application.

The Color Scheme includes border colors, dialog window interior colors, color of dialog controls such as menus, pushbuttons, text-entry controls and other color options.

Available Color Schemes:

  • black
  • red
  • green
  • brown
  • blue
  • magenta
  • cyan
  • grey
  • term’ — Terminal default (usually black on near-white and always ugly)
  • default’ — FileMangler default Color Scheme.
Example:
    fmg -c=red

Default Setting

  • If no Color Scheme is specified on the command line, then the color scheme is taken from the configuration file.
  • If no Color Scheme is specified on the command line AND if the configuration file contains no setting for the Color Scheme, or if no configuration file was found, then the application’s default color scheme is used.
  • For examples of color schemes see Configuration.


–C Configure FileMangler.

Interactively configure FileMangler.

When the configuration utility is invoked, it will by default display the values read from the default configuration file, 'FileMangler.cfg', located in FileMangler’s installation directory. Any changes to the configuration will also be stored in FileMangler.cfg.

Important Note:
If the ’-f’ command-line option is used to specify an alternate configuration filename, then the values initially displayed will be taken from the specified file, and any changes to the configuration will be written to that file.

Examples:
    fmg -C
    fmg -C -f=./special_fmg.cfg

Please refer to the chapter, see Configuration for details.

The configuration utility may also be invoked from within the application via the ’Util’ menu.
Please see Menu System Interface for details.



–p Pause to view start-up diagnostics.

Before the main application window opens, certain start-up diagnostic messages are displayed in the console window.

Normally, it is unnecessary to read these messages, but if FileMangler is not behaving as you think it should on a given system, pausing the application for a few seconds during start-up may provide an indication of the corrective action needed.

Example:
    fmg -p

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

An optional 'verbose' sub-argument is available with the Pause option, and although it is really useful only during development, it can be used to track the start-up sequence in greater detail.

Example:
    fmg -pv

— Note that this will cause the start-up sequence to pause until
a key is pressed before opening the main application.
— Note also that the verbose diagnostics require a terminal window
of at least 30 Rows x 132 Columns for proper display.



–h Display FileMangler command-line help.

This is the short form of the 'help' option, below.



––help Display FileMangler command-line help.

Command-line Help. Display a brief summary of command-line usage and options. (overrides everything on command line except '--version')



––version Report FileMangler version number.

Display the FileMangler version number and copyright information. (overrides everything else on command line)




Next: , Previous: , Up: Top   [Contents][Index]

Command Interface

Overview

Access to FileMangler’s functionality is provided through command-key combinations. The modifier keys, CTRL, ALT, SHIFT are used in combination with other keys to produce the command-key sequence.

The following chapters provide detailed command definitions, the key-combination assigned to the command and notes on command-key customization.

Note that all functionality available through the Command Interface is also available through the Menu System Interface.
See Menu System Interface.







Command-key Introduction

Definition of Terms

key binding    : assignment of a key combination to a particular function
remapping      : modification of key-combination assignments
input focus    : indicates which dialog control will receive user’s key input
GUI            : Graphical User Interface
CWD            : Current Working Directory, the directory which is
               : displayed in the active directory window
navigate       : move input focus from one dialog control to another, OR
                 move the highlight from one filename to another, OR
                 move up or down through the directory-tree structure
highlight        in a window with scrolling data, the item which is
                 displayed with a contrasting background color is the
                 highlighted item.
recursion      : moving downward through each level of the directory tree 
                 gathering information on each file found


Working in the Directory Window

The primary operational state of the application is when the input focus is on a Directory Window. You may navigate through the list of filenames and directory trees, select files for processing and use command-key sequences to invoke the desired operation. For a diagram of the Directory Window(s), please see the sections:
See Single-window Mode,
See Dual-window Mode.

To ’select’ a file or directory tree for processing, move the highlight to that item using the scrolling keys, then press the SPACE key to select that item. ’Selected’ items are visually indicated by underlining them.

Use any command-key sequence described below to perform the desired operation on all selected items.

For more detailed information about working within a Directory Window, please see Navigation.

Command Keys

The command descriptions in the following chapters cover the use of command keys to navigate within the directory-tree display windows and to perform common tasks.

The bindings discussed here are for the default key bindings. For most tasks, the key binding for the function can be be remapped to a different key combination through the FileMangler configuration utility.
See Customizing Key Commands.

Note to novice users: A Command-key combination consists of pressing and holding one or more of the modifier keys (CTRL, ALT, SHIFT), and then pressing an additional key and releasing all keys. For example:
The ’CTRL+Q’ command (Quit) is executed by pressing and holding either ’CTRL’ key, then pressing the ’Q’ key and immediately releasing both keys.

Working Around GUI limitations

The key combinations available as command keys within a console application may be limited by the operating system’s GUI desktop interface, and further limited by the terminal emulation program interface which both reserve various keycodes for their own use. To some extent, the keycodes available to the console may be adjusted by disabling various "accelerator keys" through preferences settings. However, it is not practical to disable all the accelerator keys, so compromises must be made.

In most cases, a given FileMangler function is associated with exactly one command-key combination; however, in cases where the intuitive selection for a comand-key-to-function key mapping is likely to be unavailable, more than one command-key combination may be assigned to the function.

For instance, the F01 function key is traditionally associated with ’Help’; however, the F01 key is captured by the terminal emulation program’s own ’Help’ invocation, so FileMangler’s ’Help’ is bound to both the F01 key and to the Shift+F01 key to ensure that FileMangler’s Help is available. Menu mnemonics and the ALT+0 to ALT+9 group of accelerator keys are other common examples of keycodes which may not be accessible to console applications.

Mouse Support

All FileMangler functionality is available quickly and efficiently through the command-key interface and/or through the menu interface; so mouse support is not generally a big advantage. However, for those who are more comfortable with using a mouse, FileMangler provides optional support for a mouse-driven user interface which can handle most tasks by transparently transforming mouse input to the equivalent command-key.

A text-based mouse interface is necessarily limited in what it can do, so some functionality must still be accessed through the keyboard. Give the mouse interface a try to see if it’s right for you.
Please see Mouse Support for more information.





Default Key Bindings

The command combinations listed in this section are grouped alphabetically, according to the modifier keys (CTRL, ALT, SHIFT) used in creating the command-key combination.

Please see Command Definitions for an list of commands grouped according to functional category.

Special note on the CAPS LOCK key: All command-keys are generated with CapsLock OFF. If CapsLock is on, then pressing the indicated command-key combination may generate the wrong keycode.
For instance:

With CAPS LOCK = OFF:
ALT+SHIFT+T   opens the Trashcan Management dialog
With CAPS LOCK = ON:
ALT+SHIFT+T   generates the ALT+A key (unassigned by default)
The default command-key definitions are specifically laid out to avoid CapsLock-related accidents; however, if you press a command-key combination and nothing happens, (or something unexpected happens), please check the state of the CapsLock key.


Commands using the ‘CTRL’ (Control) modifier key:

CTRL+A key Select/Deselect all files

See Selecting Files.

CTRL+B key (unassigned by default)
CTRL+C key Copy selected file(s) to Clipboard

See Copying and Moving Files.

CTRL+D key Update Timestamp of selected file(s)

See Changing the Timestamp.

CTRL+DELETE key Move selected file(s) to Trashcan

See Move Files to Trashcan.
See also SHIFT+DELETE command.

CTRL+E key Write-enable selected file(s)

See Changing File Attributes.
See also CTRL+W command.

CTRL+F key Find files by name

See Find Files in Directory Tree.

CTRL+G key Scan file(s) for matching substring

See Grep Files.

CTRL+H key (unassigned by default)
CTRL+I key (unavailable as a command-key)
CTRL+J key (unavailable as a command-key)
CTRL+K key Display list of command keys

See List of Command Keys.

CTRL+L key (unassigned by default)
CTRL+M key (unavailable as a command-key)
CTRL+N key Create a new subdirectory in the current directory

See Create a New Directory.

CTRL+O key Open ’Favorite Directories’ dialog

See Favorite Directories List.

CTRL+P key (unassigned by default)
CTRL+Q key Quit - exit the application

See Exit the Application.
See also ALT+Q command.

CTRL+R key Rename the selected file(s)

See Renaming Files.

CTRL+S key Sort the displayed files

See Sorting the File List.

CTRL+T key Tree-view Mode

See View Mode Selection.
See Tree-view Mode.

CTRL+U key Update File List

See View Mode Selection.

CTRL+V key Paste files from clipboard

See Copying and Moving Files.
See also the ’Paste Special’ command: ALT+INSERT

CTRL+W key Write-protect selected file(s)

See Changing File Attributes.
See also CTRL+E command.

CTRL+X key Cut selected file(s) to Clipboard

See Copying and Moving Files.

CTRL+Y key Mount or Unmount Filesystems

See Mounting Filesystems.

CTRL+Z key Undo most recent copy or move operation

not yet implemented
(reserved for future development)

Note that the CTRL+SHIFT+n key combinations produce the same key type/code as the CTRL+n key combinations.


Commands using the ‘ALT’ (Alt/Meta) modifier key:

ALT+A key (unassigned by default)
ALT+B key (unassigned by default)
ALT+C key (unassigned by default)
ALT+D key (unassigned by default)
ALT+E key Access ’Edit’ menu (may be captured by terminal)

See Accessing the Menu System.
See also ALT+SHIFT+E command.

ALT+F key Access ’File’ menu (may be captured by terminal)

See Accessing the Menu System.
See also ALT+SHIFT+F command.

ALT+G key (unassigned by default)
ALT+H key Access ’Help’ menu (may be captured by terminal)

See Accessing the Menu System.
See also ALT+SHIFT+H command.

ALT+I key Toggle visibility of hidden files

See Hidden Files Toggle.

ALT+J key (unassigned by default)
ALT+K key (unassigned by default)
ALT+L key (unassigned by default)
ALT+M key (unassigned by default)
ALT+N key (unassigned by default)
ALT+O key (unassigned by default)
ALT+P key (unassigned by default)
ALT+Q key Quit - exit application to current directory

See Exit the Application.
See also CTRL+Q command.

ALT+R key (unassigned by default)
ALT+S key (unassigned by default)
ALT+T key (unassigned by default)
ALT+U key Access ’Util’ menu (may be captured by terminal)

See Accessing the Menu System.
See also ALT+SHIFT+U command.

ALT+V key Access ’View’ menu (may be captured by terminal)

See Accessing the Menu System.
See also ALT+SHIFT+V command.

ALT+W key Toggle between Single-, Dual-Window Mode

See View Mode Selection.

ALT+X key (unassigned by default)
ALT+Y key (unassigned by default)
ALT+Z key (unassigned by default)

ALT+0 key (unassigned by default)
ALT+1 key (unassigned by default)
ALT+2 key (unassigned by default)
ALT+3 key (unassigned by default)
ALT+4 key (unassigned by default)
ALT+5 key (unassigned by default)
ALT+6 key (unassigned by default)
ALT+7 key (unassigned by default)
ALT+8 key (unassigned by default)
ALT+9 key (unassigned by default)

ALT+INSERT key Paste Special

See Copying and Moving Files.

ALT+' key Set Alternate Directory Window’s CWD

See View Mode Selection.


Commands using the ‘SHIFT’ modifier key:

Normal, printing characters, whether or not they are combined with the SHIFT key, cannot be used as command keys. Example: Neither ’5’ nor SHIFT+5 (’%’) can be used as a command key. For this reason, few commands may be defined using only ‘SHIFT’ plus one other key. The exceptions are:

SHIFT+DELETE key Delete files unconditionally

See Delete Files Permanently.
See also CTRL+DELETE command.

SHIFT+F01 key Invoke online help

See Invoke Online Help.
See also F01 command.


Commands using the ‘ALT+SHIFT’ modifier keys:

ALT+SHIFT+A key Create or expand archive files

See Working With Archives.
See also ALT+SHIFT+B command.

ALT+SHIFT+B key Data backup

See Backup Your Data.
See also ALT+SHIFT+A command.

ALT+SHIFT+C key Compare Files

See Compare Files.

ALT+SHIFT+D key (unassigned by default)
ALT+SHIFT+E key Edit Menu access

See Accessing the Menu System.
See also ALT+E command.

ALT+SHIFT+F key File Menu access

See Accessing the Menu System.
See also ALT+F command.

ALT+SHIFT+G key (unassigned by default)
ALT+SHIFT+H key Help Menu access

See Accessing the Menu System.
See also ALT+H command.

ALT+SHIFT+I key (unassigned by default)
ALT+SHIFT+J key (unassigned by default)
ALT+SHIFT+K key (unassigned by default)
ALT+SHIFT+L key (unassigned by default)
ALT+SHIFT+M key Activate the Menu Bar

See Accessing the Menu System.

ALT+SHIFT+N key (unassigned by default)
ALT+SHIFT+O key (unassigned by default, not recommended)
ALT+SHIFT+P key (unassigned by default)
ALT+SHIFT+Q key (unassigned by default)
ALT+SHIFT+R key Undo most recent ‘move-to-trashcan’

See Restore from Trashcan.
See also ALT+SHIFT+T command.

ALT+SHIFT+S key Synchronize data between filesystems

See Backup Your Data.
See also ALT+SHIFT+B command.

ALT+SHIFT+T key Manage the Trashcan

See Manage the Trashcan.
See also ALT+SHIFT+R command.

ALT+SHIFT+U key Util Menu access

See Accessing the Menu System.
See also ALT+U command.

ALT+SHIFT+V key View Menu access

See Accessing the Menu System.
See also ALT+V command.

ALT+SHIFT+W key (unassigned by default)
ALT+SHIFT+X key (unassigned by default)
ALT+SHIFT+Y key (unassigned by default)
ALT+SHIFT+Z key Go To Command Shell

See Shell Out.


ALT+SHIFT+0 key (unassigned by default)
ALT+SHIFT+1 key (unassigned by default)
ALT+SHIFT+2 key (unassigned by default)
ALT+SHIFT+3 key (unassigned by default)
ALT+SHIFT+4 key (unassigned by default)
ALT+SHIFT+5 key (unassigned by default)
ALT+SHIFT+6 key (unassigned by default)
ALT+SHIFT+7 key (unassigned by default)
ALT+SHIFT+8 key (unassigned by default)
ALT+SHIFT+9 key (unassigned by default)

ALT+SHIFT+' key Dual-window Navigation Lock

See View Mode Selection.

ALT+SHIFT+; key FileMangler Clipboard Management

See Manage FileMangler Clipboard.

ALT+SHIFT+[ key Display User Information

See Display User Info.

ALT+SHIFT+] key Display Filesystem Information

See Display Filesystem Info.


Commands using the ’ALT+CTRL’ modifier keys:

ALT+CTRL+A key (unassigned by default)
ALT+CTRL+B key (unassigned by default)
ALT+CTRL+C key (unassigned by default)
ALT+CTRL+D key (unassigned by default)
ALT+CTRL+E key (unassigned by default)
ALT+CTRL+F key (unassigned by default)
ALT+CTRL+G key (unassigned by default)
ALT+CTRL+H key (unassigned by default)
ALT+CTRL+I key (unassigned by default)
ALT+CTRL+J key (unassigned by default)
ALT+CTRL+K key (unassigned by default)
ALT+CTRL+L key (unassigned by default)
ALT+CTRL+M key (unassigned by default)
ALT+CTRL+N key (unassigned by default)
ALT+CTRL+O key (unassigned by default)
ALT+CTRL+P key (unassigned by default)
ALT+CTRL+Q key (unassigned by default)
ALT+CTRL+R key Resize Application Dialog

See View Mode Selection.

ALT+CTRL+S key (unassigned by default)
ALT+CTRL+T key (unassigned by default)
ALT+CTRL+U key (unassigned by default)
ALT+CTRL+V key (unassigned by default)
ALT+CTRL+W key (unassigned by default)
ALT+CTRL+X key (unassigned by default)
ALT+CTRL+Y key (unassigned by default)
ALT+CTRL+Z key (unassigned by default)

Note that the ALT+CTRL+SHIFT+n key combinations produce the same key type/code as the ALT+CTRL+n key combinations.


Please see Customizing Key Commands for information on modifying command key assignments.





Command Definitions

Command definitions in this chapter are grouped according to functional category. Please see Default Key Bindings for an alphabetical list of commands.

For file operations, certain special processing takes place for
file types other than ’Regular’ files. For more information,
please see Special File Types.






Navigation

Moving the File Highlight

Within the directory-display window one file or directory name is highlighted, indicating which file will be affected by an operational command (but also see Selecting Files). Moving the highlight is done in an intuitive way using the navigation keys.

 Up Arrow key

If highlight is not already at the top of the display data, move the highlight upward by one line, shifting the displayed data downward if necessary.

 Down Arrow key

If highlight is not already at the bottom of the display data, move the highlight downward by one line, shifting the displayed data upward if necessary.

 Page Up key

If highlight is not already on the first item in the window, highlight the first item in the window. Else, if first displayed item is not the first item in the list, shift the display items downward until the formerly-displayed items are replaced by a new group of items or until the top of the list is reached. The highlight will be on the first item in the window.

 Page Down key

If highlight is not already on the last item in the window, highlight the last item in the window. Else, if last displayed item is not the last item in the list, shift the display items upward until the formerly-displayed items are replaced by a new group of items or until the end of the list is reached. The highlight will be on the last item in the window.

 Home key

If highlight is not already on the first item in the list, shift the display items downward until first item in list is displayed at the top of the window and place the highlight on the first item in the list.

 End key

If highlight is not already on the last item in the list, shift the display items upward until last item in list is displayed at the bottom of the window and place the highlight on the last item in the list.

 Locate a file by name

To locate a specific file displayed in the current directory window, simply start typing its filename. All filenames displayed in the window are scanned, and the first filename matching the provided text will be highlighted. (Note that the scan is not case sensitive.)
Please see Find Files by Name for more information.


Moving Between Directory Windows

 TAB key
 SHIFT+TAB key

If the application is in Dual-window Mode these two keys move the input focus to the alternate directory-display window which then becomes the active window. The highlight becomes visible in the active window and invisible in the inactive window.
See Dual-window Mode.

In Single-window mode, TAB and SHIFT+TAB are ignored.
See Single-window Mode.


Moving Through the Filesystem Directory Tree

 ENTER (RET) key

When the highlight is on a subdirectory name, pressing the ENTER(RET) key will display the contents of that subdirectory.

Note that if the highlight is on a filename that is not a subdirectory, then the ENTER(RET) key does not act as a navigation key, but rather will open the 'View File' context menu.
Please see View File Contents, for more information.

 ALT+ENTER key

When highlight is on a non-directory filename, then this key is the same as the ENTER key, above.

When highlight is on a directory filename, then this key opens the context menu as decribed for the ENTER key, above.

 BACKSPACE key
 ALT+UpArrow key

Display the parent directory of the currently-displayed directory.
The parent directory is the directory that contains the currently-displayed directory.

Note that if the currently-displayed directory is the ’root’ ( '/' ) i.e. top-level directory, then the command will be ignored.





Selecting Files

Selection of the file or files to be operated upon is performed using the following command-key combinations.

A ‘selected’ item is visually indicated by underlining the item.


 SPACE key

Mark the currently-highlighted file as ‘selected’.

Marking a file indicates that a subsequent ‘Copy’, ‘Cut’, ‘Rename’, ‘Delete’ or other command will apply to that file as well as to all other marked files in the window.

 SHIFT+DownArrow
 SHIFT+UpArrow

Select a Sequence of Files

While the Shift key is held down, pressing the Up Arrow or Down Arrow key will select the current file AND the next file in the indicated direction.

If, however the next file in the indicated direction is already selected, then the current file AND the next file will be de-selected.

 CTRL+A key

Select (or de-select) ALL files in the the window.

If there are no previously-selected files in the directory window, select all files in the window. Marking these files indicates that a subsequent ’Copy’, ’Delete’ or other command will apply to all files in the window.

If there are previously-selected files in the directory window, then all selected files will be de-selected.


Notes on file selection:

  1. If no files have been explicitly selected at the time a 'Copy', 'Delete' or other command is issued, then the highlighted file is implicitly selected as the file upon which the command will operate. This is both an important convience and a potential source of user error. Consider carefully the implications of this usage rule.

    Also note that if one or more files have been marked as ’selected’ and if the highlight is on an unselected file, then the unselected file under the highlight is not included in the files affected by a subsequent 'Copy', 'Delete' etc. command.

  2. In Dual-Window Mode, if one or more files are selected in the active window, then any selected files in the inactive window will be de-selected (clipboard usage rules explained below will apply) because files may not simultaneously be selected in both windows. This is logically correct, since the clipboard is a single resource, shared by both windows.
  3. When no files are in the clipboard list, selection and de-selection of files operate as in the command descriptions above. If, however, one or more files are in the clipboard list when a file or files are selected or de-selected, additional clipboard side effects may occur:
    1. De-selecting a file that is already in the clipboard list, will result in the clipboard being cleared and all files in the directory being de-selected.
    2. De-selecting all files in the directory will result in the clipboard being cleared and all files in the directory being de-selected.
    3. Selecting a file that is not on the clipboard list, while other selected files in the window are on the clipboard, will result in the clipboard being cleared and the highlighted file being the only selected file.
  4. File selection may also be done using the mouse.
    Please see Mouse Support for more information.

Please refer also to the discussion of clipboard usage at See Other Commands.





Copying and Moving Files

The basic function of a file management application is to organize files and groups of files. This is done by ’Copy’, ’Cut’, and ’Paste’ commands. The following commands operate on the ‘selected’ files in the source Directory-Window. See Selecting Files.


 CTRL+C key

Copy selected file(s) in the Directory-Window list to the clipboard. Files are placed on the clipboard in preparation for creating a copy of those files in target directory.

The color attribute of the ‘selected’ items is changed to indicate that these items will be acted upon by the next command. No files are copied or modified by placing items on the clipboard.

 CTRL+X key

Cut selected file(s) in the Directory-Window list to the clipboard. Files are placed on the clipboard in preparation for moving those files to the target directory.

The color attribute of the ’selected’ items is changed to indicate that these items will be acted upon by the next command. No files are copied or modified by placing items on the clipboard.

 CTRL+V key

Paste file(s) in clipboard list to target directory.

Depending upon the command used to place the list of files on the clipboard ('Copy' or 'Cut'), the files in the clipboard list are either copied or moved to the target directory.

The target files will have the same name, file type, date/time stamp and access permissions as the source files. If the user is not the ’owner’ of the source file, then the corresponding target file will be ’owned’ by the user.

 ALT+INSERT key

Paste Special: Paste file(s) on the clipboard to target directory in one of the ‘SPECIAL’ ways.

When copying or moving a file (or group of files) it is often useful to apply one of the ‘special’ operations to it.

  • The most common of the special operations is to rename the file as it is written to the target directory. This allows writing of a copy of the file either in the same directory as the source file, or to another location.

    A group of files may also be renamed as they are written to the target directory, either individually, or according to a serialized filename pattern.
    Please see Renaming Files for more information on batch-mode renaming.

  • Another common operation is to create a ‘symbolic link’ (shortcut) file which references the original source file. A symbolic link does not contain the contents of the original file, but is a special type of file which contains only the path/filename of the original source file.

    A symbolic link (symlink) persists so long as the original source file remains in the original location. If the original file is moved, renamed or deleted, the symlink file can no longer access the file.

  • A less common, but often useful operation is to create a ‘hard link’ to the source file. A ‘hard link’ is essentially another way of identifying the original source file.

    There may be many hard links referencing a single file, and an access path to that file exists so long as there is at least one hard link to the file, even if the original file has been deleted.

    Note that a hard link must reside on the same filesystem as the original source file.

  • Timestamps and Permissions
    Target files will have the same ‘access’ and ‘modification’ timestamps as the source file. The ‘stat update’ timestamp will be set to the current system local time.

    Under most circumstances, the read/write/execute permission flags of the target will be the same as those of the source file.

    Exception: The timestamps and permission flags for symbolic link target files are determined by the kernel, and are not generally under program control; therefore, the timestamps will be set to the file’s creation time and the permission flags will be set for universal access (rwx/rwx/rwx).


Typical Paste Special Dialog

The layout of the Paste Special dialog window will vary somewhat according to the number and type of the source file(s). The following screenshot is for a typical multi-file operation.

┌─────────────────┤ Paste Special ├─────────────────┐ │ Source Items: 5 Reg Files and 0 Dir Trees │ Total Files: 5 (2.523M bytes) │ │ │ │ Specify type for new files: │ │ < ◆ > Copy the source files │ │ < > Create symbolic links to source files │ │ < > Create 'hard' links to source files │ │ │ │ Specify name for new files: │ │ < > Use the source file names │ │ < > Each file to be renamed individually │ │ < ◆ > Batch rename files using pattern (non-dirs) │ ├─────────────────────────────────────────────────────┤ │ │ │ │ OK CANCEL └─────────────────────────────────────────────────────┘

The features and controls of this dialog are as follows:

  • Dialog Title
  • Source Items
    This is the number of top-level items selected for the copy/move operation.
  • Total Files
    This is the number of Source Items (above) plus the contents of any directories in the source list.
  • Specify type for new files
    • Copy the source files.
      This is an ordinary (non-special) copy/move of the source file(s), with or without rename.
    • Create symbolic links to source files.
      In the target directory, create a symbolic link to each source file. See above note on symbolic-link files.
    • Create ‘hard’ links to source files.
      See above for a description of hard links.
  • Specify name for new files
    • Use the source file names
      The target files will have the same names as the source files.
    • Each file to be renamed individually
      When multiple files are being copied/moved, prompt for the name of each file individually.
    • Batch rename files using pattern
      When multiple files are being copied/moved, prompt for the format to be used for batch mode rename of the file group.

      Note that directories must be renamed individually and may not be renamed in a batch-mode operation.

  • ‘OK’ pushbutton
    Copy/move the file(s), configuring the targets according to the specified options.
  • ‘CANCEL’ pushbutton
    Abort the operation. File(s) will not be copied/moved.

An Alternate Layout for the Paste Special Dialog

As an additional example, if the source to be copied is a single symbolic link file, then the options would be the following:


┌─────────────────┤ Paste Special ├─────────────────┐ │ Source file: fm.cfg.link │ File type: 'Symbolic Link' │ │ │ │ Specify type for new files: │ │ < > Copy the symbolic link │ │ < ◆ > Copy the link target │ ..... │ Specify name for new file: │ │ < > Use the sym-link name │ │ < > Enter a new file name below │ │ < ◆ > Use name of link target │ ├─────────────────────────────────────────────────────┤ │ Copying: fm.cfg │ │ To: fm.cfg OK CANCEL └─────────────────────────────────────────────────────┘

Additional dialog layouts are available for other special cases.





Renaming Files

 CTRL+R key

Files may be renamed either singly or in groups (batch rename).


Native Linux filesystems (’ext3’, ’ext4’ etc.) accept all printing characters as valid filename characters.


Please be aware however that other filesystems (VFAT, NTFS etc.) may restrict the range of valid filename characters. For example, the single-quote (’) and double-quote (")characters may not be accepted by Windows(tm) oriented filesystems.


Even though all printing characters under Linux are technically valid filename characters, some characters should be avoided. These include “regexp” wildcard characters, characters which have special meaning for the command-line shell program, names that must be valid across multiple filesystems and characters which must be “escaped” before being passed to Linux utility programs.


Some examples would be '*' '?' '+' '%' ':' '|' '<' '>' '{' '}'.
A forward slash '/' should not be used as a filename character under Linux/UNIX, and a backslash character '\' may not be used in a Windows-oriented filename.


Note also that some older filesystems do not distinguish between uppercase and lowercase characters in filenames. To change only the case of characters in filenames on these filesystems, a two-step process will be necessary.
Example: Rename 'videos' directory to 'Videos':
         1) rename 'videos' to 'videosx'
         2) rename 'videosx' to 'Videos'
Please address all complaints to William Gates, Microsloth Corporation.


Note that for a directory to be successfully renamed, no program can be using any of the files contained in that directory. Attempting to change the path of a file that is currently in use, will cause an access violation error.


Rename a single file

To rename one file (or directory), place the highlight on the file to be renamed and press the CTRL+R (Control key plus ‘r’ key) command.

Note that if exactly one(1) file has been ‘selected’, then that file will be the one renamed.

A dialog window will open showing the current filename and a Textbox control for editing the filename.
Please see Dialog Controls for information on Textbox controls.


┌─────────────────────┤ Specify Target Filename ├──────────────────────┐ │ Source Name: P2016-02-18 11.29.32 │ │ Target Name: │ P2016-02-18 11.29.32(lowres).jpg │ ('Insert' toggles Ins/Overstrike mode) INSERT:<◆> │ │ │ OK CANCEL └────────────────────────────────────────────────────────────────────────┘

All valid filename characters are accepted. If an invalid character is entered, a warning beep will sound, and the invalid character will be discarded.

Note that the ‘INSERT’ key may be used to toggle between Insert and Overstrike input modes.


Rename multiple files

To rename multiple files in a single operation, ‘select’ the files to be renamed, then press the CTRL+R (Control key plus ‘r’ key) command. Please see Selecting Files for information on selecting files.

A dialog window will open asking whether to rename each selected file individually, or to rename all files as a group (batch mode).

┌───────────────────┤ Options for Multi-file Rename ├────────────────────┐ │ │ │ < > Each file to be renamed individually. │ │ For each selected file, prompt for new filename. │ │ < ◆ > Batch rename all files using Pattern. │ │ For all selected files, rename according to specified pattern. │ │ │ │ │ │ │ │ │ OK CANCEL └──────────────────────────────────────────────────────────────────────────┘

If files are to renamed individually, then for each file the dialog for renaming a single file will be opened as shown in the previous section.

(Note that directories must be renamed individually and may not be renamed in a batch-mode operation.)

If the files are to be renamed in batch mode, then the following dialog will be opened which may be used to create a pattern for renaming the files.

┌──────────────────────┤ Construct Rename Pattern ├──────────────────────┐ │ For automated rename of selected files: select desired option(s), enter │ │ necessary text data, and view a sample of the resulting pattern below. │ │ Sample: Bangkok_Trip-001.fext Before:< > Add text to Beginning of filename. │ │ Insert:< > Insert text before filename extension. │ After :< > Add text to end of filename. │ Replace:< ◆ > Bangkok_Trip- 3± 1± │ Replace base name with text+sequence number, Width InitVal │ │ or if Width=0 replace extension with text. │ Date :< >(yyyymmddhhmmss) OK CANCEL CLEAR HELP └──────────────────────────────────────────────────────────────────────────┘

Using this dialog, a complex pattern may be constructed which will be applied to each ‘selected’ filename.

There are four(4) primary options for creating the pattern:

  1. ‘Before’
    To insert text at the beginning of each filename, select the ‘Before’ radiobutton and enter the desired text.
  2. ‘Insert’
    To insert text just before the filename extension for each filename, select the ‘Insert’ radiobutton and enter the desired text.
  3. ‘After’
    To append text following the filename extension for each filename, select the ‘After’ radiobutton and enter the desired text.
    Note that modifying the filename extension may cause the file to be unrecognized by some applications.
  4. ‘Replace’
    To replace the existing base filename (but not the filename extension) with the specified text, select the ‘Replace’ radiobutton and enter the desired text. The specified text will be followed by a serial number beginning with the value specified by the spinner controls on the same line.

    This option may also be used to replace the filename extension, but not the base filename, (with no serialization). This is done by setting the ‘Width’ spinner to zero.
    Note that changing the filename extension may cause the file to be unrecognized by some applications.

These options may be used individually, or in combination. After specifying an option, an example of what the filenames will look like is displayed in the ‘Sample’ field.

Additional controls in this dialog are:

  1. ‘Spinner’ Controls
    — The ‘Width’ spinner specifies the number of digits in the serial number.
    — The ‘InitVal’ spinner specifies the first (lowest) serial number of the sequence.
  2. ‘Date’ Radiobutton
    Selecting this radio button will insert the system local date/time into the specified field.

    To use this option, first select one of the four basic fields AND clear all data from that field. Then select the ‘Date’ radiobutton and the timestamp will be inserted into that field. The timestamp data may then be edited if desired.

  3. ‘RENAME’ Pushbutton
    Apply the specified pattern to all selected files.
  4. ‘CANCEL’ Pushbutton
    Cancel the operation, no files will be modified.
  5. ‘CLEAR’ Pushbutton
    Reset all the dialog’s controls, discarding any changes you may have made to the fields.
  6. ‘HELP’ Pushbutton
    A quick guide to using the Rename Pattern dialog. Press the ESCAPE key to exit the help window and return to the dialog.

Because using this dialog to create a filename pattern is rather complex, several examples will be demonstrated.




Sorting the File List

The order in which the list of filenames is sorted may be specified in either of two ways.

  1. Open the ‘SortBy’ context menu using the ‘CTRL+S’ key command.
    See SortBy Context Menu, below.
  2. Access the ‘Sort Options’ dialog through the File Menu.
    See Sort Options dialog, below.

SortBy Context Menu

 CTRL+S key

The SortBy menu is a context menu, that is, a stand-alone menu which is not associated with the Menu Bar. This menu will be opened at a convenient position within the active directory window.

Highlight the desired sort option and press ENTER (RET).

To close the menu without making a selection, press the ESCAPE key.


┌─────────────────┐ Name Name Reverse Date Date Reverse Size Size Reverse Extension Extension Reverse File Type FileType Reverse No Sort └─────────────────┘

List of available sort options

  • Name (ascending)
  • Name (descending)
    Sort items alphabetically by filename. Whether alphabetical sort is case sensitive may be specified during configuration, or through the 'Sort Options' dialog described below.

    (For technical information on alphabetical sorting, see tech notes).

  • Date (ascending, older first)
  • Date (descending, newer first)
    Sort items by file-modification timestamp.

    For multiple files with the same timestamp, the items will be sorted alphabetically.

  • Size (ascending, smaller first)
  • Size (descending, larger first)
    Sort items according to the size of the file.

    For multiple files with the same file size, the items will be sorted alphabetically.

  • Extension (ascending)
  • Extension (descending)
    Sort items alphabetically according to filename extension. Whether alphabetical sort is case sensitive may be specified during configuration, or through the 'Sort Options' dialog described below.

    For multiple files with the same filename extension, the items will be sorted alphabetically by name.

  • File Type (ascending)
  • File Type (descending)
    Sort items into groups according to file type ('regular', 'directory', 'FIFO', 'symbolic link', etc.

    Within a file-type group, items are sorted alphabetically. The order of grouping is not guaranteed.

  • No Sort
    Items are displayed according to the order in which they are stored on the media (no sorting is performed).




Sort Options dialog

The Sort Options dialog is accessed through the File Menu.
(see File Menu for additional information.)



┌───────────────┤ Modify Sort Options ├───────────────┐ │ │ ┌┤ File-sort Option ├┐ < > Reverse sort order │ File Name │ Modification Date │ < ◆ > Case-sensitive sort │ │ File Size │ │ Filename Extension │ < ◆ > Show hidden files │ │ File Type │ │ No Sort │ └────────────────────┘ │ │ │ │ OK CANCEL └───────────────────────────────────────────────────────┘

The Sort Options dialog offers greater control over display of the filename data than the context menu (described above).



Note that the default sort order and other display options may be specified in the FileMangler configuration file.
Please see Configuration for more information.




Hidden Files Toggle

 ALT+I key

Toggle display of ‘hidden’ files.

The operating systems designates certain files as ‘hidden’ (not displayed in file lists) by default. Typically, these are configuration files which should be handled with care. The system indicates a ‘hidden’ file by using a full-stop ('.') character as the first character of the filename.

To display, copy or modify these files, make them visible in the file display window using the ALT+I (show ‘Invisible’ command).

When finished viewing these files, it is good practice to return them to the invisible state by pressing ALT+I again.

Toggling display of hidden files may also be done through the menu interface. See View Menu.





Trashcan and File Deletion





Move Files to Trashcan

When a file, group of files or a directory tree is no longer needed, you may provisionally delete them by moving them to the system Trashcan.

 CTRL+DELETE key

Move all ’selected’ files and directory trees to the system Trashcan.

If no files have been selected when the command key is pressed, then the currently-highlighted item is assumed as the ’selection’. Please refer to see Selecting Files for a discussion of selecting and de-selecting files.

For non-directory items (or an empty directory), the selected item(s) will immediately be moved to the Trashcan without confirmation. However, if a (non-empty) directory tree is among the selected items, you will be asked to confirm the operation.


┌────────────────┤ ALERT! ALERT! ├─────────────────┐ │ │ │ The following file is a directory. │ │ │ ObsoleteData │ │ │ Are you sure that you want to move this │ │ directory and its contents to the Trashcan? │ │ │ YES NO └─────────────────────────────────────────────────────┘

If a correctible error is encountered, you will be asked to confirm that you want to perform the indicated correction and continue the operation.

The example below warns that one or more of the files to be moved to the Trashcan are write-protected, and asks whether you want to override the write protection and continue.


┌─────────────────────┤ ALERT ├─────────────────────┐ │ │ │ Of the files to be moved, │ │ 4 are write protected. │ │ │ │ Do you want to remove protections and continue? │ │ │ │ │ │ │ YES NO └─────────────────────────────────────────────────────┘

If errors are encountered during the operation, an appropriate error message will be displayed.

Example:

┌────────────────┤ ALERT! ALERT! ├─────────────────┐ │ │ │ System Trashcan directory has become inaccessible │ │ or the target disc is full. │ │ Operation must be terminated. Sorry about that. │ │ │ │ │ OK └─────────────────────────────────────────────────────┘



Restore from Trashcan

Items which have been moved to the system Trashcan can be restored to their original position in one of two ways:

  1. To interactively select an item or items to be restored from the Trashcan, open the Trashcan-management dialog (ALT+SHIFT+T) command, described in the next chapter.
    Please see Manage the Trashcan.
  2. To automatically restore the item(s) most recently moved to the Trashcan, use the move-to-trash ‘undo’ command: ALT+SHIFT+R described in this chapter.

Either of these methods may also be invoked through the Utilities Menu. See Util Menu.


 ALT+SHIFT+R key

This is the ‘undo’ command. Use this command to restore the item(s) most recently moved to the Trashcan to their original location.

This operation scans the contents of the Trashcan and identifies the item or items with the most recent deletion timestamp. Then the item(s) with that timestamp will be restored to their original position.

  • A confirmation dialog (see below) will display the names, sizes and deletion timestamp for the item(s) to be restored.
  • If multiple items were simultaneous moved to the Trashcan during the the most recent operation, then all those items will be restored.
  • Also, the item(s) optionally may be restored to the current working directory (CWD) if it is different from the original location of the item(s).
    Please see Restore Trashcan Items in the next chapter for more information.
  • If the directory to which the item(s) were restored is not already displayed, then on completion of the operation, the active directory window be set to the target directory so you can visually confirm the restoration.
  • When restoration is complete, the CWD will be set according to the following criteria.
    • If one or more items were restored, all to the same location, the CWD will be set to that directory and one of the restored items will be highlighted.
    • If the operation was aborted, the application will remain in the CWD from which the Trashcan dialog was invoked.
  • Error conditions
    To avoid errors when restoring an item from the Trashcan, the following conditions must be met:
    • The target directory to which the item(s) will be restored must exist and you must have write-access permission for that directory.

      This includes your current working directory (CWD) if you specify that the item(s) should be restored to the CWD instead of the original target position.

    • There must be no file in the target directory which has the same name as the item to be restored. The restore operation will not overwrite existing target files.
    • If the item(s) cannot be restored, then a message will be displayed describing the error and how to correct it.
  • Technical Note: The resolution on the move-to-trash timestamp is one(1) second. FileMangler uses the same timestamp for all items moved to the Trashcan in the same operation; however, other applications may generate a new timestamp for each item processed. If so, then it is possible that items processed in the same operation by those applications could have different timestamps.

    For a detailed technical description of the Trashcan and managing its contents, please see the documentation for the 'cTrash' utility available from the author as a seperate download.
    See by the same author, for more information.

Restore-item Confirmation dialog

Restore a single file:

┌────────────────────┤ RESTORE ITEM FROM TRASHCAN ├────────────────────┐ Restore selected file to: /home/sam/Documents/Notes_on_Y2K_Bug.swx 4,241 bytes : trashed on 2016-05-14 at 02:21:58 RESTORE CANCEL [ ] Restore to CWD └────────────────────────────────────────────────────────────────────────┘

Restore multiple items:

┌────────────────────┤ RESTORE ITEM FROM TRASHCAN ├────────────────────┐ Restore 5 items to: /home/sam/Documents/CS2150/Student_Projects/2015_Fall 18 files, 9.82M bytes : trashed on 2016-05-14 at 03:04:55 RESTORE CANCEL [ ] Restore to CWD └────────────────────────────────────────────────────────────────────────┘



Manage the Trashcan

 ALT+SHIFT+T key

Open the Trashcan dialog to manage the Trashcan contents.


This dialog contains options to permanently delete files in the Trashcan OR to restore files from the Trashcan to their original position on the disk or other storage media.

┌───────┤ FileMangler - v:0.0.34 (c)2005-2016 [Press F2 for Menu] ├───────┐ │Status: Manage the Trashcan ├───────────────────────────┤ MANAGE TRASHCAN ├────────────────────────────┤ Trash Dir : /home/sam/.local/share/Trash Items : 55 Total Files : 70 ════════════════════════════════════════ File Size : 7.807M Delete selected items from the Trashcan. Size on Disc: 8.423M Free Space : 229.0G EMPTY TRASH RESTORE ITEM CLOSE ├┤ Original File Location - - -[ ITEM LIST ]- - - - - ItemSize DeleteDate ├┤
/home/sam/bin/ctrash004 183,587 2016-03-01 /home/sam/SoftwareDesign/1_TestData/.../FMe1 4,096 2016-02-18 d /home/sam/SoftwareDesign/1_TestData/.../FML2 122,691 2016-02-18 d /home/sam/.../Backup_2016_02_14b.tar.gz 4.77252M 2016-02-16 /home/sam/SoftwareDesign/.../Backup_2016_02_16.tar 4.78421M 2016-02-16 /home/sam/.../ncdialogapi-0.0.27.tar.bz2 1.06653M 2016-01-29 /home/sam/SoftwareDesign/.../FileManglerHelp.txt 43,215 2016-01-28 /home/sam/SoftwareDesign/.../Chinese--荒谬的名字 4,096 2016-01-26 d /home/sam/Downloads/PS for Purdue(ag).docx 20,899 2016-01-25 /home/sam/Downloads/PS for IUPUI(ag).docx 21,135 2016-01-25 /home/sam/SoftwareDesign/FileMangler/FMgr.o 75,648 2016-01-20 /home/sam/SoftwareDesign/.../gString_interim.hpp 71,398 2016-01-17 /home/sam/SoftwareDesign/.../gString_interim2.cpp 296,918 2016-01-17 /home/sam/SoftwareDesign/.../gString_interim.cpp 280,519 2016-01-17 /home/sam/SoftwareDesign/.../gString_interim2.hpp 71,286 2016-01-17 /run/media/sam/TravelDrive/.../ctrash-0.0.03.tar.bz2 151,752 2016-01-17 /home/sam/SoftwareDesign/.../gstring_22.html 143,886 2016-01-17 /home/sam/SoftwareDesign/.../ctrash-0.0.03.tar.bz2 151,752 2016-01-17 /home/sam/SoftwareDesign/cTrash/cTrash.cpp 206,861 2016-01-17 └────────────────────────────────────────────────────────────────────────────┘

Features and Controls of the Trashcan Dialog

  1. Dialog Title
  2. Location of Trashcan directory
    This is the full path to the base directory for the Trashcan.
    If necessary, the path will be compressed to fit into the dialog by replacing one or more intermediate directory names with ellipses.
  3. Number of items in Trashcan
    Note that this is the number of items, not necessarily the number of files. Some items may be directory trees that contain other files and directories.
  4. Total number of files in Trashcan
    Total number of files, including ordinary files, directory names and the files and subdirectories they contain.
  5. Total size of all files in Trashcan
    Combined size of all files in the Trashcan (in bytes)
  6. Approximate media space used by files in Trashcan
    Because media space allocated for files and directories is an even number of blocks (cylinders, sectors, allocation blocks, etc.) the actual space required to store the files may be somewhat larger that the file size.

    In addition, each file in the Trashcan has an associated file which contains technical info about that file. This file will be deleted at the same time as the base file it describes.

    This media-space value gives an indication of how much space will be freed on the media containing the Trashcan if the Trashcan is emptied. Note that the directory displayed in the main application’s Directory Window may, or may not be on the same physical media as the Trashcan.

  7. Approximate free space on media
    Approximate amount of unallocated space available on the media containing the Trashcan directory.

    This value is displayed for your convenience. For detailed information about your storage media: see View Menu.

  8. Context Help messages
    A brief context-help message is displayed for the dialog control which currently has the input focus. See below for detailed descriptions of each control.
  9. ’EMPTY TRASH’ pushbutton control
    Use this button to permanently delete ‘selected’ items from the Trashcan AND from the storage media.

    You will be asked to confirm the operation before the ’selected’ items are deleted. See below for a screen shot of the confirmation dialog.

    Note that this is not a ‘secure’ delete. All or part of the deleted file(s) MAY physically remain on the media. To securly remove files from the media, you will need to obtain specialized security software.

  10. ’RESTORE ITEM’ pushbutton control
    Use this button to restore the ‘selected’ items from the Trashcan to their original location, or optionally to your current working directory (CWD)..

    See Restore Trashcan Items, below for additional information on restoring items from the Trashcan.

  11. ’CLOSE DIALOG’ pushbutton control
    When you have completed the desired Empty/Restore operation(s), use this button to close the dialog and return to the main application.
  12. ’ITEM LIST’ - List of individual items in Trashcan

    Each item in the list displays:

     — original location of trashed item (compressed if necessary)
     — size of the trashed item (in bytes)
     — date the item was moved to the trash
     — if the item is a directory, then a ‘d’ 
       is displayed in the rightmost column
    

    Note that if the Trashcan is empty, this control will be invisible.


Empty the Trashcan

Files and directory trees that have been moved to the Trashcan continue to occupy space on your disk. Once you are sure that you no longer need these files, they may be permanently deleted by ‘emptying the trash.’

‘Delete Items’ Confirmation Dialog

┌────────────────────┤ DELETE ITEMS FROM TRASHCAN ├────────────────────┐ Delete all 'selected' items from the Trashcan 55 items (70 files, 7.8073M bytes) WARNING: This operation cannot be reversed! Are you sure that you want to delete the selected items from the Trashcan? DELETE CANCEL └────────────────────────────────────────────────────────────────────────┘


Restore Trashcan Items

The primary purpose of the system Trashcan is to allow discarded files to be ‘un-deleted’ i.e. restored to their original position, typically, when a file you thought was no longer needed, actually contains valuable information.

Occasionally, a file or group of files may be moved to the Trashcan by mistake and will need to be retrieved. See also the ‘undo’ command in the previous chapter. (see Restore from Trashcan).


‘Restore-item’ Confirmation dialog

The confirmation dialog has three controls.

  1. ‘RESTORE’ Pushbutton
    Restore the selected item(s) to their original location, or if specified, to the current working directory (see below).
  2. ‘CANCEL’ Pushbutton
    Cancel the pending restore operation. No files will be restored, and Trashcan data will not be modified.
  3. ‘Restore to CWD’ Radiobutton
    Select this radiobutton to restore the specified item(s) to the current working directory (CWD), rather than to their original locations.

    Deselect this radiobutton to restore the item(s) to their original locations.


Restore a single file:

┌────────────────────┤ RESTORE ITEM FROM TRASHCAN ├────────────────────┐ Restore selected file to: /home/sam/Documents/Notes_on_Y2K_Bug.swx 4,241 bytes : trashed on 2016-05-14 at 02:21:58 RESTORE CANCEL [ ] Restore to CWD └────────────────────────────────────────────────────────────────────────┘

Restore a directory tree:

┌────────────────────┤ RESTORE ITEM FROM TRASHCAN ├────────────────────┐ Restore selected directory tree to: /home/sam/Documents/ObsoleteData 18 files, 830.6K bytes : trashed on 2016-05-22 at 02:25:37 RESTORE CANCEL [ ] Restore to CWD └────────────────────────────────────────────────────────────────────────┘


Technical Notes:

The names of the items in the Trashcan directory are encoded and may be different than the names these items had when in their original locations.

For this reason, although directly viewing the contents of the Trashcan directory is possible, it may not be helpful, and directly modifying the data will corrupt the Trashcan. FileMangler decodes the original item names for display in this dialog.

Because many applications use the Trashcan, it is possible that the data may become partially corrupted by having a data file with a corrupted or missing ’.trashinfo’ file which should contain the file’s original location on the media. This is not a serious error, but if it happens, then FileMangler will display a warning message alerting you to the potential problem.

Shameless plug: For flexible, automated Trashcan management, please download the author’s 'cTrash' console utility.
(see by the same author)




Delete Files Permanently

At times, it is convenient to bypass the system Trashcan and directly delete a file or group of files.

  1. Files that are easily recreated, such as intermediate files created during a software build.
  2. Very large files which, if sent to the Trashcan would continue to take up significant space on your media.
  3. Sensitive files that you want to delete so that they cannot be restored later by some unauthorized person.

    Note that this is not a ‘secure’ delete. All or part of the deleted file(s) MAY physically remain on the media. To securely remove files from the media, you will need to obtain specialized security software.


 SHIFT+DELETE key

Permanently delete all ‘selected’ files and directory trees.

If no files have been selected when the command key is pressed, then the currently-highlighted item is assumed as the ’selection’. (Please refer to see Selecting Files for a discussion of selecting and de-delecting files.)

Because this operation cannot be undone, a warning dialog will be displayed asking you to "think carefully before acting rashly."

┌──────────────┤ WARNING! WARNING! ├───────────────┐ │ │ │ This operation cannot be undone! │ │ These files WILL NOT be placed in the Trashcan, │ │ and the deleted files will be lost forever. │ │ │ │ Are you sure that you want to continue? │ │ │ YES NO └─────────────────────────────────────────────────────┘



Create a New Directory

 CTRL+N key

Create a new subdirectory in the currently-displayed directory.
A dialog window will be opened in which you can enter the name for the new subdirectory.


  • A directory name may contain any valid filename character.

    FileMangler applies the proper input filter as the name is entered, and will make an audible beep when an invalid character is detected

  • A filename, including directory names, may be of any length up to the system-defined limit, which for POSIX systems, is 256 bytes, (NOT 256 characters).

    Please see Dialog Controls for a description of using text-input controls.

  • Permissions for the new directory will be set to full access for Owner and Group, with read and execute permisson for Others:
    USR GRP OTH
    rwx rwx r-x
    

    Please see View or Modify File Stats for more information on setting access permissions.

  • Important Note: You must have write-access to the displayed directory in order to create a subdirectory within it.

┌───────────────────────┤ Create New Directory ├───────────────────────┐ │ Directory Name: │ Photos - Thailand 2016 │ │ │ ('Insert' key toggles Insert/Overstrike) │ │ │ OK CANCEL └────────────────────────────────────────────────────────────────────────┘



Changing File Attributes

This chapter describes shortcuts for modifying the ’read’, ’write’ and ’execute’ permision bits and the timestamp of an single file or for all ‘selected’ files.

See also the next chapter: View or Modify File Stats, for detailed control over a file’s attributes.


Write Protect File(s)

 CTRL+W key

To protect a file or group of files from accidental deletion, select the file or files to be write protected, (see Selecting Files), then press the CTRL+W command-key combination.

This will RESET the write-access bits for ’Owner’, ’Group’ and ’Others’.

See Adjust Permissions, below for a description of the user-interface dialog.


Write Enable File(s)

 CTRL+E key

To remove write protection from a file or group of files, select the file or files to be write enabled, then press the CTRL+E command-key combination.

This will SET the write-access bits for ’Owner’ and ’Group’.

See Adjust Permissions, below for a description of the user-interface dialog.


Adjust Permissions for File(s)

Adjust the read/write/execute permission flags of a file or group of files.

Select the file or files to be adjusted and then press either the 'CTRL+W' or 'CTRL+E' command-key sequence (see above).

Select the 'Create custom permissions' radio button to adjust the individual permission bits, then set or clear the individual permission bits as desired. (See Dialog Controls, for information on using radio buttons.)

For all selected files, the permission bits indicated by selected controls will be SET, and the permission bits indicated by cleared (non-selected) controls will be RESET.

Note that auxilliary permission flags for ’userID’, ’groupID’ and
’sticky bit’ ARE NOT modified by this operation.

Directory names are a special case, in that true read access to a directory requires that BOTH ’Read’ and ’Execute’ flags be set. For this reason, if you select the ’Read’ flag for Owner, Group or Others, then ONLY FOR DIRECTORY NAMES in the file list: the corresponding ’Execute’ flag will also be set. For example, if you select the Owner-Read button, then the Owner-Execute button is implied for all directory names in the list.

To disable this option, clear (reset) the 'set x with r' radio button so that the permission flags for all selected files and directory names will be set/reset exactly as you indicate.

Please note: On native Linux/UNIX filesystems, there are nine (9) access permission flags which control user access to the file.

         Owner  Group  Other
         -----  -----  -----
   Read:   r      r      r
  Write:   w      w      w
Execute:   x      x      x

Other file systems such as NTFS or FAT32 may have somewhat different permission flags, but full functionality is available for all file systems supported by your platform.


┌─────────────┤ Set File Permissions ├──────────────┐ │ < > Write-protect selected files Resets 'write' bit for Owner/Group/Other. │ < > Write-enable selected files Sets 'write' bit for Owner and Group. │ < ◆ > Create custom permissions for selected files Sets specified bits. Resets all other bits. │ OWNER GROUP OTHERS │ Read: [r] [r] [r] │ Write: [w] [ ] [ ] │ Execute: [x] [ ] [ ] (for dir names, set x with r) [◆] OK CANCEL └─────────────────────────────────────────────────────┘

 Screenshot of dialog for adjusting file permissions.

On completion of the operation, a status message will be displayed in the status window indicating the number of files successfully modified, and the number of files not modified due to insufficient user privilege or other error.


Changing a File’s Timestamp

 CTRL+D key

Modify the date and/or time of a file or group of ‘selected’ files.

This will open an interactive dialog window for setting the new date and time for the file(s) using the format described below. The default value is the current system local date and time.


The timestamp limits are based on the ‘epoch’, i.e. the earliest date that most computer systems can represent.


The minimum value for the timestamp is the ‘epoch’:
    01 Jan 1970 00:00:00
The maximum value for the timestamp is system dependent:
    31 Dec 2037 23:59:59 (32-bit systems)
    31 Dec 9999 23:59:59 (64-bit systems)


Note: The timestamp of an individual file may also be updated as part of modifying a file’s stat information.
See View or Modify File Stats.


┌──────────────┤ Set File Date/Time ├──────────────┐ │ │ 02 May 2016 10:30:00 │ dd mmm yyyy hh:mm:ss │ │ │ │ │ │ Enter date and time according to indicated format. │ │ (default is current system local time) │ ACCEPT CANCEL └────────────────────────────────────────────────────┘

Please note: On native Linux/UNIX filesystems, each file has 
three (3) associated timestamps:
    ’Last Modified’ date
    ’Last Accessed’ date
    ’Last Stat Update’ date

Modifying a file’s timestamp will set BOTH the modification
timestamp and the access timestamp to the date and time you specify.
Because you are updating the file’s stats, the ’stat update’ timestamp
will be set to the current system date and time.

Other filesystems, such as NTFS, FAT32, etc., may define their file timestamps 
in different ways, so the results of updating the timestamp may be slightly 
different for those filesystems.



View or Modify File Stats

To view a file’s stats (non-content attributes), select the 'View File Stats' item from the 'ViewFile' context menu.
Please see ViewFile Context Menu for instructions on invoking this menu.

Select 'View File Stats' from the menu to view, and optionally to modify (see modify stats) the target file’s stat data. These data include the file timestamps, permission bits, owner, group and other data. Note that some data items may be changed only by the superuser ('root' user).


‘View File Stats’ Dialog

┌──────────────────────────┤ View File Stats ├───────────────────────────┐ /home/sam/SoftwareDesign/FileMangler/FmConfig │ FTYPE OWNER GROUP OTHER sUID sGID STIK INODE hLINK BYTES │ │ ----- ----- ----- ----- ---- ---- ---- -------- ----- -------- │ │ REG r w x r w x r - x NO NO NO 17563789 1 849,817 │ │ Last Modified : 04 May 2016 06:54:23 | UID: 1000 NAME: sam │ │ Last Accessed : 05 May 2016 07:40:35 | GID: 1000 NAME: sam │ │ Last Stat Update: 04 May 2016 06:54:23 | │ ├──────────────────────────────────────────────────────────────────────────┤ CLOSE MODIFY └──────────────────────────────────────────────────────────────────────────┘

The features and controls of the 'View File Stats' dialog are as follows.

  • Dialog Title
  • The path/filename of the target file
  • 'FTYPE' The target’s filetype

    A file’s filetype indicates a file’s purpose and capabilities.
    See below for a list of available filetypes.

  • Permission bits for 'OWNER', 'GROUP' and 'OTHER'

    Each of these categories includes a Read ('r'), Write ('w') and Execute ('x') flag.

  • 'sUID' set-user-ID flag

    This flag is used to change how the system interprets the owner of the file when it is executed. (executable files only)

  • 'sGID' set-group-ID flag

    This flag is used to change how the system interprets the group of the file when it is executed. (executable files only)

  • 'STIK' the sticky-bit flag

    The use of this flag (if it is used at all) is operating-system specific.

  • 'INODE'

    This value uniquely identifies the target file within the filesystem.

  • 'hLINK' hard links

    Specifies the number of ‘hard links’ i.e. number of fixed references to the file within the filesystem. A file continues to exist within the filesystem so long as there is at least one(1) hard link to it.

  • 'BYTES' size of file

    This is the size of the file in bytes. The format of this value depends on the size of the file and are shown as bytes, kilobytes, megabytes, gigabytes and terabytes (base 10).

    Examples:
       180,648  (bytes)
       28.541M  (megabytes)
       1.4452G  (gigabytes)
    
  • 'Last Modified'

    This timestamp indicates when the contents of the file were last modified.

  • 'Last Accessed'

    This timestamp indicates when the file was last opened (read or write).

  • 'Last Stat Update'

    This timestamp indicates when the file’s stats were last updated.

  • 'UID' user ID

    This is the numeric identification and the user name for the owner of the file.

  • 'GID' group ID

    This is the numeric identification and the group name for the group to which the file belongs. This is usually, but not always, the same as the UID.

  • 'CLOSE' Pushbutton

    Close the dialog.

  • 'MODIFY' Pushbutton

    Close the 'View' dialog and open the 'Modify' dialog so that the values may be modified.


If the highlighted file is a symbolic link, then stats for both the link file and the link target file will be displayed.

┌──────────────────────────┤ View File Stats ├───────────────────────────┐ /usr/lib64/libncurses++.so │ FTYPE OWNER GROUP OTHER sUID sGID STIK INODE hLINK BYTES │ │ ----- ----- ----- ----- ---- ---- ---- -------- ----- -------- │ │ LINK r w x r w x r w x NO NO NO 2376634 1 17 │ │ Last Modified : 12 Aug 2014 00:39:27 | UID: 0 NAME: root │ │ Last Accessed : 14 Aug 2016 17:40:42 | GID: 0 NAME: root │ │ Last Stat Update: 12 Aug 2014 00:39:27 | │ /usr/lib64/libncurses++.so.5.9 │ FTYPE OWNER GROUP OTHER sUID sGID STIK INODE hLINK BYTES │ │ ----- ----- ----- ----- ---- ---- ---- -------- ----- -------- │ │ REG r w x r - x r - x NO NO NO 2359959 1 78,296 │ │ Last Modified : 03 Aug 2013 11:11:48 | UID: 0 NAME: root │ │ Last Accessed : 24 Aug 2016 07:35:52 | GID: 0 NAME: root │ │ Last Stat Update: 21 Jul 2014 05:07:16 | │ ├──────────────────────────────────────────────────────────────────────────┤ CLOSE MODIFY └──────────────────────────────────────────────────────────────────────────┘


‘Modify File Stats’ Dialog

┌─────────────────────────┤ Modify File Stats ├──────────────────────────┐ /home/sam/SoftwareDesign/FileMangler/FmConfig │ │ │ FTYPE OWNER GROUP OTHER sUID sGID STIK INODE hLINK BYTES │ │ ----- ----- ----- ----- ---- ---- ---- -------- ----- -------- │ │ REG r w x r w x NO NO NO 17563789 1 849,817 │ │ Last Modified : 05 May 2016 12:08:53 | UID: 1000 NAME: sam │ │ Last Accessed : 05 May 2016 12:09:04 | GID: 1000 NAME: sam │ │ Last Stat Update: 05 May 2016 12:08:53 | │ │──────────────────────────────────────────────────────────────────────────│ │ Press UPDATE to save changes. │ │ │ │ │ │ │ │ TAB to desired field(s) and make modifications. │ │──────────────────────────────────────────────────────────────────────────│ UPDATE CANCEL HELP └──────────────────────────────────────────────────────────────────────────┘

This dialog is accessed by pressing the 'MODIFY' Pushbutton in the ‘View File Stats’ dialog described above.

This dialog gives detailed control over the stat data for a specific file. To simultaneously modify stats for multiple files, (permission bits and timestamps), please see Changing File Attributes.

The layout of the 'Modify File Stats' dialog is the same as the 'View File Stats' dialog described above except that the data may be modified. The controls are as follows.

  • Filetype (view only)

    A file’s filetype indicates a file’s purpose and capabilities.

    REG        regular file
    DIR        directory
    LINK       symbolic link
    CHDEV      character device
    BKDEV      block device
    FIFO       named pipe
    SOCK       socket
    UNK        unknown, or system-specific filetype
    

    Most files will be either ‘regular’ or ‘directory’ files. You will also occasionally encounter ‘symbolic link’ files.

    Modfying stat data for other types of files is dangerous, and often restricted by the system’s security protocol. Use care when modifying stats for those filetypes.

  • Owner read permission ('r')
  • Owner write permission ('w')
  • Owner execute permission ('x')

    Unless you are a system administrator, you will be the owner of nearly all files you will work with on a daily basis; so typically, you will give yourself Read/Write access to those files.

    For binaries, shell scripts and other executable files, you will probably want to give yourself Execute access as well.

    All ‘directory’ files that you own should usually also have execute access. If a directory does not have Execute access, you may not be able to list the contents of that directory.

    The most common modification to this group is to reset the Write-access flag so you don’t accidentally delete the file.

  • Group read permission ('r')
  • Group write permission ('w')
  • Group execute permission ('x')

    This group of access flags is designed primarily for files that belong to a work group, such as a document that may be editied by several different users.

    On a single-user system, the file’s group is nearly meaningless because the user is the only member of his or her group, so the group Read-access and Execute-access flags typically mirror owner access, while Write-access is disabled for safety.

    If your system is routinely accessed by another user or is administered remotely, it is wise to consider restricting group access.

    It is common to reset both the group’s Read-access and Write-access flags on files that contain sensitive data, to protect them from unauthorized access. Shared executable files will typically have the group Execute-access flag set.

  • Other read permission ('r')
  • Other write permission ('w')
  • Other execute permission ('x')

    ‘Others’ are any users who are not you and who are not members of your group.

    For ‘others’, it is common to reset both the Read-access and Write-access flags on all files, to protect them from unauthorized access. Shared executable files will typically have the ‘others’ Execute-access flag set.

  • Set-User-ID flag (superuser access only)

    Whie an application is running, it is sometimes advantageous for the application to return a different user ID or alias when it is queried by another process.

    — When this flag is set, the alternate user ID will be reported.
    — The system documentation calls this ’changing the persona’.
    — Only the Superuser may modify this flag.

  • Set-Group-ID flag (superuser access only)

    Whie an application is running, it is sometimes advantageous for the application to return a different group ID or alias when it is queried by another process.

    — When this flag is set, the alternate group ID will be reported.
    — The system documentation calls this ’changing the persona’.
    — Only the Superuser may modify this flag.

  • Sticky Bit flag (superuser access only)

    Early UNIX systems used this flag to increase system performance by having often-used code and data "stick" in RAM memory rather than being cycled out to disk. So far as we know all modern systems use priority (‘ring’) protocols for this, so it is possible that this flag is not used on your system. In this case, modifying the flag will cause the stat update to fail.

    Certain systems define the use of this flag for special purposes.

    It is strongly recommended that if you don’t know how the sticky-bit flag is defined on your system, the flag should not be modified.

  • INODE (view only)

    This value uniquely identifies the target file within the filesystem.

  • Hard Links (view only)

    Specifies the number of ‘hard links’ i.e. number of fixed references to the file within the filesystem. A hard link is another name for the target file (uniquely identified by its ‘inode’).

    A file continues to exist within the filesystem so long as there is at least one(1) hard link associated with it.

  • File Size (view only)

    This is the size of the file in bytes. The format of this value depends on the size of the file and are shown as bytes, kilobytes, megabytes, gigabytes and terabytes (base 10).

    Examples:
       180,648  (bytes)
       28.541M  (megabytes)
       1.4452G  (gigabytes)
    
  • 'Last Modified'

    This timestamp indicates when the contents of the file were last modified.

    The timestamp limits are based on the ‘epoch’, i.e. the earliest date that most computer systems can represent.

    The minimum value for the timestamp is the ‘epoch’:
    01 Jan 1970 00:00:00
    The maximum value for the timestamp is system dependent:
    31 Dec 2037 23:59:59 (32-bit systems)
    31 Dec 9999 23:59:59 (64-bit systems)

  • 'Last Accessed'

    This timestamp indicates when the file was last opened (read or write).

    The timestamp range is the same as that described for the modification date described above.

  • 'Last Stat Update' (view only)

    This timestamp is not under program control. The system will update this timestamp to the current system local time whenever the file’s stat data are modified, or whenever the contents of the file are changed.

  • 'UID' user ID (superuser access only)

    Assign ownership of the file to a different user ID.

    Enter the new ID number. The owner may not be specified by user name. Modifying the UID requires Superuser privilege.

  • 'GID' group ID (superuser access only)

    Assign the group association of the file to a different group ID.

    Enter the new ID number. The group may not be specified by group name. Modifying the GID requires Superuser privilege.

  • Context Help Messages

    As you move to each of the various fields and controls, a brief message explaining its function will be displayed.

  • Warning Messages

    Warning messages will be displayed for invalid input or for potential access problems.

  • 'UPDATE' Pushbutton

    Apply the changes and close the dialog.

    If errors are encountered while updating the stats, information on the type and cause of the error will be displayed.

  • 'CANCEL' Pushbutton

    Discard any pending changes and close the dialog. File stats will not be modified.

  • 'HELP' Pushbutton

    Call the ‘info’ documentation system to display the application’s documentation. The document will be opened to the top of this section. (You’re welcome! :-)


A comprehensive explanation of file attributes is beyond the scope of this document. For a detailed description of file attributes, please consult the C-language library documentation:
    info libc 'File Attributes'
See also the 'chmod' utility:
    info coreutils chmod




View File Contents

View the contents of a (non-directory) file.

Access to the 'view file' functionality is through the 'ViewFile' context menu, which is invoked by highlighting the target filename and then pressing the ENTER (RET) key.

Screenshot of the ViewFile context menu

┌─────────────────┐ View Contents View file Stats Open (execute) Find Link Target Cancel └─────────────────┘

(Please see Context Menus for more information.)

View the contents of the target file as plain text, ASCII numeric data or in the case of archive files, as a list of the archive contents. The following dialog will be opened so you can choose the format to be used for display of the file’s contents.

┌─────────────┤ View-File Format Options ├──────────────┐ View the file: 'Dialog1.cpp' as: │ │ [◆] Text [ ] Decimal [ ] SymLink file │ [ ] Hex (8-bit) [ ] Octal [ ] Archive file │ [ ] Hex (16-bit) [ ] Binary [ ] Media Metadata │ │ │ │ │ VIEW CANCEL │ Output is first formated (if necessary) and then │ │ displayed using the 'less' command-line utility. │ │ (view with scroll keys, '/' to search, 'q' to quit) │ └───────────────────────────────────────────────────────┘

The Radiobuttons of this dialog are implemented as an exclusive-OR (XOR) group, meaning that exactly one Radiobutton of the group may be selected at any one time.

Tab to the Radiobutton for the desired formatting option and press ENTER (RET). Then tab to the 'VIEW' Pushbutton and press ENTER to view the data.

Note that if you do not have read access permission for the file, an error message will be displayed.

Formatting Options

  • Text — UTF-8 encoded text.
    Plain-text files such as scripts, source code and markup-language files (e.g. HTML) files can be read as plain text, so long as the system understands the text-encoding being used. Nearly all text files under modern Linux/UNIX systems are UTF-8 encoded; however, even for legacy encodings, the text will probably display correctly.
  • Hexadecimal (8-bit or 16-bit)
    Files containing only numeric data may be viewed most easily in hexadecimal format. Whether it is easier to read the data in 8-bit or 16-bit words depends on the data itself. For numeric data that can also be interpreted as text, the text version is shown in the right margin.
  • Decimal
    Display of binary data in decimal (base-10) format has little value in the computer world, but it can sometimes be instructive.
  • Octal
    In the early days of computing when each binary bit of data was expensive to store and retrieve, octal (base-8) output made sense. In the modern world there is little reason to regress to this stone age format, but since it requires no extra effort to produce, we have included octal output as an option.
  • Binary
    While binary (base-2) output is very difficult for humans to read, it has it uses. For instance, encrypted data, video-file housekeeping data, socket data headers and so on are actually bit-wise data.
  • Symlink contents (symbolic link files only)
    In general, the actual contents of a symbolic-link file are of no interest, so by default, the contents of the file the symlink points to will be displayed. However, when a symbolic link is broken (no longer references a target file), then it is useful to read the symlink directly to determine where it thinks the target file is.

    Note that this option will only be available if the source file is a symbolic link file.

  • Archive content (archive files only)
    Archive files, by definition, contain other files and subdirectory trees. Use this option to list the names of all the files in the archive,

    Note that this option will only be available if the source file is a recognized type of archive file.
    Please see Working With Archives for further discussion of archive files.

  • Media Metadata
    Most media files (audio and video) contain metadata which describes the media stream.

    For example, a file might contain the name of the artist, the runtime, cover art, a copyright notice or other data. These metadata will likely be accessible for view/edit through whatever software package is used for playback; however, as a convenience, FileMangler can display metadata for some of the most common media formats.

    Note that this option will only be available if the source file is a supported media file format as indicated by the filename extension.

    Audio and Video formats currently supported:
       MP3         MPEG-3 audio
       OGG, OGA    Ogg/Vorbis audio (xiph.org)
    
    

    To view metadata for UDF discs (commercial DVD movies), please download the author’s ‘DVD Repair’ utility. See by the same author.

Special file types

In general, only 'regular' files and 'symbolic link' files (or their ’regular’ targets) may be viewed as described above.

  • The contents of 'directory' files are the names of the files they contain, so viewing the raw directory metadata is not often useful, and may damage the directory file. For this reason, FileMangler does not support viewing of directory metadata.
  • 'socket', 'character device', 'block device', 'fifo' and other special-purpose files have no ‘contents’ in a traditional sense, and simply receive and transmit data from other sources. For this reason, ‘viewing’ files of these types is not supported.

Implementation Note

Viewing the file contents is done with the 'less' utility. For plain text, the file is displayed directly. For numeric formats and archive-file contents, the file’s contents are first converted to human-readable form with the appropriate utility ('hexdump', 'xxd', 'tar') before being passed to 'less'.

For viewing the contents of a symbolic-link file rather than the contents of the link target, the data are converted internally.

For supported media files, the binary metadata are decoded and converted to human-readable form.

For information on using the 'less' utility, at the command line, type: 'info less'.




Open or Execute a File

When launching an external application or script from within a terminal window, there a number of factors to be considered, especially when launching that application from within an application which is already running in that window, FileMangler in this case.

  • The first, and most important consideration is whether the called application or script will run as a GUI (in a Graphical User Interface window), or run within the terminal window.
    • If the called program is a GUI application, then FileMangler can launch the external application while retaining full control of the current terminal window.
    • If, however, the called program runs in a terminal window, it must be decided whether a new terminal window should be opened, or if FileMangler should temporarily go to sleep and relinquish control of the window to the called program.
  • The next important question is whether the called program requires additional arguments beyond the name of the file itself in order to perform the desired task.
  • Third, if the selected file is not an executable file, is whether the system is configured to run the desired external application associated with the selected file. The default application associated with each type of file is handled by the system according to the file’s “MIME Type”. For instance, the MIME type associated with a BASH shell script is:
         “application-x-shellscipt”.
    The MIME type associated with OGG audio files is:
         “audio/x-vorbis+ogg”.
    For most filetypes the default application for a specific MIME type may be specified directly by using one of the system’s file management utilities. Note that your author resists the idea of allowing FileMangler to edit the system-configuration files. Instead, use Nautilus (’Files’), Dolphin, Krusader or another file manager configured specifically to your Linux installation.
    If you are feeling especially nerdy, check out the low-level control available through the “xdg-utils”. (xdg-mime, xdg-open, etc.)

    The way these associations are stored and retrieved is, to some degree, system dependent; however, the FreeDesktop.org standard is the most likely choice. According to this standard, the global MIME-type associations are stored in:
       '/usr/share/applications/default.list'
    Your personal file associations can be found at:
       '~/.local/share/applications/mimeapps.list'

    For a detailed explanation of MIME-type associations, go to:
    https://specifications.freedesktop.org/mime-apps-spec/mime-apps-spec-1.0.html

  • For shell scripts, Python, Perl, Ruby or other files containing executable instructions, there is always the choice of whether to run the program, or to open a text editor to edit the file.

    Note that to run the file the 'x' “execute” bit must be set. Please see View or Modify File Stats for information on setting the 'x' bit.

While it is not possible to anticipate all the possible side effects of launching an external program, the following dialog may be used to set the parameters of the launch.

  Important Note: FileMangler includes a configuration option which determines
  when and how this dialog will be invoked.

Please see External Programs for details.



┌────────────────┤ Launch External Program ├─────────────────┐ File: /usr/local/bin/info This is a binary executable program. [ ] Launch the program as a GUI application OR open file using the default (GUI) application for this file type. type. (FileMangler continues in the current window.) [ ] Put FileMangler to sleep and launch the program in the current window. (then type EXIT to return.) [ ◆ ] Launch the program in a new terminal window. (FileMangler continues in the current window.) Additional launch arguments (executable files only) -f ~/Apps/cTrash/ctrash.info -n 'Invoking' LAUNCH CANCEL ╞══════════════════════════════════════════════════════════════╡ If you are unsure which option to choose, be safe, select "Launch the program in a new terminal window." └──────────────────────────────────────────────────────────────┘

The features and controls of the dialog are as follows:

  • Name of the target file (including full path).
  • Target file’s category:
    a) binary (compiled) executable
    b) script file or interpreted source file
    c) non-executable data file
  • Radiobutton: Launch-as-GUI (Graphical User Interface) application, or for a non-executable file, launch the default (GUI) application associated with that type of file.

    The FileMangler application will immediately continue execution in the current window.

    GUI applications may be opened directly by FileMangler without danger of resource conflicts. If launching a console application, or script file, however, please select one of the other launch options, below.


    Please Note: If the target file is an executable script or executable interpreted source file, this Radiobutton is redefined to offer the option of editing the file instead of executing it:
    “Edit the file using the default text editor.”

    See launching a text editor, below for more information.

┌────────────────┤ Launch External Program ├─────────────────┐ File: /home/sam/bin/fmg.sh This is a shell script or interpreted program. [ ◆ ] Edit the file using the default text editor.
  • Radiobutton: Launch-in-Current-Window.
    Selecting this launch option will put the FileMangler application into hibernation mode. FileMangler will still be in RAM memory, but will not accept input and will produce no output.

    This releases control of the terminal window to the specified application program which will be launched at the command line as if you had typed the command manually.

    FileMangler will resume when called application has terminated and the user releases the window by typing ‘exit’ at the command prompt.

  • Radiobutton: Launch-in-New-Terminal-Window.
    Selecting this launch option will cause a new terminal window to be opened from which the specified application program will be launched. This window will remain open until closed by the user.

    The FileMangler application will immediately continue execution in the current window.

    Programmer's Note: Not all terminal emulators and shell programs respond in the same way to the request for a new terminal window. Size, position, font, colors and other parameters are accepted by some and ignored by others. Our implementation has been extensively tested only with gnome-terminal, konsole and xterm. Other emulators will work to varying degrees. Unfortunately, all emulators do uniformly refuse to open a new tab instead of a new window. The author has argued with the developers of terminal emulators about this issue, but thusfar without success.

  • Textbox: For executable files only, specify any additional argument to be passed to the application.
  • Pushbutton: Launch the program according to the specified parameters.
  • Pushbutton: Cancel the operation and return to the main application.
  • Quick Help message.
    As described above, there is always the possibility of resource conflicts when launching an external application from within a terminal application.

    If the external application tries to write to the current terminal window, a conflict will occur. If this happens, then FileMangler will probably “win” and will retain control. Any messages written by the external application or input requests made by that application will probably never be seen even though the application may still be running in the background.

    If there is any doubt whether the external application will try to take control of the terminal window, then choose the option to launch the application in a new terminal window.


Binary (compiled) Executables

On Linux/UNIX systems, binary executable files are formatted according to the the “ELF” (Executable and Linkable Format) standard.

A compiled binary executable file may be identified by the ELF header. Only the first four(4) bytes of this header are required to identify the file as an ELF binary file:

7f 45 4c 46 02 01 01 00 00 00 00 00 00 00 00 00 |.ELF............|
__ __ __ __                                      ____

For more information on the ELF header, see


Script Files and Interpreted Programs

Script files and interpreter source files are plain text files which contain a series of commands to be executed either by the shell program or by an interpreter for that language.

Script files and interpreter source files may be identified either by the filename extension or by the optional identifer in the first line of the file. Unfortunately, programmers who write for profit rather than for the pure joy of artistic creation, are often lazy and undisciplined so that neither the filename extension nor the identifying signature are guaranteed to be present.

For this reason, FileMangler’s logic for executable files is this:
    — if file is executable but is not a compiled binary file, then
    — the file is a shell script or interpreted source file.

Scripts and interpreter source files may be executed directly, or may be handled as client files and opened in a text editor.

Important Note: For executable scripts and interpreter source files FileMangler assumes that your default text editor is a GUI program which will be launched directly from the current terminal window. However, for the die-hard ‘vi’ fans, the clingers to 'lime', 'pico', 'jed' and other editors from the previous millenium, FileMangler can easily be modified to accomodate console editors by setting an internal flag and recompiling the application.
   — Open the "FileDlgContext.cpp" source module.
   — Search for the constant: 'CONSOLE_EDITOR'
   — Set: const bool CONSOLE_EDITOR = true ;
   — Save the changes and recompile the application.
This will force FileMangler to launch the editor (console or GUI) from a new terminal window to avoid possible resource conflicts. Please consult the README file for additional information on conditional compilation flags.


Client Files

Certain types of files cannot be run on their own, but require an external application such as a text editor, document editor, picture viewer or media player to load and process the contents of the file.

A subset of these client files must be processed by GUI applications because console applications cannot display formatted text or graphics. This group of client files we call ‘GUI clients’. GUI clients may be opened without user interaction because each of these client files is associated with a GUI application program.

  • For images and videos, opening a dialog is not necessary since the terminal cannot display images, so for recognized image and video file types, the default image/video application for that media format is launched with the name of the specified file as its argument.
  • For music, it is possible that the default player is a terminal application such as "Mpd", however, the typical music-player is implemented as a GUI application. FileMangler can be configured to include music files in the list of files which may be launched without user intervention.
  • For LibreOffice/OpenOffice documents (and documents created by that filthy office suite from Redmond, WA), a setup dialog is not necessary because we can say with some confidence that LibreOffice/OpenOffice will be needed to open these files.

For manual control over launching these automatically-identified client files, refer to External Programs which describes this configuration option.

Other types of client files such as system configuration files, HTML files and source code, may be opened for editing using the default text-editor application for that type of file. Please review the note on launching a text editor, above.

The application associated with a particular type of client is determined by the file’s MIME type as described above. While many different applications may be able to process a given client file, the preferred application for that file type may be specified directly. See your system documentation for details on setting the preferred file associations.

To launch the application associated with the selected file, FileMangler calls the 'xdg-open' utility with the path/filename of the selected file as the sole parameter. 'xdg-open' scans the file-association databases and launches the associated application.




Find Files by Name

Locate a Currently Displayed Filename

To locate a specific file displayed in the current directory window, simply start typing its filename. All filenames displayed in the window are scanned, beginning at the currently-highlighted item and moving downward through the list. If necessary, the scan will wrap to the top of the list and continue the scan. The first filename matching the provided text (if any) will be highlighted.

All printing characters are accepted as potential filename characters.
Note that the scan is not case sensitive, so that the following search strings are equivalent:

gString.hpp
gstring.hpp
GSTRING.HPP

Note that the current sort order of the displayed files does not affect the scan.

  • If a single printing character is entered, the scan will place the highlight on the first file found which has the same first character. If there are no displayed files that begin with the specified character, a warning beep will sound and the search will be terminated.
  • If the search is extended to two or more matching characters, the search string will be displayed in the Path-display control window just above the list of filenames (see diagram below), and the scan will place the highlight on the first file found which matches the search string.

    A simple help message will be displayed in the Status window.
    Please see Operational Overview for a discussion of the application’s visual layout.

  • You may erase the most-recently-entered character from the search string using either the BACKSPACE key or the DELETE key.

    If you erase all the characters from the search string, then the scan is terminated. The highlight will be positioned on the most recently matched filename.

  • If you enter one of the command-key combinations, for example a Copy, Cut or View operation, the scan will be terminated, and the highlighted file will be 'selected' for the specified operation.
  • To abort the scan, press the ESCAPE key. The highlight will be positioned on the most recently matched filename.

┌───────┤ FileMangler - v:0.0.34 (c)2005-2016 [Press F2 for Menu] ├───────┐ │Status: Filename Search: Printing characters, BKSP/DEL or ESCAPE keys. ├────────────────────────────────────────────────────────────────────────────┤ Filename: Makefi ├────────────────────────────────────────────────────────────────────────────┤ 849,772 27-Apr-2016 02:14:40 FmConfig 129,650 12-Jan-2016 10:53:00 FmConfig.cpp 23,361 12-Jan-2016 10:52:52 FmConfig.hpp 120,416 26-Apr-2016 07:36:21 FmConfig.o 230,956 15-Apr-2016 10:23:43 FmConfigi.cpp 163,208 26-Apr-2016 07:36:22 FmConfigi.o 158,691 27-Apr-2016 05:16:44 FmInterface.cpp 118,888 27-Apr-2016 05:16:47 FmInterface.o 87,310 14-Apr-2016 07:46:18 FmMenu.cpp 20,890 14-Apr-2016 07:46:03 FmMenu.hpp 72,504 26-Apr-2016 07:36:12 FmMenu.o 3,714 29-Jul-2014 11:13:43 GlobalDef.hpp 946 16-Apr-2013 09:44:43 MakeFmConfig 4,220 06-Jan-2016 07:13:15 Makefile 99,799 05-Jul-2015 05:38:17 NCurses.hpp 24,639 05-Dec-2015 10:46:50 NCursesKeyDef.hpp 1,122,234 27-Apr-2016 02:13:36 NcDialog.a 202,144 15-Jan-2016 13:34:36 NcDialog.hpp 50,690 01-Jan-2016 14:41:41 NcWindow.hpp 8,163 14-Apr-2016 11:16:18 captureMW.html 30,310 14-Apr-2016 11:16:18 captureMW.txt 1,028 26-Dec-2015 20:35:52 fmg.sh 673 25-Dec-2015 10:57:43 fmg_old.sh 70,977 13-Feb-2016 14:11:33 gString.hpp 7,895 01-Dec-2015 09:15:53 renamePattern.hpp 14,435 10-Aug-2012 07:28:46 test.cfg 14,330 10-Aug-2012 07:29:02 test2.cfg 14,678 25-Aug-2012 10:36:04 test3.cfg 14,502 10-Aug-2012 10:27:40 test3b.cfg ├────────────────────────────────────────────────────────────────────────────┤ 75 files 10.270M bytes └────────────────────────────────────────────────────────────────────────────┘


Find a File In the Displayed Directory Tree

Find a file or files in the directory tree at or below the currently displayed directory. All accessible directories and files on the directory tree will be scanned including “hidden” directories and files.

The Find command opens a sub-dialog window into which you can enter the search string and in which the files matching the search criteria will be displayed. The sub-dialog will be as wide as the application window for an optimal view of the matching path specifications. (see diagram below)

The following screenshot shows the 'Find Files' dialog with the CWD at a test-data directory called 'Find'. The directory tree for this test data extends five(5) levels below the CWD.


┌───────┤ FileMangler - v:0.0.34 (c)2005-2016 [Press F2 for Menu] ├───────┐ ├─────────────────────┤ Find Files in Directory Tree ├─────────────────────┤ │ CWD: /home/sam/SoftwareDesign/FileMangler/.../Find │ │ Enter search text: find_lev4 │ │ │ Matching Files: 5 RETURN │ │ │ 1) Enter all or part of the filename(s) for which to search. │ │ (enter valid filename characters only) │ │ 2) When the desired filename is displayed, Tab to 'Matching Files' control,│ │ highlight target filename and press Enter key to set target directory. │ │ Press the RETURN Pushbutton to return without setting the target directory.│
├────────────────────────────┤ Matching Files ├────────────────────────────┤ find_lev0a/find_lev1a/find_lev2a/find_lev3a/find_lev4b find_lev0a/find_lev1a/find_lev2a/find_lev3a/find_lev4a find_lev0a/find_lev1a/find_lev2a/find_lev3a/find_lev4_3.txt find_lev0a/find_lev1a/find_lev2a/find_lev3a/find_lev4_2.txt find_lev0a/find_lev1a/find_lev2a/find_lev3a/find_lev4_1.txt └────────────────────────────────────────────────────────────────────────────┘

The features and controls of this dialog:

  1. Application’s title line
  2. Sub-dialog title
  3. The current working directory (CWD)
  4. A Textbox control which receives your search text

    All valid filename characters are accepted as input. Wildcard characters and ‘regular expressions’ are not recognized.

    Unlike the 'Locate' function (discussed above), which compares against the beginning of the filename, 'Find' scans for a matching text sequence anywhere within the filename. The comparison is not case sensitive.

    For instance, a search for the substring 'art' will match all the following because each of these filenames contains the substring 'art' (case insensitive).

    Art Deco in 1925.odt
    Gocart Racing in Nevada.pdf
    Hard Drive Partitioning.html
    Paul Blart Mall Cop.mkv
    

    When you see the desired filename displayed in the list of matching filenames, TAB to the control containing the list (see item 7 below).

    To delete the most recently entered search character, press the BACKSPACE key.

  5. The number of files which match the current search text
  6. 'RETURN' Pushbutton

    Use the 'RETURN' Pushbutton to abort the search and return to the current working directory (CWD).

  7. The list of files which contain the search text

    The relative path of files which contain the specified substring are displayed here. The displayed path is relative to the current working directory (CWD). Thus, a matching file in the CWD will be displayed as the filename only, and a matching file in a subdirectory below the CWD will be displayed with its relative path/filename specification. See the above screenshot for examples.

    To set the directory containing a displayed file as the new CWD, place the highlight on the desired entry and press the ENTER (RET) key.

    The displayed items are color-coded according to filetype.
    Please see Special File Types for more information on color-coding of filenames.

See Dialog Controls, for more information on navigating among dialog controls.




Grep Files

** UNDER CONSTRUCTION - GREP FUNCTIONALITY NOT YET IMPLEMENTED **

 CTRL+G key

Scan selected file(s) for matching substring.

grep’ is a Linux/UNIX utility for scanning the specified files to find substrings that match the provided text search pattern. ‘grep’ is a powerful tool for those who have mastered ‘Regular Expressions, (also known as ‘regexp’). However, the grep/regexp learning curve is just too steep for new users and non-techies. If you want to be an Alpha Nerd, it will be necessary to thoroughly understand the ‘grep’ utility, but that will take time.

To fill the gap while learning to use grep/regexp directly, FileMangler provides a convenient way to access the most useful subset of the ‘grep’ functionality.

‘grep’ can scan all plain text files such as HTML, source code and email files.

‘grep’ also has some limited capacity for scanning binary files such as word-processing and spreadsheet files, as well as audio-file tag data and PDF or other mostly-text files (although the results are seldom helpful).





To learn more about ‘grep’, at the command line, please type:
info grep (ENTER)
or follow the link to the GNU grep documentation:
           http://www.gnu.org/software/grep/manual/grep.html




Backup Your Data

Perform incremental backup of your data or create an archive file containing a copy of your data.

An incremental backup means that data in the target directory will be updated only if there is no target file corresponding to the source file, or if the existing target file is older than the corresponding source file.

An archive backup means creating a single, archive file which contains the selected source data. This archive may optionally be compressed to save space.

The operation can be launched immediately, or it can be scheduled up to thirty-one(31) days in advance. (see scheduled backup)

The Backup Process

Each source file is compared with the corresponding target file.

  • If there is no file in the target directory corresponding to the source file, then the source file will be copied to the target directory.
  • If there is a target file corresponding to the source file, AND if the source file’s modification timestamp is newer than the target’s timestamp, then the older target will be overwritten with a copy of the source.

    Note that the modification date of directory contents is compared. The modification date of the 'Directory' files themselves is meaningless in this context and is ignored.

  • Note that both source and target must be of the same file type. If source and target have the same name but a different filetype, then the target will not be modified.

    Note also that only the following file types will be processed.
    ('Regular', 'Directory', 'Symlink', 'FIFO').

    ’Character Device’, ’Block Device’, ’Socket’, and other file types will be silently ignored. Copying files of these types across filesystems is often impossible, and modification of these files can compromise system stability.

  • If the target’s modification timestamp is the same as or newer than the source file’s modification date, then the target will not be modified.
  • Note that FileMangler must be in Dual-window Mode to perform backup/archive operations (see Dual-window Mode). Backup and archive operations cannot be invoked from Single-window Mode.

    If invoked as a command-line option, the operation will automatically start the application in Dual-window Mode. If the terminal window is not set wide enough for Dual-window Mode, then the operation will not proceed.

  • By default, all data including hidden files in the source directory will be ‘selected’ for processing.

    When all source data are scheduled for backup, then the source data set is determined at the time the operation actually begins. To clarify, if a delay timer is set for the operation, then the source data set is determined when the timer expires. This ensures that all recent changes to the source data are included in the backup.

    Note that if the operation is invoked as a command-line option, then all source data will be automatically ‘selected’’.

  • To process only specific data in the source directory, mark the desired items as ‘selected’ before invoking the Backup operation.

    Note that for a delayed Backup operation performed only on selected files, one or more of the selected files may have been deleted, moved or renamed before the operation actually begins. In this case, an error will be recorded in the log indicating that the source file(s) could not be found.

    Please see Selecting Files for more information.

  • Data are processed recursively; that is, all 'selected' top-level files and subdirectories and the data they contain will be processed.

Invocation

The operation can be invoked in one of three(3) ways:

  • through the ’Backup’ option in the ’Utility’ menu.
  • through the Backup command-key combination: Alt+Shift+B
  • by specifying a Backup definition file as a command-line option.
    (see 'b' option)

Regardless of which invocation you choose, a dialog window will be opened so you can adjust the parameters of the operation.


The Backup/Archive Dialog

┌───────────────────────────────┤ Perform Data Backup ├────────────────────────────────┐ │ Source Path: │ /home/sam/SoftwareDesign/FileMangler/1_TestData/CopySource │ Target Path: │ /home/sam/SoftwareDesign/FileMangler/1_TestData/CopyDest │ │ Delay the operation by: < > Create Backup Archive │ 011:45 Operation will begin: Backup_2016_02_20.tar.bz2 │ hrs mn Saturday 2016-02-20T18:00 │ < > Exclusion List │ │ ┌─────────────────┐ Log Format Backup_Def.txt │ │Verbose Mode ♦ │ │ └─────────────────┘ OK CANCEL └────────────────────────────────────────────────────────────────────────────────────────┘

The items displayed in this dialog:

  • Source Path
    This is the directory displayed in the active window.
  • Target Path
    This is the directory displayed in the inactive window.
  • Specify a delay for start of the operation

    • Begin the operation immediately (no delay)
      Set the 'hrs' and 'mn' spinners to zero.
    • Specify the amount of delay
      Set the number of hours ('hrs') and minutes ('mn') to delay before beginning the operation.

      The delay may be in the range of 000:01 (one minute) to 744:59 (31 days) from the current system local time. (Note that the actual launch time will be automatically adjusted to the next whole minute, system local time.)

    Please see Dialog Controls for a description of using dialog-window controls.

  • Optional Archive Target
    To perform an 'Archive' operation, select the 'Create Backup Archive' radiobutton, and enter the name of the archive target file (NOT a path). The 'tar' utility will be used to create the archive in the target directory.

    To create an uncompressed archive, the filename should have a filename extension of '.tar'.
    Example: Backup_2016_03_31.tar

    To create a compressed archive, the filename extension must be one of the compression extensions recognized by the 'tar' utility (see archive targets, below).
    Example: Backup_2016_03_31.tar.bz2

    If the specified archive file already exists, the filename for the new archive will be modified slightly to protect existing data.

    Example: For a target specified as:
             'Backup_2016_03_31.tar'
    
             If the specified file already exists, then
             the name will be modified to:
             'Backup_2016_03_31a.tar'
    
             If that target also exists, then
             the name will be modified to:
             'Backup_2016_03_31b.tar'
    

    Important Note:
    If the filename extension is neither '.tar' nor one of the recognized compression extensions, the operation will not proceed.

    To perform a 'Backup' operation, deselect the 'Create Backup Archive' radiobutton.
    (The archive filename (if any) will be ignored.)

    For additional archive options, please see Working With Archives.

  • Optional List of Exclusions
    Specify a definition file (see Backup Definition File, below).

    • If the operation was invoked from the command-line, then the exclusion records, if any, contained in the specified definition file will be used, and this control will be disabled.
    • If no backup definition file was specified on the command line, then the application will search for the default definition file “Backup_Def.txt”, located in the application’s installation directory.

      If the default definition file is found, then the exclusion records, if any, will be read from the file, and the 'Exclusion List' radiobutton will be set to indicate that files matching the exclusion criteria will be excluded from the backup.

    • If the operation was invoked from the menu or via command key, then the 'Exclusion List' radiobutton may be enabled or disabled to activate or deactivate the exclusion criteria.

      The definition file from which to read the exclusion criteria may be specified in the textbox control below the 'Exclusion List' radiobutton. Specify the file either through a full path/filename or as a filename only.

      If a filename only is specified, FileMangler will first look for the file in the operation’s source directory (active window), and if not found there, will look in the application’s installation directory.

    Only the 'EXCLUDE' records will be read from the indicated file, and all other records in the file will be ignored.

  • Log Format
    Select the level of detail to be reported in the log file. The source directory path, target directory path and the operational summary will always be displayed.

    There are five (5) levels of detail for reporting the individual source files.

    • Verbose
      Display a record for each source file scanned regardless of whether it is to be updated.
    • Updates Only (default)
      Display records for updated files only. This includes updates which were successful as well as those which were attempted, but failed. Files which do not require an update will not be reported.
    • Errors Only
      Display records only for attempted updates which failed (sour or target access errors, source/target mismatch error, system errors.).
    • Summary Only
      Display only the source and target directories along with the operational summary. Records for individual files and subdirectory names will not be reported.
    • Debug Selection Criteria
      This is the same as the Updates Only option except that additional information is displayed for each source file (and target file if it already exists). This option is useful primarily during development. It provides a direct, visual comparison between the source and target read/write access flags and the file modification timestamps in both ISO 8601 format and the raw system timestamp in hexadecimal (seconds since the “epoch”).

      Example:
      s: 1 1 2013-05-02T00:39:00 5181EDE4
      t: 1 1 2013-05-01T12:38:42 51814512
      ▬▬▬▶ /home/sam/SoftwareDesign/1_TestData/Somefile-04.a s: 1 1 2013-05-02T01:54:00 5181EE21
      t: 1 0 2013-05-01T12:38:42 51814512
      ACC /home/sam/SoftwareDesign/1_TestData/Somefile-05.a

    Please see operation logfile for additional informaton.


Delayed-operation Countdown

For delayed operations, when the operation is launched, a countdown dialog will show the time remaining until the operation begins.

You may cancel the pending operation at any time before the countdown reaches zero.

┌─┤ Countdown to Data Backup ├─┐ │ │ Operation is scheduled for: │ Saturday, 2016-02-20T18:00 │ │ │ Time Remaining 03:11:37 │ │ CANCEL └────────────────────────────────┘



Operation Progress Bar

For operations that require more than a few seconds to complete, a visual indicator of progress called a Progress Bar is displayed.

The Progress Bar is displayed in the status area (second line in the application window). As files are processed, the Progress Bar will advance to the right, indicating the percentage of the operation that has been completed. The percentage is calculated as the number of source bytes processed divided by the total source bytes.


┌───────┤ FileMangler - v:0.0.34 (c)2005-2016 [Press F2 for Menu] ├─────────────────────────┐ │Status:████████████████████████████████████████████ ├──────────────────────────────────────────────────────────────────────────────────────────────┤ /home/sam/SoftwareDesign/FileMangler/.../CopySource /home/sam/.../CopyDest ├─────────────────────────────────────────────────────────┐┌───────────────────────────────────┤
4,096 25-Jan-2016 09:27:14 EggMan ││ 4,096 20-Feb-2016 11:05:10 FrogMan ││ 4,096 25-Jan-2016 11:42:06 荒谬的名字     ││ 336,302 03-Feb-2012 00:17:44 Dialog1 ││ 14,612 03-Feb-2012 00:17:44 FileDlg_Trav.d ││ 90,304 03-Feb-2012 00:17:44 Generic.cpp ││ 2,428 03-Feb-2012 00:17:44 Makefile.old ││ 27,296 03-Feb-2012 00:17:44 NCurses.o ││ 16,212 03-Feb-2012 00:17:44 NcDialog.o ││ 43,292 03-Feb-2012 00:17:44 NcDialogControls.o ││ 11,200 03-Feb-2012 00:17:44 NcKey.o ││ 15,192 03-Feb-2012 00:17:44 NcScroll.o ││ 14,504 03-Feb-2012 00:17:44 NcWindow.o ││ 100 12-May-2016 03:17:08 RestoreTest01.txt ││ 200 12-May-2016 03:18:24 RestoreTest02.txt ││ 300 12-May-2016 03:19:23 RestoreTest03.txt ││ 10,192 03-Feb-2012 00:17:44 Some Text Data.txt ││ 47,400 08-Jun-2016 21:16:30 Tom's_Toothpaste.o ││ 14,720 03-Feb-2012 00:17:44 backup file.odt~ ││ 217,191 03-Feb-2012 00:17:44 grub.efi ││ 85 21-Jan-2016 20:42:25 link2FileDlg_Trav.d ││
├─────────────────────────────────────────────────────────┘└───────────────────────────────────┤ 21 files 873,818 bytes Select: 55: 2.5813M 0 files 0 bytes └──────────────────────────────────────────────────────────────────────────────────────────────┘

Screenshot modified to fit this document.


Several factors contribute to an operation requiring a significant amount of time to complete.

  • the total size of the source data.
    Many files such as music, video and images require a very large amount of storage space. Also, backup/synch operations typically process hundreds or thousands of files, so the total size of the data to be read and written could be several gigabytes.
  • the target media is physically slow to update.
    SD cards, USB flash drives, optical drives and similar media are slow to update because of the algorithm required to write data to them.
  • the target is a network drive on a remote system
    Transferring data across a network is dependent upon the speed of the connection and the amount of traffic currently on the network.

These and other factors contribute to the amount of time required to complete an operation. If an operation is taking longer than you think it should, but no progress is shown by the Progress Bar, please be patient (and possibly switch to decaf).


Summary-results Dialog

┌────────────────────────────────┤ Operation Summary ├─────────────────────────────────┐ Source Path: │ /home/sam/SoftwareDesign/FileMangler/1_TestData/CopySource │ Target Path: │ /home/sam/SoftwareDesign/FileMangler/1_TestData/CopyDest │ │ │ Operation : Backup 2016-02-20T18:00 │ Source files : 51 │ Files updated: 51 │ Files skipped: 0 │ Errors : 0 CLOSE VIEW LOG SAVE LOG └────────────────────────────────────────────────────────────────────────────────────────┘

The items displayed in this dialog:

  • Source Path
    This is the directory displayed in the active window.
  • Target Path
    This is the directory displayed in the inactive window.
  • Operation
    Type of operation (Backup, Archive, Synch) and the timestamp.
    If Archive operation, then the name of the target archive is also reported here.
    (If operation was aborted before completion, that is also indicated on this line.)
  • Source files
    Reports the total number of files ’selected’ for processing.
  • Files updated
    Reports the number of files updated.
  • Files skipped
    Reports the number of files which did not require updating.
  • Errors
    Reports the number of errors encountered during the operation.
  • ’Close’ Pushbutton
    Close the dialog and return to the main FileMangler application.
  • ’View Log’ Pushbutton
    View the raw operational log (without summary data). This is a temporary file which will be deleted when the dialog closes.
  • ’Save Log’ Pushbutton
    Insert the summary information into the log file and save it to the target directory using the previously-specified log filename.
    Please see operation logfile for more information.

Technical Notes:: If user aborts the operation before it is completed, then only the 'Files updated' count will be accurate. The other accumulated totals will be unreliable.

Special note for unsupported filetypes:
Although all files with unsupported filetypes will be correctly skipped, for Synch operations only, the number of skipped items reported may be inaccurate if files with unsupported file types are found in the source directory. In this case, the log file may be consulted for details.


The Definition File

When the operation is invoked as a command-line option, the invocation includes the name of a file defining the parameters for the operation.

The definition file is a plain text file which specifies the parameters for the Backup, Archive or Synch operations.

Each parameter consists of a field identifier, optionally followed by the value for that parameter. If no field identifer is specified for a given parameter, or if the field is blank, then the default value for that parameter will be used.

Lines beginning with the hash character '#' are interpreted as comments and will be ignored. Blank lines or lines containing only white space will also be ignored.

If a parameter contains invalid data or a syntax error, then the default value for that parameter will be used if possible, and a warning message will be displayed. However, some parameter errors cannot be automatically corrected and will cause the operation to terminate with an error message.

To avoid syntax errors, it is recommended that definition files be created using the template file 'Backup_Def.txt' included in the FileMangler installation directory.


Example definition file

# FileMangler Backup, Archive, Synch Definition File
SOURCEDIR: ~/Documents
TARGETDIR: /run/media/sam/SDCARD_64GB/Documents
OPTYPE   : Backup
OPBEGIN  : 17:30
ARCHIVE  : Weekly_Backup_12.tar
LOGFILE  : Weekly_Backup_12.log
EXCLUDE  : .o
EXCLUDE  : ~
EXCLUDE  : .bak
EXCLUDE  : .tmp

Default Parameters

The initial values displayed in the dialog will be taken from the definition file, if specified (see above), or using default parameters as follows.

  1. Source Directory
    Specify an absolute or relative path to directory containing the data to be processed.

    For Backup and Archive operations, this is the source directory.
    For Synch operations, this is the primary source (and secondary target).

    Default: The directory displayed in the window that has input focus i.e. the active window.

  2. Target Directory
    Specify an absolute or relative path of directory to which the data will be copied.

    For Backup and Archive operations, this is the target directory.
    For Synch operations, this is the primary target (and secondary source).

    Note that Source and Target may not be the same unless the operation type is 'Archive'.

    Default: The directory displayed in the inactive window i.e. the window which does not have focus.

  3. Type of Operation
    Range: ’Backup’, ’Archive’ or ’Synch’

    Default: Backup

  4. Time operation is to begin
    Specifies a time for the operation to begin. The time may be specified in either of two formats.

    • Timestamp format
      Specify a date/time for the operation to begin using an ISO 8601 format for displaying the system local time.
      yyyy-mm-ddThh:mm:ss

      Using this format, any future date and time up to 31 days in the future (inclusive) may be specified.
      For example, schedule an end-of-month backup:

      OPBEGIN: 2016-03-31T23:59:59
      

      Note that the timestamp specifies a system local time, and that locale-specific timestamp information such as time zone, UTC offset and daylight-savings-time are not considered.

    • Simple 24-hour format
      Specify a clock time in 24-hour format: hh:mm.
      Range: 00:00 to 23:59

      Using this format the operation can be specified to begin at any time up to 24 hours in the future.

      Examples, assuming that the time the application is invoked (current time) is 13:00 (01:00 pm).

      Begin at 18:00 (06:00 pm) this evening:
          OPBEGIN: 18:00
      
      Begin at 07:30 (07:30 am) tomorrow morning:
          OPBEGIN: 07:30
      

    Default: Start immediately (no start time specified)

         Example:
             OPBEGIN: 
    
  5. Name of Archive target
    When the operation is to create an archive file, optionally specify the name of the archive.

    DO NOT specify a path. The archive will be written to the operation’s target directory.

    Default: 'Backup_yyyy_mm_dd.tar.bz2'
    The default filename includes the timestamp indicating when the archive was created and also indicates an archive compressed using 'bzip2'..

    All archive files use the '.tar' utility. 'tar' optionally compresses the archive based on the filename extension. Please refer to the 'tar' documentation for a complete list of compression options supported. (info -f tar -n ’gzip’)

    Example (uncompressed archive):
       Backup_2016_06_30.tar
    
    Example (archive with bzip2 compression):
       Backup_2016_06_30.tar.bz2
    
    Example (archive with gzip compression):
       Backup_2016_06_30.tar.gz
    
  6. Name of log file
    Optionally specify a filename for an operation log to be automatically created which will contain details of the operation, including a list of any errors encountered.

    DO NOT specify a path. The log file will be written to the operation’s target directory.

    To avoid loss of data, if the log file already exists, the log will be appended to the existing file. If the file does not exist, it will be created.

    Default: 'Backup_yyyy_mm_dd.log'
    Note that if a log filename is specified in the definition file, the log will be automatically saved. If no log filename is specified, then the log may be explicitly saved at the end of the operation with the 'SAVE LOG' pushbutton in the summary-results dialog.

  7. Excluded files
    Certain categories of files or specific files may be excluded from the Backup operation.

    Important Note: Exclusion records apply to Backup operations only, and are ignored for Archive and Synch operations.

    For incremental backup operations, it is often unnecessary to include files which are easily recreated. For example, object files (files with a '.o' filename extension), or files renamed as backup copies (files ending with the tilde '~' character).

    Each category of file to be excluded must be on a separate line, and the specified text string will be compared to the end of source filename, just before the NULL terminator character.

    Example:
    To exclude object files, add a line to the end of the definition file:
    EXCLUDE: .o
    Each source file will be compared with the '.o' substring, and if a match is found, the file will not be included in the backup.
    Note that the comparison is not case sensitive.

    The filename 'FmConfig.o' will match the exclusion pattern and will not be included in the backup.

    The filename 'Strangelove.odd.odt' will not match the exclusion pattern and will be included in the backup.

    To exclude a specific file from the Backup operation, specify either the complete filename or the full path/filename. Note that environment-variable substitutions WILL NOT be performed on exclusion records.

    Examples:
        EXCLUDE: PasswordList.odt
        EXCLUDE: /home/sam/Documents/Private/PasswordList.odt
    

    Default: no files excluded


Technical Note: While the source directory cannot be the same as the target directory,
the source directory may contain the target directory, or the target directory may contain
the source directory without conflict.

This is because source data are placed on the clipboard before the operation begins
and are not copied directly from Source to Target.



Operation Log File

During Backup, Archive and Synch operations, a log is created which indicates what data were processed, what data were skipped, and any errors that occurred.

At the end of the operation, a summary of the operation will be displayed in a dialog window. This dialog provides options to view and/or save the log file (see backup summary dialog).

The log file uses a very simple format with short header records to indicate the operation performed on each file.

  • DIR:
    Indicates a directory record.
  • ▬▬▬▶
    Indicates a (non-directory) file which was successfully updated.
  • SKP:
    Indicates that the file was not processed:
    — no update needed (target is up-to-date)
    — source file is of an unsupported filetype
  • ACC:
    Indicates that update for the file encountered an access error:
    — read access error on source
    — read or write access error on target
  • ERR:
    Indicates a general error reported by the system during update of the target.
  • TYP:
    Indicates a file-type mismatch error:
    The source file is of a different file-type than the existing target file of the same name.

The following is a simple example log which describes a Backup operation for a single subdirectory and its contents. Log files for the Synch operation are formatted in a similar manner.

FileMangler Backup Logfile: 2016-02-20T23:59:42
===============================================

Source:
   /home/sam/1_TestData/CopySource
Target:
   /home/sam/1_TestData/CopyDest

Summary Results
---------------
Operation    : Backup
Source files : 6
Files updated: 5
Files skipped: 1
Errors       : 0

DIR: /home/sam/1_TestData/CopySource/FrogMan/Fm2
     ▬▬▬▶ /home/sam/1_TestData/CopySource/FrogMan/Fm2/fm2_01.txt
     SKP: /home/sam/1_TestData/CopySource/FrogMan/Fm2/fm2_02.txt
DIR: /home/sam/1_TestData/CopySource/FrogMan
     ▬▬▬▶ /home/sam/1_TestData/CopySource/FrogMan/fm_01.txt
     ▬▬▬▶ /home/sam/1_TestData/CopySource/FrogMan/fm_02.txt

END-OF-LOG

The following is a simple example log which describes an Archive operation for a single subdirectory and its contents.

FileMangler Backup Logfile: 2016-03-01T01:26:11
===============================================

Source:
   /home/sam/1_TestData/CopySource/FrogMan
Target:
   /home/sam/1_TestData/CopyDest

Summary Results
---------------
Operation    : Archive
Source files : 5
Files updated: 5
Files skipped: 0
Errors       : 0

TAR command: tar -cavv --numeric-owner 
         --file='/home/sam/1_TestData/CopyDest/Backup_2016_03_01.tar.bz2' 

Total bytes written: 20480 (20KiB, 60KiB/s)

drwxrwxr-x 1000/1000         0 2016-02-21 00:05 Fm2/
-rw-r--r-- 1000/1000      2428 2012-02-03 13:17 Fm2/fm2_01.txt
-rw-r--r-- 1000/1000      2428 2012-02-03 13:17 Fm2/fm2_02.txt
-rw-r--r-- 1000/1000      2428 2012-02-03 13:17 fm_01.txt
-rw-r--r-- 1000/1000      2428 2012-02-03 13:17 fm_02.txt

END-OF-LOG



Synchronize Directories

Synchronize data between two directories on the same or different systems. This is useful when making changes to files on multiple systems or when copying data between systems.

Synchronization means verifying that the most up-to-date data is on both filesystems. For instance, if you develop applications to run on both Ubuntu(tm) and Fedora(tm), then you need to be sure when you move your source code between systems that both systems have the current version.

The operation can be launched immediately, or it can be scheduled up to thirty-one(31) days in advance.

The Synchronization Process

Synchronization can be thought of as a two-way backup operation. First, the source data are backed up to the target, and second, the target directory becomes the source and the source directory becomes the target and the operation is repeated.

For each phase of the operation, each source file is compared with the corresponding target file.

  • If there is no file in the target directory corresponding to the source file, then the source file will be copied to the target directory.
  • If there is a target file corresponding to the source file, AND if the source file’s modification timestamp is newer than the target’s timestamp, then the older target will be overwritten with a copy of the source.

    Note that the modification date of directory contents is compared. The modification date of the 'Directory' files themselves is meaningless in this context and is ignored.

  • Note that both source and target must be of the same file type. If source and target have the same name but a different filetype, then the target will not be modified.

    Note also that only the following file types will be processed.
    ('Regular', 'Directory', 'Symlink', 'FIFO').

    ’Character Device’, ’Block Device’, ’Socket’, and other file types will be silently ignored. Copying files of these types across filesystems is often impossible, and modification of these files can compromise system stability.

  • If the target’s modification timestamp is the same as or newer than the source file’s modification date, then the target will not be modified.
  • Note that FileMangler must be in Dual-window Mode to perform synch operations (see Dual-window Mode). Synch operations cannot be invoked from Single-window Mode.

    If invoked as a command-line option, the operation will automatically start the application in Dual-window Mode. If the terminal window is not set wide enough for Dual-window Mode, then the operation will not proceed.

  • The synchronization process is designed to update ALL files of supported file types including hidden files in both the source and target directories according to the files’ modification dates. Unlike the backup process described in the previous chapter, no files will be excluded.
  • Data are processed recursively; that is, all selected top-level files and subdirectories as well as all the data they contain will be processed.

Invocation

The operation can be invoked in one of three(3) ways:

  • through the ’Synchronize’ option in the ’Utility’ menu.
  • through the Synch command-key combination: Alt+Shift+S
  • by specifying a Backup definition file as a command-line option.
    (see 'b' option)

Regardless of which invocation you choose, a dialog window will be opened so you can adjust the parameters of the operation.

┌───────────────────────────────┤ Perform Data Synch ├────────────────────────────────┐ │ Source Path: │ /home/sam/SoftwareDesign/FileMangler/1_TestData/SynchSource │ Target Path: │ /home/sam/SoftwareDesign/FileMangler/1_TestData/SynchDest │ │ Delay the operation by: < > Create Backup Archive 011:45 Operation will begin: Backup_2016_02_20.tar.bz2 │ hrs mn Saturday 2016-02-20T18:00 < > Exclusion List Backup_Def.txt │ │ OK CANCEL └────────────────────────────────────────────────────────────────────────────────────────┘

The items displayed in this dialog:

  • Source Path
    This is the directory displayed in the active window.
  • Target Path
    This is the directory displayed in the inactive window.
  • Specify a delay for start of the operation

    • Begin the operation immediately (no delay)
      Set the 'hrs' and 'mn' spinners to zero.
    • Specify the amount of delay
      Set the number of hours ('hrs') and minutes ('mn') to delay before beginning the operation.

      The delay may be in the range of 000:01 (one minute) to 744:59 (31 days) from the current system local time. (Note that the actual launch time will be automatically adjusted to the next whole minute, system local time.)

    Please see Dialog Controls for a description of using dialog-window controls.

  • Optional Archive Target (not applicable to Synch)
  • Optional List of Exclusions (not applicable to Synch)

Delayed-operation Countdown

For delayed operations, when the operation is launched, a countdown dialog will show the time remaining until the operation begins.

You may cancel the pending operation at any time before the countdown reaches zero.

┌─┤ Countdown to Data Synch ├─┐ │ │ Operation is scheduled for: │ Saturday, 2016-01-30T06:00 │ │ │ Time Remaining 02:21:45 │ │ CANCEL └────────────────────────────────┘


Operation Progress Bar

For operations that are predicted to take more than a few seconds, an interactive visual indicator of progress is displayed.
Please see Operation Progress Bar for more information.


Summary-results Dialog

┌────────────────────────────────┤ Operation Summary ├─────────────────────────────────┐ Source Path: │ /home/sam/SoftwareDesign/FileMangler/1_TestData/SynchSource │ Target Path: │ /home/sam/SoftwareDesign/FileMangler/1_TestData/SynchDest │ │ │ Operation : Synch 2016-02-20T18:00 │ Source files : 51 │ Files updated: 14 │ Files skipped: 37 │ Errors : 0 CLOSE VIEW LOG SAVE LOG └────────────────────────────────────────────────────────────────────────────────────────┘

Note on accumulated totals

Because the synchronization process is performed in two passes, the reported totals represent the combined total of files for both passes. While this is logical, it may be confusing, so keep in mind:

  • The most informative value is “Files Updated” which is the number of updates performed in both passes.
  • The “Source Files”, “Files Skipped” and “Errors” totals may include both the source and target copies of the same file.

Please see backup summary dialog for more information.


The Definition File

Please see Backup Definition File for a description of the definition file.


Default Parameters

Please see Backup Default Parameters for a list of operational defaults.




Working With Archives

This chapter discusses direct creation, modification and expansion of archive files. To view the contents of an archive file without extracting its contents, please see View File Contents.




Archive Overview

  • The 'tar' (tape archive) utility may be used to create data archive files on almost any target media, and despite the name, 'tar' archives are no longer intended primarily for writing data to reel-to-reel tape drives.
  • 'tar' is closely integrated with many popular data-compression utilities such as 'bzip2', 'gzip' and others. see Creating an Archive for a complete list of compression options.
  • 'tar' has grown over time to meet emerging needs, making it extremely flexible, but also unbelievably complex, so that only professional systems administrators are likely to understand (or need) its full capabilities.

FileMangler provides intuitive, dialog-based access to the essential 'tar' functionality for creating and modifying archives, and extracting items from an archive.

If you need greater control over archive operations, the 'tar' utility is distributed with a number of shell scripts for various operations. See the 'tar' documentation, Chapter 5 'Backups' for additional information.



Creating an Archive

In addition to creating archive files directly, FileMangler supports creation of an archive file during scheduled data backup operations.
Please see Backup Your Data for more information on data backup to an archive.

Selecting Items to Be Archived

To create an archive file, first specify the data to be written to the archive, then invoke the Create Archive dialog.

Selecting files and subdirectory trees to be included in the archive is similar to selecting items for a Copy operations.
Please see Selecting Files for a review of file selection.

Select each item you want to include in the archive. The 'selected' item(s) will be indicated by underlining the item name.

When you invoke the Create Archive dialog, all 'selected' items will be copied to the FileMangler clipboard to be used in creating the target archive.

Note that if you have previously 'copied' data to the clipboard, and have not 'selected' any items in the active window, then the data already on the clipboard will be used as the archive source data.

If you are not sure what data (if any) are already on the FileMangler clipboard, then you may view the current clipboard contents and optionally clear the data from the clipboard before proceeding. Please see Manage FileMangler Clipboard for information on managing clipboard data.

Important Note: When creating an archive, the source data will not be modified in any way.


Invoking the Create Archive Dialog

 ALT+SHIFT+A key

  • After selecting the files and subdirectories to be archived, (see above), invoke the Create Archive dialog.
    • Press the ‘SHIFT+ALT+A’ command-key combination, OR
    • In the 'Util' menu, select the 'Archive' menu item.
  • The target archive will be created in the active Directory Window, that is, the file-display window which currently has input focus.
    Please see Dialog Controls for more information on input focus.
  • Note that if the Create Archive dialog is invoked without first specifying one or more items to be archived, then a warning message will displayed, and the dialog will not be opened.
┌───────────────────┤ ALERT ALERT ├───────────────────┐ │ │ │ For archive operations, you must place source data │ │ on the clipboard, highlight the name of an existing │ │ archive file, or both. │ │ Please see documentation: "Working With Archives" │ │ │ OK └─────────────────────────────────────────────────────┘



The Create-Archive Dialog

┌────────────────┤ Create an Archive ├────────────────┐ Create an archive file from the selected data. │ Archive Name 2016_03_31.tar.bz2 │ Filename extension indicates type of │ │ compression. (see 'tar' documentation) │ EXTENSION COMPRESSION │ .tar None │ Source Files: 14 .bz2 .tbz bzip2 │ Source Bytes: 462Kb .gz .tgz gzip │ │ .tlz .lzma lzma │ │ .lz lzip │ │ .lzo lzop │ CREATE CANCEL .xz xz │ └───────────────────────────────────────────────────────┘

The Create Archive dialog has the following features.

  • Archive Name
    Specify the name of the archive to be created.

    The default name for the archive is based on the system local time and assumes 'bzip2' compression; however, you may give the archive any name provided that the filename extension is one of those listed in the table below.

    To create an uncompressed archive, use a filename extension of '.tar'.

    To create a compressed archive, use the filename extension corresponding to the type of compression desired. The most popular and efficient compression options are 'bzip2' and 'gzip'. The other options are provided for full compatibility, but are seldom used for modern archives.

    Please note that if you plan to add files to the archive at a later time, you must create an uncompressed archive. Files cannot be added to a compressed archive.

    Do not specify the name of an existing archive. FileMangler will refuse to overwrite an existing archive file.

  • Source Files
    Number of source files to be written. This includes all selected files, selected subdirectories and the subdirectory contents.
  • Source Bytes
    Total size of source data (in bytes).

    If the target archive is not compressed, then the size of the resulting archive will probably be somewhat larger than the total size of the source.

    If the target archive is compressed, then the size of the resulting archive will probably be smaller than the source data. The size of a compressed archive is affected by several factors including the type of compression used and the type of data being archived.

  • 'Create' Pushbutton
    Create the archive in the active directory window.
  • 'Cancel' Pushbutton
    Cancel the operation in progress. The archive will not be created, and the source data will not be modified.

Table of Compression Options

 Filename  Extension   Compression  Type   Example Name
 .tar None ArchiveName.tar
 .bz2 bzip2 ArchiveName.tar.bz2
 .tbz ArchiveName.tbz
 .gz gzip ArchiveName.tar.gz
 .tbz ArchiveName.tgz
 .lzma lzma ArchiveName.tar.lzma
 .tlz ArchiveName.tlz
 .lz lzip ArchiveName.tar.lz
 .lzo lzop ArchiveName.tar.lzo
 .xz xz ArchiveName.tar.xz


Operation Summary and the Log File

After the archive has been created, a summary of the operation is displayed.


┌────────────────┤ Operation Summary ├────────────────┐ Operation : Create Archive │ 2016_03_31.tar.bz2 │ │ Archive Source Data files: 14 14 │ bytes: 462Kb 462Kb │ Target: 122Kb │ Errors: 0 │ Log Written: 2016_03_31.tar.bz2.log │ CLOSE VIEW LOG SAVE LOG └───────────────────────────────────────────────────────┘

The summary dialog has the following features:

  • The type of operation just completed.
  • The name of the target archive file.
  • The number of source files and the number of files successfully written to the archive.
  • The size of the source data and the stored size recorded in the archive.

    Technical Note: Because 'tar' records the size of archived subdirectories as having zero (0) bytes, the recorded total size of the archive members may be somewhat inaccurate if the source filesystem is configured for a block size other than 4kbytes. This does not affect the integrity of the archive, only the reported summary data.

  • The size of the target archive file (in bytes).
  • The number of errors encountered.
    Errors may be caused by any number of circumstances, such as insufficient access permission, an attempt to archive a file of one of the 'special' types (character or block device files), or insufficient space on the target media.
  • 'VIEW LOG' Pushbutton
    If errors are reported, or if you are simply curious about the operation, you can view the operation log.
  • 'SAVE LOG' Pushbutton
    The log file is created as a temporary file which will be discarded when the dialog closes. If you would like to keep a copy of the log file, then choose 'SAVE LOG', and the log will be copied to the target directory using the same name as the archive, but with a '.log' extension.
    ARCHIVE : 2016_03_31.tar.gz
    LOG FILE: 2016_03_31.tar.gz.log
    
  • 'CLOSE' Pushbutton
    Close the summary dialog.

To view the contents of the new archive, highlight the archive name and press ENTER (RET) to open the ViewFile context menu. See View File Contents, for more information.

Complex Data Specification

In the case where BOTH source data AND and an existing archive file are specified, you will be asked to specify the type of operation you wish to perform. Please see complex archive source.




Expanding an Archive

Extract data from an archive file to the target filesystem location.

Specifing the Archive to be Expanded

  • To expand an archive into the same directory where the archive file itself is located, simply place the highlight on the archive filename and invoke the Expand Archive dialog as described below.
  • To expand an archive to another location, first copy the archive to the FileMangler clipboard:
    • Place the highlight on the archive filename
    • Copy the archive to the clipboard using the CTRL+C command.
    • Navigate to the directory where you wish to expand the archive.
    • Invoke the Expand Archive dialog as described below.

Invoking the Expand Archive Dialog

 ALT+SHIFT+A key

  • Invoke the Expand Archive dialog:
    • Press the SHIFT+ALT+A command-key combination, OR
    • In the 'Util' menu, select the 'Archive' menu item.
  • The archive will be expanded to the directory displayed in the active window.
  • The archive itself will not be modified in any way.

┌────────────────┤ Expand an Archive ├────────────────┐ Expand the specified archive to current directory. │ Archive Name Backup_2016_04_05.tgz │ │ Archive Files: 14 │ Archive Size : 127Kb │ Expanded Size: 462Kb │ │ │ │ │ │ │ │ │ │ │ EXPAND CANCEL └───────────────────────────────────────────────────────┘

The Expand Archive dialog has the following features.

  • Archive Name
    Name of source archive file.
  • Archive Files
    Number of files contained in the archive.
  • Archive Size
    Size of the archive file on disk (in bytes).
  • Expanded Size
    Approximate disk space which will be required to expand the archive.
  • If the target directory already contains data, then a warning message about potential data loss will also be displayed.
  • 'Expand' Pushbutton
    Expand the archive in the active directory window.
  • 'Cancel' Pushbutton
    Cancel the operation in progress. The archive will not be expanded, and any existing targets will be unmodified.

Existing Targets

CAUTION! CAUTION! CAUTION!
If files and/or top-level subdirectory names stored in the archive have the same name(s) as files/subdirectories which already exist in the target directory, then 'tar' will delete (unlink) those existing targets before writing data from the archive to the target directory.

This is almost always the right thing to do because you will naturally expect the contents of the archive to be faithfully reproduced in the target directory.

It is Strongly Recommended that an archive always be expanded into a 'clean' subdirectory to avoid potential data loss. That is, when expanding an archive, the target directory should contain only the source archive file itself, or should contain no files at all.

Technical Note: If absolute path specifications or references to a parent directory above the current working directory, are used for items stored in the archive, then the location to which those targets would actually be written is wildly unpredictable and potentially destructive.
— A leading forward-slash ('/') indicates an absolute path.
— A '..' sequence indicates a reference to parent directory.
For this reason, FileMangler instructs 'tar' to always ignore a leading '/' character in the path, and also to refuse extraction of items which contain a '..' parent-directory reference.


Operation Summary and the Log File

After the archive has been expanded, a summary of the operation is displayed.


┌────────────────┤ Operation Summary ├────────────────┐ Operation : Expand Archive │ Backup_2016_04_05.tgz │ │ Source Archive Extracted files: 14 14 │ bytes: 462Kb 462Kb │ Errors: 0 │ Log Written: Backup_2016_04_05.tgz.log │ CLOSE VIEW LOG SAVE LOG └───────────────────────────────────────────────────────┘

The summary dialog has the following features:

  • The type of operation just completed.
  • The name of the source archive file.
  • The number files in the source archive and the number of files extracted.
  • The recorded total size of data in the archive and the (approximate) size of the data expanded to the target directory.
  • The number of errors encountered.
    Errors may be caused by a number of factors such as insufficient access permission for source archive or target directory, use of incompatible options during creation of the archive, or insufficient free space on the target filesystem.
  • 'VIEW LOG' Pushbutton
    If errors are reported, or if you are simply curious about the operation, you can view the operation log.
  • 'SAVE LOG' Pushbutton
    The log file is created as a temporary file which will be discarded when the dialog closes. If you would like to keep a copy of the log file, then choose 'SAVE LOG', and the log will be copied to the target directory using the same name as the archive, but with a '.log' extension.
    ARCHIVE : Backup_2016_04_05.tgz
    LOG FILE: Backup_2016_04_05.tgz.log
    
  • 'CLOSE' Pushbutton
    Close the summary dialog.

When the summary dialog closes, the extracted items will be displayed in the active directory window.


Complex Data Specification

In the case where BOTH source data AND and an existing archive file are specified, you will be asked to specify the type of operation you wish to perform. Please see complex archive source.




Updating an Archive

The 'tar' utility provides various mechanisms for modifying an existing archive.

  • Append new data at the end of the archive. (unconditional Append)

    FileMangler supports ONLY this method for updating an existing archive.

  • The remaining update options are described for historical reasons only.
    • Update existing archive members.
      If the source file on disk is newer than the corresponding file in the archive, then append the new file to the archive (conditional Append). Note that the previous version of the archive member is still physically present in the archive, but will be overwritten by the new version during extraction. This actually defeats the purpose of an archive because it indefinitely stores obsolete data, wasting storage space and causing confusion.
      (Note that this option is not supported by FileMangler.)
    • Delete files from the archive
      All archived versions of the specified file will be deleted. This is a slow, clunky and error-prone operation at best, and is not recommended.
      (Note that this option is not supported by FileMangler.)
      Instead, expand the existing archive and then create a new archive including only the data you want.
    • Concatenate multiple archives into a single target archive. This might be useful if multiple, independent distributions were being provided as a single, integrated unit, but otherwise makes no sense.
      (Note that this option is not supported by FileMangler.)

Selecting Items to Be Added to Archive

To update an archive file, first specify the data to be appended to the archive, then highlight the archive target, and finally, invoke the Update Archive dialog.

Selecting files and subdirectory trees to be appended to the archive is similar to selecting items for a Copy operations.
Please see Selecting Files for a review of file selection.

Select each item you want to add to the archive. The 'selected' item(s) will be indicated by underlining the item name.
Do Not 'select' the target archive itself.

When you invoke the Update Archive dialog, all 'selected' items will be copied to the FileMangler clipboard to be used in updating the target archive.

Note that if you have previously 'copied' data to the clipboard, and have not 'selected' any items in the active window, then the data already on the clipboard will be added to the target archive.

Indicate the Target Archive

After the items to be added to the archive have been 'selected' and/or have been placed on the FileMangler clipboard, then move the highlight to the archive name and invoke the Update Archive dialog.

Invoking the Update Archive Dialog

 ALT+SHIFT+A key

  • After selecting the files and subdirectories to be added to the archive, (see above), and while the name of the existing archive is highlighted (not 'selected'), then invoke the Update Archive dialog.
    • Press the ‘SHIFT+ALT+A’ command-key combination, OR
    • In the 'Util' menu, select the 'Archive' menu item.
  • The new data will be appended to the target archive.
  • Note that if the Update Archive dialog is invoked without first specifying one or more items to be added to the archive, then a warning message will be displayed, and the dialog will not be opened.
┌───────────────────┤ ALERT ALERT ├───────────────────┐ │ │ │ For archive operations, you must place source data │ │ on the clipboard, highlight the name of an existing │ │ archive file, or both. │ │ Please see documentation: "Working With Archives" │ │ │ OK └─────────────────────────────────────────────────────┘

Complex Data Specification

Because you have specified BOTH source data AND and an existing archive file, you will need to verify the type of operation you wish to perform, as shown below.

╔══════════════╣ Select an Operation ╠══════════════╗ You have specified an existing archive file, Backup_2016_02_29.tar and there are 14 source files on the clipboard. Please select an operation. ║ < ◆ > Append source data to the target archive ║ ║ (note: must be an uncompressed archive) ║ ║ < > Create a new archive file using source data ║ ║ < > Extract files from archive (ignore clipboard) ║ ║ < > Cancel the operation ║ ║ ║ OK ╚═════════════════════════════════════════════════════╝

The select-an-operation dialog allows selection of exactly one(1) operation from the list of Radiobuttons.

  • Append the specified source data to the specified target Archive file. The source data are unmodified by the operation.

    Note that this option is available ONLY if the target archive is an uncompressed archive.

  • Create a new Archive using the specified source data. You will be prompted for the name of the new archive to receive the source data, and the previously-specified archive name will be ignored. The source data are unmodified by the operation.
  • Extract data from the specified archive file. Any data currently on the clipboard will be ignored.

    The source archive will not be modified in any way.

    If there are existing target files in the target directory, the existing targets will be overwritten as the data are extracted from the archive.

  • Cancel the Operation
    Abort the pending operation and return to the main application interface. Neither the specified archive nor the specified source data will be modified in any way.

The Update Archive Dialog

┌────────────────┤ Update an Archive ├────────────────┐ Append the selected data to specified archive. │ Archive Name eyeToons_2016_April.tar │ │ Archive Files: 8 │ Archive Size : 707Kb │ Expanded Size: 693Kb │ │ │ Source Files: 14 │ Source Bytes: 462Kb │ │ │ │ │ UPDATE CANCEL └───────────────────────────────────────────────────────┘

The Update Archive dialog has the following features.

  • Archive Name
    Name of the (uncompressed) archive to be updated.
  • Archive Files
    Number of files currently contained in the archive.
  • Archive Size
    Size of the archive file on disk (in bytes).
  • Expanded Size
    Approximate disk space which would be required to expand the archive.
  • Source Files
    Number of source files to be added to the archive. This includes all selected files, selected subdirectories and the subdirectory contents.
  • Source Bytes
    Total size of source data (in bytes).
  • 'Update' Pushbutton
    Append the specified source data to the archive.
  • 'Cancel' Pushbutton
    Cancel the operation in progress. Neither the specified target archive nor the specified source data will be modified in any way.

Operation Summary and the Log File

After the archive has been updated, a summary of the operation is displayed.


┌────────────────┤ Operation Summary ├────────────────┐ Operation : Update Archive │ eyeToons_2016_April.tar │ │ Archive Source Data Previous files: 22 14 (8) │ bytes: 1.16Mb 462Kb (693Kb) │ Target: 1.17Mb (707Kb) │ Errors: 0 │ │ │ CLOSE VIEW LOG SAVE LOG └───────────────────────────────────────────────────────┘

The summary dialog has the following features:

  • The type of operation just completed.
  • The name of the target archive file.
  • Files:
    1. number files contained in updated archive
    2. number of source files
    3. number of files previously in archive
  • Bytes:
    1. size of all data contained in the archive
    2. size of source data
    3. size of data previously in archive
  • Target:
    1. size of the updated archive file (in bytes)
    2. previous size of the target archive
  • The number of errors encountered.
    Errors may be caused by any number of circumstances, such as insufficient access permission for the target archive, an attempt to archive a file of one of the 'special' types (character or block device files), or insufficient space on the target media.
  • 'VIEW LOG' Pushbutton
    If errors are reported, or if you are simply curious about the operation, you can view the operation log.
  • 'SAVE LOG' Pushbutton
    The log file is created as a temporary file which will be discarded when the dialog closes. If you would like to keep a copy of the log file, then choose 'SAVE LOG', and the log will be copied to the target directory using the same name as the archive, but with a '.log' extension.
    ARCHIVE : eyeToons_2016_April.tar
    LOG FILE: eyeToons_2016_April.tar.log
    
  • 'CLOSE' Pushbutton
    Close the summary dialog.



Favorite Directories List

 CTRL+O key

‘Favorite’ directories are those which you use most often.
The Favorite Directories List provides a shortcut method of navigation to those directories.


Favorites will typically be externally-mounted storage devices such as USB flash drives, SD cards or portable hard drives. An often-used directory on the local drive would also be a good candidate for the Favorites list.


An entry in the Favorites list is a full (absolute) path specification to the desired directory.
(Environment-variable substitution is supported.)
Some examples would be:

/run/media/sam/TravelDrive16GB
/home/sam/Downloads
${HOME}
~/Documents/LessonPlans

Screenshot of ‘Favorite Directories’ dialog

┌─────────────────────────┤ Favorite Directories ├─────────────────────────┐ /run/media/sam/SoftwareDesign /run/media/sam/TravelDrive32 /run/media/sam/Backup_600GiB_NTFS /run/media/sam/TEACHBACKUP /usr/include /usr/lib /home/sam/.local/share/Trash /home/sam/Apps/FileMangler
├──────────────────────────────────────────────────────────────────────────┤ │ Highlight the desired target directory, then select 'OK'. │ │ Select 'CANCEL' to remain in current directory. │ │ │ │ Note: To edit the Favorites list, go to the │ │ 'Util' menu and select 'Configure'. │ │ │ OK CANCEL └──────────────────────────────────────────────────────────────────────────┘

The features and controls of this dialog are as follows:

  • Dialog Title
  • A scrolling list of Favorite directory path specifications
  • ‘OK’ Pushbutton
    Make the highlighted directory path the new current-working-directory.
  • ‘CANCEL’ Pushbutton
    Close the dialog without making a selection.

To add items to the list, remove items from the list or to re-order the list items, please see Configuration.





Mounting Filesystems

 CTRL+Y key

** UNDER CONSTRUCTION - FILESYSTEM MOUNTING NOT FULLY IMPLEMENTED **



View Mode Selection

 ALT+W key

Switch between Single-window and Dual-window Modes.

  • When you switch from Single-window Mode to Dual-window Mode, the new window will open in the same directory as the existing window.

    Note that the terminal window must be at least the minimum width for Dual-window Mode; else, the request will fail.
    See Dual-window Mode, for details.

  • When you switch from Dual-window Mode to Single-window Mode, the inactive Directory Window will be closed, and the active window will be resized for Single-window Mode.

 CTRL+T key

Switch to Tree-view Mode. Allows for easy access to any directory in the filesystem’s directory tree.
See Tree-view Mode.

 CTRL+U key

Update the list of items in the active Directory Window.

  • If you believe that an external application or another user (or forces of evil?) may have changed some data in the currently-displayed directory or in the subdirectories it contains, then use this command to re-read and display the contents of the directory tree.
  • Note that any file selections you may have made in this view will be discarded.
  • If the clipboard currently contains data from within this view, the clipboard will also be cleared.

 ALT+CTRL+R key

When the terminal window is resized, the FileMangler application dialog is not automatically resized to fit. The reason for this is that resizing a text-mode window requires closing and re-opening the window. If the window were closed while an operation is in progress, then that operation would be terminated, often with unfortunate results.

For this reason, a signal that the terminal window has been resized will cause the display to be refreshed; however, the application dialog will not be resized to fit, allowing any operation in progress to be completed without interruption. To be clear, although the data displayed in the window may be distorted or corrupted when the terminal window is resized, the operation will be completed normally.

When the operation has been completed, the application dialog may be resized to fit the window using the ALT+CTRL+R command.

This command should not be confused with the “Update File List” (CTRL+U) command (see previous item).

Please see View Menu ('Resize Dialog' item) for accessing this command through the menu system.

 ALT+’ key

Set the current working directory (CWD) of the alternate (inactive) Directory Window to the CWD of the active Directory Window.

This command is recognized only when operating in Dual-window Mode.

To avoid confusion, please note that this command-key sequence is the ALT key combined with the single-quote (apostrophe) key.

 ALT+SHIFT+’ key

Synchronize navigation beween windows in Dual-window Mode.

It is often useful to visually compare the contents of one directory with another or to move up and down through two directory trees in a synchronous way. For instance, use this command when visually inspecting two copies of the same data that are located in different directories.

Use the ALT+SHIFT+' command to establish a navigation synch-lock between the directory windows. An active synch-lock is indicated by an "SL" being visible between the path-display controls of the two windows.

┌───────┤ FileMangler - v:0.0.35 (c)2005-2016 [Press F2 for Menu] ├─────────────────────────────────────────────────────┐ │Status: Ctrl+Q=Quit, Shift+F1=Help, F2=Menu ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤ /home/sam/SoftwareDesign/1_TestData/Btest SL /home/sam/SoftwareDesign/1_TestData/Btestbk ├────────────────────────────────────────────────────────────┐┌────────────────────────────────────────────────────────────┤
4,096 07-Oct-2017 15:34:31 Bonobo ││ 4,096 11-May-2013 19:39:12 Bonobo 4,096 07-Oct-2017 15:37:00 Chimichanga ││ 4,096 11-May-2013 21:35:08 Chimichanga 4,096 07-Oct-2017 15:34:31 Redneck ││ 4,096 10-May-2013 22:07:55 Redneck 14,720 02-May-2013 00:39:00 Somefile-01.a ││ 14,720 02-May-2013 00:39:00 Somefile-01.a 11,188 02-May-2013 00:39:00 Somefile-02.a ││ 11,188 02-May-2013 00:39:00 Somefile-02.a 25,728 02-May-2013 00:39:00 Somefile-03.a ││ 25,728 02-May-2013 00:39:00 Somefile-03.a 25,728 02-May-2013 00:39:00 Somefile-03.xx ││ 25,728 02-May-2013 00:39:00 Somefile-03.xx 25,728 02-May-2013 00:39:00 Somefile-03.yy ││ 25,728 02-May-2013 00:39:00 Somefile-03.yy 25,728 02-May-2013 00:39:00 Somefile-03.zz ││ 25,728 02-May-2013 00:39:00 Somefile-03.zz 14,612 02-May-2013 00:39:00 Somefile-04.a ││ 14,612 02-May-2013 00:39:00 Somefile-04.a 27,464 02-May-2013 00:39:00 Somefile-05.a ││ 27,464 02-May-2013 00:39:00 Somefile-05.a 10,192 02-May-2013 00:39:00 Somefile-06.a ││ 10,192 02-May-2013 00:39:00 Somefile-06.a 14,720 02-May-2013 00:39:00 Somefile.abc ││ 14,720 02-May-2013 00:39:00 Somefile.abc ││ ││ ││ ├────────────────────────────────────────────────────────────┘└────────────────────────────────────────────────────────────┤ 13 files 208,096 bytes 13 files 208,096 bytes └──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

(The screen capture has been modified to fit this document.)

When the synch-lock is active, then pressing one of the navigation keys in the active directory window will cause a copy of that navigation key to be sent to the inactive directory window.

Navigation keys recognized by the synch-lock:

ENTER key (when highlight is on a directory name):
              Move to the specified subdirectory
BACKSPACE key or ALT+UpArrow key:
              Move to parent directory.
UpArrow, DownArrow, PageUp, PageDown, Home, End:
              Scroll through the file list.

Issue the ALT+SHIFT+' command again to disable the synch-lock.
The synch-lock is also disabled when any copy/cut/paste/rename or similar command which modifies the displayed data is issued.

This command is recognized only when operating in Dual-window Mode.

To avoid confusion, please note that this command-key sequence is the ALT key combined with the double-quote key.




Exit the Application

 CTRL+Q key

Exit to command line, returning to the directory from which the application was invoked.


 ALT+Q key

Exit to command line at the directory currently displayed in the Directory Window (CWD).

See also the important note about invocation through the memory-resident function. See invocation mechanism.




Other Commands

This chapter contains descriptions of miscellaneous special-purpose commands not covered in previous chapters.

Command Keys in this chapter

 Command Key   Description  
 SHIFT+F01 Invoke Online Help
 CTRL+K List of Command Keys
 ALT+SHIFT+C Compare Files
 ALT+SHIFT+Z Go To Command Shell
 ALT+SHIFT+; Manage FileMangler Clipboard
 ALT+SHIFT+[ Display User Info
 ALT+SHIFT+] Display Filesystem Info


Invoke Online Help

 SHIFT+F01 key
 F01 key

Display the ‘info’ (Texinfo) documentation for the FileMangler application.

Because the 'F01' key is probably captured by the terminal window, use the 'SHIFT+F01' key to invoke Help.

Help may also be invoked through the Help Menu.
See Help Menu.

Invoking Help is done in the following sequence:

  • The application temporarily goes to sleep.
  • Control is returned to the command line where the ‘info’ reader is invoked to read the documentation file.
  • When you exit the ‘info’ reader (‘q’ command), the application wakes up and resumes control.

Although accessing Help via the ‘info’ reader is convenient, if you prefer, you may also view the documentation as HTML. The HTML documentation is generally much more readable, with better formatting and full-color diagrams.

  • Load the file 'filemangler.html' into your favorite browser.
  • For proper formatting, be sure that 'infodoc-styles.css' is in the same directory as the HTML file.
  • Both files should be located in the FileMangler installation directory. (See Installation, for more information.)


List of Command Keys

 CTRL+K key

** UNDER CONSTRUCTION - LIST CURRENT KEY BINDINGS **
Display a list of the current command-key bindings.



Compare Files

 ALT+SHIFT+C key

Compare the contents of two(2) files for differences in the data according to selected criteria.

A comparison of the files’ timestamps, file size, file type, access permissions and other attributes are also reported.

Content comparison is based on the 'diff' utility which is assumed to be present on all linux/UNIX systems.


┌──────────────────┤ Compare Files ├──────────────────┐ │ File A: simple03.c │ File B: simple04.c ├───────────────────────────────────────────────────────┤ │ [ ] Brief (report identical or different) │ │ [ ] Process binary files as text │ │ [◆] Two-column output (deselect for single-column) │ │ [◆] print common lines in both columns │ │ [ ] print common lines on left only │ │ [ ] print differences only │ 3± Number of context lines for single-column output │ │ │ COMPARE CLOSE SAVE LOG └───────────────────────────────────────────────────────┘

The features and controls of this dialog are as follows:

  • Dialog Title
  • ‘FileA’ and ‘FileB’ The names of the two files to be compared.

    Note that each file must be a ‘Regular’ file or a symbolic link which points to a ‘Regular’ file. Comparison of directories or of the ‘special’ filetypes are not supported.

  • ‘Brief’ radio button

    The comparison operation will report only whether the contents of the files are identical or different. Details of any differences between the files will not be reported.

    Technical Note: For very large source files (greater than 10 megabytes) the Brief option is automatically applied to avoid creating unmanageably-large temporary files.

  • ‘Process binary files as text’ radio button

    It is often useful to compare formatted documents such as word-processing files or PDF files which may contain NULL characters, CR (carriage-return) characters or other non-printing data which 'diff' will interpret as binary data by default.

    Byte-by-byte comparison of binary files is generally not useful, because binary data is intrinsically not line oriented, and the output will probably be unreadable.

    'diff' determines whether a file contains binary data through a scanning algorithm which is system dependent. If it is determined that a source file contains binary data, then the ‘Brief’ output option is automatically applied to avoid sending binary data to the terminal window as if it were text.

    To override this default behavior, select this radio button to force processing of binary data as if it were text. (See technical note below.)

  • ‘Two-column output’ radio button

    Differences in the file may be reported in either two-column format (default) or in single-column format (de-select this radio button).

    Either format works well if there are only a few differences to be reported. However, in our opinion, the two-column format is both easier to read and more flexible for output customization. (see examples below)

    For two-column output only, three(3) additional formatting options are available.

    • ‘Print common lines in both columns’
    • ‘Print common lines on left only’
    • ‘Print differences only’

      ‘Common lines’ are those lines of text which are the same for both files. Displaying common lines is often useful for placing differences in context.

      ‘Print common lines in both columns’ duplicates the common lines in both columns for easy visual scanning of the output.

      ‘Print common lines on left only’ reduces visual clutter by printing the common lines only once. This is helpful for more easily identifying the differences, or when performing searches on the data.

      ‘Print differences only’ provides minimal output which displays only the lines which differ between the files.

    To customize output of common lines for single-column output, see the ‘context-lines’ control, below.

  • ‘Number of context lines for differing groups’ spinner

    For single-column output only:
    Adjust the number of common lines to be displayed above and below the differences in the files.

  • ‘COMPARE’ pushbutton

    Compare the files based on the criteria you have selected.

    The output is written to a temporary log file which is then displayed using the 'less' utility. When finished viewing the results, press ‘q’ (quit) to return to FileMangler.

    Multiple comparisons may be performed on the same pair of files. The log file for each comparison will overwrite the previous temporary log. (But see ‘Save Log’ below.)

  • ‘CLOSE’ pushbutton

    Close the dialog.

  • ‘SAVE LOG’ pushbutton

    Save a copy of the comparison log file to the current working directory (CWD). (The log is a plain text file.)

    The name of the log file will be the same as that of the first compared file, but with ".log" appended.

Output Examples

Report ‘Identical’ or ‘Different’ Only
FileA Path : /home/sam/SoftwareDesign/1_TestData/Diff/simple01.txt FileB Path : /home/sam/SoftwareDesign/1_TestData/Diff/simple02.txt TYPE SIZE USR GRP OTH INODE MODIFIED FileA Stats: REG 128 rw- rw- r-- 524418 30 May 2016 20:24:24 FileB Stats: REG 128 rw- rw- r-- 524408 30 May 2016 20:24:40 -------------------------------------------------------------------- Files 'simple01.txt' and 'simple02.txt' differ.

Two-column, Full Output
FileA Path : /home/sam/SoftwareDesign/1_TestData/Diff/simple03.c FileB Path : /home/sam/SoftwareDesign/1_TestData/Diff/simple04.c TYPE SIZE USR GRP OTH INODE MODIFIED FileA Stats: REG 740 rw- rw- r-- 524424 02 Jun 2016 01:54:22 FileB Stats: REG 833 rw- rw- r-- 524436 02 Jun 2016 02:25:28 -------------------------------------------------------------------- Files 'simple03.c' and 'simple04.c' differ. FileA: simple03.c FileB: simple04.c ----------------------------------- ----------------------------------- //********************************* //********************************* //** How To Catch a Tunafish //** How To Catch a Tunafish //********************************* //********************************* int main ( int argc, char* argv[], int main ( int argc, char* argv[], { { bool tunacanFly = false, bool tunacanFly = false, bigNet = false ; | bigNet = false, | toGo = false ; if ( argc > 2 ) | if ( argc > 3 ) { { in64_t myCatch ; // grams in64_t myCatch ; // grams if ( strncmp ( argv[1], "yes" if ( strncmp ( argv[1], "yes" tunacanFly = true ; tunacanFly = true ; if ( strncmp ( argv[2], "true if ( strncmp ( argv[2], "true bigNet = true ; bigNet = true ; > if ( strncmp ( argv[3], "true > toGo = true ; if ( tunacanFly ) if ( tunacanFly ) myCatch = Use_ButterflyNet myCatch = Use_ButterflyNet else else myCatch = Use_GoldenRetrie myCatch = Use_GoldenRetrie Have_Lunch ( myCatch ); | Have_Lunch ( myCatch, toGo ); } } exit 0 ; exit 0 ; } }

Two-column, Differences Only
FileA Path : /home/sam/SoftwareDesign/1_TestData/Diff/simple01.txt FileB Path : /home/sam/SoftwareDesign/1_TestData/Diff/simple02.txt TYPE SIZE USR GRP OTH INODE MODIFIED FileA Stats: REG 128 rw- rw- r-- 524418 30 May 2016 20:24:24 FileB Stats: REG 128 rw- rw- r-- 524408 30 May 2016 20:24:40 -------------------------------------------------------------------- Files 'simple01.txt' and 'simple02.txt' differ. FileA: simple01.txt FileB: simple02.txt ----------------------------------- ----------------------------------- This is a different line. | This is a DIFFERENT line.

Single-column, Two Context Lines
FileA Path : /home/sam/SoftwareDesign/1_TestData/Diff/simple01.txt FileB Path : /home/sam/SoftwareDesign/1_TestData/Diff/simple02.txt TYPE SIZE USR GRP OTH INODE MODIFIED FileA Stats: REG 128 rw- rw- r-- 524418 30 May 2016 20:24:24 FileB Stats: REG 128 rw- rw- r-- 524408 30 May 2016 20:24:40 -------------------------------------------------------------------- Files 'simple01.txt' and 'simple02.txt' differ. *** simple01.txt --- simple02.txt *************** *** 2,7 **** This is line 02. This is line 03. ! This is a different line. This is line 05. This is line 06. --- 2,7 ---- This is line 02. This is line 03. ! This is a DIFFERENT line. This is line 05. This is line 06.

Notes On File Comparisons

  • Interpreting the Output
    For two-column output, three difference indicators are used:
       |   indicates that corresponding lines are different
       >   indicates that file in right column contains 
           a line that file in left column does not
       <   indicates that file in left column contains 
           a line that file in right column does not
    
    For single-column output, a legend above the detail data 
    indicates the file to which the output belong:
      ***  indicates FileA data
      ---  indicates FileB data
    Two difference indicators are used:
       !   indicates that corresponding lines are different
       +   indicates that specified file contains a line
           that the other file does not
    

    In this document only, the indicators described are highlighted for visual clarity.

    Please see the 'diff' utility documentation for additional information on interpreting the output.

  • Output Quality:

    The 'diff' utility truncates its output to fit the width of the terminal window. Therefore setting the width of the terminal window to at least 132 columns will produce more readable output.

    'diff' also arbitrarily sets the maximum width of output to 130 columns by default; however, this seems unnecessarily restrictive. To achieve optimal output formatting, we therefore dynamically set the maximum number of output columns to the actual width of the terminal window.

    'diff' uses TAB characters to align its output. While this displays correctly when sent directly to the standard output stream (‘stdout’), misalignment can sometimes appear when ‘stdout’ is captured to a file.

  • Binary Comparisons:

    Comparing files that contain binary (non-text) data is useful primarily for determining whether the files are the same or different.

    Byte-by-byte comparison of binary data is usually not informative, AND the comparison data are huge and unreadable. FileMangler’s compare does not prevent this useless comparison; however, it is strongly discouraged.

    To prevent complete output disaster, FileMangler’s implementation of binary output converts non-printing characters (except TAB and NEWLINE) to the full-stop character: ('.').

    To perform a meaningful bytewise comparison of binary-data files we recommend running each file through the 'hexdump' utility and redirecting the output to separate files which will contain the ASCII-HEX equivalent of the binary source data. THEN perform the comparison on those text files. (It still won’t be useful, but you’ll feel like an Alpha-nerd.)

    The 'cmp' utility may also be somewhat useful if you are willing to put up with octal output.

  • Missing ‘diff’:

    In the unlikely event that the 'diff' utility is not installed on the system, then the file comparison will fail.



Go To Command Shell

 ALT+SHIFT+Z key

Temporarily return to the command line.

The application will be placed in hibernation. That is, all application resources will be retained, but all active execution threads will be put to sleep.

The command-line prompt will be displayed along with a reminder to return to the application when finished with command-line activity.

*********************
    Command Shell    
Type 'exit' to return
*********************

To return to the application, type the command:
exit (ENTER).


Reminder: If you forget to return to the application, then when you close the terminal window or tab, you will get a message that there is still an active process in the window.



Manage FileMangler Clipboard

View the contents of the application’s clipboard.

 ALT+SHIFT+; key

View the contents of the application’s clipboard.

It is sometimes useful to view the contents of the application clipboard i.e. the files and directory trees that will be affected by the next ’Paste’, ’Paste Special’ or similar command.

To avoid confusion, please note that this command-key sequence
is the ALT key + SHIFT key combined with the semicolon key, or to think of it another way: the ALT key combined with the colon key.

Please see the section see Copying and Moving Files, for more information about how the application clipboard is used. A technical description of the application clipboard may also be found at See tech notes.


Navigating in the Browse Clipboard dialog

┌──────┤ FileMangler - v:0.0.34 (c)2005-2016 [Press F2 for Menu] ├──────┐ │Status: Ctrl+Q=Quit, Shift+F1=Help, F2=Menu ├──────────────────────────────────────────────────────────────────────────┤ /home/sam/SoftwareDesign/X_Server ├──────────────────────────┤ Browse Clipboard ├──────────────────────────┤
Source Dir: /home/sam/SoftwareDesign/X_Server Files on Clipboard: 27 Byte Total, All Files: 908,934 Clipboard Storage Bytes Allocated: 6,208 Pending Operation: Copy Detailed View Close Clear Clipboard TYPE FILENAME (Tab to list, then scroll keys to view) ├─────────────────────────┤ Files On Clipboard ├─────────────────────────┤
DIR TestCode (15 files) REG X-Clipboard Info.odt REG XCB X-protocol C-language bindings.odt REG Xclipboard Utility.odt REG Xlib Display (cut buffers).odt REG Xlib Display (events).odt REG Xlib Display (selections).odt REG Xlib Display (window function).odt REG clipboard-extensions-latest - freedesktop.org.txt REG clipboards-latest - freedesktop.org.txt REG archivelist.txt REG xclipboard-1.1.3.tar.bz2 └──────────────────────────────────────────────────────────────────────────┘

The dialog features and controls within this view are described below.

  • Application title
  • A simple help message
  • Path of directory where source data are located
  • Dialog title line
  • ’Source Dir’
    Source directory path where clipboard files are located.
  • ’Files on Clipboard’
    Number of files on the clipboard, including any directory contents.
  • ’Byte Total, All Files’
    Combined size of all files on clipboard (in bytes)
  • ’Clipboard Storage Bytes Allocated’
    Temporary memory allocation used internally by the clipboard.
    This is really only useful during development, but we find it comforting.
  • ’Pending Operation’
    The operation which caused the files to be placed on the clipboard.
    This is usually either ’Copy’ or ’Cut’.
  • ’Detailed View’ Pushbutton
    Toggles between ’Summary View’ shown above, and ’Detailed View’ which displays the names of files contained in any listed directories.
  • ’Close’ Pushbutton
    Close the Browse Clipboard dialog, or if currently in ’Detailed View’, then return to ’Summary View’.
  • ’Clear Clipboard’ Pushbutton
    Clear all items from the clipboard. Any pending operation will be cancelled.
  • ’Files on Clipboard’
    This is a list of all items currently on the clipboard, either in ’Summary View’ or ’Detailed View’.


Display User Info

 ALT+SHIFT+[ key

This command opens a dialog which displays various information about your user account. This includes your User ID, account name, group information, your shell program and your home directory.

If you invoked the application as the Superuser, then the User Info dialog will display user information for the ‘root’ user.

FileMangler uses the C library functions 'getpwuid', 'getgrgid', and 'getgroups' to decode the user record stored at '/etc/passwd'.

Note that passwords and other sensitive user data ARE NOT decoded or displayed.

Example User Info Dialog

┌──────────────────────────┤ USER INFORMATION ├──────────────────────────┐ │ User ID: 1000 Member of Additional Groups: │ │ User Acct: sam 10 │ User Name: The Software Samuri 1000 │ Group ID: 1000 │ Group Name: sam │ Shell Prog: /bin/bash │ Home Dir: /home/sam │ │ │ │ OK └────────────────────────────────────────────────────────────────────────┘

The User Info dialog may also be invoked through the View Menu.
See View Menu.



Display Filesystem Info

 ALT+SHIFT+] key

A ‘filesystems’ is a physical storage device or a portion of the device that has a unique storage area defined and formatted in a specific way.

Linux/UNIX systems typically include several filesystems, some of which are system local storage areas such as the 'home' partition, the 'boot' partition or the swap disc. Others are external filesystems such as optical (DVD/CDROM) drives, USB storage devices or network drives.

Each of these filesystems incorporates several identifying characteristics. Perhaps the most important of these from a user’s point of view are the filesystem’s label (name), it’s storage capacity and how much freespace is available. Much more information is available for those who are curious about the structure of filesystems.

  • Filesystem Type
    Typical filesystem formats are EXT3, EXT4, VFAT, NTFS (fuseblk), and XFS among others.
  • Filesystem ID
    Every filesystem has a unique identification number, similar to a serial number.
  • Total, Free and Available Blocks
    Most storage devices are ‘block’ devices, that is storage space is allocated and read in discrete blocks of data bytes. For instance, a file that is only 15 bytes in size would still require an entire data block on the storage device.
  • Used and Free Bytes
    These values are calculated from the number of data blocks and the size of those blocks.
  • Total and Available INodes
    An ‘inode’ is a number which uniquely identifies each file stored on the filesystem.
  • Block and FBlock Size
    This is the number of bytes in each filesystem data block. A smaller block size will result in less wasted space (especially when there are many very small files), while a larger block will (theoretically) provide better performance for read/write operations.

    For instance, EXT3, EXT4 filesystems usually have a block size of 4 KiB because in Linux/UNIX "everything is a file," and the files tend to be rather small. In contrast, the Windows(tm) VFAT filesystem has a block size of 32 KiB which is oriented toward larger files. DVD discs on the other hand have a block size of 2 KiB for maximum storage efficiency even though the file sizes are typically half a gigabyte or more.

    Some filesystems, notably XFS, have a variable block size that can be adjusted for the expected size of the files it will contain. In this case, the reported value specifies the minimum block size.

  • Maximum Bytes for Filenames
    Each filesystem type specifies the maximum number of bytes that can be used in a filename. Most Linux-oriented filesystems specify a 255-byte maximum for filenames.

    Note also that a filesystem may limit the characters which may be used in a filename, and the operating system may limit the allowed characters even further.

  • SELinux Security context
    Security contexts are beyond the scope of this discussion, but in general Security Enhanced Linux is a set of tools used by the system kernel to provide "mandatory access control" for the data on the filesystem to prevent unauthorized access.

Example Filesystem Info Dialog

┌─────────────┤ File System Information ├─────────────┐ │ The file system which contains the files in this view │ │ has the following characteristics: │ │ File System Type: EF53 - ext4 │ File System ID: 62399710D41085CF │ │ │ Total Blocks: 70,522,296 Total Inodes17,924,096 │ Free Blocks: 62,793,732 Avail Inodes17,905,792 │ Avail Blocks: 59,205,636 Block Size 4,096 │ Used Bytes: 31.6562G FBlock Size 4,096 │ Free Bytes: 242.506G Max Filename 255 │ SELinux Security context: │ unconfined_u:object_r:user_home_t:s0 │ │ CLOSE └───────────────────────────────────────────────────────┘

The Filesystem Info dialog may also be invoked through the View Menu.
See View Menu.






Next: , Previous: , Up: Top   [Contents][Index]

Menu System Interface

The FileMangler menu interface is implemented like the menus in any GUI application. A row of menus is displayed at the top of the application window, and all application functionality is available through the menu system. Most functionality is also available through the Command Key Interface (see Command Interface).



Accessing the Menu System

 F02 key
 ALT+SHIFT+M key
  • To preserve working screen space, the Menu Bar, (that is, the row of integrated menu names) shares space with the application’s title (top line of terminal window), and by default, is initially hidden.
    To make the Menu Bar visible:
    • Press the ‘F2’ key.
      The Menu Bar will become visible and active. Use the TAB key or RightArrow key to highlight the desired menu and press ENTER (RET).
    • Press the ‘ALT+SHIFT+M’ key combination.
      If the GUI mavens have snarfed the ‘F2’ key for ‘reheat-virtual-coffee’ or something equally useful, making it unavailable to console applications, this command provides the same access as ‘F2’.
    • If the mouse interface has been enabled, the Menu Bar may be accessed by clicking anywhere in the application’s title line.
      See Mouse Support, for more information on the mouse interface.
    • If desired, the Menu Bar can be configured to be visible at all times. The Menu Bar is still activated in the ways described. The only difference is that the Menu Bar is visible even when not in use.
      See Configuration, for additional information.
  • Traditionally, pull-down menus are accessed through an ‘ALT+n’ key combination, where 'n' represents a character (usually the first character) in the menu’s name.
  • This is also true of FileMangler’s Menu Bar. The Menu Bar may be opened to a specific menu by pressing the corresponding key combination.
    ALT+F  or  ALT+SHIFT+F    'File' menu
    ALT+E  or  ALT+SHIFT+E    'Edit' menu
    ALT+V  or  ALT+SHIFT+V    'View' menu
    ALT+U  or  ALT+SHIFT+U    'Util' menu
    ALT+H  or  ALT+SHIFT+H    'Help' menu
    

    Note, however, that some or all of the ‘ALT+n’ key combinations may have been captured by the terminal-emulator window itself, meaning that any application running in the terminal window will never see them.
    The GNOME terminal’s menu, for instance, looks like this:

    File Edit View Search Terminal Tabs Help

    and thus, it captures the Alt+F, etc. key combinations UNLESS you configure the GNOME terminal to disable its menu system OR disable the menu system shortcut keys. Many users will not want to do this, so alternate command-key combinations 'ALT+SHIFT+n' are provided.


Here is a screen capture of the application title (Menu Bar inactive):

┌───────┤ FileMangler - v:0.0.34 (c)2005-2016 [Press F2 for Menu] ├───────┐

and here is the same space with the Menu Bar active:

┌───────┤ File Edit View Util Help ├───────┐

If specified by the invoking command, a menu associated with one of these Menu Bar items will also be expanded. The following chapters discuss the individual menus and their contents.

Certain context menus, the ’sort-files-by’ context menu for instance, are accessed through CTRL+n command key combinations. This is also discussed in the following chapters.





Menu Hotkeys

Opening a menu on the Menu Bar is explained in the previous chapter.
See Accessing the Menu System.

Within an open menu, an item may be selected by scrolling to that item and pressing the ENTER(RET) key; however, it is often more convenient to select the menu item through its associated ’hotkey’. A ’hotkey’ is a keyboard shortcut which allows quick selection of a menu item.

Not all menu items have associated hotkeys, but if a hotkey is defined for a particular menu item, then one character of the item will be underlined, which indicates the hotkey. Hotkeys ARE NOT case sensitive.

If a menu item ’Polish the Apple’ is displayed, and the ’A’ character in ’Apple’ is underlined, then pressing either the ’A’ or ’a’ key (or the CTRL+A key) on your keyboard will select that menu item.

In the following example, the hotkeys for the menu items are 'A', 'O' and 'k', respectively.

┌──────────────────┐ │ Polish the Apple │ │ Peel the Orange │ │ Bake the Potato │ └──────────────────┘

As a more realistic example, open the FileMangler application and enter the following key sequences (without quote marks):

       'ALT+SHIFT+V'     (open the ’View’ Menu)
           then
       'u'               (select the ’User Info’ menu item)

The dialog containing information about your user account will be displayed.

Please see the following chapters for detailed information about the individual application menus.




File Menu

 ALT+SHIFT+F key
 ALT+F key

The File Menu provides file management operations and miscellaneous application-level functionality.

┌───────┤ File Edit View Util Help ├─────────┐ │Status: E┌────────────────┐ exits menu--ESC exits menu--ESC exits menu ├──────────│File Commands >│──────────────────────────────────────────────────┤ /home/samSort Options c+SleMangler ├──────────│Favorites... c+O│──────────────────────────────────────────────────┤ │ 4,096│View File >│44:25 1_TestData │ 4,096Find Files...c+F00:53 Archive 4,096Mount... c+Y02:14 Texinfo 4,096Refresh c+U18:19 install 1,024Set Alt Cwd a+'31:50 Backup_Def.txt 144,048Cmd Shell as+Z21:32 FMgr.cpp 84,048Exit c+Q (a+Q)42:21 FMgr.hpp 78,944└────────────────┘30:21 FMgr.o 11,112 26-Jan-2017 07:44:55 FMgrDispData.hpp


  • File Commands

    The ‘File Commands’ menu item opens a sub-menu containing file-management options as listed below.

┌──────────────────┐ Select File spc │Select All c+A│ │Trash Files c+DEL│ │Copy Files c+C│ │Cut Files c+X│ Paste Files c+V│ │PasteSpecial a+INS│ Delete Files s+DEL│ Rename Files c+R│ Touch Files c+D│ Write Protect c+W│ │Write Enable c+E│ New Directory c+N│ └──────────────────┘
  • Select File (SPACE key)

    Select or de-select the highlighted file.
    Please see Selecting Files for details.

  • Select All (CTRL+A)

    Select or de-select all files and directories in the window.
    Please see Selecting Files for details.

  • Trash Files (CTRL+DELETE)

    Send selected file(s) to the Trashcan.
    Please see Move Files to Trashcan for details.

  • Copy Files (CTRL+C)

    Copy the selected files to the clipboard.
    Please see Copying and Moving Files for details.

  • Cut Files (CTRL+X)

    Cut (move) the selected files to the clipboard.
    Please see Copying and Moving Files for details.

  • Paste Files (CTRL+V)

    Paste (insert) the files on the clipboard into the currently-displayed directory.
    Please see Copying and Moving Files for details.

  • Paste Special (ALT+INSERT)

    Paste (insert) the files on the clipboard into the currently-displayed directory using one of the “special” operations.
    Please see Copying and Moving Files for details.

  • Delete Files (SHIFT+DEL)

    Bypass the Trashcan and permanently delete the selected files.
    Please see Delete Files Permanently for details.

  • Rename Files (CTRL+R)

    Rename the selected files, either individually or in batch mode.
    Please see Renaming Files for details.

  • Touch Files (CTRL+D)

    Set the timestamp on each selected file.
    Please see Changing the Timestamp for details.

  • Write Protect (CTRL+W)

    Set the write-protection bit for the selected files.
    Please see Changing File Attributes for details.

  • Write Enable (CTRL+E)

    Clear the write-protection bit for the selected files.
    Please see Changing File Attributes for details.

  • New Directory (CTRL+N)

    Create a new subdirectory in the currently-displayed directory.
    Please see Create a New Directory for details.


  • Sort Options (CTRL+S)

    The ‘Sort Options’ menu item opens a dialog from which to select the file sorting criteria, as well as a switch to show or hide “hidden” files.

    Please see Sort Options dialog for a description of this dialog.

    The dialog contains the same sorting options as the SortBy' context menu (see SortBy Context Menu), although the options are presented somewhat differently.

    (Note that the hidden-files toggle may also be access via the 'ALT+I' see Hidden Files Toggle command key.)

  • Favorites (CTRL+O)

    The “Favorites” menu item open the “Favorite Directories” dialog which contains a list of often-visited directories.

    Please see Favorite Directories for a description of this dialog.

  • View File (ENTER)

    This item provides an alternate way of accessing the 'ViewFile' context menu. This menu provides access to the highlighted file’s contents, its statistical information and more.

    Please see Context Menus for a detailed description of the functionality available through the 'ViewFile' context menu.

  • Find Files (CTRL+F)

    This menu item open a dialog from which to search the directory tree, searching for the file or files whose name contains the specified substring.

    Please see Find Files in Directory Tree for more information.

  • Mount (CTRL+Y)

    Mount or unmount an external filesystem.
    This menu item opens a dialog which contains a list of mountpoints for external devices such as USB drives, external hard drives, CD ROM drives, etc.

    Please see Mounting Filesystems for more information.

  • Refresh (CTRL+U)

    Update the list of displayed files.

    For the active file-display window, reread the contents of the directory. This will reveal any changes made to the directory since it was last read.

    This is useful when another application is currently adding, deleting or modifying files in the target directory and you need to see what changes the external application has made.

    Please see View Mode Selection for further details.

  • Set Alt Cwd (ALT+')

    In Dual-window Mode only, change the working directory of the inactive window to match the working directory of the active window.

    This command has no effect when FileMangler is in Single-window Mode.

    Please see View Mode Selection for further details.

  • Cmd Shell (ALT+SHIFT+Z)

    Put the application into hibernation mode to gain temporary access the terminal window’s command interpreter.

    Please see Go To Command Shell for further details.

  • Exit (CTRL+Q) or (ALT+Q)

    Exit the application and return to the terminal window command prompt.

    Please see Exit the Application for further details.





Edit Menu

 ALT+SHIFT+E key
 ALT+E key

The Edit Menu primarily provides Copy, Cut and Paste functionality.

This functionality is also accessible through the File Commands sub-menu in the File Menu, and perhaps more importantly, through the Copy/Cut/Paste shortcut keys. However, this menu may be most helpful for beginners and non-technical users who have not yet learned the shortcuts.

┌───────┤ File Edit View Util Help ├─────────┐ │Status: ESC exits me┌──────────────────┐ESC exits menu--ESC exits menu ├─────────────────────│Copy c+C│─────────────────────────────────────┤ /home/sam/SoftwareDeCut c+X ├─────────────────────│Paste c+V│─────────────────────────────────────┤ │ 4,096 23-Nov-20│PasteSpecial a+INS│ata │ 4,096 26-Jan-20Select All c+A 4,096 26-Nov-20Preferences... 4,096 21-Nov-20└──────────────────┘ 1,024 21-Jun-2017 22:31:50 Backup_Def.txt 144,048 08-Nov-2017 08:21:32 FMgr.cpp 84,048 13-Nov-2017 06:42:21 FMgr.hpp 78,944 26-Nov-2017 07:30:21 FMgr.o 11,112 26-Jan-2017 07:44:55 FMgrDispData.hpp


  • Copy (CTRL+C)

    Copy the selected files to the clipboard.
    Please see Copying and Moving Files for details.

  • Cut (CTRL+X)

    Cut (move) the selected files to the clipboard.
    Please see Copying and Moving Files for details.

  • Paste (CTRL+V)

    Paste (insert) the files on the clipboard into the currently-displayed directory.
    Please see Copying and Moving Files for details.

  • Paste Special (ALT+INS)

    Paste (insert) the files on the clipboard into the currently-displayed directory using one of the “special” operations.
    Please see Copying and Moving Files for details.

  • Select All (CTRL+A)

    Select or de-select all files and directories in the window.
    Please see Selecting Files for details.

  • Preferences

    Run the FileMangler configuration utility to modify the application’s default settings.

    This menu option is included as a convenience for those who are accustomed to finding an application’s configuration options under “Edit - Preferences”.
    This option is also accessible through the Configure item in the Util Menu.

    Please see Configuration for full details.





View Menu

 ALT+SHIFT+V key
 ALT+V key

The View Menu offers options for changing the way data are presented, as well as invoking various special-purpose information dialog windows.

┌───────┤ File Edit View Util Help ├─────────┐ │Status: ESC exits menu--ESC exi┌────────────────┐ menu--ESC exits menu ├────────────────────────────────│Dual Window a+W│────────────────────────────┤ /home/sam/SoftwareDesign/FileMaSingle Win a+W ├────────────────────────────────│Tree view c+T│────────────────────────────┤ │ 4,096 23-Nov-2017 14:44:2│Resize Dlg ac+R│ │ 4,096 26-Jan-2017 12:00:5Menu Bar Visible 4,096 26-Nov-2017 07:20:1Toggle SynchLock 4,096 21-Nov-2017 12:18:1User Info as+[ 1,024 21-Jun-2017 22:31:5Clipboard Info 144,048 08-Nov-2017 08:21:3File System Info 84,048 13-Nov-2017 06:42:2HiddenFiles a+I 78,944 26-Nov-2017 07:30:2└────────────────┘ 11,112 26-Jan-2017 07:44:55 FMgrDispData.hpp


  • Dual Window Mode (ALT+W)

    Re-open the application in Dual-window Mode.

    If the application is currently in Single-window Mode, switch to Dual-window Mode.

    If already in Dual-window Mode, close and re-open the dialog. This is useful if the size of the terminal window has been changed because it allows the application to adjust the size of the dialog to fit the terminal window.

    The ALT+W command toggles between Single-window and Dual-window Modes. Please see View Mode Selection for more information.

  • Single Window Mode (ALT+W)

    Re-open the application in Single-window Mode.

    If the application is currently in Dual-window Mode, switch to Single-window Mode.

    If already in Single-window Mode, this simply closes and re-open the dialog.

    The ALT+W command toggles between Single-window and Dual-window Modes. Please see View Mode Selection for more information.

  • Tree View (CTRL+T)

    Switch to ‘Tree View’ mode.

    In addition to Single-window and Dual-window display modes, the Tree-view Mode is available as an alternate way to view the filename list.

    The filesystem is displayed as a hierarchical tree with the base being the current directory.

    Please see Tree-view Mode for details.

  • Resize Dialog (ALT+CTRL+R)

    If the terminal window has been resized, resize the FileMangler application window to fit the terminal window.

    Please see Resize Application Dialog for more information.

  • Menu Bar Visible

    Toggle the Menu Bar lock.

    The Menu Bar at the top of the application window is initially invisible, and by default becomes visible only when the menu system is activated.
    See Accessing the Menu System, to review menu activation.

    Select this option to lock the Menu Bar in the visible state. Select this option again to release the lock and return the Menu Bar to the visible-when-active state.

    FileMangler may be configured to display the Menu Bar at all times.
    See LockMenuBar, configuration option.

  • Toggle Synch Lock (ALT+SHIFT+')

    Enable or disable synchronized data navigation for Dual-Window Mode.

    Allows navigation keys (Up, Down etc,) pressed in the active window to be mirrored in the inactive window.

    Please see Synch Lock for more information.

  • User Info (ALT+SHIFT+[)

    Open a dialog which displays various information about your user account. This includes your User ID, account name, group information, your shell program and your home directory.

    See Display User Info.

  • Clipboard Info (ALT+SHIFT+;)

    The FileMangler internal clipboard is used as a virtual copy of the source data used for all file management operations. The contents of the clipboard may be view and managed from within the application.

    See Manage FileMangler Clipboard.

  • File System Info (ALT+SHIFT+])

    Display information on the data-storage device (hard drive, memory stick, optical drive etc.) which contains the currently-displayed files.

    See Display Filesystem Info.

  • Hidden Files (ALT+I)

    Display or hide ‘hidden’ system files.

    Please see Hidden Files Toggle for a complete description of viewing hidden files.





Util Menu

 ALT+SHIFT+U key
 ALT+U key

The Utility Menu includes various utility operations such as data backup, Trashcan management and FileMangler configuration.

┌───────┤ File Edit View Util Help ├─────────┐ │Status: ESC exits menu--ESC exits menu--ES┌────────────────┐exits menu ├───────────────────────────────────────────│Backup as+B│─────────────────┤ /home/sam/SoftwareDesign/FileMangler Synchronize as+S ├───────────────────────────────────────────│Archive as+A│─────────────────┤ │ 4,096 23-Nov-2017 14:44:25 1_TestDat│Compare Files │ │ 4,096 26-Jan-2017 12:00:53 Archive RestoreTrsh as+R 4,096 26-Nov-2017 08:23:15 Texinfo ManageTrash as+T 4,096 21-Nov-2017 12:18:19 install Mouse Support 1,024 21-Jun-2017 22:31:50 Backup_DeConfigure... 144,048 08-Nov-2017 08:21:32 FMgr.cpp └────────────────┘ 84,048 13-Nov-2017 06:42:21 FMgr.hpp 78,944 26-Nov-2017 07:30:21 FMgr.o 11,112 26-Jan-2017 07:44:55 FMgrDispData.hpp


  • Backup (ALT+SHIFT+B)

    Perform a Backup or Archive operation on the data in the currently-displayed directory.

    NOTE: FileMangler must be in Dual-window Mode.
    Please see Dual-window Mode

    For a complete description of the Backup operation, please refer to Backup Your Data.

  • Synchronize (ALT+SHIFT+S)

    Perform a Synchronize operation between the directories displayed in the left and right windows.

    NOTE: FileMangler must be in Dual-window Mode.
    Please see Dual-window Mode

    For a complete description of the Synch operation, please refer to Synchronize Directories.

  • Archive (ALT+SHIFT+A)

    Create, expand or update archive files.

    For a complete description of the Archive management, please refer to Working With Archives.

  • Compare Files (ALT+SHIFT+C)

    Compare the contents of two(2) files and report the differences between them.

    For a complete description of the file comparison, please refer to Compare Files.

  • Restore Trash (ALT+SHIFT+R)

    Automatically identify the item(s) most recently moved to the Trashcan and restore them to their original position.

    Please see Restore from Trashcan for a complete description of the un-delete operation.

  • Manage Trash (ALT+SHIFT+T)

    View the current contents of the system Trashcan and interactively delete or restore one or more items.

    Please see Manage the Trashcan for a complete description of Trashcan management.

  • Mouse Support

    Enable or disable mouse support for the current session only.

    For a complete description of mouse support for FileMangler, please see Mouse Support.

    Please see Configuration to set the default value for mouse support.

  • Configure

    Run the FileMangler configuration utility to modify the application’s default settings.

    Please see Configuration for details.

    Note that the configuration utility may also be invoked through the '-C' command-line option.
    Please see Invoking for more information.





Help Menu

 ALT+SHIFT+H key
 ALT+H key

As the name implies, the ‘Help’ menu provides access to the information you need to use the FileMangler application most effectively.

┌───────┤ File Edit View Util Help ├─────────┐ │Status: ESC exits menu--ESC exits menu--ESC exits men┌────────────────┐ ├──────────────────────────────────────────────────────│FileMangler Help│──────┤ /home/sam/SoftwareDesign/FileMangler Key Bindings c+K ├──────────────────────────────────────────────────────│About FileMgr │──────┤ │ 4,096 23-Nov-2017 14:44:25 1_TestData └────────────────┘ │ 4,096 26-Jan-2017 12:00:53 Archive 4,096 26-Nov-2017 08:23:15 Texinfo 4,096 21-Nov-2017 12:18:19 install 1,024 21-Jun-2017 22:31:50 Backup_Def.txt 144,048 08-Nov-2017 08:21:32 FMgr.cpp 84,048 13-Nov-2017 06:42:21 FMgr.hpp 78,944 26-Nov-2017 07:30:21 FMgr.o 11,112 26-Jan-2017 07:44:55 FMgrDispData.hpp


  • FileMangler Help (SHIFT+F01)

    Display online help for the FileMangler application. This command invokes the Texinfo ‘info’ reader.

    For a complete description of the application’s documentation, please refer to Invoke Online Help.

  • Key Bindings (CTRL+K)

    Display the current command key assignments. To modify command-key assignments, please see Customizing Key Commands.

    For a complete description of the command-key assignments, please refer to List of Command Keys.

  • Help About

    Display a dialog containing application version and copyright information as well as technical support contact information.


┌──────────────────────┤ About FileMangler ├───────────────────────┐ │FileMangler: A file management utility for Linux. │ │ Version: 0.0.34 │Copyright : (c) 2005-2016 Mahlon R. Smith, The Software Samurai │ │ Beijing University of Technology - Beijing, PRC │ 马伦教授 北京工业大学 - 北京,中华人民共和国 │ │ │Developed under Fedora Linux 20, using GNU G++ (Gcc v: 4.8.0) │ │Software released under GNU General Public License, version 3, │ │and documentation under GNU Free Documentation License, version 1.3 │ │ Bugs, suggestions, or possible praise? │ │ Please contact the author at: http://www.SoftwareSam.us/ │ │ │ CLOSE SUPPORT INFORMATION └────────────────────────────────────────────────────────────────────┘

Important Note About Submitting a Technical Support Request

Additional information about the application and its operating environment is captured by pressing the ‘Support Information’ pushbutton.

This opens a sub-dialog (see below) which displays more detailed information which is needed when submitting a request for technical support.

Pressing the ‘Save To File’ pushbutton will also save a copy of this information by creating a file in the current working directory:
FileMangler_SupportRequest.txt

After this file has been created, open the file in your favorite text editor and add a description of the issue you would like to have addressed. Then, submit the tech support request form to the author via website.


┌───────────────┤ Technical Support Information ├────────────────┐ Please include this information Dynamic (shared) Libs with all tech support requests. libncursesw.so.5 │ │ NcDialog API library : 0.0.29 libtinfo.so.5 │ │ libpthread.so.0 │ │ ncursesw library : 5.9.20130511 libstdc++.so.6 │ │ libm.so.6 │ │ Locale setting : en_US.utf8 libgcc_s.so.1 │ │ libc.so.6 │ SAVE TO FILE CLOSE libdl.so.2 │ └──────────────────────────────────────────────────────────────────┘

Please see Technical Support for contact information.





Context Menus

Context menus are floating menus which are opened in response to special circumstances (contexts). These menus are not attached to the application’s Menu Bar and may appear at any convenient position within the application’s main window.

ViewFile Context Menu

To open the 'ViewFile' context menu for the highlighted filename:

  • For any non-directory file, press the ENTER (RET) key.
  • For a directory name, press the ALT+ENTER key.
  • If the mouse interface is active, the ViewFile context menu may also be activated using the mouse.
    Please see Mouse Support for more information on the mouse interface.
┌─────────────────┐ View Contents View file Stats Open (execute) Find Link Target Cancel └─────────────────┘

The options available in the menu are dependent on the filetype of the highlighted file, and whether you have read access permission for the file.

  • View Contents

    View the contents of the target file in either plain-text format or in human-readable numeric format. For archive files, the data displayed will be a list of files contained in the archive. For selected media files, the “metadata” (tag data) will be displayed. Note that only the contents of 'regular' files may be viewed in this way.

    Please see View File Contents for details.

  • View File Stats

    Select this option to view, and optionally modify the target file’s statistical data. These data include the file timestamps, permission bits, owner, group and other data. Note that some data items may be changed only by the superuser ('root' user).

    Please see View or Modify File Stats for details.

  • Open (execute)

    Launch the executable script or application binary file,
       OR
    launch the default application associated with the filetype.

    Please see Open or Execute a File for details.

  • Find Link Target

    If the highlighted filename is a symbolic link, then go to the directory which contains the sym-link’s target file and highlight that file.

    For broken symbolic links (file not found or inaccessible), an error message will be displayed.

    Note that if the highlighted file is not a symbolic link, then this option will be disabled.

  • Cancel

    Close the ViewFile context menu without taking any further action.

    Note that pressing the ESCAPE key will also close the context menu, although in this case, there may be a short delay before the menu is closed due to the way in which the ESCAPE key is presented to the console..





SortBy Context Menu

To open the 'SortBy' context menu:

  • Press the 'CTRL+S' key combination.
┌─────────────────┐ Name Name Reverse Date Date Reverse Size Size Reverse Extension Extension Reverse File Type FileType Reverse No Sort └─────────────────┘

The list of files in the current directory may be displayed according to Name, Date, file Size, filename Extension or File Type in either ascending or descending order.

Note that if FileMangler is is Dual-window Mode, then both windows will be sorted using the same criterion.

Please see Sorting the File List for more information.





Next: , Previous: , Up: Top   [Contents][Index]

Configuration




Configuration Overview

FileMangler’s configuration options are quite flexible, and it is hoped that these options will allow you to configure the application exactly the way you want it.

By default, configuration options are defined in the configuration file:
FileMangler.cfg
which is located in the same directory as the FileMangler binary (executable) file.
The next chapter (see The Configuration File) describes each available option.

An alternate configuration file may be specified as a command-line option. See 'f' option, for details.

If the specified file does not exist, it will be created.

The configuration file is fully self-documenting and can easily be edited manually using any UTF-8 capable text editor; however, for best results FileMangler’s built-in configuration utility should be used to make modifications to the configuration parameters.

Configuration Utility

Modifications to the configuration are handled interactively by the FileMangler configuration utility. This is a separate executable file ‘FmConfig’, which is called from within the FileMangler executable, either as a command-line option or through the application’s menu interface.
Please note that the configuration utility must be launched as a child process of the main application and may not be launched as a stand-alone application.

The configuration utility can be invoked in one of two ways:

1) By use of the '-C' command-line option (see ’C’ option):
   Example: fmg -C

2) Through the Utilities Menu (see Configure):

┌───────┤ File Edit View Util Help ├───────┐ │Status: ESC exits menu--ESC exits menu--ES┌───────────────────┐ts menu ├───────────────────────────────────────────│Backup as+B│────────────┤ /home/sam/SoftwareDesign/FileMangler │Synchronize as+S│ ├───────────────────────────────────────────│Archive as+A│────────────┤
│Restore Trash as+R│ │Compare Files │ │Manage Trash as+T│ Configure └───────────────────┘

Main Configuration Dialog

The configuration utility is implemented as a dialog with a group of radio-button and pushbutton controls through which each configuration parameter may be adjusted. Although the dialog appears rather complex, it is not necessary to interact with the overall functionality as a single unit. Instead, with few exceptions, each configuration option may be handled individually without disturbing the settings of the other options.

To modify one or more configuration options, select the radio button for the desired option(s) and then press the 'MODIFY' pushbutton.

Each selected option will be presented sequentially so only one option is under edit at a given moment.

Below is a screenshot of the main configuration dialog.

┌────┤ FileMangler Configuration - Edit Configuration Parameters ├─────┐ │ │ Configuration Options Current Value │ < > Window Mode - - - - - - 'ByTermSize' │ │ <◆> Sort Order - - - - - - 'Name' │ │ <◆> Case Sensitive - - - - 'true' │ │ < > Hidden Files - - - - - 'false' │ │ < > Confirm Delete - - - - 'false' │ │ < > Confirm Overwrite - - - 'ConfirmNewer' │ │ < > Lock Menu Bar - - - - - 'false' │ │ <◆> Color Scheme - - - - - 'Default' │ │ < > Enable Mouse Support - - 'enable' │ │ <◆> External Programs - - - 'AutoAudio' │ │ <◆> Favorite Directories - - 17 directory paths specified │ │ < > Command-key Map - - - - Using: default key map │ │ < > Mount Commands - - - - 4 mount commands specified │ │ < > Alternate Trashcan - - - ~/Apps/FileMangler/Trash │ │ │ │ │ │ │ MODIFY SAVE CANCEL DEFAULT ALL HELP ├────────────────────────────────────────────────────────────────────────────┤ Modify parameters for indicated configuration options. │ Target File: /home/sam/SoftwareDesign/FileMangler/FileMangler.cfg │ └────────────────────────────────────────────────────────────────────────────┘

The controls and features of this dialog are:

  • A group of Radio buttons, one for each configuration option.

    The current value of each option is listed to the right of the option name.

    Select (set) the radiobutton for each option to be edited, then press the 'MODIFY' Pushbutton.

  • 'MODIFY' Pushbutton.
    For each option chosen for modification (its radio button is selected), a sub-dialog will be opened so the new value can be chosen. The sub-dialogs are opened sequentially in the order that the options are displayed in the main dialog.
    The next chapter, Setting Config Options describes the sub-dialog for each option in detail.

  • 'SAVE' Pushbutton.
    Write all pending changes to the target configuration file and return to the main application.

    Note: If the configuration utility was invoked from the FileMangler application menu, you will be asked whether you want to restart FileMangler so the changes will immediately take effect, or if you would like to continue the current session with the old values.

┌───────────────────────────┤ RESTART ├────────────────────────────┐ │ │ │ Any changes made during configuration will take effect on restart. │ │ │ │ Re-start FileMangler now? │ │ │ │ │ YES NO └────────────────────────────────────────────────────────────────────┘

  • 'CANCEL' Pushbutton.
    Discard any pending changes and return to the main application without modifying the configuration file.

  • 'DEFAULT ALL' Pushbutton.
    Set all configuration options to their default values. The new values will be displayed to the right of each option name.

    Note that these values will not be written to the config file immediately. The values will be written when the 'SAVE' pushbutton is selected.

  • 'HELP' Pushbutton.
    This pushbutton invokes the info reader and opens the FileMangler documentation to this chapter.

  • A Textbox which displays a short context help message for the control which currently has the input focus.

  • The full path/filename of the configuration file which will received the edited configuration values.

  Settings for each configuration option are discussed  
  in the next chapter: see Setting Config Options.




Setting Config Options

   Index of Configuration Options   
  Window Mode
  Sort Order
  Case Sensitive
  Hidden Files
  Confirm Delete
  Confirm Overwrite
  Lock MenuBar
  Color Scheme
  Enable Mouse
  External Programs
  Favorite Directories
  Command-key Map
  Mount Commands
  Alternate Trashcan

This chapter describes the each configuration option and discusses
the configuration sub-dialog which is used to set the parameters for the option.


Window Mode Sub-dialog

┌────────────────────────┤ Edit 'Window Mode' ├────────────────────────┐ │ │ │ │ │ │ │ < > 'SingleWin' │ - Open application with one file-display window. │ │ │ < ◆ > 'DualWin' │ - Open application with dual file-display windows. │ │ │ < > 'ByTermSize' (default) │ - Determine display mode according to size of terminal window. │ │ │ │ │ │ │ │ OK CANCEL │ │ └────────────────────────────────────────────────────────────────────────┘

Select the default visual operating mode for the application.

The chapter, see Operational Overview fully describes the concept of the Window Modes.

Switching between Single-window Mode and Dual-window Mode is done either through the see View Menu or via the 'ALT+W' shortcut key, see View Mode Selection.

Also, see WindowMode, configuration-file option.


Sort Order Sub-dialog

┌────────────────────────┤ Edit Sort Options ├─────────────────────────┐ │ │ │ ┌─────────────┤ 'SortOrder' ├──────────────┐ │ │ │ 'Name' - by filename (ascending) │ │ │ │ 'NameR' - by filename (descending) │ < ◆ > 'CaseSensitive' │ │ │ 'Date' - by modify date (ascending) if selected, sort │ │ 'DateR' - by modify date (descending) is case sensitive │ │ 'Size' - by file size (ascending) │ │ │ │ 'SizeR' - by file size (descending) │ < > 'HiddenFiles' │ │ │ 'Ext' - by file extension (ascending) if selected, │ │ 'ExtR' - by file extension (descending) show hidden files │ │ 'Type' - by file type (Dir,Reg,Link...) │ │ │ │ 'TypeR' - by file type (reverse order) │ │ │ │ 'None' - no sort, (as stored on media) │ │ │ └──────────────────────────────────────────┘ │ │ │ OK CANCEL │ │ └────────────────────────────────────────────────────────────────────────┘

This sub-dialog contains the three(3) configuration options related to sorting of file lists.

  1. the “Sort Order” criteria
    Filenames may be sorted either low-to-high or high-to-low by Name, Date, file Size, filename Extension, file Type, (or no sort).
    Please see Sorting the File List for more information.

    Sort order may be chosen via the ‘Sort Options’ item in the see File Menu, or
    or with the CTRL+S shortcut key which opens the see SortBy Context Menu.

    Also, see SortOrder, configuration-file option.

  2. the switch to enable/disable case-sensitive file sorting
    (see below)
  3. the switch to enable/disable display of “Hidden Files”
    (see below)

Case Sensitive Sub-dialog

Case sensitivity for filename sorting is selected via the ‘CaseSensitive’ Radio button in the Edit Sort Options dialog above.

Case sensitivity is enabled by default which will cause a list of filenames to be sorted as shown in the example.

Dusty Rhodes - lyrics.odt
Energizer Bunny Hop.jpg
Flag of France.png
dirty dingus mcgee - bio.odt
encounter in paris.pdf
frogs of the amazon.gif

With case sensitive sorting disabled, the same file list would appear as:

dirty dingus mcgee - bio.odt
Dusty Rhodes - lyrics.odt
encounter in paris.pdf
Energizer Bunny Hop.jpg
Flag of France.png
frogs of the amazon.gif

Case-sensitive sorting may be enable or disabled via the ‘Sort Options’ item in the see File Menu.

Also, see CaseSensitive, configuration-file option.


Hidden Files Sub-dialog

Whether or not to display hidden files when displaying a list of filenames is selected via the ‘HiddenFiles’ Radio button in the Edit Sort Options dialog above.

Under Linux, the name of a hidden file begins with the full-stop character (period): ’.’

In general, hidden files are hidden for a reason. System configuration files such as “~/.bash_profile” are hidden to protect them from accidental damage. In addition, most hidden files and directories are seldom of direct use to the user so hiding them reduces visual clutter.

However, if you routinely work with system files, it may be advantageous to view hidden files.

Viewing of hidden files may be enabled or disabled via the ‘Sort Options’ item in the see File Menu.

Visibility of hidden-files may also be toggled through the: see View Menu,
or with the 'ALT+I' shortcut key: see Hidden Files Toggle.

Also, see HiddenFiles, configuration-file option.


Confirm Delete Sub-dialog

┌──────────────────────┤ Edit 'Confirm Delete' ├───────────────────────┐ │ │ │ │ │ │ │ │ │ < ◆ > 'true' │ - Always ask for confirmation when moving files to trashcan. │ │ │ < > 'false' (default) │ - Never ask for confirmation when moving files to trashcan. │ │ │ │ Note that confirmation is always required for non-reversible file deletions and operations involving entire directory trees. │ │ │ │ OK CANCEL │ │ └────────────────────────────────────────────────────────────────────────┘

When files are deleted or moved to the Trashcan, a verification dialog may be opened as a reminder of potential data loss.

Selecting which operations will ask for verification is a personality choice. Super-organized people may be annoyed by this dialog, while those of us who tend to get distracted by ten things at once may be comforted by a request for verification.

Operations which cannot be reversed or operations which are moving a large amount of data will always ask for verification.

However, moving a file or a small group of files to the Trashcan is a reversible operation, so verification of such operations is optional and can be configured here.

Also, see ConfirmDelete, configuration-file option.

Please see Trashcan and File Deletion for more information on using the Trashcan effectively.


Confirm Overwrite Sub-dialog

┌─────────────────────┤ Edit 'Confirm Overwrite' ├─────────────────────┐ │ │ │ │ │ │ │ < > 'Never' │ - Do not ask before overwriting existing target files. │ │ │ < ◆ > 'ConfirmNewer' (default) │ - Ask before overwriting a newer file with an older file. │ │ │ < > 'Always' │ - Always ask before overwriting existing target files. │ │ │ │ │ │ │ │ OK CANCEL │ │ └────────────────────────────────────────────────────────────────────────┘

When copying or moving files from one place to another, there are often files of the same name already in the target directory.

When this happens, the question becomes which of the files is more valuable, the one being copied or the one which is about to be overwritten.

This option allows you to choose the level of verification requested for file overwrite.

Typically, the newer version of the file is the one that should be retained, so by default, verification will be requested only if a newer file is about to be overwritten by an older one.

If you are absolutely, positively sure that you know what you are doing every minute of every day, this verification can be disabled.

If however you occasionally make mistakes, verification may be requested for all file overwrites.

Also, see ConfirmOverwrite, configuration-file option.


Lock MenuBar Sub-dialog

┌───────────────────────┤ Edit 'Lock Menu Bar' ├───────────────────────┐ │ │ │ │ │ │ │ │ │ < ◆ > 'true' │ - Lock the Menu Bar in the visible state. │ │ │ < > 'false' (default) │ - Menu Bar will be visible only when making a menu selection. │ │ │ │ │ │ │ │ │ │ │ │ OK CANCEL │ │ └────────────────────────────────────────────────────────────────────────┘

To conserve valuable display space, the FileMangler title and the Menu Bar share the top row of the dialog. By default, the Menu Bar becomes visible only when explicitly activated via the mouse or a menu hotkey.

The Menu Bar can be made permanently visible by locking it in the visible state.

The Menu Bar lock may also be enabled or disabled through the “Menu Bar Visible” option of the ‘View Menu’: see View Menu.

Also, see LockMenuBar, configuration-file option.


Color Scheme Sub-dialog

┌────────────────────────┤ Edit Color Scheme ├─────────────────────────┐ ┌────────────────┤ Red ├─────────────────┐ │ < > 'Default' Textbox (focus) Textbox(non-focus) │ < > 'Black' Pushbutton(focus) Pushbutton (n-f) │ < ◆ > 'Red' Menu │ < > 'Green' ┌────────┐ ┌──┤ sub-dialogs ├──┐ │ │ < > 'Brown' without │ border and │ │ │ < > 'Blue' input ┌────────┐ │ interior │ │ │ < > 'Magenta' focus │ with │ │ │ │ │ < > 'Cyan' └────────│ input │ │ [ ◆ ]control label│ │ │ < > 'Grey' │ │ focus │ └───────────────────┘ │ │ < > 'Terminal' │ └────────┘ │ └──────────────────────────────────────────┘ │ │ OK CANCEL │ │ └────────────────────────────────────────────────────────────────────────┘

A color scheme is the combination of colors used to present the dialog background, control objects, filenames and other visual elements of the application. This color scheme is applied during application startup.

For each item in the list of color schemes, this dialog presents a sample of the color scheme’s appearance. Although the info reader version of the documentation cannot display this color data, the HTML version of the documentation presents a fairly accurate sample.

The 'c' option command-line option may be used to override the configuration setting for the current session.

Also, see ColorScheme, configuration-file option.


Enable Mouse Sub-dialog

┌───────────────────┤ Edit 'Enable Mouse Support' ├────────────────────┐ │ │ │ < ◆ > 'enable' │ - Enable FileMangler mouse support for selection of filenames, control activation and data scrolling. │ │ │ < > 'disable' (default) │ - Disable FileMangler mouse support. │ │ │ │ Text-mode mouse support is necessarily very basic; however, you may find it to be useful. Please refer to the FileMangler online documentation, or the NcDialog API documentation for more information. │ │ │ │ │ │ OK CANCEL │ │ └────────────────────────────────────────────────────────────────────────┘

Enable or disable the mouse interface.
Please see Mouse Support for more information.

The mouse configuration may be overridden by the 'm' option command-line option, or
may be enabled or disabled for the current session via the see Util Menu.

Also, see EnableMouse, configuration-file option.


External Programs Sub-dialog

┌─────────────────────┤ Edit 'External Programs' ├─────────────────────┐ │ < > 'AutoLaunch' (default) │ - Application determines launch parameters if possible, else open a dialog to get user's preference. │ │ │ < ◆ > 'AutoAudio' │ - Same as 'AutoLaunch' but assumes that audio files will be opened by a GUI media player. │ │ │ < > 'SafeLaunch' │ - Launch from current window if it can be done without resource conflict, otherwise open program from a new terminal window. │ │ │ < > 'ManualLaunch' │ - Always open an interactive dialog to configure launch parameters. OK CANCEL │ │ └────────────────────────────────────────────────────────────────────────┘

The “External Programs” configuration option sets the way in which external programs will be launched from within FileMangler. These options indicate the amount of manual intervention needed to launch a program without causing resource conflicts within the application’s terminal window.

Within the application, external programs are launched via the “View File” context menu: see launch external app.

Also, see ExternalPrograms, configuration-file option.


Favorite Directories Sub-dialog

┌────────────────────┤ Edit Favorite Directories ├─────────────────────┐ │ │ ├────────────────────────┤ Favorite Directories ├────────────────────────┤
/run/media/sam/TEACHBACKUP /run/media/sam/BACKUP 16G /run/media/sam/SYSBACK 8GB /usr/include /usr/lib /tmp ${HOME}/.local/share/Trash /run/user/1000/gvfs
├────────────────────────────────────────────────────────────────────────┤ │Highlight the desired item using arrow keys, then: │ │ Ctrl+U : move item Up Ctrl+R : Remove item from list │ │ Ctrl+D : move item Down Ctrl+A : Add new item to list │ │ Ctrl+E : Edit item │ OK CANCEL │ │ └────────────────────────────────────────────────────────────────────────┘

“Favorite Directories” are often-visited locations which are maintained in a configuration-file list for easy access during file-management operations.

For instance, in the example dialog above, the Favorites consist of three(3) backup drives, the 'include' and 'lib' directories where interesting compiler files are located, the local Trashcan, the directory where temporary files are created and the directory where MTP-filesystem devices such as smartphones are dynamically mounted.

Scroll through the list using the UpArrow, DownArrow keys; highlight the desired entry, then use the hotkeys as indicated to edit the list:

  • CTRL+U Move item up
    Shift the highlighted item upward by one position.
  • CTRL+D Move item down
    Shift the highlighted item downward by one position.
  • CTRL+E Edit item
    A Textbox control will open just above the list so the item may be edited. When finished editing, press TAB or ENTER to return the edited data to the list.
  • CTRL+E Remove item from list
    Remove (delete) the highlighted item from the list.
    Items below the deleted entry will be shifted upward.
  • CTRL+A Add item to list
    A Textbox control will open just above the list so the new item may be entered. When the new item has been entered, press TAB or ENTER. The new item will be appended to the end of the list.

Press the 'OK' pushbutton to save the list, or press the 'CANCEL' pushbutton to discard edits. The changes will be written to the target file when you select 'SAVE' in the main configuration dialog.

Within the application, access Favorite Directories through the “Favorites” item in the File Menu, or
via the 'CTRL+O' shortcut key: see Favorite Directories List.

Also, see FavoriteDirectories, configuration-file option.


Command-key Map Sub-dialog

** UNDER CONSTRUCTION - DYNAMIC KEY MAPPING IS NOT YET IMPLEMENTED **

Please see Customizing Key Commands for a discussion of command-key remapping.

Also, see KeyMap, configuration-file option.


Mount Commands Sub-dialog

┌───────────────────────┤ Edit Mount Commands ├────────────────────────┐ │ │ ├─────────────────────┤ Mount-filesystem Commands ├──────────────────────┤
/run/media/sam/TravelDrive /run/media/sam/SD32_BACKUP /run/media/sam/LUCKYLUCY32 /media/TOSHIBA_500GB_ext4 /run/user/1000/gvfs/$MTP_PHONE
├────────────────────────────────────────────────────────────────────────┤ │Highlight the desired item using arrow keys, then: │ │ Ctrl+U : move item Up Ctrl+R : Remove item from list │ │ Ctrl+D : move item Down Ctrl+A : Add new item to list │ │ Ctrl+E : Edit item │ OK CANCEL EXPERT │ │ └────────────────────────────────────────────────────────────────────────┘

** UNDER CONSTRUCTION - FILESYSTEM MOUNTING IS NOT FULLY IMPLEMENTED **

Mounting external storage devices is a common operation in file management. System configuration may be set to allow certain types of filesystems to be mounted automatically when they are connected to the system.

If a filesystem is not automatically mounted, the system can be instructed to mount the device at a specific point on the filesystem tree structure.

Use the indicated Control-key combinations to Add, Remove, Edit or rearrange the entries in this mountpoint table.

Important Note: A mount-table “Expert Mode” is used to edit the system mount table (/etc/fstab). Because Expert Mode directly modifies the system configuration, it is critical that it functions properly. Currently, the Expert Mode dialog will read and report the current ‘fstab’ table entries, but writing new entries to the table is disabled.
Note also that Expert Mode requires Superuser privlege to modify system files.

Within the application, mounting and unmounting filesystems is done through the “Mount” item in see File Menu.

Also, see MountCommands, configuration-file option.


Alternate Trashcan Sub-dialog

┌──────────────────────┤ Edit Trashcan Options ├───────────────────────┐ │ │ │ Alternate Trashcan Path │ ~/Apps/FileMangler/Trash │ Expanded Alt Path │ /home/sam/Apps/FileMangler/Trash │ │ │ │ │ Default Desktop Trashcan │ /home/sam/.local/share/Trash │ │ │ │ │ │ │ │ │ │ │ │ OK CANCEL │ │ └────────────────────────────────────────────────────────────────────────┘

Under most circumstances the default Trashcan located in yous 'HOME' directory is the correct location. However, if you are operating as the Superuser, or if you need more flexibility when playing in the Trash, then an alternate Trashcan location may be specified.

The Trashcan is exhaustively discussed in see Manage the Trashcan, and the technical issues of using the Trashcan are discussed in see tech notes.

Also, see AlternateTrashcan, configuration-file option.




The Configuration File

The configuration file provides the application’s initial configuration parameters. These parameters may be overridden by command-line arguments specified when the application is invoked (see Invoking). In addition, many of these parameters may be modified for the current session via menu items.

The configuration file may be edited directly with any text editor, or may be modified using FileMangler’s configuration utility as described in the previous chapter.

By default, the file 'FileMangler.cfg' in the installation directory is read on startup; however, an alternate configuration file may be specified by the '-f' command-line option. See 'f' option, for additional information.

If a configuration option is not specified in the configuration file, that parameter will be set to its default value.

If a syntax error is discovered in the configuration file, a warning will be issued and the malformed parameter(s) will be set to their default values.

If no configuration file is found on startup, then all parameters will be set to their default values as indicated below.

WindowMode

The Window Mode indicates whether the application will be initially started in Single-Window Mode or Dual-Window Mode.

Note: If the terminal window is too small for Single-Window mode, an error message will be displayed and the application will exit.
Please see Operational Overview for detailed information.

Also, see Window Mode.

Arguments

  • SingleWin
    Start in Single-Window Mode. The list of files is displayed in a single window 80 columns wide and the height of the terminal window.
  • DualWin
    Start in Dual-Window Mode. Two lists of files are displayed side-by-side, filling the width and height of the terminal window.

    If terminal window is too small for Dual-Window mode, the application will display a warning and then start in Single-Window mode.

  • ByTermSize (default)
    The startup mode is determined by the size of the terminal window in which the application is invoked. If the terminal window is large enough (>= 118 columns), the application will start in Dual-Window mode, else the application will start in Single-Window mode.

Example:

WindowMode = ByTermSize


SortOrder

File-display sort option. This option specifies the order in which files are displayed in main window(s). Note that in Dual-window Mode (two file-display windows), the sort option will be the same for both.

Also, see Sort Order.

Arguments

  • Name (default)
    Sort alphabetically by filename, low-to-high with directories grouped at the top of the list.
  • NameR
    Sort alphabetically by filename, high-to-low with directories grouped at the top of the list.
  • Date
    Sort numerically by modification timestamp, low-to high.
  • DateR
    Sort numerically by modification timestamp, high-to-low.
  • Size
    Sort numerically by file size, low-to-high.
  • SizeR
    Sort numerically by file size, high-to-low.
  • Ext
    Sort alphabetically by filename extension, low-to-high. Within a group of files with the same extension, sort alphabetically by filename, low-to-high.
  • ExtR
    Sort alphabetically by filename extension, high-to-low. Within a group of files with the same extension, sort alphabetically by filename, low-to-high.
  • Type
    Group files according to file type (Regular, FIFO, Socket etc). Within each file-type group, files are sorted alphabetically by name (low-to-high).

    Directories are grouped at the top of the list. ‘Regular’ files are grouped next, and the remaining file-type groups are listed in arbitrary order according to the (presumed) likehood of encountering files of that group.

  • TypeR
    Group files according to file type (Regular, FIFO, Socket etc). Within each file-type group, files are sorted alphabetically by name (low-to-high).

    The groups are listed in an order opposite to that of the 'Type' order above (directories at the bottom of the list).

  • None
    No Sort: Display files in the order in which they are stored in the directory file. The order in which filenames are stored in a directory file is system dependent, but in general follows the the order in which the files were created or were first placed in that directory.

Example:

SortOrder = Name


CaseSensitive

The case-sensitivity flag indicates whether alphabetical sorting of files uses a case-sensitive or case-insensitive comparison test. Sort options that use alphabetical sort are:
'Name', 'NameR', 'Ext', and 'ExtR'.
For example, in a case sensitive sort, ’A’ (0x041) is less than ’a’ (0x061), so the word ‘Apple’ is less than ‘apple’.

For other sorting criteria, e.g. ‘Size’, if a group of files have the same size, then an alphabetical sub-sort is performed within that group.

In a case-INsensitive sort ’A’ and ’a’ are treated as having equal value.

Also, see Case Sensitive.

Arguments

  • true (default)
    Case-sensitive alphabetical sort.
  • false
    Case-insensitive alphabetical sort.

Example:

CaseSensitive = true


HiddenFiles

This option specifies whether “Hidden” files should be include in the list of displayed files. “Hidden” files are hidden by default.

Viewing of hidden files may be enabled or disabled via the ‘Sort Options’ item in the see File Menu.

Visibility of hidden-files may also be toggled through the: see View Menu,
or with the 'ALT+I' shortcut key: see Hidden Files Toggle.

Also, see Hidden Files.

Arguments

  • true
    Show hidden files.
  • false (default)
    Do not show hidden files.

Example:

HiddenFiles = false


ConfirmDelete

Confirmation of file deletion. This option specifies the level of confirmation to provide when moving files to the Trashcan.

Because moving a file to the Trashcan can easily be restored, without data loss, you may prefer to skip the confirmation step in this operation. This is the default.

However for extra security, FileMangler can be configured to ask for confirmation on all moves to the Trashcan.

Please note that moving non-empty directory trees to the Trashcan and deletions which bypass the Trashcan and cannot be un-deleted always require confirmation.

Also, see Confirm Delete.

Arguments

  • true
    Always prompt for confirmation before sending files to the Trashcan.
  • false (default)
    Never confirm when sending non-directory files to the Trashcan.

Example:

ConfirmDelete = false


ConfirmOverwrite

Confirmation of file overwrite. This option specifies the level of confirmation to provide when pasting a file into a directory that already contains a file of that name.

Also, see Confirm Overwrite.

Arguments

  • Always
    Always prompt for confirmation before overwriting one file with another.
  • ConfirmNewer (default)
    Confirm overwrite if the existing target file’s modification date is newer than the date of the file with which it is to be overwritten.
  • Never
    Never confirm file overwrite.

    Note that this option is more properly “Seldom Confirm Overwrite.” Overwrite of write-protected files and files with the same name but different file types must always be confirmed. For instance, overwriting a symbolic-link file with a ‘Regular’ file of the same name must be confirmed. (Overwriting a ‘Regular’ file with a symbolic link is not allowed.)

    Note also that an existing directory name is never overwritten, so no confirmation on directory names is required, but the specified confirmation rule does apply for files contained within the directory.

Example:

ConfirmOverwrite = ConfirmNewer


LockMenuBar

Lock Application Menu Bar in visible state.
The Menu Bar shares screen space with the dialog title, and is normally only visible when the user is making a menu selection. This configuration option may be used to lock the Menu Bar so it is always visible.

Enabled:

┌───────┤ File Edit View Util Help ├───────┐

Disabled:

┌───────┤ FileMangler - v:0.0.35 (c)2005-2017 [Press F2 for Menu] ├───────┐

Also, see Lock MenuBar.

Arguments

  • true
    The Menu Bar will be visible at all times.
  • false (default)
    The Menu Bar will be visible only during menu-item selection, otherwise the application title will be visible.

Example:

LockMenuBar = false


ColorScheme

Specify the application “Color Scheme.”

The Color Scheme allows selection of a set of display colors to be used when drawing borders, dialog windows, menus, controls and other dialog objects.

Color preference is a personal choice, and FileMangler provides several color configurations to match your style or mood. The Color Scheme utilizes the full 16-color palette available on most modern systems and the 256 color pairs available from the ncurses library.

The Color Scheme setting can be overridden at run-time using the '-c' command-line option. See 'c' option, for details.

Also, see Color Scheme.

Arguments

  • Default (default)
    The default color scheme is optimized for contrast and readability, using cyan borders for the main dialog and with blue menus and sub-dialogs.
  • Black
    bright white foreground, black background
  • Red
    white foreground, red background
  • Green
    white foreground, green background
  • Brown
    white foreground, brown background
  • Blue
    white foreground, blue background
  • Magenta
    white foreground, magenta background
  • Cyan
    white foreground, cyan background
  • Grey
    white foreground, grey background
  • Terminal
    Use the terminal default foreground/background for most objects with contrasting colors where necessary. This color scheme is seriously ugly, but is useful in terminal environments where there are fewer than eight(8) available colors.

Example:

ColorScheme = Default


EnableMouse

Capture all mouse activity which occurs within the application window. When mouse activity is seen within the application dialog, that mouse event is translated into the equivalent keyboard command so that the keyboard and mouse interfaces are synchronized.

  • Left button single-click is generally interpreted as pressing the ‘Space’ key, and left-button double-click is generally interpreted as pressing the ‘Enter’ key.
  • ScrollWheel mouse events are interpreted as pressing the ‘UpArrow’ or ‘DownArrow’ keys.
  • Interpretation of these mouse events is modified when used in combination with the ‘Ctrl’ and ‘Alt’ modifier keys.
  • All other mouse events will be ignored.

For detailed information on mouse support, please see Mouse Support.

Also, see Enable Mouse.

Arguments

  • disable (default)
    Disable the mouse interface for the application dialog.

    The mouse will still be active for the terminal emulation window and for other applications, but all mouse activity within the dialog window will be ignored.

  • enable
    Enable the mouse interface for the application dialog.

Example:

EnableMouse = disable


ExternalPrograms

Specify how external programs are to be opened.

FileMangler will launch external applications such as binary executable programs, shell scripts, interpreted program files (e.g. Perl, Python, Ruby), or will launch the default application associated with various kinds of data files such as text documents, LibreOffice documents, images, audio and video media files and more. These external applications are launched through the 'ViewFile' context menu.
See ViewFile Context Menu, for more information.

Also, see External Programs.

Arguments

  • AutoLaunch (default)
    Based on the file’s 'x' (execute) permission bit, the filename extension and the name of the program (if any) indicated at the top of the file (e.g. #!/bin/bash), FileMangler will determine whether the file may executed directly, or may immediately be opened using the default (GUI) application associated with the filetype, or if the user should be asked for setup information before launching the application.
  • AutoAudio
    Same as ‘AutoLaunch’ with the additional feature of never prompting for audio media files, because it will be assumed that the default audio player is a GUI application.
  • SafeLaunch
    Perform the ‘AutoLaunch’ tests, as above, and launch the external program from the current terminal window if it can be done safely, and without resource (I/O) conflict. If resource safety cannot be verified, then open a new terminal window from which to launch the external program. No setup dialog will be opened because the use of a new terminal window avoids any potential resource conflicts within the current window.
  • ManualLaunch
    For each file to be executed as an external application, or to be opened using an external application, first open a dialog to gather setup information before launching the application.

Example:

ExternalPrograms = AutoLaunch


 Technical Note: Opening a new terminal window from within the FileMangler application
 is dependent on the terminal emulator software.

 This functionality has been tested with GnomeTerm, Konsole, and XTerm. Other terminal
 emulator software should behave similarly, but this cannot be guaranteed.

 For information on the technical details of spawning a new process ID and programatically
 opening a new terminal window, please visit our website and download the “Salmon”
 student exercise.


Favorite Directories

List of user’s favorite directories.
“Favorite Directories” are often-visited locations which are maintained in a configuration-file list for easy access during file-management operations.

Each entry must resolve to an absolute path, not a relative path.

Environment variable substitution is supported.

Up to twenty-four (24) paths may be stored in this list.
A blank line signals the end of the list.

The Favorites list may be access through the File Menu, or
via the 'CTRL+O' shortcut key see Favorite Directories List.

Also, see Favorite Directories.

Example:

Favorite Directories:
${HOME}
${HOME}/SoftwareDesign
~/Documents/LessonPlans
~/Documents/GradeBook
~/Downloads
~/Music/Foreigner

(note that the blank line indicates the end of the list)

KeyMap

** UNDER CONSTRUCTION - DYNAMIC KEY MAPPING IS NOT YET IMPLEMENTED **

Mapping of command-shortcut keys.

Many command-key shortcuts are defined for quick access to to the operations specified in the FileMangler menus.

These command-shortcut keys fall into three groups:
 Control key + another key
   Example: Control+s invokes the Sort-Option menu.
 Alt key + another key
   Example: Alt+q exits application to current directory.
 Function keys
   Example: Shift+F01 opens the FileMangler Help documentation.

Please see Customizing Key Commands for a discussion of command-key remapping.

Also, see Command-key Map.

Example:

KeyMap = FmKeymap.cfg
or
KeyMap = $HOME/Documents/Lucy_ChineseKeyboard.cfg


Mount Commands

List of dynamically mountable and un-mountable file systems.

List of absolute mount-point paths (NOT device path) which the operating system has defined as being associated with particular devices. Example: /media/cdrom The usual suspects for mountable file systems are CD-ROM drives, flash drives, non-Linux/UNIX partitions, or network drives.

Many other types of file systems may also be mounted if they are fully defined by the operating system (typically in the file /etc/fstab).

The procedure for defining and tracking mountable file systems is implementation-dependent,* so please refer to the 'mount', 'umount' and 'findmnt' commands in your system documentation for instructions on defining a file-system mount point and its associated device.

Important Note: Certain filesystems can only be mounted by the super-user.

Here you have two choices: First you could log in as the Superuser before invoking FileMangler:
su PASSWORD
Second, you could invoke FileMangler as a regular user, and then the application will open a terminal window to execute the 'mount' or 'umount' command, where the system will ask for your password before executing the command. Please consult the system documentation for the ‘sudo’ command for additional information about executing a single command using executive privlege.

Up to sixteen (16) mountable filesystems may be stored in this list.
A blank line signals the end of the list.

See Mounting Filesystems, for additional information.

Also, see Mount Commands.

Example:

Mount Commands:
//* Daily Backups
/run/media/sam/TravelDrive
//* Shared software development archive
/media/SDEVBACKUP
//* Windoze partition
/media/Preload
//* Game configurations
/run/media/sam/KINGSTON

(note that the blank line indicates the end of the list)

Alternate Trashcan

Alternate location for desktop environment’s Trashcan.

The trashcan directory for the desktop environment in GNOME, KDE or any desktop using the freedesktop.org trashcan specification is located at: ~/.local/share/Trash
Example: /home/sam/.local/share/Trash

If this directory exists, AND if you as the user have read/write access to it, then it will be the location used by FileMangler when sending files to the trashcan and this parameter (if specified) will be ignored.
Technical Note: The specification states that if the Trashcan directory structure does not exist at that location, then it must “immediately be created.” FileMangler follows this instruction; the ‘Trash’ directory itself will not be created, but the structure within the ‘Trash’ directory will be created if necessary.

If you invoke FileMangler as the Superuser (‘root’ user), then the above directory specification will likely be incorrect, and you will need to specify root’s trashcan location here.

Also, for older versions of the desktop environment or for non-standard installations, you may need to specify where the trashcan directory is located. For instance, some older installations use ${HOME}/.Trash

Be aware that FileMangler WILL RUN WITHOUT TRASHCAN ACCESS, but in that case, the trashcan-files command will be disabled, and any file deletions must be done through the delete-files command.

Please specify an ABSOLUTE path, NOT a relative path.
A blank line following the command, indicates no-alternate-path-specified.

An extensive discussion of the system Trashcan may be found in the chapter see Trashcan and File Deletion.

Also, see Alternate Trashcan.

Example:

     Alternate Trashcan:
     ~/Apps/FileMangler/Trash



Customizing Key Commands

** UNDER CONSTRUCTION - DYNAMIC KEY MAPPING IS NOT YET IMPLEMENTED **

How To Assign an Alternate Command Key To an Operation

Command keys are remapped through FileMangler’s Configuration utility (see Configuration Overview), or may be assigned manually by editing the keymap configuration file, which by default is
FmKeymap.cfg
located in the FileMangler installation directory.


Important Considerations When Remapping Command Keys

Certain command-key combinations are reserved for use by the desktop environment (GNOME 2, GNOME 3, Unity, KDE, KDE Plasma, Xfce, Enlightenment and Razor-qt among others), and are not available to console-based applications.

In addition, the terminal emulation program under which FileMangler runs can affect the availability of command keys. Some key combinations may be captured by the terminal program before FileMangler (or any console application) sees them. This could cause a loss of some FileMangler functionality. To minimize such problems, disable as many terminal-specific key commands as possible. For instance, we suggest that you disable menu mnemonics, the menu access key, and most ‘accelerator’ keys such as ‘Zoom’, ‘Next Tab‘ and similar terminal emulator commands. Give special attention to the terminal preference settings for the keycode generated by the ‘BACKSPACE’ key.

FileMangler I/O (Input/Output) is controlled by the ‘ncurses’ system library which places some additional translation protocols and restrictions on the keycodes passed to an ncurses-based console application. This is reasonable because the ‘ncurses’ library must retain portability among a wide variety of platforms, but it’s something to be kept in mind.

The NcDialog-class link library enhances the keycode functionality available through the ‘ncurses’ library to provide a reasonable set of unassigned command-key combinations that are available for customizing the application interface (see below). Although these are less portable than the basic set, they have been verified to work on Wintel hardware platforms with English-language keyboards.

The following categories of command-key combinations are recognized, although keep in mind that any particular key combination may be unavailable due to the considerations described above.

  1. Printable ASCII keycodes A-Z, a-z, 0-9, space key and punctuation are accessible; however, they cannot be used as command-key combinations.
  2. The 'CTRL' modifier key in combination with a digit key or a punctuation key provides unreliable results because many of these yield the same keycode as other keys. Examples:
       The CTRL+8  combination is the same keycode as the BACKSPACE key.
       The CTRL+[  combination is the same keycode as the ESCAPE key.
       The CTRL+.  combination is the same keycode as the FULLSTOP key.
    For this reason, command-key combinations of this type should be avoided.
  3. CTRL+A through CTRL+Z, Tab, Insert, Delete, Backspace, and the arrow keys: Up, Down, Left, Right, Home, End, PageUp and PageDown are available on all keyboards that have them.
    In addition, many key combinations using keys of this group with additional CTRL, ALT and SHIFT modifiers are available.

    Function keys F01 through F12 including function-keys combined with modifier keys CTRL, ALT, SHIFT are available, although many of these are captured by the desktop environment and the terminal emulator. See below for additional information on Function keys.

    The NcDialog class on which FileMangler is built provides additional keycodes to the application.
        ALT+A through ALT+Z
        ALT+SHIFT+A through ALT+SHIFT+Z
        ALT+CTRL+A through ALT+CTRL+Z
        A variety of punctuation characters modified by ’ALT’
        A variety of punctuation characters modified by ’ALT+SHIFT’
    Again, some of these combinations may be unavailable to console-based applications on your system.

If you are uncertain about the keycodes being generated within your terminal environment, please run the NcDialog test application (packaged separately), ‘Dialog2’, test number five (5), which reports the actual keycodes being generated by your terminal. If ‘Dialog2 -5’ can see the keycode, then it is also visible to FileMangler.


Function Keys ‘F01’ through ‘F12’:

Mapping the Function Keys as application commands is discouraged.
Your Desktop environment and the Terminal window use these keys (along with their ALT, SHIFT, CTRL conditioned forms) in semi-random ways depending on your particular OS configuration.

FileMangler defines the following Function Key commands.

SHIFT+F01 key Access Online Help
F01 key (probably not available)

See Invoke Online Help.


F02 key Activate the Menu Bar

See Accessing the Menu System.
See also ALT+SHIFT+M command.

All other Function Key combinations are defined and will be recognized, but will be visible to the application only if the Desktop environment and the Terminal window ignore them.

           F01 through F12
      CTRL+F01 through CTRL+F12
     SHIFT+F01 through SHIFT+F12
CTRL+SHIFT+F01 through CTRL+SHIFT+F12

The Numeric Keypad:

When the NUMLOCK key is off, all keypad keys generate the same keycodes as the corresponding keys in the main keyboard group.

When the NUMLOCK key is on, the following keypad keys generate a unique keycode which can be assigned as FileMangler command keys:

'/' (division symbol)
'*' (multiplication symbol)
'+' (addition symbol)
'-' (subtraction symbol)
'5' (the center keypad key)

The keypad navigation keys and the special keys INSERT and DELETE generate the same keycodes as the corresponding main keyboard keys.

Note: These key definitions were obtained from all test systems; however, your particular hardware may produce different keycodes in some cases. Please see the NcDialog API, ‘Dialog2’ test application which will accurately report the keycodes generated by your system.




Next: , Previous: , Up: Top   [Contents][Index]

Installation

Installing FileMangler is a straightforward operation, whether for a single-user system or in a multi-user environment. Either way, the following step-by-step instructions will make it painless.


Prepare for Installation

Preparing for installation

  1. Download the compressed archive for the latest FileMangler release.
  2. Create an empty temporary directory and move the archive to that directory.
  3. Open a terminal window and navigate to the directory containing the archive.
    - Re-size the window to 132 columns by 35 lines (or more) for
      optimal viewing pleasure.
    - Then open a second Tab in the terminal window. This is typically
      done through the terminal’s ’File’ menu or by using the
      ‘CTRL+SHIFT+T’ shortcut key.
  4. Unpack the archive.
    - If your archive name is of the form FileMangler-n.n.nn.tar.bz2
      then: unpack using: tar -xjvf FileMangler-n.n.nn.tar.bz2
        Example: tar -xjvf FileMangler-0.2.00.tar.bz2
    This will unpack all files in the archive, placing them in the current working directory (CWD), listing each file as it is unpacked.
    - If your archive arrived in a different format, please unpack using the
     appropriate archive manager.
  5. Type the following command: cat README
    This will display a short description of the archive and any special notes about the current release.
  6. The Help document is in standard Texinfo format, so open it using the following command:
    info -f Texinfo/filemangler.info -n Installation
    This will open the Help file and bring you to the parent node of this page in the Help file. From there, follow the instructions for the type of installation you wish to do.



Installation Script

The easiest way to install FileMangler is by running the provided installation script, written in the PERL scripting language.


  1. Follow the instructions in the previous section see Prepare for Installation.
  2. Verify that the installation script is executable by setting its permission bits using the following command:
    chmod u=rwx fmginstall.pl
  3. Run the installation script:
    ./fmginstall.pl

      Don’t forget to begin your command with "./" which means
      you are executing a script in the current working directory.

    ** UNDER CONSTRUCTION **@*
    Refresh the NcDialog.a link library and header files.
    Compile the application. 
      - any object files or binary files will be deleted
      - all source files will be built and linked.
    

    By default, the application will be installed at:
    $HOME/Apps/FileMangler

      If you want to install the application in a directory other
      than the default, then specify the target directory as shown
      in the following example:
    ./fmginstall.pl /home/sam/experimental

    The specified target must exist AND you must have ’read’ and ’write’ access to it.

    The installation script will create the necessary directories if they don’t already exist and copy the needed files from your temporary directory to the installation target directory. Any existing application files in the target will be renamed as ’backup’ files ( filename~ ), before the current versions are written to the target. Any additional data in the application’s subdirectory tree will be unaffected.

    PLEASE NOTE:
    If you are not sure whether you have read/write access to your target directory, then first verify by typing:
    stat /home/sam/experimental
    Or if you want to get cute, type:
    stat /home/sam/experimental | grep 'Access: [(]'

    You should see something similar to the following:
    Access: (0700/drwx------)
    If you do not, then adjust the permissions on the target directory before installing the application. (See documentation for the 'chmod' command.)

  4. The 'fmg.sh' and 'fmg' shell script files will be copied to the last directory specified in your shell environment’s $PATH variable, typically to either '$HOME/.local/bin' or to '$HOME/bin'.

    If these scripts already exist in that directory, backup copies
    ( fmg.sh~ and fmg~ ) will be made before the new scripts are copied.

  5. A memory-resident invocation function will be defined in the file, $HOME/.bashrc. If your shell program is not bash, then this step may fail. If you are not sure what shell you are running, then simply type an invalid command such as xxx. The shell will respond with a message similar to bash: xxx: command not found... and now you know your shell program.
  6. If the installation script runs without errors, the installation is TENTATIVELY successful, but you need to test the installation as explained in See Testing Your Installation.

    When testing is complete, you may move on to install the documentation (see Install the Documentation),
    or skip to Configuration (see Configuration).





Manual Installation

Installing FileMangler Manually

** UNDER CONSTRUCTION **
If you prefer the control and the feeling of accomplishment that comes from a manual installation, or if you built the application from source code, these step-by-step instructions will guide you to a successful installation.


  1. "Don’t panic." The worst that could happen is a warning message.
  2. Unpack your archive according to the ’Prepare for Installation’ instructions in the previous section. Or if you built from source code, go to your source code directory.
  3. Select and create an installation directory
    1. The path selected should be within your own $HOME directory so that you will have read and write access to it.
    2. The preferred target is: $HOME/Apps/FileMangler
         Example: /home/sam/Apps/FileMangler
    3. The second choice would be: $HOME/FileMangler
         Example: /home/sam/FileMangler
    4. However, any directory to which you have both read and write access will work correctly.
    5. Then create the directory structure.
      Example:
          cd ~
          mkdir Apps
          mkdir ./Apps/FileMangler
  4. Copy the following files from your archive or source directory to the installation directory:
        cd (archivedir)
        cp —preserve FileMangler ’~/Apps/FileMangler/.’
        cp —preserve FmConfig ’~/Apps/FileMangler/.’
        cp —preserve FileMangler.cfg ’~/Apps/FileMangler/.’
        cp —preserve filemangler.info ’~/Apps/FileMangler/.’
        cp —preserve fmg.sh ’~/Apps/FileMangler/.’
        cp —preserve fmg ’~/Apps/FileMangler/.’

    Go to the installation directory:
        cd ~/Apps/FileMangler


    Be sure that the permission bits for the executable binaries and shell scripts are set to execute. Example:
        chmod u=rwx,g=rx,o=rx FileMangler
        chmod u=rwx,g=rx,o=rx FmConfig
        chmod u=rwx,g=rx,o=rx fmg.sh
        chmod u=rwx,g=rx,o=rx fmg

  5. If you have chosen a non-default installation path, then you will need to edit the two shell-script files to adjust the path to your installation directory. If you selected the default installation path ($HOME/Apps/FileMangler), then you may skip this step.
  6. Copy the two shell scripts to a directory on the executable search path, so they are available for execution from any working directory.
    In general, this should be the last entry in the PATH environment variable. To view the $PATH variable, type:
        echo $PATH

    The most common targets are: '$HOME/bin' OR '$HOME/.local/bin'
    or for a single-user system: '/usr/bin' OR '/usr/local/bin"


    Using the string following the last colon character (’:’) in the PATH, copy the shell-script files to the target. Example:
        cp —preserve fmg.sh ’/home/sam/.local/bin/.’
        cp —preserve fmg ’/home/sam/.local/bin/.’


    Verify that the operation was successful by going to your home directory:
        cd ~
    Then type the following:
        fmg.sh
    The FileMangler application should start successfully. If not, then be sure that the shell scripts are on the executable path AND that they contain the correct path to the binary executables i.e. to your installation directory.

  7. Create a memory-resident function to invoke FileMangler.

    When the shell scripts can successfully invoke the FileMangler application, then the application is almost fully functional; HOWEVER, one more step is needed.

    Because of the way Linux/UNIX terminals work, the fork system call is used to execute the invocation script through a child process of the process that controls the command prompt. What this means in practical terms is that the ALT+q command (exit application to current working directory) will not function properly. To correct this behavior, a memory-resident function is used to indirectly call the shell script. This allows the script to be executed by the main command-line process, and the ALT+q command will function as designed.

    Memory-resident functions are defined in the $HOME/.bashrc file, or its equivalent file for non-bash shells. If you are the least bit nervous about editing a system file, then MAKE A BACKUP COPY of the file before editing it. This file belongs to you, so you do not need to be the ’SUPERUSER’ in order to edit the file.

    1. Open the .bashrc file with your favorite text editor.
    2. Go to the end of the file and add the following text:
      # * Function to invoke FileMangler *
      fmg() {
             source ’fmg.sh’
            }
    3. Save and close the file.
  8. When all the above steps have been completed, then the installation is TENTATIVELY successful, but you need to test the installation as explained in See Testing Your Installation.

    When testing is complete, you may move on to install the documentation (see Install the Documentation),
    or skip to Configuration (see Configuration).





Multi-user Installation

Installing FileMangler in a multi-user environment is very similar to the ’Manual Installation’ described in the previous section, with the following exceptions:

  1. There is only one copy of the binary executable files, ’FileMangler’ and ’FmConfig’ which are located in a globally-visible directory on the executable path, typically /usr/local/bin
    A copy of the ’filemangler.info’ documentation file must also reside in this directory.
  2. Each user has his or her own FileMangler installation directory which contains the following subdirectories and files:
        - A Temp directory.
        - A Backup directory.
        - A copy of the configuration file, ’FileMangler.cfg’.
    ** UNDER CONSTRUCTION **
  3. ** UNDER CONSTRUCTION **
  4. Certain special requirements exist in the installation for a ’SUPERUSER’ (’root’ user) account.
    • Installation Directory
      The ’SUPERUSER’ account does not have a normal $HOME directory similar to a regular user account. By default, the ’SUPERUSER’ $HOME directory is /home, which is an inappropriate location for installing an application. Therefore, it is recommended that the ’SUPERUSER’ installation be placed somewhere in the user space.
      The associated shell scripts, configuration file, (and optionally, the memory-resident function) should be adjusted accordingly.

      It is recommended that the user-space directory be created as: /home/admins or something similar, and be owned by ’root’. Then the installation directory would become: /home/admins/Apps/FileMangler, also owned by ’root’.
      ** UNDER CONSTRUCTION **

    • Memory-resident function for use by the ’SUPERUSER’
      For full application functionality, an appropriate memory-resident function must be added to the ’SUPERUSER’ account’s bashrc file (or equivalent file for other shell programs). See Manual Installation, for a discussion of adding a memory-resident function for FileMangler invocation.

      If you will be using the sudo command to invoke the application with ’root’ privilege, then please note:

      • The $PATH environment variable for the sudo command may not include all the same search directories that are available when logged in as the ’SUPERUSER’; therefore, a copy of the fmg and fmg.sh shell scripts should be placed where the sudo command can find them.
      • The sudo command cannot easily be made to see a memory-resident function, so if invoked through sudo, the command to exit the application into the current working directory (CWD) may not be available; however, all other commands will operate as described. See Exit the Application, for additional information.
    • C ** UNDER CONSTRUCTION **
    • In these examples, the application installation is in a user-space directory, /home/admins which would be owned by the ’SUPERUSER’. The configuration file would then contain appropriate references to the directories within this space which the application will use for writing its temporary files, and if needed, an alternate Trashcan path for the ’SUPERUSER’.

      Note also that any environment substitutions used in the configuration file (for instance: $HOME) must take into account the working environment of the ’SUPERUSER’.

    • In addition, the $PATH environment variable for the sudo command may not include all the same search directories that are available when logged in as the ’SUPERUSER’; therefore, a copy of the fmg and fmg.sh shell scripts should be placed where the sudo command can find them.
    • Finally, neither the ’SUPERUSER’ environment nor the sudo command’s environment will have the memory-resident function needed for the application to exit into the current-working directory. See Exit the Application, however, all other commands will operate as described.

      An appropriate memory-resident function can be added to the ’SUPERUSER’ bashrc login script; however, the sudo command cannot easily be made to see a memory-resident function.

  5. The Texinfo documentation is installed in the usual way. See the documentation section See Install the Documentation, for details.

Install the Documentation

Installing the documentation for FileMangler is not done by the automated installation script, because it requires ’SUPERUSER’ (’root’) user privelege.


Installation of the FileMangler documentation into the Texinfo (info) database hierarchy requires editing a system file. This is not difficult but be sure to MAKE BACKUP COPIES of all the files you are about to modify or replace in case there are unexpected results.

  1. Open a terminal window
  2. Navigate to the application’s installation directory:
         cd ~/Apps/FileMangler

    (Substitute the correct path for your installed application.)

  3. Login as the ’SUPERUSER’ by entering the following commands:
         su
         (enter password for ’root’ when prompted)
         whoami
    This sequence should verify that you are now logged in as ’SUPERUSER’.
  4. Locate the master Info system directory file: ’dir’.
    Typically, ’dir’ for local users is located at:
         /usr/local/share/info/dir
    and the global ’dir’ file for all users is located at:
         /usr/share/info/dir

    The following instructions update the local ’dir’ file; however, you may insert the FileMangler menu entry into either of these files.

  5. Copy the Help file to the Info directory.
    cp --preserve=timestamps ./filemangler.info /usr/local/share/info/.
  6. Navigate to the Info directory
         cd /usr/local/share/info
  7. Verify that the Help file was copied correctly.
         ls -l filemangler.info
  8. Add the menu entry
    The ’install-info’ utility is used to modify the Info-system directory file. As ’SUPERUSER’ you can install ’filemangler.info’ with the following command:
    install-info --dir-file=dir --info-file=filemangler.info
       --name=FileMangler --debug
    

    Note that this is a single command, typed all on one line even though it may look strange as printed here.

  9. Verify the install
    Type the following command:
    'info'

    This will open the top-level menu of the Info system. Verify that your new entry is beautifully displayed and that the new Info document is accessible:
    First, press the forward-slash key ’/’ (search)
    Then, type: ’FileMangler’ (no quote marks, and press ENTER)
    The highlight should now be on the menu entry.
    Press ENTER (RET) key again, and verify that the main page of the FileMangler documentation is displayed.
    Then, exit the Info system (’q’).

  10. If the menu item is not present OR if the new Info document is not accessible, then try the installation again.

    If you want to remove the menu entry, use the command:

    install-info --dir-file=dir --info-file=filemangler.info
       --name=FileMangler --remove --debug
    

    Again, this is a single command, typed all on one line.

  11. Return to user mode
    Type: 'exit'

    This will exit the ’SUPERUSER’ mode, and you will once again
    become mild-mannered Clark Kent.


    Congratulations! The FileMangler documentation has been installed.

Note that installation of the ’filemangler.info’ file into the Info system is not necessary for invoking Help from within the FileMangler application itself because FileMangler uses its local copy of the file located in the application’s installation directory.





Testing Your Installation

To verify that your FileMangler installation was successful, please follow this simple procedure.


Testing the Installation

  1. When your automated or manual installation is complete, please close all applications and log out of your current session.
  2. Log in again, so the system can read the new memory-resident function from your '.bashrc' file.
  3. Open a terminal window. For testing, be sure that the terminal window size is at least 80 columns by 25 rows.
  4. To verify that the 'fmg' function is now in memory, use the command: 'declare -f fmg'.
  5. Navigate to a directory that contains NO FileMangler files, for example, your home directory:
    'cd ~'
  6. Note the directory you are in, using:
    'pwd'
  7. Invoke the application:
    'fmg -Ws'

    If FileMangler starts without warnings, then continue to the next step.


    Otherwise, if FileMangler displays a warning on startup, you will need to verify the items listed in the next section ’Debugging the Installation’, and correct any problems you may find before continuing with the test.

  8. Test the application’s access to the local Help file by executing the Help, command-key sequence: SHIFT+F01 (press and hold the SHIFT key, then press the F01 key, then release both keys).
      For more information:
        See Default Key Bindings, or
        see Help Menu).
    If the Info engine correctly displays the first page of this document, then the local Help file is accessible.
    Close the Help file by pressing the ’q’ (Quit) key.
  9. Use the arrow keys to place the highlight on your ’Documents’ directory or any subdirectory name and press the ’ENTER" (’RET’) key to display the contents of that directory.
  10. Press the 'ALT+q' command-key combination to exit the application into the current working directory (CWD).
  11. Again note the directory you are in, using:
    'pwd'

    You should be in the $HOME/Documents directory (or directory you selected), NOT in your original $HOME directory.

    If you are in the expected directory, your installation is complete and you may move on to install the documentation.
    See Install the Documentation,
    (or skip to Configuration see Configuration).
    Otherwise, try, try again.

  12. If you are testing the application as the ’SUPERUSER’, then certain additional or different tests may be required. We don’t hold your hand for this, but see Multi-user Installation for details on creating a ’SUPERUSER’ installation.
  13. Key bindings defined for your terminal window may affect some functionality within FileMangler, specifically the BACKSPACE, DELETE and certain other keys that arrive at the terminal as ’escape sequences’. If a key is not yielding the response that you expect, the first place to look is at the terminal window’s key-binding settings. See also See Customizing Key Commands, for customizing the application’s key map.
  14. Color definitions within a terminal window are different for every system distribution. Therefore, you may need to experiment a bit to match the terminal window’s colors with the colors for which FileMangler was designed.
    Note that individual ’color schemes’ may be previewed in the FileMangler Configuration utility, so changes to the terminal window’s color map will be immediately reflected in the display.
    See also See Configuration, for ’color scheme’ selection.

    FileMangler’s color schemes have been defined under the GNOME terminal v:3.10.2, 16-color ’Linux Console’ color group as distributed under the Fedora 20 release. This is arguably the most common pre-defined color map for Linux distributions. As defined, FileMangler’s color schemes are high-contrast, easily readable and subjectively pleasing; however, your mileage may vary.

    For the GNOME terminal, color attributes may be selected either by specifying a pre-defined group OR by specifying each color separately (not really recommended). See the GNOME terminal’s ’Edit’ menu, ’Profile Preferences’, and click on the ’Colors’ tab.

    For the Konsole terminal, color attribute settings are considerably more flexible, although the basic color-attribute groups are very similar (if not identical) to those defined for GNOME. See the Konsole ’Settings’ menu, ’Manage Profiles’, and click on the ’Edit Profile’ button and then the ’Appearance’ tab.

    Other terminal emulators such as CLI Companion, Guake, Terminator, Tilde, Yakuake and others have similar color-configuration interfaces. Please refer to the documentation for your terminal.

    FileMangler also runs happily under vanilla color XTERM, although setting the XTERM color map is beyond the scope of this document.


Debugging the Installation

The FileMangler installation sequence is quite a simple one, (after all, this isn’t Windows(tm)). The following descriptions assume the default installation. If you have chosen to do a custom installation, please mentally substitute the appropriate path names.


The only commands you will need are:

'cat'     (display file contents)
'cd'      (change directory),
'chmod'   (modify file permissions)
'cp'      (copy a file),
'grep'    (search file contents),
'mkdir'   (create a subdirectory).
'declare' (display memory-resident functions)
'info'    (invoke online help engine)

  If you are not comfortable using the Linux/UNIX command line utilities, please seek the help
  of your friendly neighborhood geek or any reasonably intelligent 12-year-old child.


All commands are executed by entering the specified text (excluding the enclosing quote marks) and then pressing the ENTER(RET) key. It is assumed that you already have permission to copy and modify files within your own HOME directory tree.


            All commands and file names ARE CASE SENSITIVE!


  1. Verify that the application’s subdirectory tree exists, and that the application files are in their proper place.
    'ls -l yourinstallationpath'
    Example: 'ls -lg $HOME/Apps/FileMangler'
    Output should look something like this:
    -rwxrwxr-x. 1 sam 1374130 Dec 21 03:20 FileMangler
    -rw-rw-r--. 1 sam   14933 Aug 13 12:33 FileMangler.cfg
    -rw-rw-r--. 1 sam  588934 Jan 15 19:57 filemangler.html
    -rw-rw-r--. 1 sam  401559 Apr 15 19:57 filemangler.info
    -rwxrwxr-x. 1 sam  786822 Dec 21 03:23 FmConfig
    -rwxr-xr-x. 1 sam     932 Dec 26 20:36 fmg
    -rwxr-xr-x. 1 sam     932 Dec 26 20:36 fmg.sh
    
  2. Verify that the ’Alternate Trashcan’ section of the configuration file (if used) is set appropriately.
    See Configuration, for more information.
  3. Verify that the ’fmg.sh’ and ’fmg’ shell scripts exist in one of the directories on your execution path AND that the ’execute’ bit is set for each.
    Type: 'echo $PATH'
    
    then, for the path you selected during installation,
    Type: 'ls -l yourbinpath/fmg*'
    
    Example Output:
        -rwxr-xr-x. 1 sam sam 932 Dec 26 20:36 fmg
        -rwxr-xr-x. 1 sam sam 932 Dec 26 20:36 fmg.sh
           ^--- (owner 'execute bit' is here)
    
  4. Verify that the 'fmg' memory-resident function exists.
    'declare -f fmg'
  5. Verify that the online Help file is visible to the Info engine.
    'info filemangler'
  6. Then run through the steps for testing the installation again.




Building from Sources

Building the FileMangler application from source code.

  1. The FileMangler application as well as the NcDialog link library upon which the application dialog is built are all written in GNU C++ (gcc 4.8.0 and above), using the ’-std=gnu++11’ switch.
  2. Building FileMangler from source code requires the following link libraries:
    ‘NcDialog API’ (v:0.0.29 or above)
       Available as a separate download from author's website
       (Install and build before building FileMangler.)
    ‘FileDlg.a’
       Created as part of the FileMangler build process,
    ‘ncursesw’ (v:5.9 or above)
       Included with all Linux distributions
       (but not always installed by default)
    ‘pthread’ (v:2.18 or above)
       Distributed with the GNU compiler.
    
  3. Running FileMangler also requires access to the following shared (dynamic-load) libraries or their equivalents:
    linux-vdso.so.1 =>  (0x00007fff05d39000)
    libncursesw.so.5 => /lib64/libncursesw.so.5 (0x0000003a1a400000)
    libtinfo.so.5 => /lib64/libtinfo.so.5 (0x0000003a2fc00000)
    libpthread.so.0 => /lib64/libpthread.so.0 (0x0000003a19800000)
    libstdc++.so.6 => /lib64/libstdc++.so.6 (0x0000003a28000000)
    libm.so.6 => /lib64/libm.so.6 (0x0000003a1a000000)
    libgcc_s.so.1 => /lib64/libgcc_s.so.1 (0x0000003a1bc00000)
    libc.so.6 => /lib64/libc.so.6 (0x0000003a19000000)
    libdl.so.2 => /lib64/libdl.so.2 (0x0000003a19400000)
    /lib64/ld-linux-x86-64.so.2 (0x0000003a18c00000)
    

    Please refer to the ’ldd’ utility to discover how this information is obtained.

    If the load libraries exist on your system, but are not visible during the build, you may need to define the LD_LIBRARY_PATH environment variable which instructs the linker to search the specified path for the needed libraries.

  4. If you have not done so already, download, unpack and build the:
    'NcDialog API' library

    If you have already built the NcDialog API library, then you may skip this step.

    This package is available from the author’s website as a separate download.

  5. Unpack the source code archive into your work directory.
    We recommend that your work-directory tree look something like this:
       .../NcDialog/Dialog1     <== NcDialog source lives here
                   /Dialog2
                   /Dialog3
                   /Dialog4
                   /Dialogw
                   /Dialogx
       .../FileMangler          <== FileMangler source lives here
                   /Archive     <== (previous source code versions)
                   /Install     <== (for creating xxx.tar.bz2)
                   /Texinfo     <== FileMangler documentation lives here
    

    This layout will allow the ’refreshlib’ section in the Makefile to work properly:
    gmake refreshlib
    This command copies the latest NcDialog.a library and associated header files to the FileMangler directory.

  6. Make your ‘FileMangler’ directory the current working directory.

    (The primary makefile is ‘Makefile’, and a secondary makefile ‘MakeFmConfig’ is called indirectly from inside ‘Makefile’.)

  7. Invoke the build using the following command:
    'gmake all'
    NOTE: Building FileMangler is done with the compiler’s most sensitive
          warning level, and should build with no errors and no warnings. 
          We are, after all, not just animals pooping in the forest.
    
  8. When the build is complete, follow the instructions for:
    See Manual Installation.



Next: , Previous: , Up: Top   [Contents][Index]

Technical Support

Please Note: All trademarks and service marks mentioned in this
document are the entirely-too-proprietary property of their
respective owners, and this author makes no representation of
affiliation with or ownership of any of the damned things.

Contact

FileMangler (fmg) binary, source code and associated Texinfo 
documentation were written and are maintained by:

                         Mahlon R. Smith,
                      The Software Samurai
                 Beijing University of Technology
                 on the web at: www.SoftwareSam.us 

For bugs, suggestions, periodic updates, or possible praise, 
please post a message to the author via website.

The author wishes to thank everyone for their intelligent, kind
and thoughtful responses.  (ranters I can live without)



To submit a technical support request, please start the FileMangler 
application.
— Select ‘Help About’ from the ‘Help’ menu.
— Select the ‘Support Information’ pushbutton.
— In the sub-dialog, select ‘Save To File’.
A file containing the basic support information will be written to 
the current working directory: 
                  FileMangler_SupportRequest.txt
Open this file in your favorite text editor and add a description of 
the issue you would like to have addressed.

If you have been unable to successfully compile and run the application, 
of course you will not be able to submit the automatically captured 
information, so please include as much of the following as possible:
— FileMangler version number
— NcDialog library version number
— The ncursesw link library version
— System locale (type ‘echo $LANG’)
— The GCC/G++ compiler verison (type ‘gcc --version’)
— A list of dynamic libraries (type ‘ldd FileMangler’)
— Name of the shell program (bash, etc.)
— Name of terminal program (GNOME, Konsole, etc.)
— A full description of the problem encountered.

Submit the completed form by posting to the website listed above.

Please see Gathering Tech Support Data for additional information.


History

FileMangler (fmg) began life in pre-historic times as an experiment in drawing windowed data to the MS-DOS(tm) console. Your author had just taken delivery of a super-cool new 16MHz system with 16Mb of RAM and an amber-pixeled monochrome monitor which was the envy of our fellow Silicon Valley geeks. Frankly, I was drunk with power, and wanted to see if the system could run something more exciting than Emacs and the command-line debugger. Therefore, FileMangler is designed with a menu-driven user interface which was frankly not easy to implement in DOS. The venerable, MS-DOS(tm) ’List’ file manager by Vernon Buerg had only recently been released, and although it was a capable utility, it was a bit ridiculous to expect executives and other lower forms of life to master its Emacs-style command-key interface.

Although the DOS version of FileMangler was not generally released, it enjoyed moderate success in several companies for which I worked or consulted in those early days, but had faded away by the time Windows95(tm) was released.

At about this time, IBM(tm) unceremoniously dumped OS/2 Warp(tm), so I abandoned the DOS/Windows(tm) world, and began looking for alternatives to the inadequate file management utilities, both console and GUI, of early Redhat Linux(tm). A curses-based version of FileMangler seemed a promising solution.

Thus began a long journey upon which you are now a fellow traveler.  
                   Welcome to FileMangler!  :-)

By the same author

  • NcDialog Application Programming Interface (API) library.
    The NcDialog API forms the basis for most of our other software projects. It provides the application developer with the tools to create dialog-based console applications, without the need to learn anything about the complexities of the underlying ‘ncurses’ C-language library.

    Console applications have always been the most efficient and easily-implemented of computer programs. What they lacked was a friendly and visually-pleasing user interface.

    With the NcDialog API, console applications can now be used and understood by experts and novice users alike.

  • Console Trashcan (ctrash) is a simple, console-based (command-line) utility for managing the contents of your local Trashcan. Send items to the trash, restore items from the trash, report the trashcan contents, and empty the trash. ’ctrash’ is designed as a safer, and more flexible alternative to the ’rm’ and ’rmdir’ commands.

  • Infodoc, post-processing and CSS style for HTML documents created by the Texinfo (makeinfo) utility. If you write documentation using the Texinfo/makeinfo documentation engine, AND if you care at all about what your documentation looks like, then you really do need the ‘infodoc-styles.css‘ definition file and the ‘idpp’ HTML post-processor.

    The HTML version of this document was formatted using ‘idpp’ and is displayed using the ‘infodoc-styles.css‘ definition file. Many more examples are available on the author’s website.

  • gString text internationalization tool.
    gString implements a C++ class that may be integraged into any application for smooth and painless text formatting, and for converting between UTF-8 and ‘wchar_t’ (wide) character encoding.

    The gString class is lightweight, consisting of one C++ source module and one header file. The gString class may be directly integrated into an application, or may be built as a link library.
    The gString class is also embedded within the NcDialog API library (see above).

  • Source Profiler (srcprof) is a source code analysis tool for determining the ‘maintainability’ of source code modules.

    ‘srcprof’ can be used to profile source code for high-level languages such as C, C++ and Java, as well as various assembly languages and scripting languages such as Python, Perl and Ruby. For a complete list of currently-supported source languages, please see the Source Profiler documentation.

    ’srcprof’ can be used both as a productivity-measurement tool and as a tool for testing source code quality based on an evaluation of its ‘maintainability’.

    Source Profiler is a console-based utility, which runs as either a pure, command-line utility, OR as a dialog application based on the NcDialog API.

  • DVD Repair (dvdrep) is a utility for exploring the contents of a damaged DVD video disc and rescuing as much of the data as possible.

    ‘dvdrep’ can be used to rescue data from any non-encrypted DVD video source disc that is formatted using the Universal Disc Format (UDF) filesystem (as all commercially produced DVD movies are).

    ‘dvdrep’ takes a layered approach to the analysis of the source disc. A detailed log file is maintained for each step of the process in case manual intervention is needed at a later step.

    DVD Repair is based on the NcDialog API, and thus will run in almost any GNU/Linux or UNIX terminal environment.

  • tbXClip clipboard access for console applications.
    Access to the system clipboard by console applications has traditionally been tedious, time-consuming and fragile.

    tbXClip utilizes the new XML interface to the X-server to provide simple, robust communication between the application and the system clipboard.

  • crcPlus (crcplus) is a reference model and demonstration program for implementating CRC (Cyclic Redundancy Check) data error dectection. crcPlus provides a reliable reference algorithm for verifying the function of other CRC generators and decoders as well as providing the tools to build a fully customizable hash table (lookup table) for creating your own high-speed CRC generator.
  • Taggit (taggit) is a demonstration program written for students, or for anyone who wishes to create a console application with a multilingual user interface.

    Conceptually, Taggit is an audio-file tag editor (metadata editor), and is album oriented rather than file oriented so that all audio files in an album may be edited simultaneously.

    Taggit is not intended as a full-featured tag editor; for instance, Taggit does not access online databases of audio tag information. Taggit fully supports tag editing for two audio formats: MP3 and OGG/Vorbis.

    The OGG/Vorbis I specification is supported for all text tags in '.ogg' and '.oga' audio files.

    For MP3 audio files, all tag frames of the ID3v2.3 standard are supported, along with some features of ID3v2.4, such as support for UTF-8 text encoding which enables writing text tags in any language.

    Taggit is implemented in four(4) user interface languages: Español (Spanish), Zhōngwén (中文) (Chinese, simplified), Tiếng Việt (Vietnamese) and English (U.S.). Additional user interface languages (both LTR and RTL) may be added with minimum effort.

  • Various other Linux utilities designed as academic exercises are also available for student use. For example: interprocess communication pipes, FIFOs, sockets, shared memory blocks, multi-threading, the ’Sleeping Barber’ problem and so on.
    These cannot be considered as production-worthy, but they demonstrate the concepts in simple terms.



Tech Notes

  1. FileMangler is built and tested under Fedora Linux and Ubuntu Linux
    running on various WinTel (x86) hardware platforms.
      NOTE: If you are successfully (or not so successfully) running
            FileMangler under another Linux/UNIX distribution, please
            send the author a note about your experiences.
  2. FileMangler is written entirely in C++, using what we hope is an easy-to-read, self-documenting and easy-to-maintain style.
         For additional technical information, Please see
         the section on building from source code.
         See Building from Sources.
  3. External Libraries
    Every effort has been make to retain independence from third-party function libraries. Although libraries, such as the GNOME toolkit, Kdebase or LibXML are often useful and sometimes indispensable for software development projects, they may increase by orders of magnitude the difficulty in building an application from source code. For this reason, FileMangler is built entirely without third-party libraries. Only two link libraries are used in the build:
         ncursesw
         pthread
    Both of these libraries are pre-installed on most Linux/UNIX systems. For the required library versions, please see See Building from Sources.

    The user interface dialog library around which FileMangler is built is:
         NcDialog.a
    The NcDialog API library is by the same author and is described in see by the same author.

  4. FileMangler’s low-level file-management functionality comes from a combination of C/C++ library functions, system calls, and invocation of various command-line utilities whose output is redirected and interpreted within the application. As such, FileMangler can smoothly accomplish tasks which would be difficult to implement in a GUI environment.
  5. Online Help
    Online Help from within the application is accessed by calling the ’Info’ documentation system. To simplify installation, FileMangler does not require that the Help file 'filemangler.info' be installed into the Info system menu, but installation of the documentation is recommended.
    See Install the Documentation.
  6. The FileMangler Clipboard
    Linux/UNIX systems have a complex system clipboard for copy/move operations on text, graphics, files and more.
          FileMangler DOES NOT use the system clipboard
                  for file-management operations.
    
          The system clipboard is used only for copy/cut/paste 
          of text data to and from textbox controls.
    

    FileMangler internally implements a simple, single-purpose clipboard which is used to specify filenames and directory names which will be operated on by subsequent commands.

    The contents of the FileMangler clipboard may be viewed from within the application, but its contents are not available to other applications. (see Other Commands)

    Internally, the FileMangler clipboard is simply a (rather complex) doubly-linked list of descriptors for all files, directory names and directory contents which indicates the location and attributes of those items. If you are interested in the actual descriptors, please download the FileMangler source code and see the class definitions in FMgr.hpp.

  7. System Trashcan
    The location of the Trashcan for provisionally-deleted files is system dependent, AND there may be multiple Trashcans defined: one for each local user, as well as the SUPERUSER (system-wide) Trashcan and possible Trashcans tied to networked drives, removable drives and for special operations.

    The application takes its best guess at the Trashcan location.
    For Redhat(tm)-based, Debian-based and SUSE-based distributions, the default user-space Trashcan is defined as:
        ‘$HOME/.local/share/Trash’
    but other user-space locations are possible, and the SUPERUSER’s Trashcan could be almost anywhere.

    If the Trashcan is not found on application start-up, then you will need to specify the actual Trashcan location in the configuration file. See Configuration.
    To locate the little bugger, try the following search, keeping in mind that ’Trash’ directories may or may not be ’hidden’ files i.e. ’Trash’ or ’.Trash’
        ‘cd /’
        ‘sudo find -name *Trash’

  8. Mouse Interface
    The NcDialog library on which FileMangler is based includes support for a mouse-based user interface, and optional mouse support for the FileMangler application is available, but not necessary for full functionality.
  9. Start-up Sequence
    Because the startup sequence requires inter-process communication, a shared memory area is established between processes. It has been observed that if the application is invoked before the operating system is fully awake, the shared-memory allocation will sometimes fail with:
              "Error! Unable to allocate shared-memory space" 
    This is not a problem with FileMangler itself, but rather an unavailability of system resources. Simply count to three and invoke the application again.

    To view the start-up sequence before the application dialog opens, please see 'p' option, to pause for a moment before opening the window.

  10. Alphabetical Sorting
    Alphabetical sorting of filenames and other text data requires a design decision. True alphabetical sorting that supports all languages and locales consumes significant system resources and is unbearably slow.

    Most filenames will be in a single language, or a small number of languages at most, which will be correctly sorted according to the rules of your system’s locale. For this reason, we have implemented alphabetical sorting using a somewhat less accurate, but fast and lightweight method.

    • Within the character set of a given language, sorting will be correct. However, mixed-language sorting may sometimes appear odd because the character sets of different languages are related numerically, rather than alphabetically.

      As an example, your author routinely works in both English and Chinese. All Chinese characters are numerically greater than English characters, and Chinese filenames will therefore be grouped together following the English filenames.

    • Case sensitivity (uppercase/lowercase) follows the rules of the locale specified by the system, so sorting text data in the language(s) of that locale will be correct, but case sensitive sorting for languages not supported by your locale may not be as you would expect.

    In summary, unless you, like this author edit papers in multiple languages for peer-reviewed journals, (or you work as a United Nations translator), alphabetical sorting will probably never be an issue.




Next: , Previous: , Up: Top   [Contents][Index]

Copyright Notice

The FileMangler application binary and source code are released
under the GNU General Public License (GPL),
and the user documentation (this document) is released 
under the GNU Free Documentation License (FDL).

Copyright © 2005 - 2017
              Mahlon R. Smith, The Software Samurai


This manual describes version 0.0.35 of FileMangler.


  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.3
  or any later version published by the Free Software Foundation;
  with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
  Texts.  A copy of the license is included in the section entitled 
  "GNU Free Documentation License".

GNU General Public License

Version 3, 29 June 2007
Copyright © 2007 Free Software Foundation, Inc. http://fsf.org/

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.

Preamble

The GNU General Public License is a free, copyleft license for software and other kinds of works.

The licenses for most software and other practical works are designed to take away your freedom to share and change the works. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change all versions of a program—to make sure it remains free software for all its users. We, the Free Software Foundation, use the GNU General Public License for most of our software; it applies also to any other work released this way by its authors. You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for them if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs, and that you know you can do these things.

To protect your rights, we need to prevent others from denying you these rights or asking you to surrender the rights. Therefore, you have certain responsibilities if you distribute copies of the software, or if you modify it: responsibilities to respect the freedom of others.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must pass on to the recipients the same freedoms that you received. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

Developers that use the GNU GPL protect your rights with two steps: (1) assert copyright on the software, and (2) offer you this License giving you legal permission to copy, distribute and/or modify it.

For the developers’ and authors’ protection, the GPL clearly explains that there is no warranty for this free software. For both users’ and authors’ sake, the GPL requires that modified versions be marked as changed, so that their problems will not be attributed erroneously to authors of previous versions.

Some devices are designed to deny users access to install or run modified versions of the software inside them, although the manufacturer can do so. This is fundamentally incompatible with the aim of protecting users’ freedom to change the software. The systematic pattern of such abuse occurs in the area of products for individuals to use, which is precisely where it is most unacceptable. Therefore, we have designed this version of the GPL to prohibit the practice for those products. If such problems arise substantially in other domains, we stand ready to extend this provision to those domains in future versions of the GPL, as needed to protect the freedom of users.

Finally, every program is threatened constantly by software patents. States should not allow patents to restrict development and use of software on general-purpose computers, but in those that do, we wish to avoid the special danger that patents applied to a free program could make it effectively proprietary. To prevent this, the GPL assures that patents cannot be used to render the program non-free.

The precise terms and conditions for copying, distribution and modification follow.

TERMS AND CONDITIONS

  1. Definitions.

    “This License” refers to version 3 of the GNU General Public License.

    “Copyright” also means copyright-like laws that apply to other kinds of works, such as semiconductor masks.

    “The Program” refers to any copyrightable work licensed under this License. Each licensee is addressed as “you”. “Licensees” and “recipients” may be individuals or organizations.

    To “modify” a work means to copy from or adapt all or part of the work in a fashion requiring copyright permission, other than the making of an exact copy. The resulting work is called a “modified version” of the earlier work or a work “based on” the earlier work.

    A “covered work” means either the unmodified Program or a work based on the Program.

    To “propagate” a work means to do anything with it that, without permission, would make you directly or secondarily liable for infringement under applicable copyright law, except executing it on a computer or modifying a private copy. Propagation includes copying, distribution (with or without modification), making available to the public, and in some countries other activities as well.

    To “convey” a work means any kind of propagation that enables other parties to make or receive copies. Mere interaction with a user through a computer network, with no transfer of a copy, is not conveying.

    An interactive user interface displays “Appropriate Legal Notices” to the extent that it includes a convenient and prominently visible feature that (1) displays an appropriate copyright notice, and (2) tells the user that there is no warranty for the work (except to the extent that warranties are provided), that licensees may convey the work under this License, and how to view a copy of this License. If the interface presents a list of user commands or options, such as a menu, a prominent item in the list meets this criterion.

  2. Source Code.

    The “source code” for a work means the preferred form of the work for making modifications to it. “Object code” means any non-source form of a work.

    A “Standard Interface” means an interface that either is an official standard defined by a recognized standards body, or, in the case of interfaces specified for a particular programming language, one that is widely used among developers working in that language.

    The “System Libraries” of an executable work include anything, other than the work as a whole, that (a) is included in the normal form of packaging a Major Component, but which is not part of that Major Component, and (b) serves only to enable use of the work with that Major Component, or to implement a Standard Interface for which an implementation is available to the public in source code form. A “Major Component”, in this context, means a major essential component (kernel, window system, and so on) of the specific operating system (if any) on which the executable work runs, or a compiler used to produce the work, or an object code interpreter used to run it.

    The “Corresponding Source” for a work in object code form means all the source code needed to generate, install, and (for an executable work) run the object code and to modify the work, including scripts to control those activities. However, it does not include the work’s System Libraries, or general-purpose tools or generally available free programs which are used unmodified in performing those activities but which are not part of the work. For example, Corresponding Source includes interface definition files associated with source files for the work, and the source code for shared libraries and dynamically linked subprograms that the work is specifically designed to require, such as by intimate data communication or control flow between those subprograms and other parts of the work.

    The Corresponding Source need not include anything that users can regenerate automatically from other parts of the Corresponding Source.

    The Corresponding Source for a work in source code form is that same work.

  3. Basic Permissions.

    All rights granted under this License are granted for the term of copyright on the Program, and are irrevocable provided the stated conditions are met. This License explicitly affirms your unlimited permission to run the unmodified Program. The output from running a covered work is covered by this License only if the output, given its content, constitutes a covered work. This License acknowledges your rights of fair use or other equivalent, as provided by copyright law.

    You may make, run and propagate covered works that you do not convey, without conditions so long as your license otherwise remains in force. You may convey covered works to others for the sole purpose of having them make modifications exclusively for you, or provide you with facilities for running those works, provided that you comply with the terms of this License in conveying all material for which you do not control copyright. Those thus making or running the covered works for you must do so exclusively on your behalf, under your direction and control, on terms that prohibit them from making any copies of your copyrighted material outside their relationship with you.

    Conveying under any other circumstances is permitted solely under the conditions stated below. Sublicensing is not allowed; section 10 makes it unnecessary.

  4. Protecting Users’ Legal Rights From Anti-Circumvention Law.

    No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention of such measures.

    When you convey a covered work, you waive any legal power to forbid circumvention of technological measures to the extent such circumvention is effected by exercising rights under this License with respect to the covered work, and you disclaim any intention to limit operation or modification of the work as a means of enforcing, against the work’s users, your or third parties’ legal rights to forbid circumvention of technological measures.

  5. Conveying Verbatim Copies.

    You may convey verbatim copies of the Program’s source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice; keep intact all notices stating that this License and any non-permissive terms added in accord with section 7 apply to the code; keep intact all notices of the absence of any warranty; and give all recipients a copy of this License along with the Program.

    You may charge any price or no price for each copy that you convey, and you may offer support or warranty protection for a fee.

  6. Conveying Modified Source Versions.

    You may convey a work based on the Program, or the modifications to produce it from the Program, in the form of source code under the terms of section 4, provided that you also meet all of these conditions:

    1. The work must carry prominent notices stating that you modified it, and giving a relevant date.
    2. The work must carry prominent notices stating that it is released under this License and any conditions added under section 7. This requirement modifies the requirement in section 4 to “keep intact all notices”.
    3. You must license the entire work, as a whole, under this License to anyone who comes into possession of a copy. This License will therefore apply, along with any applicable section 7 additional terms, to the whole of the work, and all its parts, regardless of how they are packaged. This License gives no permission to license the work in any other way, but it does not invalidate such permission if you have separately received it.
    4. If the work has interactive user interfaces, each must display Appropriate Legal Notices; however, if the Program has interactive interfaces that do not display Appropriate Legal Notices, your work need not make them do so.

    A compilation of a covered work with other separate and independent works, which are not by their nature extensions of the covered work, and which are not combined with it such as to form a larger program, in or on a volume of a storage or distribution medium, is called an “aggregate” if the compilation and its resulting copyright are not used to limit the access or legal rights of the compilation’s users beyond what the individual works permit. Inclusion of a covered work in an aggregate does not cause this License to apply to the other parts of the aggregate.

  7. Conveying Non-Source Forms.

    You may convey a covered work in object code form under the terms of sections 4 and 5, provided that you also convey the machine-readable Corresponding Source under the terms of this License, in one of these ways:

    1. Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by the Corresponding Source fixed on a durable physical medium customarily used for software interchange.
    2. Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by a written offer, valid for at least three years and valid for as long as you offer spare parts or customer support for that product model, to give anyone who possesses the object code either (1) a copy of the Corresponding Source for all the software in the product that is covered by this License, on a durable physical medium customarily used for software interchange, for a price no more than your reasonable cost of physically performing this conveying of source, or (2) access to copy the Corresponding Source from a network server at no charge.
    3. Convey individual copies of the object code with a copy of the written offer to provide the Corresponding Source. This alternative is allowed only occasionally and noncommercially, and only if you received the object code with such an offer, in accord with subsection 6b.
    4. Convey the object code by offering access from a designated place (gratis or for a charge), and offer equivalent access to the Corresponding Source in the same way through the same place at no further charge. You need not require recipients to copy the Corresponding Source along with the object code. If the place to copy the object code is a network server, the Corresponding Source may be on a different server (operated by you or a third party) that supports equivalent copying facilities, provided you maintain clear directions next to the object code saying where to find the Corresponding Source. Regardless of what server hosts the Corresponding Source, you remain obligated to ensure that it is available for as long as needed to satisfy these requirements.
    5. Convey the object code using peer-to-peer transmission, provided you inform other peers where the object code and Corresponding Source of the work are being offered to the general public at no charge under subsection 6d.

    A separable portion of the object code, whose source code is excluded from the Corresponding Source as a System Library, need not be included in conveying the object code work.

    A “User Product” is either (1) a “consumer product”, which means any tangible personal property which is normally used for personal, family, or household purposes, or (2) anything designed or sold for incorporation into a dwelling. In determining whether a product is a consumer product, doubtful cases shall be resolved in favor of coverage. For a particular product received by a particular user, “normally used” refers to a typical or common use of that class of product, regardless of the status of the particular user or of the way in which the particular user actually uses, or expects or is expected to use, the product. A product is a consumer product regardless of whether the product has substantial commercial, industrial or non-consumer uses, unless such uses represent the only significant mode of use of the product.

    “Installation Information” for a User Product means any methods, procedures, authorization keys, or other information required to install and execute modified versions of a covered work in that User Product from a modified version of its Corresponding Source. The information must suffice to ensure that the continued functioning of the modified object code is in no case prevented or interfered with solely because modification has been made.

    If you convey an object code work under this section in, or with, or specifically for use in, a User Product, and the conveying occurs as part of a transaction in which the right of possession and use of the User Product is transferred to the recipient in perpetuity or for a fixed term (regardless of how the transaction is characterized), the Corresponding Source conveyed under this section must be accompanied by the Installation Information. But this requirement does not apply if neither you nor any third party retains the ability to install modified object code on the User Product (for example, the work has been installed in ROM).

    The requirement to provide Installation Information does not include a requirement to continue to provide support service, warranty, or updates for a work that has been modified or installed by the recipient, or for the User Product in which it has been modified or installed. Access to a network may be denied when the modification itself materially and adversely affects the operation of the network or violates the rules and protocols for communication across the network.

    Corresponding Source conveyed, and Installation Information provided, in accord with this section must be in a format that is publicly documented (and with an implementation available to the public in source code form), and must require no special password or key for unpacking, reading or copying.

  8. Additional Terms.

    “Additional permissions” are terms that supplement the terms of this License by making exceptions from one or more of its conditions. Additional permissions that are applicable to the entire Program shall be treated as though they were included in this License, to the extent that they are valid under applicable law. If additional permissions apply only to part of the Program, that part may be used separately under those permissions, but the entire Program remains governed by this License without regard to the additional permissions.

    When you convey a copy of a covered work, you may at your option remove any additional permissions from that copy, or from any part of it. (Additional permissions may be written to require their own removal in certain cases when you modify the work.) You may place additional permissions on material, added by you to a covered work, for which you have or can give appropriate copyright permission.

    Notwithstanding any other provision of this License, for material you add to a covered work, you may (if authorized by the copyright holders of that material) supplement the terms of this License with terms:

    1. Disclaiming warranty or limiting liability differently from the terms of sections 15 and 16 of this License; or
    2. Requiring preservation of specified reasonable legal notices or author attributions in that material or in the Appropriate Legal Notices displayed by works containing it; or
    3. Prohibiting misrepresentation of the origin of that material, or requiring that modified versions of such material be marked in reasonable ways as different from the original version; or
    4. Limiting the use for publicity purposes of names of licensors or authors of the material; or
    5. Declining to grant rights under trademark law for use of some trade names, trademarks, or service marks; or
    6. Requiring indemnification of licensors and authors of that material by anyone who conveys the material (or modified versions of it) with contractual assumptions of liability to the recipient, for any liability that these contractual assumptions directly impose on those licensors and authors.

    All other non-permissive additional terms are considered “further restrictions” within the meaning of section 10. If the Program as you received it, or any part of it, contains a notice stating that it is governed by this License along with a term that is a further restriction, you may remove that term. If a license document contains a further restriction but permits relicensing or conveying under this License, you may add to a covered work material governed by the terms of that license document, provided that the further restriction does not survive such relicensing or conveying.

    If you add terms to a covered work in accord with this section, you must place, in the relevant source files, a statement of the additional terms that apply to those files, or a notice indicating where to find the applicable terms.

    Additional terms, permissive or non-permissive, may be stated in the form of a separately written license, or stated as exceptions; the above requirements apply either way.

  9. Termination.

    You may not propagate or modify a covered work except as expressly provided under this License. Any attempt otherwise to propagate or modify it is void, and will automatically terminate your rights under this License (including any patent licenses granted under the third paragraph of section 11).

    However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.

    Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.

    Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, you do not qualify to receive new licenses for the same material under section 10.

  10. Acceptance Not Required for Having Copies.

    You are not required to accept this License in order to receive or run a copy of the Program. Ancillary propagation of a covered work occurring solely as a consequence of using peer-to-peer transmission to receive a copy likewise does not require acceptance. However, nothing other than this License grants you permission to propagate or modify any covered work. These actions infringe copyright if you do not accept this License. Therefore, by modifying or propagating a covered work, you indicate your acceptance of this License to do so.

  11. Automatic Licensing of Downstream Recipients.

    Each time you convey a covered work, the recipient automatically receives a license from the original licensors, to run, modify and propagate that work, subject to this License. You are not responsible for enforcing compliance by third parties with this License.

    An “entity transaction” is a transaction transferring control of an organization, or substantially all assets of one, or subdividing an organization, or merging organizations. If propagation of a covered work results from an entity transaction, each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party’s predecessor in interest had or could give under the previous paragraph, plus a right to possession of the Corresponding Source of the work from the predecessor in interest, if the predecessor has it or can get it with reasonable efforts.

    You may not impose any further restrictions on the exercise of the rights granted or affirmed under this License. For example, you may not impose a license fee, royalty, or other charge for exercise of rights granted under this License, and you may not initiate litigation (including a cross-claim or counterclaim in a lawsuit) alleging that any patent claim is infringed by making, using, selling, offering for sale, or importing the Program or any portion of it.

  12. Patents.

    A “contributor” is a copyright holder who authorizes use under this License of the Program or a work on which the Program is based. The work thus licensed is called the contributor’s “contributor version”.

    A contributor’s “essential patent claims” are all patent claims owned or controlled by the contributor, whether already acquired or hereafter acquired, that would be infringed by some manner, permitted by this License, of making, using, or selling its contributor version, but do not include claims that would be infringed only as a consequence of further modification of the contributor version. For purposes of this definition, “control” includes the right to grant patent sublicenses in a manner consistent with the requirements of this License.

    Each contributor grants you a non-exclusive, worldwide, royalty-free patent license under the contributor’s essential patent claims, to make, use, sell, offer for sale, import and otherwise run, modify and propagate the contents of its contributor version.

    In the following three paragraphs, a “patent license” is any express agreement or commitment, however denominated, not to enforce a patent (such as an express permission to practice a patent or covenant not to sue for patent infringement). To “grant” such a patent license to a party means to make such an agreement or commitment not to enforce a patent against the party.

    If you convey a covered work, knowingly relying on a patent license, and the Corresponding Source of the work is not available for anyone to copy, free of charge and under the terms of this License, through a publicly available network server or other readily accessible means, then you must either (1) cause the Corresponding Source to be so available, or (2) arrange to deprive yourself of the benefit of the patent license for this particular work, or (3) arrange, in a manner consistent with the requirements of this License, to extend the patent license to downstream recipients. “Knowingly relying” means you have actual knowledge that, but for the patent license, your conveying the covered work in a country, or your recipient’s use of the covered work in a country, would infringe one or more identifiable patents in that country that you have reason to believe are valid.

    If, pursuant to or in connection with a single transaction or arrangement, you convey, or propagate by procuring conveyance of, a covered work, and grant a patent license to some of the parties receiving the covered work authorizing them to use, propagate, modify or convey a specific copy of the covered work, then the patent license you grant is automatically extended to all recipients of the covered work and works based on it.

    A patent license is “discriminatory” if it does not include within the scope of its coverage, prohibits the exercise of, or is conditioned on the non-exercise of one or more of the rights that are specifically granted under this License. You may not convey a covered work if you are a party to an arrangement with a third party that is in the business of distributing software, under which you make payment to the third party based on the extent of your activity of conveying the work, and under which the third party grants, to any of the parties who would receive the covered work from you, a discriminatory patent license (a) in connection with copies of the covered work conveyed by you (or copies made from those copies), or (b) primarily for and in connection with specific products or compilations that contain the covered work, unless you entered into that arrangement, or that patent license was granted, prior to 28 March 2007.

    Nothing in this License shall be construed as excluding or limiting any implied license or other defenses to infringement that may otherwise be available to you under applicable patent law.

  13. No Surrender of Others’ Freedom.

    If conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot convey a covered work so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not convey it at all. For example, if you agree to terms that obligate you to collect a royalty for further conveying from those to whom you convey the Program, the only way you could satisfy both those terms and this License would be to refrain entirely from conveying the Program.

  14. Use with the GNU Affero General Public License.

    Notwithstanding any other provision of this License, you have permission to link or combine any covered work with a work licensed under version 3 of the GNU Affero General Public License into a single combined work, and to convey the resulting work. The terms of this License will continue to apply to the part which is the covered work, but the special requirements of the GNU Affero General Public License, section 13, concerning interaction through a network will apply to the combination as such.

  15. Revised Versions of this License.

    The Free Software Foundation may publish revised and/or new versions of the GNU General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

    Each version is given a distinguishing version number. If the Program specifies that a certain numbered version of the GNU General Public License “or any later version” applies to it, you have the option of following the terms and conditions either of that numbered version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the GNU General Public License, you may choose any version ever published by the Free Software Foundation.

    If the Program specifies that a proxy can decide which future versions of the GNU General Public License can be used, that proxy’s public statement of acceptance of a version permanently authorizes you to choose that version for the Program.

    Later license versions may give you additional or different permissions. However, no additional obligations are imposed on any author or copyright holder as a result of your choosing to follow a later version.

  16. Disclaimer of Warranty.

    THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

  17. Limitation of Liability.

    IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

  18. Interpretation of Sections 15 and 16.

    If the disclaimer of warranty and limitation of liability provided above cannot be given local legal effect according to their terms, reviewing courts shall apply local law that most closely approximates an absolute waiver of all civil liability in connection with the Program, unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee.

END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively state the exclusion of warranty; and each file should have at least the “copyright” line and a pointer to where the full notice is found.

one line to give the program's name and a brief idea of what it does.
Copyright (C) year name of author

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or (at
your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see http://www.gnu.org/licenses/.

Also add information on how to contact you by electronic and paper mail.

If the program does terminal interaction, make it output a short notice like this when it starts in an interactive mode:

program Copyright (C) year name of author
This program comes with ABSOLUTELY NO WARRANTY; for details type ‘show w’.
This is free software, and you are welcome to redistribute it
under certain conditions; type ‘show c’ for details.

The hypothetical commands ‘show w’ and ‘show c’ should show the appropriate parts of the General Public License. Of course, your program’s commands might be different; for a GUI interface, you would use an “about box”.

You should also get your employer (if you work as a programmer) or school, if any, to sign a “copyright disclaimer” for the program, if necessary. For more information on this, and how to apply and follow the GNU GPL, see http://www.gnu.org/licenses/.

The GNU General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License. But first, please read http://www.gnu.org/philosophy/why-not-lgpl.html.


GNU Free Documentation License

Version 1.3, 3 November 2008
Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
http://fsf.org/

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
  1. PREAMBLE

    The purpose of this License is to make a manual, textbook, or other functional and useful document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

    This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

    We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

  2. APPLICABILITY AND DEFINITIONS

    This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.

    A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

    A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

    The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.

    The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.

    A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.

    Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.

    The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text.

    The “publisher” means any person or entity that distributes copies of the Document to the public.

    A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.

    The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.

  3. VERBATIM COPYING

    You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

    You may also lend copies, under the same conditions stated above, and you may publicly display copies.

  4. COPYING IN QUANTITY

    If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

    If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

    If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

    It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

  5. MODIFICATIONS

    You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

    1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
    2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.
    3. State on the Title page the name of the publisher of the Modified Version, as the publisher.
    4. Preserve all the copyright notices of the Document.
    5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
    6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
    7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document’s license notice.
    8. Include an unaltered copy of this License.
    9. Preserve the section Entitled “History”, Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled “History” in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
    10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the “History” section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
    11. For any section Entitled “Acknowledgements” or “Dedications”, Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
    12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
    13. Delete any section Entitled “Endorsements”. Such a section may not be included in the Modified Version.
    14. Do not retitle any existing section to be Entitled “Endorsements” or to conflict in title with any Invariant Section.
    15. Preserve any Warranty Disclaimers.

    If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These titles must be distinct from any other section titles.

    You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

    You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

    The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

  6. COMBINING DOCUMENTS

    You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.

    The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

    In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements.”

  7. COLLECTIONS OF DOCUMENTS

    You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

    You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

  8. AGGREGATION WITH INDEPENDENT WORKS

    A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.

    If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document’s Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.

  9. TRANSLATION

    Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.

    If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.

  10. TERMINATION

    You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, or distribute it is void, and will automatically terminate your rights under this License.

    However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.

    Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.

    Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it.

  11. FUTURE REVISIONS OF THIS LICENSE

    The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

    Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. If the Document specifies that a proxy can decide which future versions of this License can be used, that proxy’s public statement of acceptance of a version permanently authorizes you to choose that version for the Document.

  12. RELICENSING

    “Massive Multiauthor Collaboration Site” (or “MMC Site”) means any World Wide Web server that publishes copyrightable works and also provides prominent facilities for anybody to edit those works. A public wiki that anybody can edit is an example of such a server. A “Massive Multiauthor Collaboration” (or “MMC”) contained in the site means any set of copyrightable works thus published on the MMC site.

    “CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 license published by Creative Commons Corporation, a not-for-profit corporation with a principal place of business in San Francisco, California, as well as future copyleft versions of that license published by that same organization.

    “Incorporate” means to publish or republish a Document, in whole or in part, as part of another Document.

    An MMC is “eligible for relicensing” if it is licensed under this License, and if all works that were first published under this License somewhere other than this MMC, and subsequently incorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections, and (2) were thus incorporated prior to November 1, 2008.

    The operator of an MMC Site may republish an MMC contained in the site under CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible for relicensing.

ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

  Copyright (C)  year  your name.
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.3
  or any later version published by the Free Software Foundation;
  with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
  Texts.  A copy of the license is included in the section entitled ``GNU
  Free Documentation License''.

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with…Texts.” line with this:

    with the Invariant Sections being list their titles, with
    the Front-Cover Texts being list, and with the Back-Cover Texts
    being list.

If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.


Previous: , Up: Top   [Contents][Index]

Index

Jump to:   0  
A   B   C   D   E   F   G   H   I   J   K   L   M   N   O   P   Q   R   S   T   U   V   W  
Index Entry  Section

0
01 Introduction: Introduction
02 Operational Overview: Operational Overview
02.1 Single-window Mode: Single-window Mode
02.2 Dual-window Mode: Dual-window Mode
02.3 Tree-view Mode: Tree-view Mode
02.4 Special File Types: Special File Types
02.5 Dialog Controls: Dialog Controls
02.6 Mouse Support: Mouse Support
03 Invoking: Invoking
03.1 Invocation Options: Invocation Options
04 Command Interface: Command Interface
04.1 Command-key Introduction: Command-key Introduction
04.2 Default Key Bindings: Default Key Bindings
04.3 Command Definitions: Command Definitions
04.3.01 Navigation: Navigation
04.3.02 Selecting Files: Selecting Files
04.3.03 Copying and Moving Files: Copying and Moving Files
04.3.04 Renaming Files: Renaming Files
04.3.05 Sorting the File List: Sorting the File List
04.3.06 Trashcan and File Deletion: Trashcan and File Deletion
04.3.06a Move Files to Trashcan: Move Files to Trashcan
04.3.06b Restore from Trashcan: Restore from Trashcan
04.3.06c Manage the Trashcan: Manage the Trashcan
04.3.06d Delete Files Permanently: Delete Files Permanently
04.3.07 Create a New Directory: Create a New Directory
04.3.08 Changing File Attributes: Changing File Attributes
04.3.09 View or Modify File Stats: View or Modify File Stats
04.3.10 View File Contents: View File Contents
04.3.11 Open or Execute a File: Open or Execute a File
04.3.12 Find Files by Name: Find Files by Name
04.3.13 Grep Files: Grep Files
04.3.14 Backup Your Data: Backup Your Data
04.3.15 Synchronize Directories: Synchronize Directories
04.3.16 Working With Archives: Working With Archives
04.3.16a Archive Overview: Archive Overview
04.3.16b Creating an Archive: Creating an Archive
04.3.16c Expanding an Archive: Expanding an Archive
04.3.16d Updating an Archive: Updating an Archive
04.3.17 Favorite Directories List: Favorite Directories List
04.3.18 Mounting Filesystems: Mounting Filesystems
04.3.19 View Mode Selection: View Mode Selection
04.3.20 Exit the Application: Exit the Application
04.3.21 Other Commands: Other Commands
05 Menu System Interface: Menu System Interface
05.1 Accessing the Menu System: Accessing the Menu System
05.2 Menu Hotkeys: Menu Hotkeys
05.3 File Menu: File Menu
05.4 Edit Menu: Edit Menu
05.5 View Menu: View Menu
05.6 Util Menu: Util Menu
05.7 Help Menu: Help Menu
05.8 Context Menus: Context Menus
06 Configuration: Configuration
06.1 Configuration Overview: Configuration Overview
06.2 Setting Config Options: Setting Config Options
06.3 The Configuration File: The Configuration File
06.4 Customizing Key Commands: Customizing Key Commands
07 Installation: Installation
07.1 Prepare for Installation: Prepare for Installation
07.2 Installation Script: Installation Script
07.3 Manual Installation: Manual Installation
07.4 Multi-user Installation: Multi-user Installation
07.5 Install the Documentation: Install the Documentation
07.6 Testing Your Installation: Testing Your Installation
07.7 Building from Sources: Building from Sources
08 Technical Support: Technical Support
09 Copyright Notice: Copyright Notice
09.01 GNU General Public License: GNU General Public License
09.02 GNU Free Documentation License: GNU Free Documentation License

A
a option: Invocation Options
accessing external filesystems: Mounting Filesystems
adjust file timestamp: View or Modify File Stats
adjust permission flags: Changing File Attributes
alt window CWD: View Mode Selection
ALT+’ key: View Mode Selection
ALT+0 key: Default Key Bindings
ALT+1 key: Default Key Bindings
ALT+2 key: Default Key Bindings
ALT+3 key: Default Key Bindings
ALT+4 key: Default Key Bindings
ALT+5 key: Default Key Bindings
ALT+6 key: Default Key Bindings
ALT+7 key: Default Key Bindings
ALT+8 key: Default Key Bindings
ALT+9 key: Default Key Bindings
ALT+A key: Default Key Bindings
ALT+B key: Default Key Bindings
ALT+C key: Default Key Bindings
ALT+CTRL+A key: Default Key Bindings
ALT+CTRL+B key: Default Key Bindings
ALT+CTRL+C key: Default Key Bindings
ALT+CTRL+D key: Default Key Bindings
ALT+CTRL+E key: Default Key Bindings
ALT+CTRL+F key: Default Key Bindings
ALT+CTRL+G key: Default Key Bindings
ALT+CTRL+H key: Default Key Bindings
ALT+CTRL+I key: Default Key Bindings
ALT+CTRL+J key: Default Key Bindings
ALT+CTRL+K key: Default Key Bindings
ALT+CTRL+L key: Default Key Bindings
ALT+CTRL+M key: Default Key Bindings
ALT+CTRL+N key: Default Key Bindings
ALT+CTRL+O key: Default Key Bindings
ALT+CTRL+O key: Default Key Bindings
ALT+CTRL+P key: Default Key Bindings
ALT+CTRL+R key: View Mode Selection
ALT+CTRL+S key: Default Key Bindings
ALT+CTRL+T key: Default Key Bindings
ALT+CTRL+U key: Default Key Bindings
ALT+CTRL+V key: Default Key Bindings
ALT+CTRL+W key: Default Key Bindings
ALT+CTRL+X key: Default Key Bindings
ALT+CTRL+Y key: Default Key Bindings
ALT+CTRL+Z key: Default Key Bindings
ALT+D key: Default Key Bindings
ALT+E key: Edit Menu
ALT+ENTER key: Navigation
ALT+F key: File Menu
ALT+G key: Default Key Bindings
ALT+H key: Help Menu
ALT+I key: Sorting the File List
ALT+INSERT key: Copying and Moving Files
ALT+J key: Default Key Bindings
ALT+K key: Default Key Bindings
ALT+L key: Default Key Bindings
ALT+M key: Default Key Bindings
ALT+N key: Default Key Bindings
ALT+O key: Default Key Bindings
ALT+P key: Default Key Bindings
ALT+Q key: Exit the Application
ALT+R key: Default Key Bindings
ALT+S key: Default Key Bindings
ALT+SHIFT+’ key: View Mode Selection
ALT+SHIFT+0 key: Default Key Bindings
ALT+SHIFT+1 key: Default Key Bindings
ALT+SHIFT+2 key: Default Key Bindings
ALT+SHIFT+3 key: Default Key Bindings
ALT+SHIFT+4 key: Default Key Bindings
ALT+SHIFT+5 key: Default Key Bindings
ALT+SHIFT+6 key: Default Key Bindings
ALT+SHIFT+7 key: Default Key Bindings
ALT+SHIFT+8 key: Default Key Bindings
ALT+SHIFT+9 key: Default Key Bindings
ALT+SHIFT+; key: Other Commands
ALT+SHIFT+A key (create): Creating an Archive
ALT+SHIFT+A key (expand): Expanding an Archive
ALT+SHIFT+A key (update): Updating an Archive
ALT+SHIFT+B key: Default Key Bindings
ALT+SHIFT+C key: Other Commands
ALT+SHIFT+D key: Default Key Bindings
ALT+SHIFT+E key: Edit Menu
ALT+SHIFT+F key: File Menu
ALT+SHIFT+G key: Default Key Bindings
ALT+SHIFT+H key: Help Menu
ALT+SHIFT+I key: Default Key Bindings
ALT+SHIFT+J key: Default Key Bindings
ALT+SHIFT+K key: Default Key Bindings
ALT+SHIFT+L key: Default Key Bindings
ALT+SHIFT+M key: Accessing the Menu System
ALT+SHIFT+N key: Default Key Bindings
ALT+SHIFT+O key: Default Key Bindings
ALT+SHIFT+P key: Default Key Bindings
ALT+SHIFT+Q key: Default Key Bindings
ALT+SHIFT+R key: Restore from Trashcan
ALT+SHIFT+S key: Default Key Bindings
ALT+SHIFT+T key: Manage the Trashcan
ALT+SHIFT+U key: Util Menu
ALT+SHIFT+V key: View Menu
ALT+SHIFT+W key: Default Key Bindings
ALT+SHIFT+X key: Default Key Bindings
ALT+SHIFT+Y key: Default Key Bindings
ALT+SHIFT+Z key: Other Commands
ALT+SHIFT+[ key: Other Commands
ALT+SHIFT+] key: Other Commands
ALT+T key: Default Key Bindings
ALT+U key: Util Menu
ALT+UpArrow key: Navigation
ALT+V key: View Menu
ALT+W key: View Mode Selection
ALT+X key: Default Key Bindings
ALT+Y key: Default Key Bindings
ALT+Z key: Default Key Bindings
application clipboard: Other Commands
archive compression options: Creating an Archive
archive files: Working With Archives
archive files, creating: Backup Your Data
archive files, creating: Creating an Archive
arguments, command-line: Invoking
attribute bits: Changing File Attributes

B
b option: Invocation Options
BACKSPACE key: Navigation
backup log fle: Backup Your Data
backup your data: Backup Your Data
backup, delayed: Backup Your Data
batch rename: Renaming Files
by the same author: Technical Support
bzip2: Creating an Archive

C
c option: Invocation Options
C option: Invocation Options
capabilities: Introduction
caps lock key: Default Key Bindings
clipboard: Other Commands
command key: Command Interface
command keys, remapping: Customizing Key Commands
command-key interface: Introduction
command-key list: Other Commands
command-line arguments: Invoking
commands, menu: Menu System Interface
commands, other: Other Commands
compare files: Other Commands
compression, data: Creating an Archive
config options, setting: Setting Config Options
configuration: Configuration
configuration file: The Configuration File
configuration utility: Configuration Overview
contact info: Technical Support
contents, view file: View File Contents
context menu, SortBy: Context Menus
context menu, ViewFile: Context Menus
context menus: Context Menus
control types, dialog: Dialog Controls
control, list: Dialog Controls
control, menu: Dialog Controls
control, pushbutton: Dialog Controls
control, radiobutton: Dialog Controls
control, spinner: Dialog Controls
control, textbox: Dialog Controls
copy files: Copying and Moving Files
copyright info: Help Menu
create directory: Create a New Directory
creating archive files: Backup Your Data
creating archive files: Creating an Archive
CTRL+A key: Selecting Files
CTRL+B key: Default Key Bindings
CTRL+C key: Copying and Moving Files
CTRL+D key: Changing File Attributes
CTRL+DELETE key: Move Files to Trashcan
CTRL+E key: Changing File Attributes
CTRL+F key: Find Files by Name
CTRL+G key: Grep Files
CTRL+H key: Default Key Bindings
CTRL+I key: Default Key Bindings
CTRL+J key: Default Key Bindings
CTRL+K key: Other Commands
CTRL+L key: Default Key Bindings
CTRL+M key: Default Key Bindings
CTRL+N key: Create a New Directory
CTRL+O key: Favorite Directories List
CTRL+P key: Default Key Bindings
CTRL+Q key: Exit the Application
CTRL+R key: Renaming Files
CTRL+S key: Sorting the File List
CTRL+T key: View Mode Selection
CTRL+U key: View Mode Selection
CTRL+V key: Default Key Bindings
CTRL+V key: Copying and Moving Files
CTRL+W key: Changing File Attributes
CTRL+X key: Default Key Bindings
CTRL+X key: Copying and Moving Files
CTRL+Y key: Default Key Bindings
CTRL+Y key: Mounting Filesystems
CTRL+Z key: Default Key Bindings
cut files: Copying and Moving Files
CWD, set alt window: View Mode Selection

D
d option: Invocation Options
data backup: Backup Your Data
data compression: Creating an Archive
debugging the installation: Testing Your Installation
debugging the installation: Testing Your Installation
default key bindings: Default Key Bindings
delayed backup: Backup Your Data
delayed backup, specifying: Backup Your Data
delete files: Trashcan and File Deletion
delete files: Delete Files Permanently
dialog control types: Dialog Controls
dialog, resize: View Mode Selection
directory synchronization: Synchronize Directories
directory, create: Create a New Directory
display modes: View Mode Selection
documentation installation: Install the Documentation
Down Arrow key: Navigation
dual-window synch lock: View Mode Selection

E
empty trashcan: Manage the Trashcan
End key: Navigation
end session: Exit the Application
ENTER (RET) key: Navigation
execute binary or script file: Open or Execute a File
exit the application: Exit the Application
external app, launch: Context Menus
external app, open file with: Open or Execute a File
external filesystems: Mounting Filesystems
external libraries: Technical Support

F
f option: Invocation Options
F01 key: Other Commands
F02 key: Accessing the Menu System
favorites list: Favorite Directories List
file backup: Backup Your Data
file comparison: Other Commands
file contents, view: View File Contents
file contents, view: Context Menus
file deletion: Delete Files Permanently
file properties: View or Modify File Stats
file stats: View or Modify File Stats
file stats, modify: View or Modify File Stats
file substring match: Grep Files
file types, special: Special File Types
filename, locate by: Navigation
files, locate: Find Files by Name
files, synchronize: Synchronize Directories
filesystem info: Other Commands
filesystems: Mounting Filesystems
find files: Find Files by Name
find symlink target: Context Menus
fmg - FileMangler Docs: Top
functionality, menu: Menu System Interface

G
geek nectar: Technical Support
grep files: Grep Files
gzip: Creating an Archive

H
h option: Invocation Options
help option: Invocation Options
help, online: Other Commands
help-about dialog: Help Menu
history: Technical Support
Home key: Navigation

I
IME utilities: Introduction
input method engine: Introduction
installation, automated: Installation Script
installation, documentation: Install the Documentation
installation, manual: Manual Installation
installation, multiuser: Multi-user Installation
interface, mouse-driven: Mouse Support
invocation mechanism: Invoking
invoking as superuser: Invoking

J
jump to directory: Favorite Directories List

K
key bindings, default: Default Key Bindings
key combination: Command Interface
key sequence: Command Interface
keycodes available to terminal applications: Customizing Key Commands

L
launch external app: Context Menus
list control: Dialog Controls
list of command keys: Other Commands
locate by filename: Navigation
locate files: Find Files by Name
lock dual-window synch: View Mode Selection
log, backup/synch: Backup Your Data

M
m option: Invocation Options
manage trashcan: Manage the Trashcan
menu control: Dialog Controls
menu interface: Introduction
menu system: Menu System Interface
miscellaneous commands: Other Commands
mode, display: View Mode Selection
mode, view switching: View Mode Selection
modify file ownership: View or Modify File Stats
modify file permission bits: View or Modify File Stats
modify file stats: View or Modify File Stats
modify timestamp: Changing File Attributes
mount disc: Mounting Filesystems
mount filesystem: Mounting Filesystems
mouse support: Mouse Support
mouse support: Command-key Introduction

N
navigation keys: Navigation
new directory: Create a New Directory
notes, technical: Technical Support

O
often-visited directories: Favorite Directories List
online help: Other Commands
online help: Technical Support
open file with external app: Open or Execute a File
operating mode: Operational Overview
option summary: Invoking
option, a: Invocation Options
option, b: Invocation Options
option, c: Invocation Options
option, C: Invocation Options
option, d: Invocation Options
option, f: Invocation Options
option, h: Invocation Options
option, help: Invocation Options
option, m: Invocation Options
option, p: Invocation Options
option, s: Invocation Options
option, t: Invocation Options
option, version: Invocation Options
option, w: Invocation Options
options, command-line: Invoking
options, configuration: Setting Config Options
other commands: Other Commands

P
p option: Invocation Options
Page Down key: Navigation
Page Up key: Navigation
paste files: Copying and Moving Files
paste special: Copying and Moving Files
perform data backups: Backup Your Data
perform directory synchronization: Synchronize Directories
permanently delete files: Delete Files Permanently
permission bits: Changing File Attributes
platforms, testing: Technical Support
properties, file: View or Modify File Stats
pushbutton control: Dialog Controls

Q
quit the application: Exit the Application

R
radiobutton control: Dialog Controls
remapping command keys: Customizing Key Commands
rename files: Renaming Files
resize dialog: View Mode Selection
restore from trashcan: Restore from Trashcan
restore from trashcan: Manage the Trashcan
root user, invoking as: Invoking
run binary or script file: Open or Execute a File

S
s option: Invocation Options
scan files for substring: Grep Files
scheduled backup: Backup Your Data
screen shots: Single-window Mode
search for files: Find Files by Name
selecting files: Selecting Files
setting config options: Setting Config Options
SHIFT+DELETE key: Delete Files Permanently
SHIFT+DownArrow: Selecting Files
SHIFT+F01 key: Other Commands
SHIFT+TAB key: Navigation
SHIFT+UpArrow: Selecting Files
shortcut keys: Other Commands
sort file list: Sorting the File List
SortBy context menu: Context Menus
SPACE key: Selecting Files
special file types: Special File Types
spinner control: Dialog Controls
statistics, file: View or Modify File Stats
stats, file: View or Modify File Stats
stats, modify file: View or Modify File Stats
stats, view file: Context Menus
subdirectory, create: Create a New Directory
summary of options: Invoking
superuser, invoking as: Invoking
support: Help Menu
switching view mode: View Mode Selection
symlink target, find: Context Menus
synch log file: Backup Your Data
synch, delayed: Synchronize Directories
synch-lock: View Mode Selection
synchronization, directory: Synchronize Directories
synchronize your data: Synchronize Directories

T
t option: Invocation Options
TAB key: Navigation
tar archive, creating: Backup Your Data
tar archive, creating: Creating an Archive
tar archives: Working With Archives
tech notes: Technical Support
tech support: Help Menu
terminal window, resize: View Mode Selection
test your installation: Testing Your Installation
testing platforms: Technical Support
Texinfo documentation: Install the Documentation
textbox control: Dialog Controls
timestamp, modify: Changing File Attributes
touch file timestamp: Changing File Attributes
trash, undo move to: Restore from Trashcan
trashcan files: Trashcan and File Deletion
trashcan, empty: Manage the Trashcan
trashcan, manage: Manage the Trashcan
trashcan, move files to: Move Files to Trashcan
trashcan, restore items: Restore from Trashcan
trashcan, restore items: Manage the Trashcan

U
undelete item in trash: Manage the Trashcan
undo move to trash: Restore from Trashcan
unmount disc: Mounting Filesystems
unmount filesystem: Mounting Filesystems
Up Arrow key: Navigation
update file timestamp: Changing File Attributes
usage notes: Invoking
user info: Other Commands
user interface: Introduction

V
verify installation: Testing Your Installation
version option: Invocation Options
view clipboard contents: Other Commands
view file contents: View File Contents
view file contents: Context Menus
view file stats: Context Menus
view mode selection: View Mode Selection
ViewFile context menu: Context Menus

W
w option: Invocation Options
window mode: Operational Overview
write enable: Changing File Attributes
write protect: Changing File Attributes

Jump to:   0  
A   B   C   D   E   F   G   H   I   J   K   L   M   N   O   P   Q   R   S   T   U   V   W