doc: added help message and a reference to it in README.md

3 files changed, 81 insertions, 20 deletions

diff --git a/README.md b/README.md
index a65cdb7..f5881f1 100644
--- a/README.md
+++ b/README.md
@@ -10,12 +10,15 @@ and instructions on setting it up.
 
 Language introduction
 ---------------------
-STILL TODO (or to modify)
-how functional is it?
-myslip is a lisp-inspired language, but a bit different
-(mostly, because I have never really written lisp except
- for in emacs, so I have no clue of what lisp usually is
- like).
+
+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.
+
 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.
@@ -31,8 +34,8 @@ be the operator that is passed the rest of the expressions
 as arguments.
 
 
-Running the project
--------------------
+Running myslip
+--------------
 
 myslip can be built using cargo 1.88.0. Instructions to
 install cargo can be found online:
@@ -44,22 +47,39 @@ 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
 ```console
-TODO
 $ sudo apt install curl git
-$ curl ??? | sh ???
-$ git clone ???
+$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+$ git clone 'https://git.cron4.fi/myslip.git'
 $ cd myslip
 ```
-and then the interpreter can be accessed either via
-`cargo run`, or then 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
-TODO
 $ cargo build
-$ ln ??? ???
+$ ln "$(pwd)/target/debug/myslip" ~/.local/bin/myslip
 $ myslip
 ```
 
-Exit the REPL by CTRL+C, CTRL+D or entering "exit".
+Exit the REPL by pressing CTRL+C, CTRL+D or entering "exit".
+
+For a quick reference on how to use the `myslip` command,
+see `myslip --help`.
 
+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.
+
+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`.
diff --git a/TUTORIAL.md b/TUTORIAL.md
index d7bf266..4cf8948 100644
--- a/TUTORIAL.md
+++ b/TUTORIAL.md
@@ -44,6 +44,15 @@ Decimals are truncated in division:
 2 : Int
 ```
 
+Increment and decrement operators are supplied by the
+standard library:
+```console
+> (-- 1)
+0 : Int
+> (++ 1)
+2 : Int
+```
+
 
 Booleans
 --------
@@ -65,6 +74,15 @@ false : Bool
 false : Bool
 ```
 
+If-expressions are provided by the standard library in the
+form `(if [condition] [iftrue] [iffalse])`:
+```console
+> (if true 1 0)
+1 : Int
+> (if false 1 0)
+0 : Int
+```
+
 
 Integer comparisons
 -------------------
@@ -99,7 +117,8 @@ x saved
 ```
 The REPL interprets this as `((let x 1) x)`, which you
 could also type but would make a more cumbersome REPLing
-experience.
+experience (and would make loading definitions from files
+nigh impossible).
 
 Shadowing works as expected:
 ```console
diff --git a/src/main.rs b/src/main.rs
index 2e9ee5f..0fcf340 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -42,6 +42,7 @@ fn main() {
 
     let mut next_is_load = false;
     let mut no_stdlib = false;
+    let mut help = false;
     for arg in env::args() {
 
 	if next_is_load {
@@ -54,9 +55,10 @@ fn main() {
 	    s if s.ends_with("myslip") => continue,
 	    "-l" | "--load" => next_is_load = true,
 	    "--no-stdlib" => no_stdlib = true,
+	    "--help" | "-h" | "-?" => help = true,
 	    s => match file_to_execute {
 		Some(n) => {
-		    println!("Error: can't execute both '{}' and '{}', please specify just one file", s, n);
+		    println!("Error: can't execute both '{}' and '{}', please specify just one file. See '--help' for correct syntax.", s, n);
 		    return;
 		},
 		None => file_to_execute = Some(s.to_string()),
@@ -64,9 +66,29 @@ fn main() {
 	}
 
     }
+    if help {
+	println!("{}", String::from("") +
+		 "myslip [options] [file]\n" +
+		 "\n" +
+		 "If [file] is given, executes the s-expression contained by\n" +
+		 "the file. Otherwise starts the myslip repl.\n" +
+		 "\n" +
+		 "Options:\n" +
+		 "\n" +
+		 "  --load [defs] | -l [defs]  loads declarations from file\n" +
+		 "                             named [defs] before execution\n" +
+		 "\n" +
+		 "  --no-stdlib                stops myslip from loading the\n" +
+		 "                             standard library at startup\n" +
+		 "\n" +
+		 "  --help | -h | -?           displays this help message\n"
+
+	);
+	return;
+    }
     if next_is_load {
 	println!(
-"Error: '--load' can't be the last element of the argument list "
+"Error: '--load' can't be the last element of the argument list. See '--help' for correct syntax."
 	);
 	return;
     }
@@ -87,7 +109,7 @@ fn main() {
 
     match file_to_execute {
 	Some(name) => {
-	    let mut exp = match read_file_to_execute(name) {
+	    let exp = match read_file_to_execute(name) {
 		Ok(e) => e,
 		Err(e) => {
 		    println!("Error reading source file: {e}");