[shepherd] 05/07: doc: Document the sexp protocol.

[Ludovic Courtès]

civodul pushed a commit to branch master
in repository shepherd.

commit 96a04e75d16baf9f44460d402a8b9ad1e34933f6
Author: Ludovic Courtès <address@hidden>
Date:   Wed Jan 27 14:36:16 2016 +0100

    doc: Document the sexp protocol.
    
    * shepherd.texi (Communication): Document the sexp protocol.
---
 shepherd.texi |   29 +++++++++++++++++++++++++++++
 1 files changed, 29 insertions(+), 0 deletions(-)

diff --git a/shepherd.texi b/shepherd.texi
index a380c7e..88acd33 100644
--- a/shepherd.texi
+++ b/shepherd.texi
@@ -1119,6 +1119,35 @@ inserts a newline.  It writes to whatever is the main 
output target of
 the Shepherd, which might be multiple at the same time in future versions.
 @end deffn
 
address@hidden protocol, between @command{shepherd} and its clients
+Under the hood, @code{write-command} and @code{read-command} write/read
+commands as s-expressions (sexps).  Each sexp is intelligible and
+specifies a protocol version.  The idea is that users can write their
+own clients rather than having to invoke @command{herd}.  For instance,
+when you type @command{herd status}, what is sent over the wire is the
+following sexp:
+
address@hidden
+(shepherd-command
+  (version 0)
+  (action status) (service root)
+  (arguments ()) (directory "/data/src/dmd"))
address@hidden lisp
+
+The reply is also an sexp, along these lines:
+
address@hidden
+(reply (version 0)
+       (result (((service @dots{}) @dots{})))
+       (error #f) (messages ()))
address@hidden lisp
+
+This reply indicates that the @code{status} action was successful,
+because @code{error} is @code{#f}, and gives a list of sexps denoting
+the status of services as its @code{result}.  The @code{messages} field
+is a possibly-empty list of strings meant to be displayed as is to the
+user.
+
 
 @c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@