doc: added system requirements & fixed map x to x orHEADdevel

1 files changed, 52 insertions, 30 deletions

diff --git a/README.md b/README.md
index 3f62d29..11be6ff 100644
--- a/README.md
+++ b/README.md
@@ -4,24 +4,24 @@ myslip README
 =============
 
 Below is a short introduction to this programming language
-and instructions on setting it up.
-`TUTORIAL.md` may help getting familiar with the language.
+and instructions on setting it up. `TUTORIAL.md` may help
+getting familiar with the language.
 
 
 Language introduction
 ---------------------
 
 Myslip is a functional, symbolically interpreted programming
-language. It's syntax is inspired by lisp and polish
-notation. The author hasn't programmed much in lisp-variants
-or in (non-general-purpose) functional languages, so the
-language might include some slips or oddities, hence
-the name. But the language is coherent within itself,
-so learning it shouldn't be too hard.
+language. It's syntax is inspired by lisp and polish notation.
+The author hasn't programmed much in lisp-variants or in
+(non-general-purpose) functional languages, so the language
+might include some slips or oddities, hence the name. But the
+language is coherent within itself, so learning it shouldn't
+be too hard.
 
-Valid myslip s-expressions may be atoms of different types
-or lists of them, though not all syntactically valid
-myslip expressions are ones that can be evaluated.
+Valid myslip s-expressions may be atoms of different types or
+lists of them, though not all syntactically valid myslip
+expressions are ones that can be evaluated.
 
 The following is s-expressions explained intuitively in
 something that looks a bit like a BNF:
@@ -29,22 +29,20 @@ something that looks a bit like a BNF:
 S-expression := Atom | List
 Atom := Operator | Value | Variable ...
 List := (S-expression ... S-expression)
-```
 Don't take it to be exact. For example lists are actually
 implemented as linked lists.
 
-The myslip interpreter performs type checking on
-s-expressions and evaluates them according to polish
-notation, ie. the first S-expression of a list is taken to
-be the operator that is passed the rest of the expressions
-as arguments.
+The myslip interpreter performs type checking on s-expressions
+and evaluates them according to polish notation, ie. the first
+S-expression of a list is taken to be the operator that is
+passed the rest of the expressions as arguments.
 
 
 Running myslip
 --------------
 
-myslip can be built using cargo 1.88.0. Instructions to
-install cargo can be found online:
+myslip can be built using Cargo versions 1.88.0 and 1.89.0.
+Instructions to install cargo can be found online:
 https://doc.rust-lang.org/cargo/getting-started/installation.html
 
 If you are having trouble due to having a different version
@@ -52,21 +50,45 @@ and you used rustup for your cargo installation, you can
 follow these instructions on how to change the rust version
 https://rust-lang.github.io/rustup/overrides.html
 
-TODO: system requirements? try it out on debian
-So, for example
+So, for example on some linux systems featuring the `apt`
+package manager, the following works (tested on Debian 13)`:
 ```console
-$ sudo apt install curl git
+$ sudo apt install curl git builb-essential
 $ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+$ . "$HOME/.cargo/env"
 $ git clone 'https://git.cron4.fi/myslip.git'
 $ cd myslip
 ```
-and then myslip can be accessed either via `cargo run`,
-or alternatively you can add it to your `$PATH`:
+and then myslip can be accessed either via `cargo run`, or
+alternatively you can add it to your `$PATH`:
 ```console
 $ cargo build
+$ mkdir -p ~/.local/bin
+$ export PATH="$PATH:~/.local/bin"
+$ echo 'export PATH="$PATH:~/.local/bin"' >> ~/.bashrc
+$ ln "$(pwd)/target/debug/myslip" ~/.local/bin/myslip
+$ myslip
+```
+
+Installation has been tested on Aalto SSH servers in addition
+to debian/13 in case you prefer that. Here is how to install
+and compile the project there:
+```console
+$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+$ ~/.cargo/bin/cargo --version
+$ git clone 'https://git.cron4.fi/myslip.git'
+$ cd myslip/
+$ ~/.cargo/bin/cargo build
+$ mkdir -p ~/.local/bin
 $ ln "$(pwd)/target/debug/myslip" ~/.local/bin/myslip
+$ export PATH="$PATH:~/.local/bin"
 $ myslip
 ```
+Of course you must update your path next time when you open
+your shell too, so you might want to add
+`export PATH=$PATH:~/.local/bin` to your `~/.bashrc` in case
+you don't have a personal preference on how to manage your
+`$PATH` and other environment variables.
 
 Exit the REPL by pressing CTRL+C, CTRL+D or entering "exit".
 
@@ -79,15 +101,15 @@ Running `myslip filename.slip` tries to read a file named
 `filename.slip` as an s-expression and evaluates it.
 
 On the other hand, running `myslip` without specifying an
-executable file opens a REPL, in which you can enter
-one s-expression per line for evaluation. Variables bound
-in earlier expressions can be used.
+executable file opens a REPL, in which you can enter one
+s-expression per line for evaluation. Variables bound in
+earlier expressions can be used.
 
 If you wish to load a set of definitions from a file, say
 `header.slip`, use the `--load`-argument (`-l` for short):
 ```console
 $ myslip -l header.slip
 ```
-The standard library, found in `stdlib.slip`, is loaded
-in an equivalent way by default. If you wish to disable
-it, you can use the option `--no-stdlib`.
+The standard library, found in `stdlib.slip`, is loaded in an
+equivalent way by default. If you wish to disable it, you can
+use the option `--no-stdlib`.