Documenting (system repl server)

[Ian Price]

It isn't much but I've had a stab at documenting (system repl server) so
that I could feel less guilty about suggesting people use it.

Aside from it's sparseness, the two main issues I've had are
1. Under what section of the manual should it be placed, and
2. How to represent complex optional arguments

For now, I have currently placed it in a new subsection of 6.17 (Reading
and Evaluating Scheme Code). I'm not entirely convinced this is the
right place for it, better suggestions welcome.

For 2, I have described the optional in the text, rather than trying to
placing the expression directly in the prototype.

Rough patch is attached.

-- 
Ian Price -- shift-reset.com

"Programming is like pinball. The reward for doing it well is
the opportunity to do it again" - from "The Wizardy Compiled"

>From d3efaf09c4b57e3055afb503a6c0fd5c7a115ec8 Mon Sep 17 00:00:00 2001
From: Ian Price <address@hidden>
Date: Mon, 18 Mar 2013 18:55:18 +0000
Subject: [PATCH] Document (system repl server)

* doc/ref/api-evaluation.texi (REPL Servers): New Subsection.
---
 doc/ref/api-evaluation.texi |   40 ++++++++++++++++++++++++++++++++++++++++
 1 files changed, 40 insertions(+), 0 deletions(-)

diff --git a/doc/ref/api-evaluation.texi b/doc/ref/api-evaluation.texi
index 5c932a7..ff76580 100644
--- a/doc/ref/api-evaluation.texi
+++ b/doc/ref/api-evaluation.texi
@@ -22,6 +22,7 @@ loading, evaluating, and compiling Scheme code at run time.
 * Delayed Evaluation::          Postponing evaluation until it is needed.
 * Local Evaluation::            Evaluation in a local lexical environment.
 * Local Inclusion::             Compile-time inclusion of one file in another.
+* REPL Servers::                Serving a REPL over a socket.
 @end menu
 
 
@@ -1219,6 +1220,45 @@ the source files for a package (as you should!).  It 
makes it possible
 to evaluate an installed file from source, instead of relying on the
 @code{.go} file being up to date.
 
address@hidden REPL Servers
address@hidden REPL Servers
+
+The procedures in this section are provided by
address@hidden
+(use-modules (system repl server))
address@hidden lisp
+
+When an application is written in Guile, it is often convenient to
+allow the user to be able to interact with it by evaluating Scheme
+expressions in a REPL.
+
address@hidden {Scheme Procedure} make-tcp-server-socket [#:host=#f] @
+                          [#:addr] [#:port=37146]
+Returns a stream socket bound to a given address @var{addr} and port
+number @var{port}. If the @var{host} is given, and @var{addr} is not,
+then the @var{host} string is converted to an address. If neither is
+given, we use the loopback address.
address@hidden deffn
+
address@hidden {Scheme Procedure} make-unix-domain-server-socket 
[#:path="/tmp/guile-socket"]
+Returns a UNIX domain socket, bound to a given @var{path}.
address@hidden deffn
+
address@hidden {Scheme Procedure} run-server [server-socket]
address@hidden {Scheme Procedure} spawn-server [server-socket]
address@hidden creates and runs a repl, making it available over
+the given @var{server-socket}. If @var{server-socket} is not provided,
+it defaults to the socket created by calling
address@hidden with no arguments.
+
address@hidden is similar, but it runs the server in a new
+thread, rather than the existing one.
address@hidden deffn
+
address@hidden {Scheme Procedure} stop-server-and-clients!
+Closes the connection on all running server sockets.
address@hidden deffn
+
 @c Local Variables:
 @c TeX-master: "guile.texi"
 @c End:
-- 
1.7.7.6