Package    : CommExtract
Author     : Mahlon R. Smith 
             Copyright (c) 2024 Mahlon R. Smith, The Software Samurai 
                GNU GPL copyright notice below 
 
Unpack this archive using the following command:
              tar -xjvf commextract-x.x.xx.tar.bz2

Description: Extract C++ comment lines from a source file, then remove 
the comment token (//) and leading/trailing whitespace, to create plain text 
which can then be inserted into the documentation for that project. 
 
The author has found this to be a useful tool, in that his development 
style for a new project is to write the comments first. The code is then 
written to implement the project described in those comments. 
This is ALSO the approach all of our students are encouraged to use for 
their class projects. 
 
The practical result of this approach is that the project documentation 
essentially writes itself. The bulk of the comments can be moved to a 
ReadMe file or to a Texinfo documentation file. However, it is rather 
tedious to manually remove the C++ comment tokens, so this simple utility 
performs the task automagically.
---  ---  ---  ---  ---  ---  ---  ---  ---  ---  ---  ---  ---  ---  ---  ---

Copyright Notice: 
This program is free software: you can redistribute it and/or modify it 
under the terms of the GNU General Public License as published by the Free 
Software Foundation, either version 3 of the License, or (at your option) 
any later version. 
 
This program is distributed in the hope that it will be useful, but 
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 
or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License 
for more details. 
 
You should have received a copy of the GNU General Public License along 
with this program.  If not, see <http://www.gnu.org/licenses/>. 
---  ---  ---  ---  ---  ---  ---  ---  ---  ---  ---  ---  ---  ---  ---  ---

Development Tools: 
------------------------------
G++ v:13.3.1 20240913 
Fedora v:39 
GNOME Term v:3.50.1 (GNOME 45)

Files Included in the archive:
------------------------------
CommExtract
   CommExtract.hpp            // Application-class definition
   CommExtract.cpp            // Application-class implementation
   CxFile.hpp                 // File-management definitions
   CxFile.cpp                 // File-management methods
   gString.hpp                // Class definition for text formatting and analysis
   gString.cpp                // Implementation of gString class
   Makefile                   // make (gmake) recipe file
   comex                      // binary executable (x86_64)
   create_archive.pl          // Perl script for creating distribution archive
   README                     // this file


--------------
Release Notes:
--------------
1) Because this is a smelly old hack and not a production-worthy 
   application, we assume that the user IS the owner of the source and 
   target files and of the directory in which they live. This simplifies 
   the access-validation process. For a more robust validatation of file 
   access, see our FileMangler application. 
2) It is expected (but not enforced) that source and target files are in the 
   current working directory (CWD). It would be rather dangerous to create 
   and/or truncate a target file at some random position in the filesystem. 
      Beware! 
3) The actual reformatting of the text data is handled by the gString class. 
   The gString source included in this package is also available as a 
   stand-alone package and well as being integrated into our NcDialog API 
   library. 
4) If the source data contains ASCII Tab characters (0x09): 
   first, DON'T use tabs in source code, and second, the columns of the 
   output will be misaligned. Sorry about that :) 
5) Terminal Configuration: 
   a) The width of the I/O streams are set the first time they are used. 
      The wide input/output streams are accessed through the 'wcin' and 
      'wcout' classs, respectively. 
      The narrow input/output streams are accessed through the 'cin' and 
      'cout' classes, respectively. Narrow streams are not used in this 
      application. (No application written in the current century should 
      use narrow-stream I/O.)
   b) The terminal's "locale" determines the character encoding used, and the 
      primary language expected. This determines the way the terminal will 
      handle certain text formatting -- for instance, currency symbols 
      and number formats. 
      It is important to understand that if the application does not 
      explicitly set the desired locale, the so-called "C-local" is used. 
      The C-locale restricts the character set to an ASCII superset (7-8-bit 
      characters), and is unacceptable for any serious application.
6) The file 'create_archive.pl' is not needed by the application. It is used 
   to verify the source data configuration and to create the distribution 
   archive. It is included in this package only as an example of using 
   Perl to perform file-management chores. Your humble author is certainly 
   no expert in the Perl language, but the code provides examples for some 
   simple constructs.
7) Data Processing Logic: 
   For each line in the specified range: 
   a) Scan over leading whitespace. 
      If first non-whitespace characters are not "//", skip the line. 
   b) If first non-whitespace is "//" C++ comment: 
      a) If "//" is followed by '*', include it in sequence to be deleted. 
      b) If '//' or '//*' is followed by a space, include it in sequence 
         to be deleted, (2, 3 or 4 characters, total) 
   c) If the line ends with a trailing '*', remove it. 
   d) Strip whitespace: 
      a) If 'wspAll' flag is set, strip both leading and trailing whitespace. 
      b) Else, strip trailing whitespace only. 
         (maintains vertical column alignment) 
   e) Append a single space to the end of the line. 
   f) Write the reformatted text to the output file. 

----------------
Version History: 
----------------
v: 0.00.02 30-Sep-2024 
   -- Errors identified by beta-tester corrected 30-Sep (Thanks Lucy!) 
   -- Added timestamp to output (because it was fun).
   -- Created documentation in the form of a readme file. 
      Note that creating this file took about twenty minutes, and  
      served as a real-world test of application functionality.
   -- Wrote Perl script for creating distribution archive.
   -- Posted to website: 01-Oct-2024

v: 0.00.01 26-Sep-2024 
   -- First Effort. 
      - Define the user interface (command-line arguments). 
      - File management utilities adapted (in simplified form) from 
        our AcEdit application. 
      - First beta release 29-Sep-2024. 

