README file for Console Trashcan (ctrash) application.

Copyright 2015-2020 by The Software Samurai
on the web:  http://www.SoftwareSam.us/
Software released under GPL3+, and documentation released under FDL1.3+
=======================================================================

Unpack this archive using the following command:
              tar -xjvf ctrash-x.x.xx.tar.bz2

  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -
This package contains the Console Trashcan (ctrash) source code and 
documentation. You will need to build the application binary for your target 
system (see below).

The 'ctrash' utility is a console (command-line) utility which provides 
comprehensive control of your system's Trashcan from within a terminal window.

   a) Move files and directory trees to the Trashcan.

   b) Restore items from the Trashcan.

   c) Report statistical data on the contents of the Trashcan.

   d) Empty the Trashcan.

   e) Emulate the 'rm' command by _provisionally_ deleting the data.

   f) We are sure that the 'ctrash' utility is superior in every way to 
      the Nautilus (aka 'Files') Trashcan manager. We hope you agree.

  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -
The directory tree of files included in this cTrash release is organized as follows.

cTrash/                 // Source code directory
   cTrash.cpp           // Startup code and user interface methods
   cTrash.hpp           // cTrash class definition and general definitions
   cTrashFile.cpp       // cTrash methods for file copy, move, delete
   cTrashFile.hpp       // Definitions for file manipulation
   cTrashCan.cpp        // Direct Trashcan management methods
   gString.cpp          // gString class for formatting text data
   gString.hpp          // gString class definition
   Makefile             // Build the cTrash application
   README               // Package description, release notes (this file)
   VERSION_HISTORY      // Change log

   /Texinfo             // cTrash documentation
      ctrash.info          // cTrash documentation in 'info' format
      ctrash.html          // cTrash documentation in HTML format
      infodoc-styles.css   // CSS style definition required by the HTML documentation
      cTrash.texi          // Documentation source files
      same_author.texi
      texi_macros.texi
      fdl-1.3.texi         // Free Documentation License
      gpl-3.0.texi         // GNU Public License
      Makefile             // Build the documentation
      applycss             // Post-processing the HTML document using 'idpp' utility
      applycss_response.txt // Post-processing instructions

To read the full Texinfo documentation for this package, type: 
                   info -f ctrash.info
or even better, open the 'ctrash.html' file in your favorite browser.
Note that the infodoc-styles.css style information must be in the same directory.


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

-- =========================================
-- NOTES on the current release of cTrash  =
-- =========================================

-- Build requires the GNU C++ compiler, version 4.8.0 or higher.
   -- FULL C++11 SUPPORT IS REQUIRED for a successful build.
   -- See below for a summary description of building the cTrash application 
      from source. (Don't worry, it's easy :)

-- Build and testing are done on both Fedora Linux and Ubuntu Linux on 32-bit 
   and 64-bit Wintel hardware. Both GNOME and Konsole terminals (Bash shell) 
   are used during testing. If your system is configured differently from these, 
   please post us a message about your experiences.

-- Current Release v:0.0.06
   -- All reported issues have been addressed.
   -- Programmers always believe that our work is totally bug-free, and we 
      are always wrong. Please report all bugs or suspected bugs via the 
      website.

-- See VERSION_HISTORY for details on updates made for this release.


-- =====================================
-- Building the 'ctrash' applications: =
-- =====================================
   This is just a quick reference.
   See the cTrash online documentation for full details.
   Open a terminal window and navigate to the documentation 
   directory.
            Example:  cd cTrash/Texinfo
   Then open the documentation file to the 'Building from Source' chapter.
            info -f ctrash.info -n 'Building from Source'
   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

   1) Open a terminal window.

   2) Navigate to the directory where you want to unpack the archive.
            (See tree structure of the archive above.)

   3) Copy the compressed archive to the target directory.
            Example: cp ~/Downloads/ctrash-x.x.xx.tar.bz2

   4) Unpack the archive:
      a) If your target directory already contains an 'cTrash' directory, 
         then rename it before unpacking the new archive.
            Example:  mv cTrash cTrash_OLD
      b) All contents of the compressed archive will be unpacked into a tree 
         whose base directory is 'cTrash'. 
      c) Unpack the archive.
            tar -xjvf ctrash-x.x.xx.tar.bz2

   5) Navigate to the directory which contains the source code.
            cd cTrash

   6) Build the 'ctrash' application.
      a) Be sure that your compiler version is 4.8.0 or greater.
            g++ --version
      b) Build the application.
            gmake clean
            gmake
      c) The build should be clean with no errors and no warnings.
         If there are errors, then the most likely cause would be that the 
         compiler cannot find a necessary header file or library.
         Check your LIB_PATH and other environment variables.

   7) Once you have a clean build, invoke with a request for version number.
            ./ctrash --version
      a) If the application successfully reports the version number and 
         copyright notice, then the application has been built correctly.
      b) If the application does not run, then verify that all necessary libraries 
         are installed on your system. Run the 'ldd' command to list the 
         necessary libraries. The needed libraries should look something like 
         the following. These are all standard libraries which should be 
         installed on your system by default.

         [cTrash]$ ldd ctrash
            linux-vdso.so.1 (0x00007fff3217c000)
            libstdc++.so.6 => /lib64/libstdc++.so.6 (0x00007f2ae95d0000)
            libm.so.6 => /lib64/libm.so.6 (0x00007f2ae948a000)
            libgcc_s.so.1 => /lib64/libgcc_s.so.1 (0x00007f2ae9470000)
            libc.so.6 => /lib64/libc.so.6 (0x00007f2ae92aa000)
            /lib64/ld-linux-x86-64.so.2 (0x00007f2ae97e8000)

   8) Verify that the application can find your default Trashcan directory.
      To do this, simply generate a summary report of the Trashcan's current 
      contents.
         ./ctrash -s

      If the Trashcan is not found, please see the cTrash documentation for 
      details on how to locate your local Trashcan.

   9) Please see the cTrash documentation for notes on installation of the 
      binary executable file and the online documentation.


-- ============================
-- Known bugs and other issues:
-- ============================
   -- No outstanding bug reports.

   -- Planned enhancements:
      -- Automate the build and install using a script file.
      -- Structure application to incorporate an optional build of cTrash 
         as a link library.
      -- Addition of optional ANSI color output.
      -- Add an optional, dialog-based build using the NcDialogAPI (ncurses).

