Add README.md files for moterm and moterm_example_app.
R=jamesr@chromium.org
Review URL: https://codereview.chromium.org/1337563002 .
diff --git a/apps/moterm/README.md b/apps/moterm/README.md
new file mode 100644
index 0000000..d37a8d4
--- /dev/null
+++ b/apps/moterm/README.md
@@ -0,0 +1,27 @@
+# Moterm
+
+`moterm` is an application that provides an embeddable view, which provides a
+VT100-style terminal that its embedder can connect to other applications. It is
+not useful as a standalone application (embedded by something, like a window
+manager, that is not aware of how to control it).
+
+For an example of an embedder that's useful as a standalone application, see the
+[Moterm example application](../../examples/moterm_example_app).
+
+## Details
+
+`moterm` exposes the `mojo.terminal.Terminal` interface to its embedder. Via
+this interface, its embedder may connect to the terminal directly (for direct
+input/output with the terminal) or request that the terminal connect to another
+application. In the latter case, that application should implement the
+`mojo.terminal.TerminalClient` interface.
+
+Output to/input from the terminal is done via a `mojo.files.File` that behaves
+"like a terminal" (in much the same way as in Unix one has terminal device
+files and file descriptors to them).
+
+## See also
+
+* [//examples/moterm_example_app](../../examples/moterm_example_app)
+* [//mojo/services/files/public/interfaces](../../mojo/services/files/public/interfaces)
+* [//mojo/services/terminal/public/interfaces](../../mojo/services/terminal/public/interfaces)
diff --git a/examples/moterm_example_app/README.md b/examples/moterm_example_app/README.md
new file mode 100644
index 0000000..190b276
--- /dev/null
+++ b/examples/moterm_example_app/README.md
@@ -0,0 +1,53 @@
+# Moterm example application
+
+`moterm_example_app` is an example application that embeds
+[Moterm](../../apps/moterm), uses it to provide a prompt, and allows it to be
+connected to other applications (which should implement the
+`mojo.terminal.TerminalClient` interface).
+
+## Running
+
+On Linux, run it in the usual way, e.g.:
+
+ $ mojo/devtools/common/mojo_run --enable-multiprocess "mojo:window_manager mojo:moterm_example_app"
+
+You'll probably need to click on the window to give it keyboard focus. You may
+also want to resize the window (especially horizontally) to make it bigger.
+
+At the `:)` prompt, you may enter the URL for any application implementing the
+`mojo.terminal.TerminalClient` interface. E.g.:
+
+ :) mojo:dart_netcat
+
+At this point, the terminal's input/output is transferred to the specified
+application. In this case, it just outputs a help message and closes the
+terminal, returning you to the `:)` prompt. You may also try:
+
+ :) mojo:dart_netcat?localhost&port=80
+
+In this case, `mojo:dart_netcat` will make a TCP connection to the specified
+host/port. Assuming you have a web server running on your machine, you may try
+entering:
+
+ GET /
+
+(It's probably a bug in `mojo:dart_netcat` that it doesn't close the terminal
+"file". You can press Control-D to return to the `:)` prompt. The unhandled Dart
+exception after you press Control-D is definitely a bug.)
+
+Another example you may try is:
+
+ :) file:///path/to/src/examples/js/repl.js
+
+At its `>` prompt, you can enter JavaScript expressions. E.g.:
+
+ > function add(x, y) { return x + y; }
+ undefined
+ > add("hello ", 123)
+ "hello 123"
+
+## See also
+
+* [//apps/moterm](../../apps/moterm)
+* [//examples/dart/netcat](../dart/netcat)
+* [//examples/js/repl.js](../dart/js/repl.js)
