Revamp Install and Run pages for Windows and Linux

.gitignore

@@ -17,3 +17,4 @@ node_modules/
 _gen/
 .hugo_build.lock
 .idea
+data/bibliography.json

content/en/software/install-and-run/_index.md

@@ -1,4 +1,4 @@
----
+---
 title: Install and Run
 aliases:
  - /medley/using/build/
@@ -11,25 +11,9 @@ weight: 10
 type: docs
 ---
 
-You can install Medley on a variety of different computer systems. 
-
-
-### Download and install from a release
-  * [Running on Linux](./running-on-linux)
-    * Packages for .deb distributions and source to build for others
-  * [Running on Mac](./running-on-mac)
-    * for MacOS
-  * [Running on Windows](./running-on-win)
-    * [Running on Windows with WSL](./running-on-wsl)
-
-
-Medley has a virtual machine architecture: there's a virtual machine implementation (called Maiko) and Lisp software that is compiled into instructions for it. The compiled code and memory images can be moved from one architecture to another -- only Maiko needs to be ported. Maiko has been substantially revised and modernized, so you can to run Medley on many different OSes and machine architectures.
-
-See the [Maiko README](https://github.com/Interlisp/maiko#readme) and [Medley README](https://github.com/Interlisp/medley#readme) in their respective GitHub repository pages for more details on how to build and run them.
+Packaged releases of Medley are available for Linux (most recent distros), MacOS and Windows 10/11.  Both x86_64 and Arm64 systems are supported (as well as Arm7 - e.g., Raspberry Pi - for Linux).  Instructions for installing and running Medley on these platforms are linked below.
 
-The current systems we've tested or for which we have confirmed reports can be found [in the Maiko github repository](https://github.com/Interlisp/maiko/tree/master/bin), including:
-* OS:  FreeBSD, Linux, MacOS, Solaris, Windows (using WSL or CygWin)
-* CPU: arm7l, arm64, PowerPC, SPARC, i386, x86_64
+Medley is capable of running on a variety of other OSes including FreeBSD and Solaris as well as on other CPU architectures including i386, SPARC, PowerPC, and Risc-V.  To install and run Medley on these platforms, you will need to build Medley (and its underlying virtual machine, *Maiko*) from the sources available in the Interlisp repos on github.com.  Instructions for building Medley and Maiko can be be found on github in the [*readme* for Maiko](https://github.com/interlisp/maiko) and the [*readme* for Medley](https://github.com/interlisp/medley).
 
 
 

content/en/software/install-and-run/linux/_index.md

@@ -0,0 +1,119 @@
+---
+title: Install and Run on Linux
+weight: 20
+aliases:
+ - /software/install-and-run/running-on-linux/
+type: docs
+---
+<style>.td-content blockquote { border-left: none; color: inherit; padding-left: 2rem;}</style>
+
+*Note that these instructions do not apply to Linux distros running within Windows System For Linux (WSL).  [Separate instructions are available for WSL here.](../windows/wsl).*
+
+Medley installs and runs on most recent Linux distros (Alpine Linux is one exception).  All that is strictly required is that the distro include an X Windows server.   Most of the testing for Medley has been done on Ubuntu 20.04 and 22.04.
+
+We also recommend that the Linux system have a web browser installed.  A browser is not strictly necessary to run Medley, but several features of the system (e.g., displaying some user documentation) will not work without a browser installed.
+
+## **Install Medley**
+
+Medley can be installed on Linux in one of two configurations: *standard* and *local*. 
+
+* Standard installation is available only for Debian-based distros (e.g., Debian, Ubuntu, MX Linux, Mint Linux, etc.).  It will install Medley into system directories (i.e., /usr/local/interlisp) and automatically install any prerequisite packages.
+* Local installation will install Medley into any user directory but any prerequisite packages must be installed manually.
+
+Standard installations are ideal for users who want to explore Medley (including its system code) or to develop applications built on top of Medley.  Standard installations are not good for users who want to modify the Medley system code, since that code is installed in protected locations.
+
+### **Standard Installation (for Debian-based distros only)**
+
+1.  Download the installation file (.deb) for the latest release from the [Medley downloads site](https://online.interlisp.org/downloads/medley_downloads.html)  from under the heading Linux/Standard/Linux.  There are are separate .deb files for X86_64, Arm64 and Arm7 (e.g., Raspberry Pi) systems.  Download the one that corresponds to your machine architecture.  We will refer to the downloaded file as ***\<deb_filepath>***
+
+ <div align="center"><img alt="Medley Downloads Page" width=500 src="./images/downloads-page-linux-standard.png"><p>&nbsp;</p></div>
+
+   > >Alternatively, you can download the .deb files for the current or any previous release from the Medley Releases page on the Interlisp GitHub site.  [Instructions for this can be found here](./linux-standard-from-github).
+
+2.  Into any  Linux terminal, enter the following commands.  This will install Medley and all prerequisite packages.
+
+	```
+	ubuntu@oio:~$ sudo apt update
+	ubuntu@oio:~$ sudo apt install -y <deb_filepath>
+	```
+	
+### **Local Installation**
+1.  Create a directory into which Medley will be installed.  We will refer to this directory as ***\<install_dir>***
+
+2.  Download the release tar file (.tgz) for the latest release from the [Medley downloads site](https://online.interlisp.org/downloads/medley_downloads.html)  from under the heading Linux/Local/Linux.  There are are separate .tgz files for X86_64,  Arm64 , and Arm7 (e.g., Raspberry Pi) systems.  Download the one that corresponds to your machine architecture.  We will refer to the downloaded file as ***\<tgz_filepath>***
+ 
+<div align="center"><img alt="Medley Downloads Page" width=500 src="./images/downloads-page-linux-local.png"><p>&nbsp;</p></div>
+
+   > >Alternatively, you can download the .deb files for the current or any previous release from the Medley Releases page on the Interlisp GitHub site.  [Instructions for this can be found here](./linux-local-from-github).
+
+3. Untar ***<tgz_filepath>*** using the following command:
+   ```
+   ubuntu@oio:~$ tar -xz -C <install_dir> -f <tgz_filepath>
+   ```
+4.  Using the package manager for your distro (e.g., apt for Debian and Ubuntu distros), install the following packages:
+a) man-db
+b) xdg-utils
+c) tigervnc
+> ***Notes:***
+
+> 4.1.  If *xdg-utils* is not available for your Linux distro, then Medley will still run well, with the exception of a few sub-systems that require opening external (to Medley) files.
+
+> 4.2. On Debian-based systems (including Ubuntu), the *tigervnc* package is not available.  Instead install both the *tigervnc-standalone-server package* and the *tigervnc-xorg-extension* package.
+
+## **Multiple Installations**
+**Standard Installations**
+Multiple standard installations are not possible.  It is possible to have a single Standard installation alongside one or more Local installations.
+
+**Local Installations**
+For local installations, you can install multiple copies of Medley (e.g. different releases).  Simply place each installation into a separate ***install_dir***. And follow the install instructions above.
+
+Each Medley installation so installed will operate independently of other Medley installations.  The Medley system code for each installation will remain separate. However, in general the installations will share a single file system. So care must be taken to coordinate access to the file system.
+
+## **Update Medley**
+To update any given Medley installation (e.g., to install a new release), download the updated .deb or .tgz installer file as described above.  Then (re)run the appropriate install procedure as described above.
+
+The chosen Medley installation will be updated.  Any user files (i.e., files created by the user that are not part of the Medley distribution) in the Medley file system will remain intact.
+
+## **Run Medley**
+Medley is started from any Linux terminal using the following commands.
+##### **Standard Installations**
+```
+medley <flags and options>
+```
+   Example:
+<img alt="Start Medley Standard" width=500 src="./images/linux-standard.png">
+
+##### **Local Installations**
+```
+cd <install_dir>
+./medley <flags and options>
+```
+   Example:
+<img alt="Start Medley Standard" width=500 src="./images/linux-local.png">
+
+Documentation for the `<flags and options>` to the `medley` command can be found [here](https://online.interlisp.org/downloads/man_medley.html)
+
+For first-time users: `medley --vnc --apps --interlisp --noscroll` or, equivalently, `medley -v -a -e -n` is a good starting point.  This will give you a fully populated Medley system, including the applications built on Medley such as Notecards and Rooms.
+
+This will bring up the Medley environment in a separate Window on your Windows desktop.  The Medley desktop and windows will all be contained within this Window as shown below.
+
+![Medley window open on Windows desktop](./images/Medley-on-Linux.png)
+
+
+
+## **Use Medley**
+Once Medley is up and running, see [here](../../using-medley/_index) for tips on how to navigate and use the Medley environment.
+
+By default, Medley will use (creating, if necessary) a directory called *$HOME/il*.  This will be used by the Medley system as its *LOGINDIR* as follows:
+ 
+  1.  Medley will start up with *LOGINDIR* as its current connected directory.
+
+   2. Medley will load any personal init file from *LOGINDIR*/INIT or *LOGINDIR*/INIT.LCOM. 
+
+   3. Medley will use *LOGINDIR*/vmem/ to store its virtual memory file(s).  
+ 
+ The location of *LOGINDIR* can be changed using the `--logindir` option to `medley`.  In particular, if you have multiple installations of Medley that you would like to keep completely separate, then you can use the `--logindir` option to ensure the *LOGINDIR* for each installation is unique.
+
+To exit Medley, type ```(IL:LOGOUT)``` at any Exec window prompt.
+
+

content/en/software/install-and-run/linux/linux-local-from-github.md

@@ -0,0 +1,19 @@
+---
+title: Download WSL (Local Installation) Install Files from Github
+weight: 40
+toc_hide: true
+hide_summary: true
+type: docs
+---
+<style>.td-content blockquote { border-left: none; color: inherit; padding-left: 2rem;}</style>
+
+1.  Go to the [Releases page for Interlisp/Medley on github.com](https://github.com/interlisp/medley/releases).  Here you will see a list of releases in reverse chronological order.  
+ <div align="center"><img alt="Github Releases Page" width=500 src="../images/releases-page-landing.png"><p>&nbsp;</p></div>
+
+3. Choose the release you are interested in (most likely the release marked ***Latest***) and click on the arrow next the word ***Assets*** to reveal the list of assets (i.e., installation files) for that release.   
+
+4. To download the .tgz install file, click on the link that ends with ***.tgz*** and begins with either ***medley-full-linux-x86_64*** (if you are installing on an x86_64-based machine)  or ***medley-full-linux-aarch64*** (if you are installing on an Arm64-based machine) or  ***medley-full-linux-arm7l*** (if you are installing on an Arm7-based machine - e.g., a Raspberry Pi).
+<div align="center"><img alt="Github Releases Page Assets" width=500 src="../images/releases-page-linux-local.png"><p>&nbsp;</p></div>
+
+
+

content/en/software/install-and-run/linux/linux-standard-from-github.md

@@ -0,0 +1,19 @@
+---
+title: Download WSL (Standard Installation) Install Files from Github
+weight: 40
+toc_hide: true
+hide_summary: true
+type: docs
+---
+<style>.td-content blockquote { border-left: none; color: inherit; padding-left: 2rem;}</style>
+
+1.  Go to the [Releases page for Interlisp/Medley on github.com](https://github.com/interlisp/medley/releases).  Here you will see a list of releases in reverse chronological order.  
+ <div align="center"><img alt="Github Releases Page" width=500 src="../images/releases-page-landing.png"><p>&nbsp;</p></div>
+
+3. Choose the release you are interested in (most likely the release marked ***Latest***) and click on the arrow next the word ***Assets*** to reveal the list of assets (i.e., installation files) for that release.   
+
+4. To download the .tgz install file, click on the link that ends with ***.deb*** and begins with either ***medley-full-linux-x86_64*** (if you are installing on an x86_64-based machine)  or ***medley-full-linux-aarch64*** (if you are installing on an Arm64-based machine) or  ***medley-full-linux-arm7l*** (if you are installing on an Arm7-based machine - e.g., a Raspberry Pi).
+<div align="center"><img alt="Github Releases Page Assets" width=500 src="../images/releases-page-linux-standard.png"><p>&nbsp;</p></div>
+
+
+

content/en/software/install-and-run/macos/_index.md

@@ -0,0 +1,110 @@
+---
+title: Install and Run on MacOS
+weight: 30
+type: docs
+aliases:
+  - /running/running-on-mac
+  - /software/install-and-run/running-on-mac/
+---
+<style>.td-content blockquote { border-left: none; color: inherit; padding-left: 2rem;}</style>
+
+## **Prerequisite: Install XQuartz**
+
+Before installing and running Medley on your Mac, you will need to download and install XQuartz - an open-source X11 Windows server for the Mac.  You can download the latest XQuartz .pkg from  [XQuartz.org](https://xquartz.org) and install it using the MacOS installer.
+
+If you do not have a three-button mouse on your Mac, you will need to set `Emulate three button mouse` in the XQuartz preferences.        
+
+>To do so, start XQuartz (e.g., by double clicking the XQuartz icon within Launchpad). Select XQuartz->Preferences from the menu bar. In the Preferences dialog, select the Input tab and then check the *Emulate three button mouse* option.
+
+## **Install Medley**
+
+Medley releases on MacOS are distributed as a .zip file.  The .zip file contains universal binaries so that the same file can be used for either Intel or Apple Silicon machines.
+
+To install Medley:
+
+1. Download the latest release .zip from the [Medley downloads page](https://online.interlisp.org/downloads/medley_downloads.html) , under the heading "MacOS ...".
+
+ <div align="center"><img alt="Medley Downloads Page" width=500 src="./images/downloads-page-macos.png"><p>&nbsp;</p></div>
+
+>> You can also download the installation .zip file for the latest as well as any prior releases from the Medley Releases page on the Interlisp GitHub site.  [Instructions for this can be found here](./macos-from-github). 
+
+2.  Copy the downloaded *medley-full-macos-universal...zip* file (which MacOS treats as an unzipped folder) from the Downloads folder into any folder of your choosing.  Optionally,  rename the target folder of the copy from *medley-full-macos-universal...* to something more manageable - e.g., *medley-latest*.  For the purposes of these instructions, we will call this (renamed) folder the *\<medley_folder>*.
+
+3. In a Terminal window, you will need to remove the quarantine attributes from the executable files by executing the following command:
+
+```
+   xattr -d com.apple.quarantine <path to medley_folder>/maiko/darwin.universal/lde*
+```
+For example (assuming *\<path to medley_folder>* is *~/il/medley-latest*): 
+
+```
+    ssd@Mac-mini ~ % xattr -d com.apple.quarantine ~/il/medley-latest/maiko/darwin.universal/lde*
+```
+## **Multiple Installations**
+You can install multiple copies of Medley (e.g. different releases).  Simply make sure the *<medley_folder>* for each installation has a unique pathname and then follow the install instructions above.
+
+Each Medley installation so installed will operate independently of other Medley installations.  The Medley system code for each installation will remain separate. However, in general the installations will share a single file system. So care must be taken to coordinate access to the file system.
+
+## **Update Medley**
+To update any given Medley installation (e.g., to install a new release), download the updated .zip installer file as described above.  
+
+The simplest update would be to delete the original *\<medley_folder>* and install the updated zip file as described above.  However, this will delete any files/folders added by the user to *\<medley_folder>*.
+
+To preserve any user added files in *\<medley_folder>*, you instead need to open a Terminal and execute the following command: 
+```
+    cp -rp <path to downloaded zip folder> <path to medley_folder>
+```
+
+For example (assuming that ***\<medley_folder>*** is *~/il/medley2* and that the updated .zip folder is *~/Downloads/medley-full-macos-universal-240126-39ee2ecb_231112-42477318/*):
+```
+    ssd@mini ~ % cp -rp ~/Downloads/medley-full-macos-universal-240126-39ee2ecb_231112-42477318/* ~/il/medley2
+```
+The chosen Medley installation will be updated.  Any user files (i.e., files created by the user that are not part of the Medley distribution) in the Medley file system will remain intact.
+
+## **Run Medley**
+
+On MacOS, Medley must be started from a Terminal window.
+
+At the Terminal prompt, you need to execute the  following commands: 
+```
+    cd <path to medley_folder>/medley`
+    ./medley <flags and options>
+  ```
+
+For example: 
+```
+    ssd@Mac-mini ~ % cd ~/il/medley-latest/medley
+    ssd@Mac-mini medley % ./medley --apps --interlisp --noscroll
+```
+Note that the first time you run it, Medley may take 10-15 seconds to start up as it starts the XQuartz X Windows server (assuming that it is not already running).
+>You can optionally start the XQuartz server manually before starting Medley.  It will take 10-15 seconds to start up and then display an Xterm window in the upper-left corner of the screen.  You can just close this Xterm window.
+
+Documentation for the `<flags and options>` to the `medley` command can be found [here](https://online.interlisp.org/downloads/man_medley.html)
+
+For first-time users: `medley --vnc --apps --interlisp --noscroll` or, equivalently, `medley -v -a -e -n` is a good starting point.  This will give you a fully populated Medley system, including the applications built on Medley such as Notecards and Rooms. It will also start with a Interlisp Exec window (instead of the default Xerox Common Lisp Exec window).
+
+This will bring up the Medley environment in a separate window on your desktop.  The Medley desktop and windows will all be contained within this window as shown below.
+
+![Medley window open on MacOS desktop](./images/Medley-on-MacOS.png)
+
+## **Use Medley**
+Once Medley is up and running, see [here](../../using-medley/_index) for tips on how to navigate and use the Medley environment.
+
+By default, Medley will use (creating, if necessary) a directory called *$HOME/il*.  This will be used by the Medley
+system as its *LOGINDIR* as follows:
+
+  1.  Medley will start up with *LOGINDIR* as its current connected directory.
+
+   2. Medley will load any personal init file from *LOGINDIR*/INIT or *LOGINDIR*/INIT.LCOM. 
+
+   3. Medley will use *LOGINDIR*/vmem/ to store its virtual memory file(s).  
+
+ The location of *LOGINDIR* can be changed using the `--logindir` option to `medley`.  In particular, if you have multiple installations of Medley that you would like to keep completely separate, then you can use the `--logindir` option to ensure the *LOGINDIR* for each installation is unique.
+
+To exit Medley, type ```(IL:LOGOUT)``` at any Exec window prompt.
+
+
+
+
+
+

content/en/software/install-and-run/macos/macos-from-github.md

@@ -0,0 +1,19 @@
+---
+title: Download MacOS Install File from Github
+weight: 40
+toc_hide: true
+hide_summary: true
+type: docs
+---
+<style>.td-content blockquote { border-left: none; color: inherit; padding-left: 2rem;}</style>
+
+1.  Go to the [Releases page for Interlisp/Medley on github.com](https://github.com/interlisp/medley/releases).  Here you will see a list of releases in reverse chronological order.  
+ <div align="center"><img alt="Github Releases Page" width=500 src="../images/releases-page-landing.png"><p>&nbsp;</p></div>
+
+3. Choose the release you are interested in (most likely the release marked ***Latest***) and click on the arrow next the word ***Assets*** to reveal the list of assets (i.e., installation files) for that release.   
+
+4. To download the .zip install file, click on the link that begins with ***medley-full-macos-universal*** and ends with ***.zip***.
+<div align="center"><img alt="Github Releases Page Assets" width=500 src="../images/releases-page-macos.png"><p>&nbsp;</p></div>
+
+
+