Big reorganisation to hopefully make everything clearer.

* It goes through the necessary steps in a more logical order (python,
  check pip, check tkinter, only then get source, use pip, run
  application).

  As a result the necessary instructions for macOS should be clearer.

Running-from-source.md

@@ -1,57 +1,93 @@
-Running from source
+#Running from source
-===
 
 You will currently need at least Python 3.7.x to run `stable` code.  In order to run
 `develop` you will need Python 3.8.x or higher (3.9.x has had some testing).
 
-1. On MacOS you will likely need a Python install from [the official Python 
+## Ensure Python is installed
-   website](https://www.python.org/), rather than using HomeBrew.  See
-   [#670 Update requirements.txt for MacOS](https://github.com/EDCD/EDMarketConnector/issues/670)
-   for discussion about this.
 
-1. You have two choices:
+On Windows or macOS Download and install an appropriate version from
-    1. Using a zip of the latest stable source. Download and extract the
+[python.org](https://python.org).  Do **not use HomeBrew** on macOS, that 
+version is known to have a broken `tk`.  See [#670 Update requirements.txt for 
+MacOS](https://github.com/EDCD/EDMarketConnector/issues/670)
+for discussion about this.
+
+
+On Linux you should use your distribution's Python 3.x packages. Note that at
+least Debian 10 still has 2.7.x as `python` and `pip`, and you will need to 
+specify `python3` (from the package of that name) and `pip3` (from 
+`python3-pip` in the commands below in order to use a 3.x version.
+
+As and when we move from Python 3.7 to 3.8 or beyond you might find that 
+your Linux distribution is still only shipping Python 3.7, in which case 
+you will need to install a later version separately and ensure you are 
+using the correct version.  You already need at least Python 3.8.x to use our
+`develop` branch code.
+
+## Ensure you have working `pip`
+
+Ensure you have `pip` or `pip3` installed, check with `pip --version` or
+`pip3 --version`.
+
+On Debian you will need the `python3-pip` package installed.
+
+Otherwise see [Installing pip](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#installing-pip).
+
+##Ensure you have tkinter installed
+
+If using a python.org package it will include this.
+
+On Debian / Ubuntu / other Debian derivatives the package you need to install
+is `python3-tk`.
+
+## Obtain a copy of the application source
+
+Choose one of the following:
+
+1. Using a zip of the latest stable source. Download and extract the
      [latest stable source code](https://github.com/EDCD/EDMarketConnector/archive/stable.zip).
  
-    1. OR Clone and checkout the source using git:
+1. OR Clone and checkout the source using git:
-        1. `cd <directory you want ot be the parent of the source>`
+     1. `cd <directory you want t be the parent of the source>`
-        1. `git clone https://github.com/EDCD/EDMarketConnector.git`
+     1. `git clone https://github.com/EDCD/EDMarketConnector.git`
-        1. `cd EDMarketConnector`
+     1. `cd EDMarketConnector`
-        1. `git checkout stable`
+     1. `git checkout stable`
 
-    As per [Contributing.md](https://github.com/EDCD/EDMarketConnector/blob/main/Contributing.md#git-branch-structure-and-tag-conventions)
+As per [Contributing.md](https://github.com/EDCD/EDMarketConnector/blob/main/Contributing.md#git-branch-structure-and-tag-conventions)
 `stable` will contain the latest released code, or possibly some extra
 commits leading up to the next release.  If you're feeling slightly
 braver you could use the [main branch source code](https://github.com/EDCD/EDMarketConnector/archive/main.zip)
 (or `git checkout main`) instead which might contain newer code that we
 consider stable enough for the next release.
 
-    *NB: Do not use the `master` branch*, it's almost empty!  The name is
+**NB: Do not use the `master` branch**, it's almost empty!  The name is
-    deprecated and we use `main` instead.
+deprecated and we use `main` instead.
 
-1. Ensure you have 'pip' or 'pip3' installed, see [Installing pip](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#installing-pip).
+## Use `pip` to install application requirements
 
-1. Ensure additional necessary Python modules are installed with `pip install -r requirements.txt` .
+1. Ensure additional necessary Python modules are installed with
-    * Note that on Debian (at least up to and including 10.x aka 'Buster') you'll `pip3 install -r requirements.txt` .
+   
-    * If you get 'command not found' or similar for the 'pip' command then
+    `pip install -r requirements.txt` .
+
+  * Note that on Debian (at least up to and including 10.x aka 'Buster') 
+    you'll need `pip3 install -r requirements.txt` .
+  * If you get 'command not found' or similar for the 'pip' command then
      first try: `python -m pip --user install pip`.
 
-1. Ensure you have tkinter installed if required (such as on Linux)
+## Run the application
-    * On Debian / Ubuntu / other Debian derivatives the package you want is
-     `python3-tk`.
 
-1. Run this application:
+  * Linux: `python3 EDMarketConnector.py` .
-
+  * Mac: `python3 EDMarketConnector.py` .
-    * Linux: `./EDMarketConnector.py` .
+  * Windows: `EDMarketConnector.py` .
-    * Mac: `python ./EDMarketConnector.py` .
-    * Windows: `EDMarketConnector.py` .
 
 
-Command-line
+#Command-line
---------
 
-The command-line program `EDMC.py` writes the current system and station (if docked) to stdout and optionally writes player status, ship locations, ship loadout and/or station data to file.
+The command-line program `EDMC.py` writes the current system and station (if
-This program requires that the user has performed [setup](#setup) and verification through the app.
+docked) to stdout and optionally writes player status, ship locations, ship
+loadout and/or station data to file.
+
+This program requires that the user has performed Frontier 
+Authentication through the main application.
 
 Arguments: