update Rpi install instructions

alpha.md

@@ -0,0 +1,5 @@
+> [!CAUTION]
+>
+> - This is an **alpha release**, used for validating new features.  *Some features are likely to be incomplete or non-functional*.
+> - **Alpha releases are not normally used in actual competitions.** 
+> - Export your current database before updating if it contains important data.

beta.md

@@ -0,0 +1,4 @@
+> [!WARNING]
+>
+> - This is a **beta release**, used for testing and translation. ***Some features could be non-functional***.
+> - Beta releases are **not** normally used in actual competitions, except when a new feature is required. Use extreme care in testing if you intend to do so.

rc.md

@@ -0,0 +1,4 @@
+> [!WARNING]
+>
+> - This is a release candidate [(see definition)](https://en.wikipedia.org/wiki/Software_release_life_cycle#Release_candidate), used for final public testing and translation. *It is still a preliminary release*
+> - You should test all releases, with actual data, *several days* before a competition. This is especially important when considering the use of a release candidate.

src/main/markdown/docs/LocalLinuxMacSetup.md

@@ -1,6 +1,6 @@
 ## macOS, Linux or RaspberryOS Installation
 
-> Pre-requisite:  You may need to perform a simple install prior to installing owlcms.  See the [Installing Java](#installing-java) section at the bottom of this page to check.
+> Pre-requisite:  You may need to install the Java language on your computer before installing owlcms. See [Installing Java](#installing-java) section at the bottom of this page to check.
 
 ## Installation
 
@@ -10,16 +10,17 @@
 
 - Double-click on the downloaded zip file, and extract the files to a directory. 
 
-  - On a Mac We suggest you use `~/owlcms` as the unzipped location.
+  - We suggest you use `owlcms`  in your home directory as the unzip location
 
-- Go to your installation directory where you unzipped owlcms
+- Start a terminal window and go to the installation directory where you unzipped owlcms. `~/owlcms` is the shortcut abbreviation for the `owlcms` directory inside your home. 
 
   ```bash
+  cd ~/owlcms
   java -jar owlcms.jar
   ```
-  This will actually start the program. See [Initial Startup](#initial-startup) for how to proceed.
+  This will start the program. See [Initial Startup](#initial-startup) below for how to proceed further.
 
-  If you just want to use dummy data to practice (this will not touch your actual database), click on the grey box to copy this command and paste it.
+- If you just want to use dummy data to practice (this will not touch your actual database), you can add the following additional options to the java command to start with demo data and run in memory without touching your data.
 
   ```
   java -DmemoryMode=true -DinitialData=LARGEGROUP_DEMO -jar owlcms.jar
@@ -28,36 +29,41 @@
 
 ## Initial Startup
 
-When owlcms is started on a laptop, two windows are visible:  a command-line window, and an internet browser
+When owlcms is started on a laptop, two windows are used:  a command-line window, and an internet browser
 
-- The command-line window (typically with a black background) is where the OWLCMS primary web server shows its execution log.  
+- The terminal (command-line) window (typically with a black background) is where the OWLCMS primary web server shows its execution log.  Something like this will be visible to show that all is going well.  If you have already started the owlcms program, you may see an error message telling you that you can only have one at a time -- you will need to find the other one and stop it.
+  ![log](img/LocalInstall/log.png)
 
-  All the other displays and screens connect to the primary server.  <u>You can stop the program by clicking on the x</u> or clicking in the window and typing `Control-C`.  The various screens and displays will spin in wait mode until you restart the primary program -- there is normally no need to restart or refresh them.
+- Normally, a browser will be opened automatically.  If the browser does not open automatically, start a browser and navigate to http://localhost:8080 .  The browser will sit there waiting for the program to finish loading the database and become ready.
 
-- Depending on the platform, a browser will be opened automatically (or not).  If the browser does not open automatically, navigate to http://localhost:8080
+- After the browser page loads, if you look at the top, you will see what address to use when connecting from other laptops
 
-- After the browser opens, if you look at the top, you will see two or more lines that tell you how to open more browsers and connect them to the primary server.
+  ![startup](img/LocalInstall/startup.png)
 
-  ![060_urls](img\LocalInstall\060_urls.png)
+  In this example the other laptops on the network would use the address `http://192.168.1.174:8080/` to communicate with the primary server.  "(wired)" refers to the fact that the primary laptop is connected via an Ethernet cable to its router -- see [Local Access](EquipmentSetup#local-access-over-a-local-network) for discussion.  
 
-  In this example the other laptops on the network would use the address `http://192.168.4.1:8080/` to communicate with the primary server.  "(wired)" refers to the fact that the primary laptop is connected via an Ethernet wire to its router -- see [Local Access](EquipmentSetup#local-access-over-a-local-network) for discussion.  When available, a wired connection is preferred.
+  > When running a competition with a local router, it is recommended to connect the owlcms server to the router with an Ethernet cable.  If a (wired) address is shown, this is the one you should use on the other laptops.
+  
+  The addresses shown <u>depend on your own specific networking setup</u> and you normally use one of the addresses displayed on the home page.
+
+  If none of the addresses listed work, something in your networking setup is preventing access.   The most likely cause is a firewall running on the server or on the network, which will need to be disabled. 
 
-  The address <u>depends on your own specific networking setup</u> and you must use one of the addresses displayed **on your setup.**  If none of the addresses listed work, you will need to refer to the persons that set up the networking at your site and on your laptop.  A "proxy" or a "firewall", or some other technical configuration may be blocking access, or requiring a different address that the server can't discover.
+- All the other displays and screens connect to the primary server.  <u>You can stop the program by clicking on the x</u> or clicking in the window and typing `Control-C`.  If you stop the program, all the other screens and displays will wait.  If you restart the main program, they will notice and reload.  Normally there is no need to reload them manually, but there is no harm in doing so.
 
 ## Installing Java
 
 Make sure you have a Java17 installed. 
 
 - You can type `java -version` in a Terminal window to see if it is installed, and if so, what version you have.
 
-- On RaspberryOS, Java is already installed.
+- If Java is missing
 
-- For macOS, see [MacOS Java 17](https://adoptium.net/temurin/releases/?os=mac&package=jre&arch=aarch64&version=17) and download the .pkg file. (Temurin is the code name for one of the free Java releases). Double-click the file.
+  - For macOS, see [MacOS Java 17](https://adoptium.net/temurin/releases/?os=mac&package=jre&arch=aarch64&version=17) and download the .pkg file. (Temurin is the code name for one of the free Java releases). Double-click the file.
+  - For Raspberry Pi, Ubuntu and other Debian variants, type
 
-- For Ubuntu and other Debian variants, the following should work.
 
   ```bash
-  sudo apt install default-jre
+      sudo apt install openjdk-17-jdk
   ```
 
-- For other Linux distros, see [Linux Java 17](https://adoptium.net/temurin/releases/?os=linux&package=jre&arch=any&version=17) and choose according to the Linux you run
+  - For other Linux distros, see [Linux Java 17](https://adoptium.net/temurin/releases/?os=linux&package=jre&arch=any&version=17) and choose according to the Linux you run

src/main/markdown/docs/LocalWindowsSetup.md

@@ -26,27 +26,34 @@ When OWLCMS is started on a laptop, two windows are visible:  a command-line win
 
 ![040_starting](img\LocalInstall\040_starting.png)
 
-- The command-line window (typically with a black background) is where the OWLCMS primary web server shows its execution log.  
+- The terminal (command-line) window (typically with a black background) is where the OWLCMS primary web server shows its execution log.  Something like this will be visible to show that all is going well.  If you have already started the owlcms program, you may see an error message telling you that you can only have one at a time -- you will need to find the other one and stop it.
+  ![log](img/LocalInstall/log.png)
+
+- Normally, a browser will be opened automatically.  If the browser does not open automatically, start a browser and navigate to http://localhost:8080 .  The browser will sit there waiting for the program to finish loading the database and become ready.
+
+- After the browser page loads, if you look at the top, you will see what address to use when connecting from other laptops
+
+  ![startup](img/LocalInstall/startup.png)
 
-  All the other displays and screens connect to the primary server.  <u>You can stop the program by clicking on the x</u> or clicking in the window and typing `Control-C`.  The various screens and displays will spin in wait mode until you restart the primary program -- there is normally no need to restart or refresh them.
+  In this example the other laptops on the network would use the address `http://192.168.1.174:8080/` to communicate with the primary server.  "(wired)" refers to the fact that the primary laptop is connected via an Ethernet cable to its router -- see [Local Access](EquipmentSetup#local-access-over-a-local-network) for discussion.  
 
-- The white window is a normal browser.  If you look at the top, you will see two or more lines that tell you how to open more browsers and connect them to the primary server.
+  > When running a competition with a local router, it is recommended to connect the owlcms server to the router with an Ethernet cable.  If a (wired) address is shown, this is the one you should use on the other laptops.
 
-  ![060_urls](img\LocalInstall\060_urls.png)
+  The addresses shown <u>depend on your own specific networking setup</u> and you normally use one of the addresses displayed on the home page.
 
-  In this example the other laptops on the network would use the address `http://192.168.4.1:8080/` to communicate with the primary server.  "(wired)" refers to the fact that the primary laptop is connected via an Ethernet wire to its router -- see [Local Access](EquipmentSetup#local-access-over-a-local-network) for discussion.  When available, a wired connection is preferred.
+  If none of the addresses listed work, something in your networking setup is preventing access.   The most likely cause is a firewall running on the server or on the network, which will need to be disabled. 
 
-  The address <u>depends on your own specific networking setup</u> and you must use one of the addresses displayed **on your setup.**  If none of the addresses listed work, you will need to refer to the persons that set up the networking at your site and on your laptop.  A "proxy" or a "firewall", or some other technical configuration may be blocking access, or requiring a different address that the server can't discover.
+- All the other displays and screens connect to the primary server.  <u>You can stop the program by clicking on the x</u> or clicking in the window and typing `Control-C`.  If you stop the program, all the other screens and displays will wait.  If you restart the main program, they will notice and reload.  Normally there is no need to reload them manually, but there is no harm in doing so.
 
-  ## Accessing the Program Files and Configuration
+## Accessing the Program Files and Configuration
 
-  In order to uninstall owlcms4, to report problems, or to change some program configurations, you may need to access the program directory. In order to do so, right-click on the desktop shortcut and select "Open File Location"
+In order to uninstall owlcms4, to report problems, or to change some program configurations, you may need to access the program directory. In order to do so, right-click on the desktop shortcut and select "Open File Location"
 
-  ![070_openLocation](img\LocalInstall\070_openLocation.png)
+![070_openLocation](img\LocalInstall\070_openLocation.png)
 
-  If you do so, you will see the installation directory content:
+If you do so, you will see the installation directory content:
 
-  ![080_files](img\LocalInstall\080_files.png)
+![080_files](img\LocalInstall\080_files.png)
 
 - `owlcms.exe` starts the owlcms server.  `demo-owlcms.exe` does the same, but using fictitious data that is reset anew on every start; this makes it perfect for practicing.