README file for AnsiCmd library and EarthPoints test application.

Copyright 2022-2026 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 ansicmd-x.x.xx.tar.bz2

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


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

AnsiCmd/                // Source code directory
   AnsiCmd.hpp          // AnsiCmd class definition
   AnsiCmdDef.hpp       // Definition of ANSI escape sequences and secondary classes
   AnsiCmd.cpp          // Main AnsiCmd methods
   AnsiCmdApi.cpp       // Miscellaneous application-level methods
   AnsiCmdAca.cpp       // acaExpand-class implementation
   AnsiCmdSkf.cpp       // Implementation of skForm and skField classes
   AnsiCmdWin.hpp       // Definition of ACWin derived class and support definitions
   AnsiCmdWin.cpp       // Implementation of ACWin derived class
   AnsiCmdWix.cpp       // Additional ACWin class methods
   AnsiCmdDlg.hpp       // ACDlg class definition
   AnsiCmdDlg.cpp       // ACDlg class implementation
   AnsiCmdTest.cpp      // Testing the functionality of the AnsiCmd class
   WaylandCB.hpp        // System clipboard manager definition
   WaylandCB.cpp        // System clipboard manager implementation
   TFMan.hpp            // Temporary-file manager
   EarthPoints.hpp      // Definition of EarthPoints application class
   EarthPoints.cpp      // Application framework (calculates GPS arc-distances)
   EpParse.cpp          // Parse command-line arguments and application startup code
   gString.hpp          // Class definition for text formatting and internationalization
   gString.cpp          // Implementation of gString class
   AnsiCmd.lib          // Link library build (for x86_64 only)
   epts                 // EarthPoints executable file (for x86_64 only)
   Makefile             // Build the EarthPoints application with AnsiCmd library
   report.pl            // Report conditional compilation settings (Perl script)
   US_Capitols.txt      // Database file of GPS coordinates for EarthPoints application
   UK_GPS.txt           // Database file of GPS coordinate for EarthPoints application
   testpoints.txt       // Database file of GPS coordinates to test parsing of records
   README               // Package description, release notes (this file)
   VERSION_HISTORY      // Change log

   /CsvView             // Demonstration application -- view CSV-encoded files
      CsvView.hpp       // Definition of the CsvView class and supporting constructs
      CsvView.cpp       // Implementation of CsvView class and user interface
      CsvFile.hpp       // Definition of file management classes and definitions
      CsvFile.cpp       // General file management methods
      csvsource.txt     // Sample plain-text file from which the CSV samples were generated
      csvv              // Application binary executable (x86_64)
      Makefile          // Build the CsvView application with AnsiCmd library
     /1_TestData        // Directory containing sample CSV-encoded files
      utf16be.csv       // UTF-16BE encoded sample (big-endian)
      utf16be_cr.csv    // UTF-16BE with cr/lf pairs
      utf16be_dq.csv    // UTF-16LE encoded sample with embedded delimeters
      utf16be_dqcr.csv  // UTF-16LE encoded sample with embedded delimeters AND CR/LF pairs
      utf16le.csv       // UTF-16LE encoded sample (little-endian)
      utf16le_cr.csv    // UTF-16LE with cr/lf pairs
      utf16le_dq.csv    // UTF-16LE encoded sample with embedded delimeters
      utf16le_dqcr.csv  // UTF-16LE encoded sample with embedded delimeters AND CR/LF pairs
      utf8.csv          // UTF-8 encoded sample
      utf8_cr.csv       // UTF-8 with cr/lf pairs
      utf8_dq.csv       // UTF-8 encoded sample with embedded delimeters
      utf8bom.csv       // UTF-8 encoded sample with BOM (byte-order-mark)
      utf8bom_cr.csv    // UTF-8 with byte-order-mark and cr/lf pairs

   /AcEdit              // Demonstration application -- (very) simple text editor
      AcEdit.cpp        // Demonstration application -- Editor
      AcEdit.hpp        // Application class definition and support definitions
      AcEditCfg.cpp     // Startup and configuration
      AcEditFile.cpp    // File management
      AcEditFile.hpp    // File management definitions
      AcEditMenu.cpp    // Application menu support
      ace.cfg           // Application configuration file
      ace               // Application binary executable (x86_64)
      Makefile          // Build the AcEdit application with AnsiCmd library
     /1_TestData        // Directory containing sample files for edit
      Welcome1.txt
      TestFile.cpp
      LoremIpsum.txt
      unicorny.txt

   /TFMTest             // Demonstration application -- Temporary-file management
      TFMTest.cpp       // Application source code.
      Makefile          // Build the TFMTest application

   /Texinfo             // AnsiCmd documentation
      ansicmd.info         // AnsiCmd documentation in 'info' format
      ansicmd.html         // AnsiCmd documentation in HTML format
      infodoc-styles.css   // CSS style definition required by the HTML documentation
      AnsiCmd_00_menu.texi // AnsiCmd documentation source (Texinfo format)
      AnsiCmd_01_introduction.texi
      AnsiCmd_02_invoking.texi
      AnsiCmd_03_library.texi
      AnsiCmd_04_window.texi
      AnsiCmd_05_testing.texi
      AnsiCmd_06_buildsource.texi
      AnsiCmd_07_gStringTextTool.texi
      AnsiCmd_08_CsvView.texi
      AnsiCmd_09_AcEdit.texi
      AnsiCmd_10_TFMTest.texi
      texi_macros.texi     // General macro definitions for creating Texinfo documents
      same_author.texi     // Boilerplate for Software Sam's published software
      gpl-3.0.texi         // GNU General Public License text (from FSF)
      fdl-1.3.texi         // GNU Free Documentation License text (from FSF)
      Makefile             // Build the info and HTML documents
      applycss             // bash script file for applying HTML post-processing 

