Update README.adoc

Author: Derek Hower

README.adoc

@@ -51,9 +51,14 @@ This repository contains:
 
 == Prerequisites
 
-The only requirement is the `Singularity CE` (>= 3.3) or `Apptainer` (>= 1.0) container system. Either one will work (they are forks).
+There are two supported ways to run the RISC-V Unified Database,
+both of which are container-based.
 
-If it is not installed, either as your IT admin or:
+=== Singularity/Apptainer
+
+You can run within `Singularity CE` (>= 3.3) or `Apptainer` (>= 1.0) container system. Either one will work (they are forks).
+
+If it is not installed, either ask your IT admin or:
 
  * For Apptainer, see https://apptainer.org/docs/admin/main/installation.html[Apptainer Installation].
  * For Singularity CE, see https://docs.sylabs.io/guides/latest/admin-guide/installation.html[Singularity CE Installation].
@@ -62,35 +67,31 @@ If it is not installed, either as your IT admin or:
 You do *not* need root privileges to download or use the container. However, to modify/build the container,
 you will need either root privileges or the ability to run in `fakeroot` mode. See https://docs.sylabs.io/guides/4.1/user-guide/fakeroot.html[Singularity Fakeroot Documentation] for more information.
 
-== Setup
+When you run with Singularity/Apptainer, the files under `bin/`
+will run within the container, _e.g._:
 
-Do once:
+```bash
+./bin/ruby --version
+# => ruby 3.2.3 (2024-01-18 revision 52bb2ac0a6) [x86_64-linux-gnu]
+```
 
-[source,bash]
-----
-./bin/setup
+=== Devcontainer
 
-# or, if you also want development tools (:development group in Gemfile) installed
-# DEVELOPMENT=1 ./bin/setup
-----
+You can also leverage https://containers.dev/[devcontainers] to run the RISC-V Unified Database.
 
-[NOTE]
-If you forget, don't worry. Setup will be invoked by any program in bin/ if necessary.
+This is especially useful when using Visual Studio Code or GitHub codespaces, as it will setup up your IDE environment for you.
+
+==== VS Code
 
-=== VSCode
+To run the devcontainer locally, you will need to have https://docs.docker.com/engine/install[Docker installed].
 
-If using Visual Studio Code and want to use development tools, you will need to restart the editor
-after setup.
+With Docker installed, install the https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers[Dev Containers] extension in VS Code.
 
-Helpful extensions are
+You can then run `Dev Containers: Open Folder in Container...` from the Command Palette (Ctrl+Shift+P) and select the folder with this repository.
 
- * https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode[AsciiDoc]
- * https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml[YAML]
- * https://marketplace.visualstudio.com/items?itemName=castwide.solargraph[Solargraph] (for a Ruby Language Server)
- * https://marketplace.visualstudio.com/items?itemName=onnovalkering.vscode-singularity[Singularity] (if you plan on working on the container)
+==== GitHub Codespaces
 
-The `.vscode/settings.json` file in the repo will ensure that Solargraph works without any additional
-configuration (assuming you've already run ./bin/setup).
+You can start a GitHub Codespace for this repository by clicking the "Code" button and selecting "Open with Codespaces".
 
 == Tasks
 
@@ -100,9 +101,16 @@ Quick start:
 ----
 ./do --tasks                 # list all documented tasks
 
-# examples
-./do validate                # validate against the schema
-./do gen:arch[generic_rv64]  # generate arch spec for the 'generic_rv64' config
+## examples
+
+# validate against the schema
+./do validate
+
+# generate all versions of ISA manual, as an Antora static website
+./do gen:html_manual MANUAL_NAME=isa VERSIONS=all
+
+# generate an implementation-specific spec for the 'generic_rv64' config
+./do gen:arch[generic_rv64]
 ----
 
 == More info