Fix #55: add WSL instructions

docs/README.md

@@ -12,7 +12,8 @@ For each desktop and laptop you want to use for M269:
 - Make sure you have about 1 Gb disk space and a recent version of your operating system.
 - Make sure you have created your M269 folder and have put the M269 book there,
   as instructed in the Resources tab of the M269 website.
-- To **install** the software for the first time, follow the instructions for
+- If you want to have Linux on your Windows machine, first [install WSL](install-wsl.md).
+- To **install** the M269 software for the first time, follow the instructions for
   [Linux](install-linux.md), [macOS](install-mac.md) or [Windows](install-windows.md).
 - To **upgrade** the software on any operating system, follow [these instructions](upgrade.md).
 - To **remove** the software on any operating system, follow [these instructions](uninstall.md).

docs/install-linux.md

@@ -3,29 +3,33 @@
 > **Tip:** To avoid errors, instead of typing the commands below,
 > select and copy them from this page and paste them into the terminal.
 
-1. Open a terminal.
+**WSL:** Remember that opening a terminal means to open a PowerShell and enter `wsl`.
+
+1. Open a new terminal. Do _not_ use an already opened terminal.
 
 2. Enter `python3.12 -V` to check if you have Python 3.12.
    If you get an error message like 'command not found':
    - Enter `sudo apt install python3.12` or similar.
      (Search online for instructions for your Linux distribution.)
-   - If you're using a Debian-based distribution like Ubuntu,
-   enter _in addition_ `sudo apt install python3.12-venv` or similar.
 
-3. If you installed Python in step 2, close the terminal and open a new one.
+3. If you're using a Debian-based distribution like Ubuntu,
+   enter `sudo apt install python3.12-venv` or similar.
+
+4. If you installed Python in step 2, close the terminal and open a new one.
 
-4. Enter `cd <M269 folder path>`, e.g. `cd ~/OU/m269-25j`,
+5. Enter `cd <M269 folder path>`, e.g. `cd ~/OU/m269-25j`,
    to go to your M269 folder. (`~` is a shorthand for your home folder.)
+   - **WSL:** If your M269 folder is e.g. on `C:\OU\m269-25j` then
+      you must enter `cd /mnt/c/OU/m269-25`.
 
-5. Enter `curl -LO https://github.com/dsa-ou/m269-installer/raw/main/install.sh`
+6. Enter `curl -LO https://github.com/dsa-ou/m269-installer/raw/main/install.sh`
    to download the installation script.
 
-6. Enter `chmod +x install.sh` to allow the installation script to run.
+7. Enter `chmod +x install.sh` to allow the installation script to run.
 
-7. Enter `./install.sh` to run the installation script.
-   Ignore a message about pytype and networkx being incompatible.
+8. Enter `./install.sh` to run the installation script.
 
-8. Close the terminal.
+9. Close the terminal.
 
 You will have these files in your M269 folder:
 - `install.sh`: the installation script

docs/install-wsl.md

@@ -0,0 +1,31 @@
+# Installing WSL
+
+[Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/about)
+(WSL) allows Windows and Linux to be used at the same time on the same machine.
+It also allows both operating systems to access each other's files.
+
+We thank our tutor Andy Connolly for an initial version of these instructions
+and for checking this final version.
+
+> **Tip:** To avoid errors, instead of typing the commands below,
+> select and copy them from this page and paste them into the PowerShell.
+
+1. Open a PowerShell.
+2. Enter `wsl --install -d Ubuntu-24.04` to install an Ubuntu Linux distribution with Python 3.12.
+   During the process you will be asked to create an administrator password.
+3. Restart your machine.
+4. Open a PowerShell.
+5. Enter `wsl` to start using Linux.
+6. Enter `sudo apt update && sudo apt upgrade -y` to upgrade the Linux software.
+   The `sudo` command will ask you for the administrator password.
+7. Optional: If you prefer to use `python` rather than `python3` to start python,
+   enter `sudo apt install python-is-python3`.
+8. Close the PowerShell.
+
+From now on, follow the Linux instructions, with two small changes:
+when you're asked to open a terminal, open a PowerShell instead and enter `wsl`;
+when you're asked to close a terminal, close the PowerShell.
+
+Click now on the link below to install the M269 software on Linux.
+
+⇧ [Home](README.md)  | [Installing on Linux](install-linux.md) ⇨

docs/upgrade.md

@@ -6,14 +6,19 @@ In the latter case, you will have to upgrade one or two packages,
 rather than re-install the whole software.
 
 We will announce any required upgrades in the M269 news.
-If we tell you to 'upgrade p1 and p2', where p1 and p2 are package names,
+If we tell you to 'upgrade p1, p2 and ...', where p1, p2, ... are package names,
 do as follows:
 
-1. Open a new PowerShell (Windows) or terminal (Linux, macOS).
+1. If you have a browser page open with your Jupyter notebooks:
+   - Save them.
+   - Quit JupyterLab with File > Shut Down.
+   - Close the browser page.
+   - Close the PowerShell or terminal from which you started JupyterLab.
+2. Open a new PowerShell (Windows) or terminal (Linux, macOS).
    Do *not* use an already opened PowerShell or terminal.
-2. Enter `m269-25j` to activate the M269 software.
-3. Enter `pip install --upgrade p1 p2`. For example,
-   `pip install --upgrade allowed` will only reinstall the `allowed` package.
-4. Close the PowerShell or terminal, or enter `nb` to start working in JupyterLab.
+3. Enter `m269-25j` to activate the M269 software.
+4. Enter `pip install --upgrade p1 p2 ...`. Use only spaces to separate package names.
+   For example, `pip install --upgrade allowed` only upgrades the `allowed` package.
+5. Close the PowerShell or terminal, or enter `nb` to start working in JupyterLab.
 
 ⇦ [Installing](install.md) | ⇧ [Home](README.md) | [Re-installing](reinstall.md) ⇨

docs/use.md

@@ -42,10 +42,12 @@ and you are using `bash`, enter in the terminal
  ```
 Then close the terminal, and start again from step 1.
 
-**macOS:** If you use Safari, you should change a configuration setting
-the first time you open JupyterLab. Choose the menu option Settings > Settings Editor.
-In the settings search box, type 'windowing'. In the settings pane that appears,
-change the windowing mode to defer. The change is automatically saved.
-Close the settings pane.
+**macOS:** If you use Safari, do as follows when opening JupyterLab for the first time.
+
+1. Choose the menu option Settings > Settings Editor.
+2. In the settings search box, type 'windowing' without the quote marks.
+3. In the settings pane that appears, change the windowing mode to defer.
+   The change is automatically saved.
+4. Close the settings editor pane.
 
 ⇦ [Upgrading](upgrade.md) | ⇧ [Home](README.md) | [Uninstalling](uninstall.md) ⇨