Improve documentation (#11)

.github/workflows/ci_linux.yml

@@ -1,4 +1,4 @@
-name: CI Linux
+name: Linux CI
 
 on:
   push:

.github/workflows/ci_windows.yml

@@ -1,4 +1,4 @@
-name: CI Windows
+name: Windows CI
 
 on:
   push:

README.md

@@ -4,55 +4,55 @@
 [![windows](https://github.com/kevgo/run-that-app/actions/workflows/ci_windows.yml/badge.svg)](https://github.com/kevgo/run-that-app/actions/workflows/ci_windows.yml)
 
 _Run-that-app_ executes small third-party tools used by software developers
-(linters, checkers , verifiers) that often have no good way of being installed.
-Like Docker, _run-that-app_ works on Linux, Windows, and macOS. Unlike Docker,
-_run-that-app_ is extremely lean, fast, has zero dependencies, doesn't create
-the Docker in Docker problem, and leaves a very small footprint on your
-computer.
+(linters, checkers, verifiers) without the need to install them first. This
+reduces boilerplate code in developer tooling and on CI servers.
+
+_Run-that-app_ runs on all major computer platforms including Linux, Windows,
+and macOS. Installs happen in seconds, don't require _sudo_, and store nothing
+but the executables on your hard drive. Run-that-app has zero dependencies and
+avoids the Docker-in-Docker problem.
 
 ### quickstart
 
-```bash
-# download the _run-that-app_ executable
-curl https://raw.githubusercontent.com/kevgo/run-that-app/main/install.sh | sh
+1. Download the run-that-app executable:
 
-# run an app (in this case ShellCheck)
-./run-that-app [email protected]
-```
+   ```bash
+   curl https://raw.githubusercontent.com/kevgo/run-that-app/main/download.sh | sh
+   ```
 
-Please note that you need to provide the version exactly like it is in the app
-repository. On GitHub Releases, the version tag often begins with the letter
-`v`.
+2. Run an app (in this case the GitHub CLI)
+
+   ```bash
+   ./run-that-app [email protected]
+   ```
 
 ### why
 
 Reasons to use _run-that-app_ over traditional forms of installation (package
 managers) are:
 
 - You need to run a binary for which no good way to install them exists, for
-  example binaries distributed via GitHub Releases.
-- You use or support a wide variety of operating systems and want to avoid
-  having to deal with an endless variety of package managers like Homebrew, Nix,
-  Scoop, Chocolatey, winget, DNF, pacman, apt, pkg, snap, zypper, xbps, portage,
-  etc.
+  example binaries distributed through GitHub Releases.
+- You use or support a variety of operating systems and want to avoid having to
+  deal with an endless variety of package managers like Homebrew, Nix, Scoop,
+  Chocolatey, winget, DNF, pacman, apt, pkg, snap, zypper, xbps, portage, etc.
 - You don't want to write and maintain Bash scripts to install your dependencies
   and deal with various versions and flavors of `curl`, `gzip`, and `tar`
 - You work in an environment in which no package manager is available.
 - You need a different version of an application than the one installed by your
   package manager.
-- You work on multiple projects that require different versions development
+- You work on multiple projects that require different versions of development
   tools.
-- You want to avoid the overhead of working inside Docker.
+- You want to avoid the overhead of Docker.
 - You want to install third-party tools as fast as possible for the best
   developer experience.
 
 ### how it works
 
 When running a third-party application, _run-that-app_:
 
-- determines your platform (operating system, CPU architecture)
 - downloads and unpacks the matching executable for your platform - this
-  typically takes just a second or two for most applications
+  typically takes just a second or two
 - stores the downloaded executable under `~/.run-that-app` on your hard drive
 - executes this binary
 
@@ -62,38 +62,49 @@ When running a third-party application, _run-that-app_:
 run-that-app [run-that-app options] <app name> [app options]
 ```
 
+Options:
+
+- `--ignore-unavailable`: if there is no pre-compiled binary for your platform,
+  do nothing. This is useful for non-essential tools where it's okay if the tool
+  doesn't run.
+- `--include-global`: if there is no pre-compiled binary for your platform, but
+  a similarly named binary in your PATH, run the latter.
+- `--log`: enable all logging
+- `--log=domain`: enable logging for the given domain
+  - see the available domains by running with all logging enabled
+
 ### examples
 
+Runs ShellCheck version 0.9.0 with the arguments `--color=always myscript.sh`.
+
 ```bash
-run-that-app --fallback-to-global --allow-unavailable [email protected] --color=always myscript.sh
+run-that-app --include-global --ignore-unavailable [email protected] --color=always myscript.sh
 ```
 
-- Runs ShellCheck version 0.9.0 with the arguments `--color=always myscript.sh`.
-- Because the `--fallback-to-global` option is enabled, if there is no binary
-  available for your platform, _run-that-app_ looks for one in the PATH and runs
-  that one.
-- The `--allow-unavailable` switch makes _run-that-app_ do nothing if the app
-  cannot be found. ShellCheck is just a linter and it's okay if it cannot run on
-  a few exotic developer machines.
+Same call but if ShellCheck is not available, do nothing.
+
+```bash
+run-that-app --ignore-unavailable [email protected] --color=always myscript.sh
+```
 
 ### Q&A
 
-#### Wouldn't it be more appropriate to use the package manager of my system to install third-party applications?
+#### Why not use the package manager of my system to install third-party applications?
 
-Yes if your and everybody else's package manager installs a version that works
-for all your use cases.
+Do it if your and everybody else's package manager installs all needed tools at
+versions that work for your use cases.
 
 #### What if an app does not provide binaries for my platform?
 
-If the app is not essential, you can provide the `--allow-unavailable` switch
+If the app is not essential, you can provide the `--ignore-unavailable` switch
 and _run-that-app_ will simply do nothing, including not exiting with an error.
 
 #### What if I compile an app that doesn't provide binaries for my platform myself?
 
-Add your version to the PATH and call _run-that-app_ with the `--use-global-app`
+Add your version to the PATH and call _run-that-app_ with the `--include-global`
 switch to make it run your app. In this case _run-that-app_ does not guarantee
 that the app has the correct version.
 
 #### What about apps that require a dependency like NodeJS or Python?
 
-Use the package manager of those platforms to run that app!
+Use the package manager of those frameworks to run that app!

src/apps/gh.rs

@@ -56,7 +56,7 @@ fn cpu_text(cpu: Cpu) -> &'static str {
 
 fn ext_text(os: Os) -> &'static str {
     match os {
-        Os::Linux => "tgz",
+        Os::Linux => "tar.gz",
         Os::Windows | Os::MacOS => "zip",
     }
 }

src/cmd/help.rs

@@ -10,7 +10,7 @@ pub fn help(output: &dyn Output) -> ExitCode {
 }
 
 fn print_usage(output: &dyn Output) {
-    output.println("Usage: binstall install [options] application@version\n");
+    output.println("Usage: run-that-app install [options] application@version\n");
 }
 
 pub fn print_options(output: &dyn Output) {
@@ -28,8 +28,9 @@ Options:
 
 fn print_examples(output: &dyn Output) {
     output.println("Examples:");
-    output
-        .println("\"binstall [email protected]\" installs https://github.com/cli/cli at version 2.34.0\n");
+    output.println(
+        "\"run-that-app [email protected]\" installs https://github.com/cli/cli at version 2.34.0\n",
+    );
 }
 
 pub fn print_installable_apps(output: &dyn Output) {

src/error.rs

@@ -94,21 +94,21 @@ impl UserError {
             }
             UserError::UnsupportedCPU(name) => {
                 error(&format!("Your CPU ({name}) is currently not supported."));
-                desc("Request support for your platform at https://github.com/kevgo/binstall/issues.");
+                desc("Request support for your platform at https://github.com/kevgo/run-that-app/issues.");
             }
             UserError::UnsupportedPlatform => {
                 error("This application does not seem to support your platform.");
                 desc("It looks like there are no binary versions for this app for your platform.
 
-As a workaround, you could install this app in other ways and then run \"binstall --fallback-to-existing\".
-If you are okay moving forward without this app, you can provide the \"--allow-unavailable\" switch and binstall will install a non-functional stub for it.",
+As a workaround, you could install this app in other ways and then run \"run-that-app --fallback-to-existing\".
+If you are okay moving forward without this app, you can provide the \"--ignore-unavailable\" switch and run-that-app will ignore this failure.",
                               );
             }
             UserError::UnsupportedOS(name) => {
                 error(&format!(
                     "Your operating system ({name}) is currently not supported."
                 ));
-                desc("Request support for your platform at https://github.com/kevgo/binstall/issues.");
+                desc("Request support for your platform at https://github.com/kevgo/run-that-app/issues.");
             } // UserError::UnsupportedPlatformAndNoGlobalApp { app_name, platform } => {
             UserError::YardRootIsNotFolder { root } => {
                 error("The internal storage has the wrong structure.");