From 5ccddd3af321b5771f936690a78a62cd60219d4b Mon Sep 17 00:00:00 2001
From: Danila Danko <br4ch1st0chr0n3@gmail.com>
Date: Wed, 14 Feb 2024 15:27:48 +0300
Subject: [PATCH] refactor: readme structure, commands

---
 README.md | 93 ++++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 62 insertions(+), 31 deletions(-)

diff --git a/README.md b/README.md
index 21420c2da..67bab4d5f 100644
--- a/README.md
+++ b/README.md
@@ -14,41 +14,49 @@ Contrary to traditional normalization in λ-calculus, we aim at rewriting rules
 help reduce certain metrics of expressions. In particular, we are interested in reducing
 attribute access (`t.a`) that amounts to _dynamic dispatch_.
 
-## Usage
+## Install
 
-Clone this repo.
+You can install the `normalizer-phi` executable globally via [stack](https://docs.haskellstack.org/en/stable).
+Then, the `normalize-phi` executable will be available on `PATH`.
+
+### Install from the repository
 
 ```sh
-git clone https://github.com/objectionary/normalizer.git
+git clone https://github.com/objectionary/normalizer
 cd normalizer
+export LANG=C.UTF-8
+stack install normalize-phi
+normalize-phi --help
 ```
 
-### Install
-
-You can install the `normalizer-phi` executable globally via [stack](https://docs.haskellstack.org/en/stable/README/).
-Then, the `normalize-phi` executable will be available on `PATH` and in `~/.local/bin/` on `Linux` and `macOS`.
+### Install from Hackage
 
 ```sh
-stack install
-normalize-phi --help
+stack update
+export LANG=C.UTF-8
+stack install --resolver lts-22.11 eo-phi-normalizer-0.1.0
 ```
 
-Alternatively, run the executable via `stack` without global installation (see the following sections).
+### Uninstall
 
-### CLI
+Learn where `stack` installs programs.
 
-The `eo-phi-normalizer` package provides an executable `normalize-phi` that has a CLI.
+```sh
+stack path --programs
+```
 
-Run the executable via `stack run`.
+Learn how to uninstall a program.
 
 ```sh
-stack run normalize-phi -- --help
+stack uninstall
 ```
 
-Or
+## Use
+
+Learn about `normalize-phi` options.
 
 ```sh
-stack run -- --help
+normalize-phi --help
 ```
 
 ```console
@@ -64,12 +72,13 @@ Available options:
   -o,--output STRING       Output file path (defaults to stdout)
 ```
 
-#### expression
+### Sample program
 
-Save an expression into a file `test.phi` that will be used in subsequent commands.
+Save a $\varphi$-calculus program to a file.
+This program will be used in subsequent commands.
 
 ```sh
-cat > test.phi <<EOM
+cat > program.phi <<EOM
 {
   a ↦
     ⟦
@@ -84,14 +93,24 @@ cat > test.phi <<EOM
 EOM
 ```
 
+### Prepare environment
+
+The commands in the following sections access files that are available in the project repository.
+Clone and enter the repository directory.
+
+```sh
+git clone https://github.com/objectionary/normalizer
+cd normalizer
+```
+
 #### `--ruleset-yaml`
 
-Normalize a 𝜑-expression from `test.phi` using a ruleset (See [Rulesets](#rulesets)).
+Normalize a 𝜑-expression from `program.phi` using a ruleset (See [Rulesets](#rulesets)).
 
 There can be multiple numbered results that correspond to multiple rule application sequences.
 
 ```sh
-stack run -- --rules-yaml ./eo-phi-normalizer/test/eo/phi/rules/yegor.yaml test.phi
+normalize-phi --rules-yaml ./eo-phi-normalizer/test/eo/phi/rules/yegor.yaml program.phi
 ```
 
 ```console
@@ -110,7 +129,7 @@ Normalize an expression using a ruleset (See [Rulesets](#rulesets)).
 Read the expression from stdin.
 
 ```sh
-cat test.phi | stack run -- --rules-yaml ./eo-phi-normalizer/test/eo/phi/rules/yegor.yaml
+cat program.phi | normalize-phi --rules-yaml ./eo-phi-normalizer/test/eo/phi/rules/yegor.yaml
 ```
 
 ```console
@@ -126,7 +145,7 @@ Result 1 out of 1:
 Alternatively, the path to the file containing a Phi expression can be passed as a positional argument:
 
 ```sh
-stack run -- --rules-yaml ./eo-phi-normalizer/test/eo/phi/rules/yegor.yaml test.phi
+normalize-phi --rules-yaml ./eo-phi-normalizer/test/eo/phi/rules/yegor.yaml program.phi
 ```
 
 #### `--chain`
@@ -134,7 +153,7 @@ stack run -- --rules-yaml ./eo-phi-normalizer/test/eo/phi/rules/yegor.yaml test.
 Use `--chain` to see numbered normalization steps for each normalization result.
 
 ```sh
-cat test.phi | stack run -- --chain --rules-yaml ./eo-phi-normalizer/test/eo/phi/rules/yegor.yaml
+cat program.phi | normalize-phi --chain --rules-yaml ./eo-phi-normalizer/test/eo/phi/rules/yegor.yaml
 ```
 
 ```console
@@ -153,7 +172,7 @@ Result 1 out of 1:
 Use `--single` to print a single normalized program.
 
 ```sh
-stack run -- --single --rules-yaml ./eo-phi-normalizer/test/eo/phi/rules/yegor.yaml test.phi
+normalize-phi --single --rules-yaml ./eo-phi-normalizer/test/eo/phi/rules/yegor.yaml program.phi
 ```
 
 ```console
@@ -205,20 +224,32 @@ When there is a match, the matched parts of the expression are bound to metavari
 
 Additionally, there are unit tests for rules. Each unit test provides `input` and `output` expressions. An `output` expression is not reused in other tests, so it is safe to let it be an empty string when no match can happen.
 
-## Development
+## Develop
 
-### `stack`
+We recommend using [stack](https://docs.haskellstack.org/en/stable/README/) for quick local development and testing.
 
-The project is developed using the [Stack tool](https://docs.haskellstack.org/en/stable/README/).
-
-We recommend using `stack` for quick local development and testing. Clone this project and run `stack build`.
+Clone this project and run `stack build`.
 
 ```sh
-git clone https://github.com/objectionary/normalizer.git
+git clone https://github.com/objectionary/normalizer
 cd normalizer
 stack build
 ```
 
+### Run
+
+Run the executable via `stack run`.
+
+```sh
+stack run normalize-phi -- --help
+```
+
+Or, omit the executable name.
+
+```sh
+stack run -- --help
+```
+
 ### Test
 
 Run all tests