Attempting documentation again.

git-svn-id: https://www.unprompted.com/svn/projects/tildefriends/trunk@3375 ed5197a5-7fde-0310-b194-c3ffbd925b24

README.md

@@ -9,19 +9,23 @@ Tilde Friends is a program that aims to securely host pure JavaScript web applic
 ## Building
 Tilde Friends is [routinely](https://www.unprompted.com/projects/build/tildefriends) built on Linux, Windows, and OS X.
 
-1. Get and build [Google V8](https://code.google.com/p/v8-wiki/wiki/UsingGit) (latest 3.30).
-2. Get and build [libuv](https://github.com/libuv/libuv) (latest 1.0).
+1. Get and build [Google V8](https://github.com/v8/v8/wiki/Building%20from%20Source) (latest 5.5).
+2. Get and build [libuv](https://github.com/libuv/libuv) (latest 1.10.1).
 3. Run:
   ```
   scons uv=path/to/libuv v8=path/to/v8
   ```
 
 ## Running
-Running the built tildefriends executable will start a web server.  This is a good starting point: <http://localhost:12345/tasks>.
+Running the built tildefriends executable will start a web server.  This is a good starting point: <http://localhost:12345/>.
 
 The first use to create an account and log in will be granted administrative privileges.  Everything can be managed entirely from the web interface.
 
-This is a work in progress.
+This is all a work in progress.
+
+## Documentation
+
+See the [users guide](docs/guide.md) for documentation.
 
 ## License
 All code unless otherwise noted in [COPYING](https://www.unprompted.com/projects/browser/projects/tildefriends/trunk/COPYING) is provided under the [Affero GPL 3.0](https://www.unprompted.com/projects/browser/projects/tildefriends/trunk/LICENSE) license.

docs/guide.md

@@ -0,0 +1,188 @@
+# Philosophy
+
+Tilde Friends is a platform for making, running, and sharing web applications.
+
+When you visit Tilde Friends in a web browser, you are presented with a
+terminal interface, typically with a big text output box covering most of the
+page and an input box at the bottom, into which text or commands can be
+entered.  A script runs to produce text output and consume user input.
+
+The script is a Tilde Friends application, and it runs on the server, which
+means that unlike client-side JavaScript, it can have the ability to read and
+write files on the server or create network connections to other machines.
+Unlike node.js or other server-side runtime environments, applications are
+limited for security reasons to not interfere with each other or bring the
+entire server down.
+
+Above the terminal, an "Edit" link brings a visitor to the source code for the
+current Tilde Friends application, which they can then edit, save as their own,
+and run.
+
+# Architecture
+
+Tilde Friends is a C++ application with a JavaScript runtime that provides
+restricted access to filesystem, network, and other system resources.  The core
+process runs a core set of scripts that implement a web server, typically
+starting a new process for each visitor's session which runs scripts for the
+active application and stopping it when the visitor leaves.
+
+Only the core process has access to most system resources, but session
+processes can be given accesss through the core process.
+
+Service processes are identical to session processes, but they are not tied to
+a user session.
+
+## Communication
+
+In the same way that web browsers expose APIs for scripts running in the
+browser to modify the document, play sounds and video, and draw, Tilde Friends
+exposes APIs for scripts running on a Tilde Friends server to interact with a
+visitor's web browser, read and write files on the server, and otherwise
+interact with the world.
+
+There are several distinct classes of APIs.
+
+First, there are low-level functions exposed from C++ to JavaScript.  Most of
+these are only available to the core process.  These typically only go through
+a basic JavaScript to C++ transition and are relatively fast and immediate.
+
+	// Displays some text to the server's console.
+	print("Hello, world!");
+
+There is a mechanism for communicating between processes.  Functions can be
+exported and called across process boundaries.  When this is done, any
+arguments are serialized to a network protocol, deserialized by the other
+process, the function called, and finally any return value is passed back in
+the same way.  Any functions referenced by the arguments or return value are
+also exported and can be subsequently called across process boundaries.
+Functions called across process boundaries are always asynchronous, returning a
+Promise.  Care must be taken for security reasons to not pass dangerous
+functions ("deleteAllMydata()") to untrusted processes, and it is best for
+performance reasons to minimize the data size transferred between processes.
+
+	// Send an "add" function to any other running processes.  When called, it
+	// will run in this process.
+	core.broadcast({add: function(x, y) { return x + y; }});
+
+	// Receive the above message and call the function.
+	core.register("onMessage", function(sender, message) {
+		message.add(3, 4).then(x => terminal.print(x.toString()));
+	});
+
+Finally, there is a core web interface that runs on the client's browser that
+extends access to a running Tilde Friends script.
+
+	// Displays a message in the client's browser.
+	terminal.print("Hello, world!");
+
+## API Documentation
+
+The Tilde Friends API is very much evolving.
+
+All currently registered methods can be explored in the
+[documentation](https://www.tildefriends.net/~cory/documentation) app.
+
+All browser-facing methods are implemented in [client.js](core/client.js).
+Most process-related methods are implemented in [core.js](core/core.js).
+
+Higher-level behaviors are often implemented within library-style apps
+themselves and are beyond the scope of this document.
+
+### Terminal
+All interaction with a human user is through a terminal-like interface.  Though
+it is somewhat limiting, it makes simple things easy, and it is possible to
+construct complicated interfaces by creating and interacting with an iframe.
+
+#### terminal.print(arguments...)
+Print to the terminal.  Arguments and lists are recursively expanded.  Numerous
+special values are supported as implemented in client.cs.
+
+	// Create a link.
+	terminal.print({href: "http://www.tildefriends.net/", value: "Tilde Friends!"});
+
+	// Create an iframe.
+	terminal.print({iframe: "<b>Hello, world!</b>", width: 640, height: 480});
+
+	// Use style.
+	terminal.print({style: "color: #f00", value: "Hello, world!"});
+
+	// Create a link that when clicked will act as if the user typed a command.
+	terminal.print({command: "exit", value: "Get out of here."});
+
+#### terminal.clear()
+Clears the terminal output.
+
+#### terminal.readLine()
+Read a line of input from the user.
+
+#### terminal.setEcho(echo)
+Controls whether the terminal will automatically echo user input.  Defaults to true.
+
+#### terminal.setPrompt(prompt)
+Sets the terminal prompt.  The default is ">".
+
+#### terminal.setTitle(title)
+Sets the browser window/tab title.
+
+#### terminal.split(terminalList)
+Reconfigures the terminal layout, potentially into multiple split panes.
+
+	terminal.split([
+		{
+			type: "horizontal",
+			children: [
+				{name: "left", basis: "2in", grow: 0, shrink: 0},
+				{name: "middle", grow: 1},
+				{name: "right", basis: "2in", grow: 0, shrink: 0},
+			],
+		},
+	]);
+
+#### terminal.select(name)
+Directs subsequent output to the named terminal.
+
+#### terminal.postMessageToIframe(iframeName, message)
+Sends a message to the iframe that was created with the given name, using the
+browser's window.postMessage.
+
+### Database
+Tilde Friends uses lmdb as a basic key value store.  Keys and values are all
+expected to be of type String.  Each application gets its own isolated
+database.
+
+#### database.get(key)
+Retrieve the database value associated with the given key.
+
+#### database.set(key, value)
+Sets the database value for the given key, overwriting any existing value.
+
+#### database.remove(key)
+Remove the database entry for the given key.
+
+#### database.getAlll()
+Retrieve a list of all key names.
+
+### Network
+Network access is generally not extended to untrusted users.
+
+It is necessary to grant network permissions to an app owner through the
+administration app.
+
+Apps that require network access must declare it like this:
+
+	//! { "permissions": ["network"] }
+
+#### network.newConnection()
+Creates a Connection object.
+
+#### connection.connect(host, port)
+Opens a TCP connection to host:port.
+
+#### connection.read(readCallback)
+Begins reading and calls readCallback(data) for all data received.
+
+#### connection.write(data)
+Writes data to the connection.
+
+#### connection.close()
+Closes the connection.