From d88137b1d653f2efcd7407af10e3bd4907d7b86a Mon Sep 17 00:00:00 2001
From: lethosor <lethosor@gmail.com>
Date: Sun, 19 Jul 2020 01:13:43 -0400
Subject: [PATCH] Split remote API info into separate doc, add example tools
 and clients

---
 docs/Dev-intro.rst |  9 ++-------
 docs/Remote.rst    | 47 ++++++++++++++++++++++++++++++++++++++++++++++
 docs/index-dev.rst |  1 +
 3 files changed, 50 insertions(+), 7 deletions(-)
 create mode 100644 docs/Remote.rst

diff --git a/docs/Dev-intro.rst b/docs/Dev-intro.rst
index 9a08533c0..2a17313fe 100644
--- a/docs/Dev-intro.rst
+++ b/docs/Dev-intro.rst
@@ -77,11 +77,6 @@ some functions (and some entire modules) are currently only available in C++.
 
 Remote access interface
 -----------------------
-DFHack supports remote access by exchanging Google protobuf messages via a TCP
-socket. Both the core and plugins can define remotely accessible methods. The
-``dfhack-run`` command uses this interface to invoke ordinary console commands.
-
-Currently the supported set of requests is limited, because the developers don't
-know what exactly is most useful.  `remotefortressreader` provides a fairly
-comprehensive interface for visualisers such as :forums:`Armok Vision <146473>`.
 
+DFHack provides a remote access interface that external tools can connect to and
+use to interact with DF. See `remote` for more information.
diff --git a/docs/Remote.rst b/docs/Remote.rst
new file mode 100644
index 000000000..b7c65b032
--- /dev/null
+++ b/docs/Remote.rst
@@ -0,0 +1,47 @@
+.. _remote:
+
+=======================
+DFHack Remote Interface
+=======================
+
+DFHack provides a remote access interface that external tools can connect to and
+use to interact with DF. This is implemented with `Google protobuf`_ messages
+exchanged over a TCP socket (which only accepts connections from the local
+machine by default). Both the core and plugins can define remotely-accessible
+methods (often referred to as **RPC methods**). The RPC methods currently
+available are not comprehensive, but can be extended with plugins.
+
+.. _Google protobuf: https://developers.google.com/protocol-buffers
+
+.. contents::
+    :local:
+
+Examples
+========
+
+The `dfhack-run` command uses the RPC interface to invoke DFHack commands
+(or Lua functions) externally.
+
+Plugins that implement RPC methods include:
+
+- `rename`
+- `remotefortressreader`
+- `isoworldremote`
+
+Plugins that use the RPC API include:
+
+- `stonesense`
+
+Third-party tools that use the RPC API include:
+
+- `Armok Vision <https://github.com/RosaryMala/armok-vision>`_ (:forums:`Bay12 forums thread <146473>`)
+
+Client libraries
+================
+
+Some external libraries are available for interacting with the remote interface
+from other (non-C++) languages, including:
+
+- `RemoteClientDF-Net <https://github.com/RosaryMala/RemoteClientDF-Net>`_ for C#
+- `dfhackrpc <https://github.com/BenLubar/dfhackrpc>`_ for Go
+- `dfhack-remote <https://github.com/alexchandel/dfhack-remote>`_ for JavaScript
diff --git a/docs/index-dev.rst b/docs/index-dev.rst
index 617c0c0d7..560137609 100644
--- a/docs/index-dev.rst
+++ b/docs/index-dev.rst
@@ -15,5 +15,6 @@ These are pages relevant to people developing for DFHack.
    /docs/Documentation
    /docs/Structures-intro
    /docs/Memory-research
+   /docs/Remote
    /docs/Binpatches