Merge pull request #124 from objectionary/123-improve-readme-structure

123 improve readme structure

README.md

@@ -14,41 +14,52 @@ 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 from Hackage
+
+```sh
+stack update
+export LANG=C.UTF-8
+stack install --resolver lts-22.11 eo-phi-normalizer-0.1.0
 ```
 
-### Install
+### Uninstall
 
-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`.
+Learn where `stack` installs programs.
 
 ```sh
-# Commands
-stack install
-normalize-phi --help
+stack path --programs
 ```
 
-Alternatively, run the executable via `stack` without global installation (see the following sections).
+Learn how to uninstall a program.
 
-### CLI
+```sh
+stack uninstall
+```
 
-The `eo-phi-normalizer` package provides an executable `normalize-phi` that has a CLI.
+## Use
 
-Run the executable via `stack run`.
+Learn about `normalize-phi` options.
 
 ```sh
-# Commands
-stack run normalize-phi -- --help
-# Or
-stack run -- --help
+normalize-phi --help
+```
 
-# Output:
+```console
 Normalizer
 
 Usage: normalize-phi [-c|--chain] [--rules-yaml STRING] [-o|--output STRING]
@@ -61,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 ↦
     ⟦
@@ -81,17 +93,27 @@ 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
-# Command
-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
+```
 
-# Output
+```console
 Rule set based on Yegor's draft
 Input:
 { a ↦ ⟦ b ↦ ⟦ c ↦ ∅, d ↦ ⟦ φ ↦ ξ.ρ.c ⟧ ⟧, e ↦ ξ.b (c ↦ ⟦ ⟧).d ⟧.e }
@@ -107,10 +129,10 @@ Normalize an expression using a ruleset (See [Rulesets](#rulesets)).
 Read the expression from stdin.
 
 ```sh
-# Command
-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
+```
 
-# Output
+```console
 Rule set based on Yegor's draft
 Input:
 { a ↦ ⟦ b ↦ ⟦ c ↦ ∅, d ↦ ⟦ φ ↦ ξ.ρ.c ⟧ ⟧, e ↦ ξ.b (c ↦ ⟦ ⟧).d ⟧.e }
@@ -121,19 +143,20 @@ 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`
 
 Use `--chain` to see numbered normalization steps for each normalization result.
 
 ```sh
-# Command
-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
+```
 
-# Output
+```console
 Rule set based on Yegor's draft
 Input:
 { a ↦ ⟦ b ↦ ⟦ c ↦ ∅, d ↦ ⟦ φ ↦ ξ.ρ.c ⟧ ⟧, e ↦ ξ.b (c ↦ ⟦ ⟧).d ⟧.e }
@@ -149,10 +172,10 @@ Result 1 out of 1:
 Use `--single` to print a single normalized program.
 
 ```sh
-# Command
-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
+```
 
-# Output
+```console
 ⟦ a ↦ ξ.b (c ↦ ⟦ ⟧).d (ρ ↦ ⟦ b ↦ ⟦ c ↦ ∅, d ↦ ⟦ φ ↦ ξ.ρ.c ⟧ ⟧ ⟧) ⟧
 ```
 
@@ -201,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
-
-### `stack`
+## Develop
 
-The project is developed using the [Stack tool](https://docs.haskellstack.org/en/stable/README/).
+We recommend using [stack](https://docs.haskellstack.org/en/stable/README/) for quick local development and testing.
 
-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