README file for Exercalc (ecalc) weekly exercise calculator.

Copyright 2020-2021 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 exercalc-x.x.xx.tar.bz2

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

The 'ecalc' application is implemented as a console dialog and facilitates 
recording and analysis of daily or weekly exercise progress.

   1) Exercalc is written from the ground up as a multilingual application and 
      currently supports English, Spanish, Chinese (simplified) and Vietnamese.
      Adding new user interface languages for both left-to-right (LTR) languages 
      and right-to-left (RTL) languages is straightforward and requires very 
      little programming skill.

   2) Exercalc uses the Metabolic Equivalent for Task (METs) database to 
      calculate the effectiveness of the selected exercise type.

   3) Exercise types which are directly supported are:
      a) Walking
      b) Running
      c) Bicycling
      d) General cardio exercise (weight lifting, yard work, etc.)

   4) Exercalc is written specifically as a teaching tool for students 
      as well as working professionals.
      a) The C++ source code includes EXTENSIVE internal documentation.
      b) The external documentation is both comprehensive and comprehensible.
      c) The only external library needed is the NcDialog API written by the 
         same author. (The NcDialog API is based on the ncursesw C-language 
         library which is included with nearly all GNU/Linux distributions.)
      d) Exercalc is built using the GNU C++ compiler (C++11 support required).
         See below for build instructions.


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

Exercalc/               // Source code directory
   Exercalc.hpp         // Exercalc class definition and general definitions
   Exercalc.cpp         // Exercalc-class instantiation methods
   EcConfig.hpp         // Startup and configuration definitions
   EcConfig.cpp         // Startup, configuration and misc. utility methods
   EcLog.hpp            // Log file access definitions
   EcLog.cpp            // Log file storage and retrieval methods
   Exercalc.cfg         // Configuration file (modify using any text editor)
   Makefile             // Build the Exercalc application
   README               // Package description, release notes (this file)
   VERSION_HISTORY      // Change log

   /Texinfo             // Exercalc documentation
      exercalc.info        // Exercalc documentation in 'info' format
      exercalc.html        // Exercalc documentation in HTML format
      infodoc-styles.css   // CSS style definition required by the HTML documentation
      Exercalc.texi        // Exercalc documentation source (Texinfo format)
      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

Note that additional files comprising the NcDialog API are required for a 
successful build. (see below for details)
   NcDialog.a           // NcDialog API library
   GlobalDef.hpp        // General definitions for the NcDialog API
   NCurses.hpp          // Primitive interface to the 'ncursesw' C-language library
   NCursesKeyDef.hpp    // Constant keycode definitions
   NcWindow.hpp         // The parent class of all NcDialog windows and controls
   NcDialog.hpp         // The NcDialog class definition
   gString.hpp          // Class definition for text formatting and internationalization


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


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

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

-- Build requires the GNU C++ compiler, version 4.8.0 or higher. Current
   development version is v:10.3.1.
   -- FULL C++11 SUPPORT IS REQUIRED for a successful build.
   -- See below for a summary description of building the Exercalc 
      application from source.

-- 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
   -- All documented functionality is fully implemented; however, this 
      application is constructed specifically as a teaching tool, and for 
      this reason, some features are simplistic by design.
   -- 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.


   -- ============================
   -- 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.
   -- Several sections of debugging code remain active so that students 
      may experiment

   -- Planned updates:
      -- Implementation of an RTL (right-to-left) user-interface language, 
         probably Hebrew (or Yiddish) because they are the only RTL languages 
         with which the author is familiar. 
         -- Verify that all RTL hooks are fully functional.


-- ====================================
-- Building the 'ecalc' applications: =
-- ====================================
   This is just a quick reference.
   See the Exercalc online documentation for full details.
   Open a terminal window and navigate to the documentation 
   directory.
            Example:  cd Exercalc/Texinfo
   Then open the documentation file to the 'Building from Source' chapter.
            info -f exercalc.info -n 'Building from Source'
   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
   IMPORTANT: Before building Exercalc, you must first download and build the 
   =========  NcDialog API library. The NcDialog directory should be installed 
              at the same directory level as the Exercalc directory.
              Example: /home/sam/SoftwareDesign/NcDialog
                       /home/sam/SoftwareDesign/Exercalc
              See the NcDialog API documentation for details.
   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

   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/exercalc-0.0.01.tar.bz2

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

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

   6) Copy the necessary components from the NcDialog library:
            gmake refreshlib
            (see above for a list of necessary NcDialog files)

   7) Build the 'ecalc' 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.
            ./ecalc --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.

         [Exercalc]$ ldd ecalc
            linux-vdso.so.1 (0x00007ffe801a5000)
            libncursesw.so.6 => /lib64/libncursesw.so.6 (0x00007f6fed559000)
            libtinfo.so.6 => /lib64/libtinfo.so.6 (0x00007f6fed52a000)
            libstdc++.so.6 => /lib64/libstdc++.so.6 (0x00007f6fed342000)
            libm.so.6 => /lib64/libm.so.6 (0x00007f6fed1fc000)
            libgcc_s.so.1 => /lib64/libgcc_s.so.1 (0x00007f6fed1e1000)
            libc.so.6 => /lib64/libc.so.6 (0x00007f6fed016000)
            libdl.so.2 => /lib64/libdl.so.2 (0x00007f6fed00d000)
            /lib64/ld-linux-x86-64.so.2 (0x00007f6fed5b9000)

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

