From 751c2aedfd05590f5b6e7f5059159d304a4408d3 Mon Sep 17 00:00:00 2001
From: crc <crc@noemail.net>
Date: Fri, 9 Nov 2018 03:11:58 +0000
Subject: [PATCH] expand notes on the retro binary in the README

FossilOrigin-Name: b24afd52b5a810b6af67241846572a386db8f53138ad192e8d45a532176e1a7a
---
 README.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 52 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index dd7bf1a..557e169 100644
--- a/README.md
+++ b/README.md
@@ -43,15 +43,61 @@ The primary executable is `retro`. This is used for running the
 examples and the Atua (gopher) & Casket (http) servers that
 power forthworks.com.
 
-`retro` embeds the image into the binary, making it trivial
-to copy and deploy.
+The `retro` executable embeds the image into the binary, making
+it trivial to copy and deploy.
 
-The `retro` interface also extends the language with many new
-words and vocabularies, adding scripting, file i/o, gopher, and
+This interface layer also extends the language with many new
+words and vocabularies, adds scripting, file i/o, gopher, and
 floating point math support.
 
-When run without any command line arguments, this will start
-the *listener*, a basic REPL for interactive use.
+The `retro` executable can handle a variety of command line
+arguments:
+
+    retro
+
+Starts the *listener*, a basic REPL for interactive use.
+
+    retro -i
+
+Starts the *listener*, a basic REPL for interactive use.
+
+    retro -c
+
+Starts the *listener*, a basic REPL for interactive use. With
+`-c`, it runs in character breaking mode, where input is run
+as soon as a space or enter is encountered. This requires RETRO
+to have been built with TERMIOS support.
+
+    retro filename
+
+This will run the code in the specified file, then exit. This
+is also used to run programs as shell-type scripts using a
+header line like `#!/usr/bin/env retro`.
+
+    retro -i -f filename
+
+This will run the code in the specified file, then start the
+listener.
+
+    retro -c -f filename
+
+This will run the code in the specified file, then start the
+listener in character breaking mode.
+
+    retro -h
+
+Displays a summary of the command line arguments.
+
+Source files for use with `retro` are written with code in
+fenced blocks:
+
+    commentary here
+     
+    ~~~
+    code here
+    ~~~
+
+Anything outside the fenced blocks will be ignored.
 
 ### retro-repl