v3.0 release, mainly to provide installers. Add display of FX path to build.bat. Update web pages.

Author: fjwright

README.md

@@ -1,17 +1,22 @@
 # Run-REDUCE
 
-## A JavaFX GUI to run CLI versions of the REDUCE Computer Algebra System
+## A JavaFX GUI to run any CLI version of the REDUCE Computer Algebra System
 
-### Francis Wright, December 2020
+### Francis Wright, March 2021
 
 I originally implemented Run-REDUCE using Swing as the obsolete
 project now called
-[Run-REDUCE-0](https://fjwright.github.io/Run-REDUCE-0/).  I
-originally called the current JavaFX version Run-REDUCE-FX but I have
-now dropped the "-FX" suffix.  It requires Java 11 or later plus
-JavaFX 11 or later, although I recommend using Java 15 plus JavaFX 15
-since I currently build Run-REDUCE using Java 15, set to language
-level 11, plus JavaFX 15.
+[Run-REDUCE-0](https://fjwright.github.io/Run-REDUCE-0/) and I called
+the current JavaFX version Run-REDUCE-FX, but I have since dropped the
+"-FX" suffix.  Run-REDUCE requires Java and JavaFX version 11 or
+later, although I recommend using version 16 since I currently build
+Run-REDUCE using Java 16, set to language level 11, plus JavaFX 16.
+Future versions may require Java 16 or later.
+
+However, if possible, I recommend using the self-contained installers
+available for 64-bit Windows 10 and Gnu/Linux distributions based on
+Debian (e.g. Ubuntu) or Red Hat (e.g. Fedora), which include all
+required Java and JavaFX support and hide the implementation details.
 
 For further general background information please see the [Run-REDUCE
 web page](https://fjwright.github.io/Run-REDUCE/).  For information
@@ -22,10 +27,10 @@ Guide](https://fjwright.github.io/Run-REDUCE/UserGuide.html) (which is
 also included in Run-REDUCE and easily accessible via the Help menu).
 
 See also the [release notes for all recent
-releases](https://github.com/fjwright/Run-REDUCE/releases).
+version](https://github.com/fjwright/Run-REDUCE/releases).
 
 Run-REDUCE should run on any platform that supports JavaFX 11 (or
-later), but I can only test it on Microsoft Windows and Linux.
+later), but I can only test it on Microsoft Windows and Gnu/Linux.
 (Whilst Java is portable, filesystem structures, installation
 conventions and display systems are not!)
 

docs/InstallAndRun.md

@@ -1,21 +1,79 @@
 # Run-REDUCE Install and Run Guide
 
-## Francis Wright, December 2020
-
 Run-REDUCE is an open-source JavaFX GUI to run the REDUCE Computer
 Algebra System.  REDUCE must be obtained from
 [SourceForge](https://sourceforge.net/projects/reduce-algebra/) and
 installed separately.  Run-REDUCE should find a standard REDUCE
 installation automatically and not **require** any initial
-configuration, at least on Microsoft Windows and Linux.  With
+configuration, at least on Microsoft Windows and Gnu/Linux.  With
 [suitable
 configuration](https://fjwright.github.io/Run-REDUCE/UserGuide.html#Configure)
-it **should** run on any platform that supports JavaFX 11 or later,
-but I can only test on 64-bit Windows 10, Ubuntu 18/20 and Fedora 32.
+it **should** run on any platform that supports JavaFX, but I can only
+test on 64-bit Windows, Ubuntu and Fedora.
+
+I recommend that you use the appropriate installer but you can also
+use the platform-independent JAR, although this is considerably more
+complicated.  Please note that: the installers are quite large, around
+50 MB, whereas the JAR is well under 1 MB; I may release installers
+less frequently than JARs.
+
+
+## Using an Installer
+
+I provide installers for 64-bit Windows and Gnu/Linux, which include
+customised versions of Java and JavaFX (but not REDUCE).  The
+appropriate installer will have a name of the following form, where
+*\<version\>* represents the version of Run-REDUCE:
+
+Platform                             | Installer Filename
+-------------------------------------|-------------------
+Microsoft Windows                    | Run-REDUCE-*\<version\>*.msi
+Debian-based Gnu/Linux, e.g. Ubuntu  | run-reduce\_*\<version\>*-1_amd64.deb
+Red Hat-based Gnu/Linux, e.g. Fedora | run-reduce-*\<version\>*-1.x86\_64.rpm
+
+Download the latest available installer file for your platform from
+the [GitHub releases
+page](https://github.com/fjwright/Run-REDUCE/releases) and run it,
+e.g. by double-clicking on it.
+
+### Microsoft Windows
+
+The Run-REDUCE package will be installed in the folder `C:\Program
+Files\Run-REDUCE` by default, but you can change this.  It will appear
+as an installed app in *Settings* under *Apps & features*, which can
+be used to uninstall it.  It will also appear in the *Start Menu* in
+the *Reduce* folder, which provides the recommended way to run it.  To
+update the Run-REDUCE package you just need to run the installer for
+the new version.
+
+### Gnu/Linux
 
-You need to have a Java Runtime Environment (JRE) and JavaFX libraries
-installed, both version 11 or later (preferably the latest release);
-see below for details.
+The Run-REDUCE package will be installed in the directory
+`/opt/run-reduce` and will appear as an installed app in *Software*,
+which can be used to uninstall it.  It will also appear in
+*Applications* in the *Unknown/Other* category, which provides the
+easiest way to run it.
+
+To update the Run-REDUCE package you need to uninstall the old version
+and then install the new version.  One way to do this is to run the
+installer for the new version **twice**; the first run just invites
+you to uninstall the old version, but does not install the new
+version.
+
+The executable is actually installed as
+`/opt/run-reduce/bin/Run-REDUCE` and you can use this full pathname as
+a shell command to run Run-REDUCE if you want, but the directory is
+not automatically added to your PATH.  Note that if you run Run-REDUCE
+this way then you will probably see a GDK warning message, which you
+can ignore.  (It is not displayed when you run Run-REDUCE from
+*Applications*.)
+
+
+## Using the JAR
+
+To run the JAR, you need to have a Java Runtime Environment (JRE) and
+JavaFX libraries installed, both version 11 or later (preferably the
+latest release); see below for details.
 
 You also need to download the file
 [Run-REDUCE.jar](https://github.com/fjwright/Run-REDUCE/releases/latest/download/Run-REDUCE.jar)
@@ -71,20 +129,19 @@ option unless you want it for running other Java applications (but
 keep the *Add to PATH* option).
 
 On other platforms, install `adoptopenjdk-<latest>-hotspot-jre`, where
-`<latest>` represents the highest number available, currently 15.  If
-you prefer, you can use Java 11 and the non-JRE version (see above).
+`<latest>` represents the highest number available.  If you prefer,
+you can use Java 11 and/or the non-JRE version (see above).
 
 
 ## Install OpenJFX
 
 Visit [OpenJFX](https://openjfx.io/), scroll down and click on the
-*Download* button.  Scroll down to *Latest Release* (or you can
-currently use JavaFX 11 if you prefer), download the appropriate
-*JavaFX SDK* file (not the *jmods* file) and save it.  Move it
-somewhere appropriate (anywhere should work) and unzip it.  Make a
-note of the full pathname of the *lib* sub-directory or copy it, since
-you need it to set up the `PATH_TO_FX` environment variable; see
-below.
+*Download* button.  Scroll down to *Latest Release* (or you can use
+JavaFX 11 if you prefer), download the appropriate *JavaFX SDK* file
+(**not** the *jmods* file) and save it.  Move it somewhere appropriate
+(anywhere should work) and unzip it.  Make a note of the full pathname
+of the *lib* sub-directory or copy it, since you need it to set up the
+`PATH_TO_FX` environment variable; see below.
 
 
 ## Run Run-REDUCE using a Batch File on...
@@ -131,33 +188,25 @@ PATH_TO_FX=path-to-openjfx/lib
 followed by a space.
 
 An easy way to run Run-REDUCE using a shell command is first to open
-*Files* and navigate to the directory to which you downloaded
-*Run-REDUCE.jar*.  Right-click in this directory and select *Open
-in Terminal*.  You can now run Run-REDUCE as described above by
-executing the shell command
+*Files*, navigate to the directory to which you downloaded
+*Run-REDUCE.jar* and set the file permissions to make *Run-REDUCE*
+executable.  Right-click in, or open the drop-down menu for, this
+directory and select *Open in Terminal*.  You can now run Run-REDUCE
+as described above by executing the shell command
 
 ``` shell
-. Run-REDUCE
+./Run-REDUCE
 ```
 
-(Note that the above command has the form dot space filename, where
-dot is a short name for the *source* command.  If you set the file
-permissions to make Run-REDUCE executable, you can run it as
-`./Run-REDUCE`, but this doesn't gain much!)
-
 
 ## Known Issues
 
-On my main Windows computer, which has an HD display, I find that I
-need to use a larger REDUCE I/O font size than I would expect.  (A
-font with the same numerical size appears smaller than in Run-REDUCE.)
-This may be because JavaFX font sizes don't reflect display scaling.
-
-On Ubuntu 18 and 20, by default, two warning message appears and on
-Ubuntu 18 some dialogues jump when they first appear.  The warning
-about *libcanberra-gtk-module* can be avoided by using *Synaptic* to
-install *libcanberra-gtk-module* (or you can just ignore it).  In
-order to avoid the other problems, I have included the option
+When running *Run-REDUCE.jar* on Ubuntu 18 and 20, by default, two
+warning messages appear and on Ubuntu 18 some dialogues jump when they
+first appear.  The warning about *libcanberra-gtk-module* can be
+avoided by using *Synaptic* to install *libcanberra-gtk-module* (or
+you can just ignore the warning).  In order to avoid the other
+problems, I have included the option
 
 ``` shell
 -Djdk.gtk.version=2
@@ -171,13 +220,19 @@ I have been advised that on Kubuntu 18.04.4 it may be necessary to
 install the Gnome 2 theme Adwaita.  You may also find that the About
 and error dialogue boxes are too small by default.
 
-If *Run-REDUCE* misbehaves or crashes, try including the option
+If *Run-REDUCE.jar* misbehaves or crashes, try including the option
 
 ``` shell
 -Dprism.order=sw
 ```
 
-which tells Java to use software display rendering.  On Fedora, you
-may find that the *Gnome Classic* desktop environment works better
-than *Gnome*.  (One way to select your desktop environment is by using
-the settings icon on the login screen.)
+which tells Java to use software display rendering.
+
+On Fedora, you may find that the *Gnome Classic* desktop environment
+works better than *Gnome*.  (One way to select your desktop
+environment is by using the settings icon on the login screen.)  I
+find that on Fedora 32 and 33 using the default desktop, namely GNOME
+(Wayland), dialogues jump when opened or closed, whereas using either
+GNOME Classic or GNOME on Xorg (X11) avoids this problem.
+
+Francis Wright, March 2021