To read the full Texinfo documentation for this package, type: 
                   info -f ansicmd.info
or even better, open the 'ansicmd.html' file in your favorite browser.


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

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

-- Build requires the GNU C++ compiler, version 4.8.0 or higher. 
   Current development version is v:12.3.1 20230508 (Red Hat 12.3.1-1)
   -- FULL C++17 SUPPORT IS REQUIRED for a successful build.
   -- See below for a summary description of building the EarthPoints
      application from source.

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

-- Rebuilding the Texinfo documentation requires 'makeinfo' (texi2any) v:6.8 
   or greater.
-- Rebuilding the HTML documentation requires the 'idpp' post-processor 
   utility, which is part of the 'Infodoc' package (v:0.0.16) available 
   for download on the author's website. 

-- Current Release
   -- Significant additions have been made since the initial release.
      All basic functionality has been verified, although some functionality 
      must be considered as a work-in-progress.
      All functionality is subject to revision as the project moves forward.
   -- NOTE: When the Linux console window is first opened, the system's support 
      for dynamic memory allocation may not yet be fully awake.
      Because the AnsiCmd library does a significant amount of dynamic memory 
      allocation and release (heap memory), the first time an AnsiCmd-based 
      application is opened, a memory-allocation error may cause the application 
      to hang. If this happens:
        1) Perform a controlled abort: (CTRL+4 or CTRL+\) key combination.
        2) Execute a terminal window reset: ('reset' utility), then
        3) Restart the application.
      In a future release, we hope to encapsulate dynamic memory allocation 
      to prevent this problem; however, that is a major project with its 
      own set of headaches.
   -- 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.
   -- Documentation is incomplete in some sections and is subject to 
      significant revision as the project moves forward.

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


   -- ============================
   -- Known bugs and other issues:
   -- ============================
   -- Customization of METs value for age, weight, gender and other factors 
      are not implemented in this version. The METs tables are used in 
      their published form.
   -- As delivered, all debugging code is active under conditional compile 
      directives. Please refer to the documentation for a discussion of 
      conditional compilation directives.

   -- Planned updates:
      -- Implementation in Zhongwen (simplified Chinese) is planned. 
      -- Implementation of the AcEdit application is incomplete.
         Functionality will be strengthened as time permits.


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

   1) Open a terminal window.

   2) Navigate to the directory where you want to unpack the archive.
            Example: cd ~/sam/SoftwareDesign

   3) Copy the compressed archive to the target directory.
            Example: cp ~/Downloads/ansicmd-0.0.05.tar.bz2

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

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

   7) Build the 'epts' application.
      a) Be sure that your compiler version is 9.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.

   8) Once you have a clean build, invoke with a request for version number.
            ./epts --versionA
      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.

         [AnsiCmd]$ ldd epts
            linux-vdso.so.1 (0x00007fff48bf4000)
            libstdc++.so.6 => /lib64/libstdc++.so.6 (0x00007fa9cfe00000)
            libm.so.6 => /lib64/libm.so.6 (0x00007fa9d00ea000)
            libgcc_s.so.1 => /lib64/libgcc_s.so.1 (0x00007fa9d00ca000)
            libc.so.6 => /lib64/libc.so.6 (0x00007fa9cfc23000)
            /lib64/ld-linux-x86-64.so.2 (0x00007fa9d01df000)

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

