From 3de7858a3966e6c4ce3b295525aa02357ec4437e Mon Sep 17 00:00:00 2001
From: Fredrik Ekre <ekrefredrik@gmail.com>
Date: Thu, 12 Dec 2024 15:28:07 +0100
Subject: [PATCH] Add quick start section to the README

This patch adds a quick start section to the README with copy-pasteable
setup commands. Closes #80. Also removes some discussion about shell
alias and the `-m` flag and instead recommend using the shell script
wrapper.
---
 README.md | 93 +++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 77 insertions(+), 16 deletions(-)

diff --git a/README.md b/README.md
index 1ae8246..ecfb3e4 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,7 @@ that is appreciated by most Go programmers, see for example the following
 
 ### Table of contents
 
+ - [Quick start](#quick-start)
  - [Installation](#installation)
  - [Usage](#usage)
     - [CLI](#cli)
@@ -33,6 +34,31 @@ that is appreciated by most Go programmers, see for example the following
  - [Version policy](#version-policy)
  - [Formatting specification](#formatting-specification)
 
+## Quick start
+
+Copy-pasteable setup commands for the impatient:
+
+```sh
+# Install Runic
+julia --project=@runic -e 'using Pkg; Pkg.add("Runic")'
+# Install the runic shell script
+curl -fsSL -o ~/.local/bin/runic https://raw.githubusercontent.com/fredrikekre/Runic.jl/refs/heads/master/bin/runic
+chmod +x ~/.local/bin/runic
+```
+
+Assuming `~/.local/bin` is in your `PATH` you can now invoke `runic`, e.g.:
+
+```sh
+runic --version # Show version info
+runic --help    # Show documentation
+```
+
+```sh
+# Format all files in-place in the current directory (recursively)
+# !! DON'T DO THIS FROM YOUR HOME DIRECTORY !!
+runic --inplace .
+```
+
 ## Installation
 
 Runic can be installed with Julia's package manager:
@@ -48,34 +74,69 @@ Runic in a separate project such as e.g. the shared project `@runic`:
 julia --project=@runic -e 'using Pkg; Pkg.add("Runic")'
 ```
 
-## Usage
-
-### CLI
+The main interface to Runic is the command line interface (CLI) through the `main` function:
 
-The main interface to Runic is the command line interface (CLI) through the `main` function
-invoked with the `-m` flag. See the output of `julia -m Runic --help` below for usage
-details.
+```sh
+julia --project=@runic -e 'using Runic; exit(Runic.main(ARGS))' -- <args>
+```
 
-The following snippet can be added to your shell startup file so that the CLI can be invoked
-a bit more ergonomically. This assumes Runic is installed in the `@runic` shared project as
-suggested in the [Installation](#installation) section above. Adjust the `--project` flag if
-you installed Runic elsewhere.
+To simplify the invocation of the CLI it is recommended to install the
+[`runic`](https://github.com/fredrikekre/Runic.jl/blob/master/bin/runic) shell script into a
+directory in your `PATH`. This can be done with the following commands (replace the two
+occurences of `~/.local/bin` if needed):
 
 ```sh
-alias runic="julia --project=@runic -m Runic"
+# Download the script into ~/.local/bin
+curl -fsSL -o ~/.local/bin/runic https://raw.githubusercontent.com/fredrikekre/Runic.jl/refs/heads/master/bin/runic
+# Make the script executable
+chmod +x ~/.local/bin/runic
+# Verify the installation
+runic --version
 ```
 
 > [!NOTE]
-> The `-m` command line flag is only available in Julia 1.12 and later. In earlier versions
-> you have to invoke the `main` function explicitly, for example:
+> Alternatively you can can add a shell alias to your shell startup file. The drawback of
+> this approach is that runic can only be invoked from the shell and not by other programs.
 > ```sh
-> julia -e 'using Runic; exit(Runic.main(ARGS))' -- <args>
+> alias runic="julia --project=@runic -e 'using Runic; exit(Runic.main(ARGS))' --"
+> # alias runic="julia --project=@runic -m Runic"
 > ```
-> For this incantation the following shell alias can be used:
+
+> [!NOTE]
+> In Julia 1.12 and later the `main` function can be invoked with the `-m` flag, i.e.:
 > ```sh
-> alias runic="julia --project=@runic -e 'using Runic; exit(Runic.main(ARGS))' --"
+> julia --project=@runic -m Runic <args>
 > ```
 
+## Usage
+
+### CLI
+
+The CLI is the main interface to Runic. `runic --help` will show all available options
+(output included below). Some example invokations are listed here.
+
+Format a single file in place:
+```sh
+runic --inplace file.jl
+```
+
+Format all files in a directory (recursively) in place:
+```sh
+runic --inplace src/
+```
+
+Verify formatting of all files in a directory with verbose and diff output:
+```sh
+runic --check --diff --verbose src/
+```
+
+Format the content of standard in and print the result to standard out:
+```sh
+echo "1+1" | runic
+```
+
+Output of `runic --help` for a complete list of options:
+
 ```
 $ runic --help
 NAME