Improved top level documentation

BUGS

@@ -27,7 +27,16 @@ then it may be time to send in a bug report.
 
 =-=
 
-The BEST WAY TO SEND IN A BUG REPORT is via calc GitHub issue URL:
+If you encounter a warning or error in compiling, or if you
+find a calc bug and you wish to send is a fix, we recommend
+that you submit your change using the GitHub pull request:
+
+    https://github.com/lcn2/calc/pulls
+
+=-=
+
+If you just want to send us a bug report, we recommend
+doing so via the GitHub issue process:
 
     https://github.com/lcn2/calc/issues
 
@@ -119,6 +128,8 @@ Known bugs in calc:
     The output of the alg_config.cal resource file is bogus.
     We would welcome a replacement for this code.
 
+    Calc may not compile natively under Windows 11. See README.WINDOWS.
+
     We are sure some more bugs exist.  When you find them, please let
     us know!  See the above for details on how to report and were to
     Email your bug reports and hopefully patches to fix them.

CHANGES

@@ -37,6 +37,20 @@ The following are the changes from calc version 2.14.0.11 to date:
 
     Now assuming that <stdio.h> is available under _WIN32 and _WIN64.
 
+    Added some preliminary notes about attempts to compile calc
+    under Windows 11.
+
+	BTW: While we are unable to use Windows 11, we welcome
+	     Windows 11 developers to try compiling calc natively
+	     (instead of via a Linux virtual machine).  If you are
+	     able to compile Windows 11 natively, we would welcome
+	     GitHub pull requests showing any needed modifications:
+
+		https://github.com/lcn2/calc/pulls
+
+	     Please also add notes to the 'Compiling calc under Windows 11'
+	     section in README.WINDOWS file.
+
 
 The following are the changes from calc version 2.14.0.9 to 2.14.0.10:
 

HOWTO.INSTALL

@@ -3,20 +3,21 @@ IMPORTANT: Please see the section at the bottom of this file for
 	   some important information on Makefiles used in calc.
 
 ###################################################################
-# IMPORTANT: DO NOT run GNU make in parallel mode!!!		  #
+# IMPORTANT: DO NOT use make in parallel mode!!!		  #
 ###################################################################
 # Unfortunately due to the complex dependency issues between	  #
-# Makefile, Makefile.ship and custom/Makefile, parallel GNU make  #
+# Makefile, Makefile.ship and custom/Makefile, parallel make      #
 # is NOT recommended.  Sorry (tm Canada) :)			  #
 ###################################################################
 
-Installing calc from the bzip2-ed tarball in 4 easy steps:
+Installing calc from the bzip2-ed tarball: 4 easy steps:
 
-    (0)  If your platform supports i686 RPMs, you may want to go to:
+    (0) If your platform supports i686 RPMs, you may want to go to:
 
-	    http://www.isthe.com/chongo/src/calc/
+	    https://github.com/lcn2/calc/releases
 
-	and use these RPMs:
+	Open up the 'Assets' tag below a given release and
+	download these RPMs:
 
 	    * calc*.i686.rpm
 		- all that is needed if you just want to use calc
@@ -25,17 +26,26 @@ Installing calc from the bzip2-ed tarball in 4 easy steps:
 	        - calc *.h header and *.a lib files for use in other programs
 
 	    * calc.*.src.rpm
-	        - calc source in RPM package form
+	        - calc source via a SRPM package
 
-	The following 4 steps apply to calc source tree that comes from either:
+	Alternately to the above github link, you might try looking at
+	the RPMs under:
 
-		bunzip2 -c calc-*.tar.bz2 | tar -xvf -
+	    http://www.isthe.com/chongo/src/calc/
 
-	or from:
+=-=
 
-		rpm -ivh calc-*.src.rpm
+The following 4 steps apply to calc source tree that comes from either:
-		cd /var/tmp
+
-		bunzip2 -c /usr/src/redhat/SOURCES/calc-*.tar.bz2 | tar -xvf -
+	bunzip2 -c calc-*.tar.bz2 | tar -xvf -
+
+or from:
+
+	rpm -ivh calc-*.src.rpm
+	cd /var/tmp
+	bunzip2 -c /usr/src/redhat/SOURCES/calc-*.tar.bz2 | tar -xvf -
+
+4 steps:
 
     (1)	Look at the makefile, and adjust it to suit your needs.
 
@@ -204,9 +214,6 @@ Installing calc from the bzip2-ed tarball in 4 easy steps:
 
 	make check
 
-	==> If you run into problems, read the BUGS file and follow
-	    the instructions found in there.
-
 	NOTE: For a quiet check which only prints if something goes wrong:
 
 		make chk
@@ -218,6 +225,9 @@ Installing calc from the bzip2-ed tarball in 4 easy steps:
 We suggest that you might want to read the README.FIRST file and look at
 the calc help subsystem.  See also the README.md file.
 
