docs: fix/improve example docs

Closes #833.

docs/examples/README.md

@@ -6,10 +6,11 @@ examples are provided; where each example has:
 1. Explanatory text, and
 2. Working source code.
 
->  NOTE  The examples use the 'cyan' build tool, as it is expected to be the
->        common tool used for initializing and building projects.
+The examples use the [Cyan](https://github.com/teal-language/cyan) build tool,
+as it is expected to be the common tool used for initializing and building
+projects. You can install Cyan with `luarocks install cyan`.
 
-In all of these examples it is assumed that the root directory is 'examples'.
+In all of these examples it is assumed that the root directory is `examples`.
 
 ## Files
 
@@ -19,22 +20,28 @@ handles, and basic IO.
 
 ### Create the Project
 
-Create your 'files' project with `cyan init files`.
+The `docs/examples/files` folder contains an example of the finished project.
+But let's follow the steps to replicate it from scratch.
+
+Go to your home folder (so that you're not within a Teal project, such as the
+Teal repository itself), and create your `myproject` project with `cyan init
+myproject`.
 
 ```
-examples> cyan init files
-    Info Created directory files
-    Info Created directory files/src
-    Info Created directory files/build
-    Info Wrote files/tlconfig.lua
+> cd
+~> cyan init myproject
+    Info Created directory myproject
+    Info Created directory myproject/src
+    Info Created directory myproject/build
+    Info Wrote myproject/tlconfig.lua
 ```
 
 Cyan has created a configuration file (`tlconfig`) and two directories. This
 is the standard project layout.
 
 ```
-examples> cd files
-files> find .
+~> cd myproject
+~/myproject> find .
 .
 ./build
 ./src
@@ -46,22 +53,22 @@ files> find .
 In this example `main.tl` will be the program that gets run. More complex
 projects will have modules that are called from main.
 
-Create [src/main.tl](files/src/main.tl).
+Create [src/main.tl](files/src/main.tl) in your project.
 
 ### Build the Project
 
 Use Cyan to build the project.
 
 ```
-files> cyan build
+~/myproject> cyan build
     Info Type checked src/main.tl
     Info Wrote build/main.lua
 ```
 
 And now the project directories look like...
 
 ```
-files> tree .
+~/myproject> find .
 .
 ./build
 ./build/main.lua
@@ -72,16 +79,19 @@ files> tree .
 
 ### Run the Project
 
-The program reads input arguments `-i <filename>` and `-o <filename>` from
-the command line to select input and output filenames. If those are not
-given, it uses standard input and standard output as fallback defaults.
+This simple program takes in input, converts it to uppercase, and produces an
+output.
+
+The program reads input arguments `-i <filename>` and `-o <filename>` from the
+command line to select input and output filenames. If those are not given, it
+uses standard input and standard output as fallback defaults.
 
 In this example the program reads data from the `ls` command piped via
 standard input, and writes to a file:
 
 ```
-files> ls -R1 | lua build/main.lua -o tmp.out
-files> cat tmp.out
+~/myproject> ls -R1 | lua build/main.lua -o tmp.out
+~/myproject> cat tmp.out
 BUILD
 SRC
 TLCONFIG.LUA
@@ -96,5 +106,5 @@ MAIN.TL
 You can delete the temporary file.
 
 ```
-files> rm tmp.out
+~/myproject> rm tmp.out
 ```

docs/examples/files/src/main.tl

@@ -42,7 +42,7 @@ local function parse_arguments(args: {string}): string, string
 end
 
 -- create or return file handles
-local function get_fd(name: string, mode: string, default: FILE): FILE, string
+local function get_fd(name: string, mode: io.OpenMode, default: FILE): FILE, string
    if not name then
       return default
    end