docs: A document about running code (#1013)

* docs: A document about running code

* fix: Tweaks

* docs: More information about running code

Co-authored-by: Erik Svedang <erik@Eriks-iMac.local>

README.md

@@ -45,9 +45,8 @@ The key features of Carp are the following:
     (SDLApp.run-with-callbacks &app SDLApp.quit-on-esc tick draw state)))
 ```
 
-To build this example, save it to a file called 'example.carp' and load it with ```(load "example.carp")```, then execute ```(build)``` to build an executable, and ```(run)``` to start. The external dependencies are SDL2 and pkg-config. On macOS Catalina libiconv is also required.
-
-For a slightly longer example, check out [Reptile](examples/reptile.carp) - a Snake clone in Carp.
+For instructions on how to run this code, see [this document](docs/HowToRunCode.md).
+For more examples, check out the [examples](examples) directory.
 
 ### Language Designer & Lead Developer
 [Erik Svedäng](http://www.eriksvedang.com) ([@e_svedang](https://twitter.com/e_svedang))

docs/HowToRunCode.md

@@ -0,0 +1,57 @@
+# How to run code
+
+This document is aimed at people just starting out with Carp, in particular if you want to try out the [examples](../examples).
+
+## Prerequisites
+
+Make sure that you have [installed the Carp compiler and its dependencies](Install.md) and that you can start it without any error messages. Here's how it should look:
+
+```bash
+$ carp
+Welcome to Carp X.Y.Z
+This is free software with ABSOLUTELY NO WARRANTY.
+Evaluate (help) for more information.
+鲤
+```
+
+The `鲤` character on the last line is the [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop) prompt, it means that Carp is waiting for you to enter a command.
+
+## Running code from the REPL
+
+You can load some code with:
+
+```bash
+鲤 (load "some_file.carp")
+```
+
+The path to the file should be relative to where you started `carp` (or in your [search-path](Libraries.md) path).
+It is also possible to paste a block of code (even multiple top-level expressions) into the REPL.
+
+To build and run, first do:
+
+```bash
+鲤 (build)
+```
+
+And then:
+
+```
+鲤 (run)
+```
+
+## Running code from the terminal
+
+If you don't want to work in the REPL and use a more classic "compile & run" setup, do this:
+
+```bash
+$ carp some_file.carp -x
+```
+
+Any files you list as arguments to `carp` will be loaded (this works when starting the REPL too).
+The `-x` flag means that you want to compile and run the code immedately, exiting afterwards.
+
+If you just want to build the executable, use `-b` instead:
+
+```bash
+$ carp some_file.carp -b
+```

docs/Manual.md

@@ -3,6 +3,7 @@
 ### Related pages
 
 * [Installation](Install.md) - how to acquire and configure the Carp compiler
+* [How To Run Code](HowToRunCode.md) - compile and execute .carp files
 * [Tooling](Tooling.md) - supported editors
 * [Libraries](Libraries.md) - how to work with libraries and modules
 * [Multimedia](Multimedia.md) - graphics, sounds, etc
@@ -12,7 +13,7 @@
 
 To learn more about the Carp language and its syntax and semantics, check out the [Carp Language Guide](LanguageGuide.md).
 
-### Basics
+### REPL Basics
 
 The Carp language is very tightly integrated with the REPL, everything you want to do to your program can be controlled from here.