doc: setup guide, and cleanup main README.md (#902)

Author: c-dilks

README.md

@@ -3,30 +3,12 @@
 [![Validation Status](https://github.com/JeffersonLab/coatjava/actions/workflows/validation.yml/badge.svg)](https://github.com/JeffersonLab/coatjava/actions/workflows/validation.yml)
 [![Coverage](https://badgen.net/static/JaCoCo/coverage/purple)](https://jeffersonlab.github.io/coatjava/jacoco)
 
-- [**Documentation Homepage**](https://jeffersonlab.github.io/coatjava)
-- [API Documentation (Javadoc)](https://jeffersonlab.github.io/coatjava/javadoc)
-- [Developer notes](/docs/dev_notes.md)
+| Table of Contents | |
+| --- | --- |
+| [:star: **Documentation Homepage** :star:](https://jeffersonlab.github.io/coatjava) | API documentation, HIPO banks, and more |
+| [Developer notes](/docs/dev_notes.md) | Notes for developers and maintainers |
 
-----
+---
 
-The original repository for COATJAVA was named "clas12-offline-software" and is [now archived and read-only](https://github.com/JeffersonLab/clas12-offline-software).  On May 17, 2023, this new repository was created by running BFG Repo Cleaner to get rid of old, large data files and things that should never have been in the repository, giving 10x reduction in repository size, clone time, etc, and renamed `coatjava`.  The most critical, GitHub-specific aspects have been transferred to this new repository:
-
-* Open issues
-* Branch protection rules
-* User access permission
-
-But some things remain only in the original repository:
-
-* Release notes up to 9.0.1 (probably worth transferring)
-* Closed issues (probably not worth transferring)
-* Wiki (never really utilized and probably worth restarting from scratch)
-
-Due to the cleanup, previously existing forks and local copies of the old repository will not be automatically mergeable.
-
-----
-
-If you just want to use the software without modifying/building it, you can download a pre-built package from the [GitHub releases](https://github.com/JeffersonLab/coatjava/releases) page or the corresponding repo at [JLab](https://clasweb.jlab.org/clas12offline/distribution/coatjava/).  Builds on JLab machines are also available, see the [general software wiki](https://clasweb.jlab.org/wiki/index.php/CLAS12_Software_Center) for setting up your environment to use them.
-
-For anything more, see the "General Developer Documentation" link on that software wiki, which points [here](https://clasweb.jlab.org/wiki/index.php/COATJAVA_Developer_Docs).
-
-The [troubleshooting](https://github.com/JeffersonLab/clas12-offline-software/wiki/Troubleshooting) wiki page may also still be useful but likely outdated.
+> [!NOTE]
+> The original repository for COATJAVA was named "clas12-offline-software" and is [now archived and read-only](https://github.com/JeffersonLab/clas12-offline-software).  On May 17, 2023, this new repository was created by running BFG Repo Cleaner to get rid of old, large data files and things that should never have been in the repository, giving 10x reduction in repository size, clone time, etc, and renamed `coatjava`.  

docs/mkdocs/docs/index.md

@@ -6,6 +6,7 @@
 | --- | --- |
 | [**API Documentation**](javadoc/index.html) | Documentation for classes and methods |
 | [**HIPO Banks**](banks.md) | Bank descriptions |
+| [**Setup and Installation**](setup.md) | How to obtain or build and install the software |
 | [**Source code**](https://github.com/JeffersonLab/coatjava) | The source code `git` repository |
 
 ---

docs/mkdocs/docs/setup.md

@@ -0,0 +1,53 @@
+# Setup Guide
+
+<br>
+
+## Obtaining the Software
+
+If you just want to use the software without modifying/building it, you can download a pre-built package from the [GitHub releases](https://github.com/JeffersonLab/coatjava/releases) page or the corresponding repo at [JLab](https://clasweb.jlab.org/clas12offline/distribution/coatjava/).  Builds on JLab machines are also available, see the [general software wiki](https://clasweb.jlab.org/wiki/index.php/CLAS12_Software_Center) for setting up your environment to use them.
+
+If you would rather build and install it yourself, `git clone` [the repository](https://github.com/JeffersonLab/coatjava), then skip to the next section below.
+
+For anything more, see the "General Developer Documentation" link on that software wiki, which points [here](https://clasweb.jlab.org/wiki/index.php/COATJAVA_Developer_Docs).
+
+The [troubleshooting](https://github.com/JeffersonLab/clas12-offline-software/wiki/Troubleshooting) wiki page may also still be useful but likely outdated.
+
+<br>
+
+## Dependencies
+
+- Java
+- Maven
+
+Maven will automatically obtain all other dependencies.
+
+<br>
+
+## Building and Installing
+
+Run the installation script:
+```
+./build-coatjava.sh
+```
+
+For more usage guidance, run:
+```
+./build-coatjava.sh --help
+```
+
+The software will then be installed _within_ the top-level repository directory, in a subdirectory named `coatjava/`, which contains:
+
+| Directory | Description |
+| --- | --- |
+| `bin` | Executables for the user, such as `recon-util` |
+| `etc` | Various supplementary files, such as bank schema and magnetic field maps |
+| `lib` | JAR files |
+| `libexec` | Internal scripts |
+
+<br>
+
+## Troubleshooting
+
+If you want to _cleanly_ rebuild, use the `--clean` option for `build-coatjava.sh`.
+
+If you need to clean your Maven cache, which by default is stored in `~/.m2/repository`, you can try either removing that directory, or renaming it, so that it is recreated. Then try to build `coatjava` again.

docs/mkdocs/mkdocs.yaml

@@ -1,7 +1,8 @@
 site_name: COATJAVA Documentation
 nav:
   - Home: index.md
-  - HIPO Bank Definitions: banks.md
+  - HIPO Banks: banks.md
+  - Setup Guide: setup.md
 use_directory_urls: false
 extra:
   homepage: index.html