+In general, if you run into problems, read the BUGS file and follow
+the instructions.
+
 =-=
 
 On calc Makefiles:
@@ -241,10 +251,10 @@ SHELL= ...
 
     On some systems such as macOS, the bash shell is very
     far behind to the point where is cannot be depended on.
-    On such systems, the zsh may be a much better alternative
+    On such systems, the sh may be a much better alternative
     shell for this Makefile to use:
 
-	    SHELL= /bin/zsh
+	    SHELL= /bin/sh
 
 Makefile
 
@@ -252,7 +262,7 @@ Makefile
 
     This is our internal Makefile that drives how we build calc.
     For critical rules in Makefile.ship, there is a corresponding
-    rule in Makefile that calls ${MAKE} -f Makefile.ship with,
+    rule, Makefile, that calls ${MAKE} -f Makefile.ship with,
     additional commands, args and Makefile variables.  The ${XVAR}
     Makefile variable, for example, is passed on each call to
     ${MAKE} -f Makefile.ship so that the environment and parameters of
@@ -328,7 +338,7 @@ Makefile.ship
     the custom/Makefile.  In particular the Makefile.ship lines:
 
 	# start of host target cut
-	... these go in between custom/Makefile.head and custom/Makefile.tail
+	... these go between custom/Makefile.head and custom/Makefile.tail
 	# end of host target cut
 
 Makefile.simple

README.WINDOWS

@@ -3,6 +3,17 @@ Dear calc user on a Windows based system,
 See the HOWTO.INSTALL file for information on how to build and install calc.
 See also the README file.
 
+BTW: While we are unable to use Windows 11, we welcome
+     Windows 11 developers to try compiling calc natively
+     (instead of via a Linux virtual machine).  If you are
+     able to compile Windows 11 natively, we would welcome
+     GitHub pull requests showing any needed modifications:
+
+	https://github.com/lcn2/calc/pulls
+
+     Please also add notes to the 'Compiling calc under Windows 11'
+     section in README.WINDOWS file.
+
 NOTE: The main developers do not have access to a Windows based platform.
       While we will make an effort to not break calc Windows based system,
       our lack of a Windows test environment will mean we will make mistakes
@@ -10,10 +21,37 @@ NOTE: The main developers do not have access to a Windows based platform.
       Of course you are welcome to send us any patches that fix your
       Windows build environment.
 
+=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
+=-= Compiling calc under Windows 11 =-=
+=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
+We were given this advice from a Windows 11 developer:
-=-= compiling with Windows Subsystem for Linux (WSL) =-Cygwin =-=
+
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
+    Windows 11 users should try:
+
+	https://git-scm.com/downloads
+
+	    When you run the installer wizard, make sure you choose/check
+	    the git bash installer option.
+
+	https://www.mingw-w64.org/
+
+	    Runtime environment for GCC & LLVM for 32 and 64 bit Windows
+
+	    We suggest Windows 11 users consider using MINGW64.
+
+We would prefer a Windows 11 solution that does not require a Windows 11
+developer to install a Linux virtual machine.  Nevertheless, a Windows 11
+user might want to use the Microsoft Windows Subsystem (WSL) for Linux:
+
+	https://docs.microsoft.com/en-us/windows/wsl/
+
+    We have been told that you will need to turn on virtualization
+    to use this WSL subsystem.
+
+=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
+=-= Compiling calc under Windows 10 via Windows Subsystem for Linux (WSL) =-=
+=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 
 It has been reported that calc version 2.12.6.4 has been successfully
 compiled, installed and running on Windows 10 on 2018 Jan 21.
@@ -78,9 +116,9 @@ needs.
 
 In particular:
 
-	Just copy the win32/*.[ch] files up into the top level calc
+    Just copy the win32/*.[ch] files up into the top level calc
-	source directory, edit them (if needed) and build using the
+    source directory, edit them (if needed) and build using the
-	Cygwin GCC compiler and Cygwin build environment.
+    Cygwin GCC compiler and Cygwin build environment.
 
 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 =-= compiling under DJGPP =-=

input.c

@@ -971,11 +971,12 @@ runrcfiles(void)
  *
  * _WIN32 and _WIN64 NOTE:
  *
- *	This function does not work under _WIN32 or _WIN64. The sbuf->st_ino is always
+ *	This function likely will not work under _WIN32 or _WIN64.
- *	zero because the FAT and NTFS filesystems do not support inodes.
+ *
- *	They also don't support links, which is why you need this function
+ *	The sbuf->st_ino is always zero because the FAT and NTFS filesystems
- *	under UNIX. For _WIN32 or _WIN64, use _fullpath() to determine if you have
+ *	do not support inodes.  Those filesystems don't support links, which
- *	already opened a file.
+ *	is why you need this function under UNIX. For _WIN32 or _WIN64, use
+ *	_fullpath() to determine if you have already opened a file.
  *
  * given:
  *	sbuf		stat of the inode in question