README file for AnsiCmd library and EarthPoints test application.

Copyright 2022-2023 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       // 
   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
   AnsiCmdTest.cpp      // Testing the functionality of the AnsiCmd class
   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
   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

   /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.texi         // AnsiCmd documentation source (Texinfo format)
      applycss             // bash script file for applying HTML post-processing 
      idpp_response.txt    // 'idpp' response file for HTML post-processing
      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

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++11 SUPPORT IS REQUIRED for a successful build.
   -- See below for a summary description of building the EarchPoints
      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.14) available 
   for download on the author's website. 

-- Current Release
   -- This is the first general release. All basic functionality has been 
      verified, although some functionality is still a bit rough.
      All functionality is subject to revision as the project moves forward.
   -- 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. 


-- ===================================
-- 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.03.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 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.

   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.

