JAL-3248 a bit more

diff --git a/doc/building-OLD.html b/doc/building-OLD.html
index f5e0b28..a51565c 100755 (executable)
--- a/doc/building-OLD.html
+++ b/doc/building-OLD.html
@@ -45,7 +45,6 @@ Then you can <code>cd jalview</code> to get into the top level jalview dir.
 <p>To run Jalview, you just need the jalview classes and the .jar libraries that Jalview depends on.</p>
 
 
-<!--
 <p>
 You will need the following (hopefully):<br>
 <ul>
@@ -115,7 +114,6 @@ dist. But first you need to make your own key:
                mechanism (e.g. Netbeans' executable Jar and dependent lib directory).
                The hand-crafted ant build.xml is (currently) the only officially
                supported method of building distributable versions of Jalview.</p>
-        -->
 <address>
 <a href="mailto:help@jalview.org">Jalview development team</a>
 </address>

diff --git a/doc/building.md b/doc/building.md
index 70b142f..b47c648 100644 (file)
--- a/doc/building.md
+++ b/doc/building.md
@@ -19,7 +19,7 @@ java -jar getdown-launcher.jar . jalview
 ```
 
 
-## What you will need
+## Setting up
 
 The method here is described in terms of using a command line.  You can easily do this on linux or in a Terminal window in macOS.  You can do it in Windows.
 
@@ -28,62 +28,85 @@ The method here is described in terms of using a command line.  You can easily d
 * git
 
 ### Java 11 JDK
+
+#### All platforms
 We recommend obtaining an OpenJDK JDK 11 (since 11 is the long term support release) from AdoptOpenJDK: <https://adoptopenjdk.net/?variant=openjdk11&jvmVariant=hotspot>, either the *Installer* or `.zip`/`.tar.gz` variants whichever you prefer (if you're not sure, choose the *Installer*).
 
+You can also install adoptopenjdk11 using either `brew` (macOS) or `choco` (Windows):
+
+#### alternative MacOS/Homebrew
+```
+brew tap adoptopenjdk/openjdk
+brew cask install adoptopenjdk11
+```
+
+#### alternative Windows/Chocolatey
+```
+choco install adoptopenjdk11
+```
+
+#### alternative Linux/yum|apt
+
+see <https://adoptopenjdk.net/installation.html#linux-pkg>
+
+
 ### gradle and git
 You should be able to install the latest (or close to the latest) versions of gradle and git using your OS package manager.
 
-#### For **macOS**
+#### MacOS
 we recommend using `brew`, which can be installed following the instructions at <https://brew.sh/>.
 After installing `brew`, open a Terminal window and type in (using an Administrator privileged user):
 
-```
+```bash
 brew install gradle git
 ```
 
 or
 
-```
+```bash
 brew upgrade gradle git
 ```
 
 if you already have them installed but need to upgrade the version.
 
-#### For **linux**
+#### Windows
+
+we suggest using the **Chocolatey** package manager.  See install instructions at <https://chocolatey.org/>, and you will just need
+
+```bash
+choco install gradle
+choco install git
+```
+
+Alternatively, you could install a real `bash` shell and install both `gradle` and `git` through `apt-get`.
+See <https://devblogs.microsoft.com/commandline/bash-on-ubuntu-on-windows-download-now-3/> 
+for how to install the ubuntu bash shell in Windows 10.
+
+Another alternative would be to install them separately. For `gradle` follow the instructions at <https://gradle.org/install/>, and for `git` here are a couple of suggestions: Git for Windows <https://gitforwindows.org/>.
+Getting the individual installs working together on the command line will be trickier 
+so we recommend using Chocolatey or bash.
+
+
+#### Linux
 this will depend on which distribution you're using.
 
 ##### For *Debian* based distributions (e.g. Mint, Ubuntu, Debian)
 run
 
-```
+```bash
  sudo apt-get install gradle git
 ```
 
 ##### for RPM-based distributions (e.g. Fedora, CentOS, RedHat)
 run
 
-```
+```bash
 sudo yum install gradle git
 ```
 
 If you have some other version of linux you'll probably be able to work it out!
 
 
-#### For **Windows**
-
-we suggest using the **Chocolatey** package manager.  See install instructions at <https://chocolatey.org/>, and you will just need
-
-```
-choco install gradle git
-```
-
-Alternatively, you could install a real `bash` shell and install both `gradle` and `git` through `apt-get`.
-See <https://devblogs.microsoft.com/commandline/bash-on-ubuntu-on-windows-download-now-3/> 
-for how to install the ubuntu bash shell in Windows 10.
-
-Another alternative would be to install them separately. For `gradle` follow the instructions at <https://gradle.org/install/>, and for `git` here are a couple of suggestions: Git for Windows <https://gitforwindows.org/>.
-
-
 
 
 ## Downloading the Jalview source tree
@@ -92,23 +115,31 @@ This can be done with `git`.
 On the command line, change directory to where you want to download Jalview's build-tree 
 top level directory.  Then run
 
-```
+```bash
 git clone http://source.jalview.org/git/jalview.git
 ```
 
 You'll get some progress output and after a minute or two you should have the full 
 Jalview build-tree in the folder `jalview`.
 
-## What's in the source tree?
+### What's in the source tree?
 
-Change directory into the `jalview` folder:
+Within the `jalview` folder:
 
-```
-cd jalview
-```
-and you'll find most of the Jalview source files under `src`. Some important resource 
-files can be found under `resources`.  The helper jar libraries can currently be found 
-in `j8lib` for Java 1.8 runtime and `j11lib` for Java 11 runtime.
+|  dir      | contains|
+|-----------|---------|
+| `src`     | the Jalview application source `.java` files
+| `resource`| non-java resources used in the Jalview application |
+| `classes` (after compiling) | contains the compiled Java classes for the Jalview application
+| `bin`     | used by eclipse for compiled classes
+| `j8lib`   | libraries needed to run Jalview under Java 1.8
+| `j11lib`  | libraries needed to run Jalivew under Java 11
+| `build`   | the gradle build dir
+| `dist`    | assembled `.jar` files needed to run Jalview application
+| `examples`| example input files usable by Jalview
+| | 
+
+Note that you need a Java 11 JDK to compile Jalview whether your target build is Java 1.8 or Java 11.