Update instructions for building and running & coordinate with Wiki (#161)

* Move instructions for building and running to Wiki

* oops typo

* Move (revised) build instructions back

* More tweaking

Author: masinter

README-mac.md

@@ -0,0 +1,24 @@
+# Running Medley Interlisp on a Mac.
+
+Running on MacOS requires an X server, and building on a Mac requires X client libraries. An X-server for x86 can be freely obtained at https://www.xquartz.org/. For the new arm64 MacOS 11, you'll need https://x.org which you can get via MacPorts or Brew.
+
+
+### Middle-mouse tweak
+
+if you don't have a 3-button mouse (wheel = middle mouse)
+you can enable FN-left to be middle. Run in a terminal:
+
+```sh
+defaults write org.macosforge.xquartz.X11 enable_fake_buttons -boolean true
+defaults write org.macosforge.xquartz.X11 fake_button2 fn
+defaults write org.macosforge.xquartz.X11 fake_button3 none
+```
+
+To turn the settings back to the original default values do:
+
+```sh
+defaults write org.macosforge.xquartz.X11 enable_fake_buttons -boolean false
+defaults delete org.macosforge.xquartz.X11 fake_button2
+defaults delete org.macosforge.xquartz.X11 fake_button3
+```
+

README.md

@@ -1,106 +1,85 @@
-# medley 
-This repo is for the overall Lisp environment for Medley Interlisp.
+# Medley 
+This repo is for the Lisp environment of [Medley Interlisp](https://Interlisp.org). We've made great process in sorting out what we have (some dusty corners notwithstanding), but there's quite a bit more work to do. Please report problems!
 
-A sub-project is [Interlisp/maiko](https://github.com/Interlisp/maiko) which is the implementation of the Lisp virtual machine. If you want to run on some other platform that we haven't tried, you just need to port/build Maiko.
+See [Medley Interlisp Introduction](https://github.com/Interlisp/medley/wiki/Medley-Interlisp-Introduction) for an overview.
 
-Newcomers to Medley Interlisp should check out [Blake McBride's Introduction to Medley](https://github.com/Interlisp/medley-intro)
+A sub-project is [Interlisp/maiko](https://github.com/Interlisp/maiko), which is the implementation (in C) of the Medley virtual machine. 
 
-We've made great process in sorting out what we have (some dusty corners notwithstanding) and are gearing up to fix problems as they are found.
 
-## Running Medley on all platforms with Docker
+## Instructions for Building and Running
 
-If this is your first time working with Docker, you'll want to [install it](https://docs.docker.com/get-docker/) before continuing. You'll also need a modern VNC client; [TightVNC](https://www.tightvnc.com/) works well.
+### Setting up X
 
-Next, you can either pull a prebuilt image or build from scratch:
+Medley Interlisp needs an X-Server to manage its display. Most Linux desktops have one. 
+If you have a high-resolution display, note that much of the graphics was designed for a low-resolution display, so an X-server that does "pixel doublilng" is best. (E.g., Raspberry Pi does pixel doubling on 4K displayes).
+* It also presumes you have a 3-button mouse (the scroll-wheel on some mice act as one with some difficulty.) See [README-mac.md](./README-mac.md) for more info on dealing with that.
 
-### Using a prebuilt image (recommended)
+### Running Medley Interlisp
 
-1. `$ docker run -p 5900:5900 interlisp/medley`
-2. Run a VNC viewer and connect to localhost.
-
-### Building from scratch
-
-1. Pull the latest Medley repo.
-2. `$ cd medley`
-3. Pull Maiko: `$ git submodule update --init --recursive`
-4. `$ docker build . -t interlisp/medley`
-5. And then as above.
-
-
-## Running Medley on macOS
-
-1. Download and install [XQuartz](https://www.xquartz.org/releases/). MacPorts has the most recent builds.
-2. Clone this repo and [Interlisp/maiko](https://github.com/Interlisp/maiko) into the same parent directory.
-3. In a terminal:
-```sh
-cd maiko/bin
-./makeright x
-
-cd ../../medley
-./run-medley --dimensions 1440x800 -full &
+The `run-medley` script in this repo sets up some convenient defaults. Running Medley can be done by typing:
 ```
-
-### Middle-mouse tweak
-
-if you don't have a 3-button mouse (wheel = middle mouse)
-you can enable FN-left to be middle. Run in a terminal:
-
-```sh
-defaults write org.macosforge.xquartz.X11 enable_fake_buttons -boolean true
-defaults write org.macosforge.xquartz.X11 fake_button2 fn
-defaults write org.macosforge.xquartz.X11 fake_button3 none
+$ cd medley
+$ ./run-medley
 ```
 
-To turn the settings back to the original default values do:
+Or, if you wish to start Medley up with a different SYSOUT:
 
-```sh
-defaults write org.macosforge.xquartz.X11 enable_fake_buttons -boolean false
-defaults delete org.macosforge.xquartz.X11 fake_button2
-defaults delete org.macosforge.xquartz.X11 fake_button3
+```
+$ cd medley
+$ ./run-medley <SYSOUT-file-name>
 ```
 
+Once the system comes up, give it a few seconds to initialize.
 
-## Running Medley on Windows with WSL
-
-Get the Windows X server called [Xming](https://sourceforge.net/projects/xming/) (the default options will do).
+The first time the system is run it loads the system image that comes
+with the system.  When you exit the system (or "do a `SaveVM`" menu
+option) the state of your machine is saved in a file named
+`~/lisp.virtualmem`.  Subsequent system startups load the
+`~/lisp.virtualmem` image by default.
 
-Make Maiko following the instructions [in that repo](https://github.com/Interlisp/maiko), and 
-copy `lde` and `ldex` from `linux.x86_64` into your path (/usr/local/bin).
+### Exiting The System
 
-```sh
-export MEDLEYDIR=/mnt/c/path-to-medley-directory
-export HOME=/mnt/c/path-to-windows-home
-export DISPLAY=:0
-export LDEINIT="$MEDLEYDIR"/greetfiles/LOCAL-INIT
+The system may be exited from the Interlisp prompt by typing:
 
-cd "$MEDLEYDIR"
+```
+(LOGOUT)
+```
 
-IP=1.2.3.4  # your Windows machine's local IP
-./run-medley --dimensions 1440x800 --display "$IP":0 -bw 0 -full &
+Or from the Common Lisp prompt with:
 ```
+(IL:LOGOUT)
+```
+When you logout of the system, Medley automatically creates a binary
+dump of your system located in your home directory named
+`lisp.virtualmem`. The next time you run the system, if you don't
+specify a specific image to run, Medley restores that image so that
+you can continue right where you left off.
+
+* [Using Medley Interlisp](https://github.com/Interlisp/medley/wiki/Using-Medley-Interlisp)
+
 
 ## Naming conventions and directory structure
 
 File Names and Extensions: Most Interlisp source file names are
 UPPERCASE and Interlisp didn't use file extensions for its source
-files.  (note that any .TEDIT or .TXT file is probably documentation
+files. A .TEDIT or .TXT file is probably documentation
 for the package of same name, at least in the library,
-internal/library, lispusers)
+internal/library, lispusers.
 
 The current repo has both Lisp sources and compiled .LCOM and .DFASL
 files, because some files don't compile in a vanilla lisp.sysout .
 
 Each directory should have a README.md, but briefly
-- basics -- old sysouts needed (for now) for rebuilding new sysouts
+
 - docs -- Documentation files (either PDFs or online help)
 - fonts -- raster fonts (or font widths) in various resolutions for display, postscript, interpress, press formats
-- greetfiles -- should have any necessary setup of directories Lisp should look in for load
-- internal -- These _were_ internal to Venue
+- greetfiles -- various configuration setups
+- internal -- These _were_ internal to Venue; now internal/library and internal/test
 - library  -- packages that were supported (30 years ago)
 - lispusers -- packages that were only half supported (ditto)
 - loadups   -- has sysouts and other builds
 - makesysout -- files for making new sysouts for various configurations, based on basics
-- patches -- ""
+- patches -- for cases where reloading doesn't wor
 - sunloadup --  support information for making a new lisp.sysout from scratch
 - sources   -- sources for Interlisp and Common Lisp implementations
 - unicode  -- data files for support of XCCS to and from Unicode mappings