README file for FileMangler file management utility. Release 0.0.40
Copyright 2005-2025 by The Software Samurai
Software released under GPL3+, and documentation released under FDL1.3+
=======================================================================
a) This application requires the NcDialogAPI library, also available 
   on the author's website.
b) The 'ncurses' development platform is required by the NcDialog 
   library. 'ncurses' is available on most distro mirrors:
      ftp://ftp.gnu.org/gnu/ncurses/
      sudo dnf install ncurses-devel  or
      sudo apt-get install libncurses6-dev libncursesw6-dev
   See also Thomas E. Dickey's:
      https://invisible-island.net/archives/ncurses/
   Please see the NcDialogAPI docs for more info.

Download and unpack the distribution archive alongside the NcDialog API 
source directory:

   tar -xjvf filemangler-0.0.40.tar.bz2

The recommended source-directory configuration is shown below. This allows 
the FileMangler 'Makefile' to access the needed headers and link library 
from the NcDialog API package.

   .../FileMangler          <== FileMangler source lives here
               /Texinfo     <== FileMangler documentation lives here
   .../NcDialog/Dialog1     <== NcDialog source lives here
               /Dialog2     <== test and demonstration code
               /Dialog3           "   "       "         "
               /Dialog4           "   "       "         "
               /Dialogw           "   "       "         "
               /Dialogx           "   "       "         "
               /Keymap            "   "       "         "
               /Texinfo     <== NcDialog documentation lives here


For instructions on building the application, type the following command:

   info -f ./Texinfo/filemangler.info -n 'Building from Sources'

For installation instructions, type the following command:

   info -f ./Texinfo/filemangler.info -n 'Automatic Installation'


Notes on the current release:
=============================
1) Package Contents:
--------------------
FileMangler.hpp      # FileMangler class (top-level application class)
FileMangler.cpp      FmKeymap.hpp         FmCommand.cpp
FmInterface.cpp      FmMenu.cpp           FmMenu.hpp
FmBackup.cpp

FmConfig.hpp         # FmConfig class (configuration sub-process)
FmConfig.cpp         FmConfigi.cpp

FileDlg.hpp          # FileDlg class (primary user interface)
FileDlg.cpp          FileDlgContext.cpp   renamePattern.hpp
FileDlgBackup.cpp    FileDlgClipbrd.cpp   FileDlgRename.cpp
FileDlgStat.cpp      FileDlgTrash.cpp     FileDlgTree.cpp
FileDlgDelete.cpp    FileDlgPaste.cpp     FileDlgMedia.cpp
FileDlgPrompt.cpp    FileDlgUtil1.cpp     FileDlgUtil2.cpp
Progbar.hpp          Progbar.cpp

FMgr.hpp             # FMgr class (low-level file management)
FMgr.cpp             FMgrStats.cpp           FMgrSort.cpp
FMgrTree.cpp         FMgrGvfs.cpp            FMgrDispData.hpp

Makefile             # Makefile (build instructions for compiler/linker)

# Auxilliary Files
FileMangler.cfg      # Template for application configuration
FmKeymap.cfg         # Template for application hotkey mapping
Backup_Def.txt       # Template for defining a data backup operation
fmg                  # Bash shell script for invocation
fmg.sh               # Bash shell script for invocation
fmgr.sh              # Bash shell script for invocation as super-user (root)
fmginstall.pl        # Perl script for application installation
uninstall-docs.pl    # Perl script to remove FileMangler docs from info database
VERSION_HISTORY      # FileMangler version history
README               # This file

# Documentation
FmgChapter00_Header.texi
FmgChapter01_Introduction.texi
FmgChapter02_OperationalOverview.texi
FmgChapter03_Invoking.texi
FmgChapter04_CommandKeyInterface.texi
FmgChapter05_MenuSystemInterface.texi
FmgChapter06_Configuration.texi
FmgChapter07_Installation.texi
FmgChapter08_TechnicalSupport.texi
same_author.texi
Makefile             # Makefile (instructions for makeinfo/texi2any)
texi_macros.texi     # Texinfo macros used for documentation source
filemangler.html     # FileMangler documentation, HTML format
filemangler.info     # FileMangler documentation, info format
gpl-3.0.texi         # GNU Public License source code
fdl-1.3.texi         # Free Documentation License source code
applycss             # Perl script for applying CSS to HTML output
infodoc-styles.css   # CSS3 formatting definitions

2) GNU C++ Compiler:
--------------------
Building the FileMangler application and the NcDialog API library require 
C++11 support (gnu gcc c++ version 4.8.0 or above).
GNU C++ (gcc 8.1.0 or greater) is recommended.
See the "Building from Sources" chapter of the FileMangler documentation for 
details.

3) 'gio' Utility:
-----------------
File operations on smartphone/tablet devices require installation of the 
'gio' command-line utility. All systems with a recent GNOME desktop environment 
include this utility, but if you are not certain whether 'gio' is installed 
on your system, type:
      gio --version
If installed, 'gio' will respond with "2.82.5" or something similar. 
Installation of the 'gio' utility is highly recommended. Although FileMangler 
can access smartphone devices using the standard Linux block-device tools, 
such access is unbelievably slow and some functionality may be unavailable.
See the "Installation" chapter of the FileMangler documentation for details.

4) 'wl-clipboard' Utility:
--------------------------
For full access to the Wayland system clipboard, FileMangler requires the 
3rd-party "wl-clipboard" utilities: "wl-copy" and "wl-paste". These utilities 
are usually not part of the basic system installation and must be installed 
separately. To determine whether they are installed on your system, type:
      wl-copy --version
      wl-paste --version
They should each respond with something similar to:
      wl-clipboard 2.2.1
      Copyright (C) 2018-2023 Sergey Bugaev
See the "Installation" chapter of the FileMangler documentation for details.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Please see the file "VERSION_HISTORY" for a list of all changes since the 
previous release.


Known bugs and other issues:
============================
-- Although the current release provides greatly-improved support for 
   smartphones, tablets and other MTP/GVFS virtual filesystems, the 
   available underlying tools are not yet mature. For this reason, file 
   operations are rather slow and recursive operations on virtual filesystem 
   trees are not supported for these devices.
   -- When mounting a smartphone device, the first attempt will often fail.
      When this happens, we perform an automatic retry. This is usually 
      successful, but if it fails, try the mount operation again.
   For best performance, updating to the newest stable release of your GNU/Linux 
   platform is recommended. Releases after mid-2019 provide improved support for 
   the GNOME Virtual File System (GVFS) and the Media Transfer Protocol (MTP).
-- Error establishing clipboard connection when invoking FileMangler as superuser.
   This is because the wl-clipboard utilities are not functional under 
   'sudo' commands, presumably because a needed file is not where the superuser 
   can find it. For example, "sudo wl-paste" reports the following error:
      Failed to connect to a Wayland server: No such file or directory.
      Please check whether /run/user/0/wayland-0 socket exists and is accessible.
   Note that '/run/user/1000/wayland-0' exists BUT '/run/user/0/wayland-0' does not; 
   It is _possible_ that as superuser, creating a sym-link to the socket or 
   installing a second copy of the wl-clipboard utilities would overcome this 
   problem; however at this time, sockets owned by the superuser are beyond 
   the scope of this project.


For future development:
=======================
-- Add multi-language support (Spanish and Chinese).

-- Improve performance and stability of access to smartphone/tablet devices.

-- Add support for reading metadata from additional audio, and image file 
   formats.

The full to-do list of possible future enhancements can be found at the top 
of the FileMangler.cpp source module. 

