Work on improving documentation

docs/grammar.md

@@ -6,18 +6,18 @@ The actual parser may do something slightly different (but equivalent) than this
 ## The Grammar
 * program ::= expr_list? _end_
 * expr_list ::= expr+
-* expr ::= atom | invocation
-* atom ::= _number_ | _boolean_ | _string_ | _symbol_ | lambda | _identifier_ | special_form
-* invocation ::= **(** (_identifier_ | special_form) expr_list? **)**
+* expr ::= atom \| invocation
+* atom ::= _number_ \| _boolean_ \| _string_ \| _symbol_ \| lambda \| _identifier_ \| special_form
+* invocation ::= **(** (_identifier_ \| special_form) expr_list? **)**
 * lambda ::= **{** params? expr **}**
-* params ::= **|** identifier+ **|**
-* special_form ::= **if** | **cond** | **define** | **do** | **and** | **or**
+* params ::= **\|** identifier+ **\|**
+* special_form ::= **if** \| **cond** \| **define** \| **do** \| **and** \| **or**
 
 ### Tokens
 Above, all words/characters **in bold** are token literals, while all words _in italics_ are "specially defined tokens":
 * _end_ is the end of the input stream.
 * _number_ is any "word" that can be parsed as a Rust `f64`.
-* _boolean_ ::= **true** | **false**
+* _boolean_ ::= **true** \| **false**
 * _string_ ::= **"** _c_* **"**, where _c_ is any character except `"`. There are also the escape sequences `\\`, `\n`, `\r`, `\t`, `\"`. Strings such as `"\"` and "\z" are considered invalid tokens.
 * _symbol_ ::= **#**_c_+, where _c_ is any character excluding whitespace.
 * _identifier_ is pretty much any word that doesn't conflict with another token.

docs/index.md

@@ -4,6 +4,7 @@ This is the main page for Psil.
 NOTE: most of this documentation is automatically generated! This is done using `cargo run -- --dump-docs`. To update it, update the associated Psil code, and then regenerate the docs.
 
 ## Subpages
+* [A 5-minute (or less?) introduction to Psil](intro.md)
 * [A description of Psil's grammar](grammar.md)
 * modules
   * [boolean](modules/boolean.md)

docs/intro.md

@@ -0,0 +1,65 @@
+# An Introduction to Psil
+This brief guide is written in the style of ["Learn X in Y minutes"](https://learnxinyminutes.com/).
+
+```lisp
+;;; 0. Intro
+; Comments are started with a semi-colon.
+; Currently, there are no multiline comments.
+
+; Psil is a Lisp-like programming language written in Rust.
+; Nothing about it is too crazy, as long as you've programmed before.
+; The command `psil` without any arguments will start a Psil REPL.
+; `psil file.lisp` will load and run a particlar psil file.
+
+;;; 1. Basic types
+; We have numbers,
+5 ; 5
+
+; booleans,
+true ; true
+false ; false
+
+; strings,
+"Hello" ; Hello
+
+; symbols,
+#symbol ; #symbol
+
+; and lastly...
+
+;;; 2. Procedures
+; The standard library includes many procedures, such as...
++ ; <procedure>
+put ; <procedure>
+
+; Procedures are first-class citizens, and are their own type, as you can see.
+; But obviously, they are most useful in being directly invoked, as follows:
+(+ 5 5) ; 10
+(put "Hello World") ; Hello World
+
+; Psil uses "S-expression" syntax for these invocations.
+; An invocation has the following grammar:
+; (proc arg1 arg2)
+; An invocation starts and ends with matching parentheses.
+; Like Polish notation, the procedure being invoked goes first, then the arguments.
+; A procedure might have multiple arguments, or none at all.
+; Arguments may have type restrictions as well.
+; As usual, consult the documentation: https://eric-unc.tech/psil/
+
+; Every procedure returns something.
+; If there is nothing interesting to return, returning `#void` is conventional.
+; You can combine invocations together to do interesting things, like this:
+(put "5*5 + 8 is... " (+ (* 5 5) 8)) ; 5*5 + 8 is... 33
+
+;;; 3. Special forms
+; Special forms are special kinds of procedures, but more like "keywords" from other languages.
+; They are as first-class, just like other precedures, which may be unusual from other backgrounds.
+; As of the current version, Psil has the following special forms:
+define ; <procedure>
+cond ; <procedure>
+if ; <procedure>
+and ; <procedure>
+or ; <procedure>
+
+; Special forms generally have special parsing or execution.
+```