\input texinfo
@setfilename protocol.info
@settitle The Phylogenetic Tree Editing Protocol

@c Update this number only and always when you actually update the manual!
@set protocol-version 7

@setchapternewpage off

@ifinfo

This document describes the protocol used by the RDP gene editor to
communicate with the phylogenetic support subprocess.

This document was written by Jim Blandy.  It is in the public domain.
@end ifinfo

@titlepage
@sp 10
@center @titlefont{The Phylogenetic Tree Editing Protocol}
@sp 4
@center Jim Blandy, July 1994

@vskip 0pt plus 1filll
This document is in the public domain.
@end titlepage


@c ======================================================================
@node Top, Introduction, (dir), (dir)

@ifinfo
This document describes the protocol the RDP gene editor uses to
communicate with the phylogenetic support subprocess.
@end ifinfo

@menu
* Introduction::                Why this protocol is useful.
* Selection::                   What selection means.
* Conventions::                 General conventions the protocol follows.
* Requests::                    The protocol requests.
* Replies::                     The replies they might generate.
* Display::                     How the tree is displayed.
@end menu

@node Introduction, Selection, Top, Top
@unnumbered Introduction

The RDP gene editor can present phylogenetically arranged listings of
the organisms present in a particular file or database.  The listings
are arranged to facilitate browsing of database according to taxonomic
groupings.  The user can list selected taxa in detail, and hide
uninteresting taxa.

Emacs lisp is too slow to implement some of these features with
reasonable response times, as they occasionally require sophisticated
searches and traversals of phylogenetic trees.  To comfortably support
these operations, the gene editor runs a subprocess, written in C, to do
the more interesting operations.  The gene editor tells the server where
the user has clicked, or which menu item the user has chosen, and the
server replies with a series of instructions to update the display
accordingly.

This manual documents version @value{protocol-version} of the protocol.


@c ======================================================================
@node Selection, Conventions, Introduction, Top
@chapter What Selection Means

The purpose of the phylo editor is to allow the user to conveniently
specify a set of organisms.  Interior nodes of a tree exist only to
provide meaningful groupings of the child organisms at the leaves.

Therefore, it's important to define what it means for an interior node
to be @dfn{selected}.  We say that an interior node is selected iff all
of its descendant leaf nodes are selected.

Thus, when the user selects an interior node, if all its leaves are
selected, we unselect them all; otherwise, we select them all.  When the
user selects or unselects a leaf, we check its parents to see if any of
them have become selected or not, to redisplay properly.


@c ======================================================================
@node Conventions, Requests, Selection, Top
@chapter Conventions

The editor sends @dfn{requests} to the server, asking it to perform a
particular user command.  Syntactically, a request is a sequence of
strings terminated by an unescaped newline, the first of which is the
name of the requested function, and the rest of which are the request's
arguments.  Strings are either delimited by whitespace, or placed in
double quotes.  For example, if the user clicks to select the organism
@var{Thermus thermophilus}, whose shortname is @samp{T.thmophl}, the
editor will send the server a request of the form:

@example
select "T.thmophl"
@end example

This request consists of two strings, @samp{select} and
@samp{T.thmophl}.  A space separates the two.  Since the second string
starts with a double quote, it extends until the next double quote.
Double quotes may be included in quoted strings if you place a backslash
in front of them.  Strings may contain any character, including newlines
and null characters (ASCII NUL).  Newlines may (but need not be) written
as @code{\n}.  In general, the syntax for strings is that supported by
Emacs lisp strings, without text properties.

After processing a request, the server sends a series of @dfn{replies}.
Reply lines look like Emacs lisp function calls; they are designed to be
read and evaluated by the editor.  For example, after successfully
performing the @code{select} request shown in the previous example, the
server might respond as follows:

@example
(phylo-display-node "T.thmophl" #("            T.thmophl    \"Thermus
 thermophilus\" str. HB8 (ATCC 27634; DSM 579)\n" 0 80 (mouse-face ph
ylo-mouse-unselected face nil) 80 81 (mouse-face nil face nil)))
(phylo-done)
@end example

This indicates that the editor should redisplay the given node with the
string provided (which may use the Emacs Lisp syntax for strings with
text properties), and then listen for further user input.

If there had been no taxon in the tree named @samp{T.thmophl} then the
server would have replied as follows:

@example
(phylo-error "no node named \"GREEN NON-SULPHUR SUBDIVISION\"")
@end example

Note that, although strings can contain newlines, the server always uses
the @samp{\n} syntax to denote them.  Thus, the client may assume that
whenever it receives a newline character from the server, it is
preceeded by a syntactically complete command.  We thus impose no
restrictions on the data to be exchanged between client and server,
while allowing the client to efficiently recognize reply boundaries.

Note that, when the server writes data to a file, the quoting
conventions described above are not used.  The output files contain only
data, and never replies or requests, so there is no need to distinguish
data from metadata.


@c ======================================================================
@node Requests, Replies, Conventions, Top
@chapter Requests

Here are the requests available to the client.  In these requests, the
string @code{!root} may be used in place of a node name, to refer to the
root of the tree.  Each of these requests will elicit at least a
@code{phylo-done} reply from the server, preceeded by zero or more other
replies.


@deffn Request check-version version
Indicate that the client expects to use version @var{version} of the
protocol.  Send a @code{phylo-okay} response if @var{version} is the
version of the protocol this server speaks; otherwise, signal an error.
@end deffn


@deffn Request use-tree tree-file organism-file
Read a tree from @var{tree-file}, which should follow the format used by
the @samp{.phylo} files from the Ribsomal Database Project.  (We hope to
support other tree formats, like Newick, in the future.)  Read a list of
organisms from @var{organism-file}.  Trim the tree to include only those
organisms mentioned therein, and those internal nodes needed to support
them.
@end deffn


@deffn Request select node
The user has asked that @var{node} be selected (or unselected, if it is
selected already).  The server should respond with a set of replies to
update the display.
@end deffn


@deffn Request select-range start-node end-node
The user has selected or unselected a range of nodes, extending from
@var{start-node} to @var{end-node}.  @var{start-node} may fall before or
after @var{end-node} in the usual traversal order, or they may be the
same node.

An @dfn{apparent leaf} is a node which is a leaf node, or a closed
interior node; it is displayed as a node with no children.
If @var{start-node} is selected, unselect all apparent leaves in the
range.  Otherwise, select all apparent leaves in the range.
@end deffn


@deffn Request open node
The user has asked that @var{node} be opened (or closed, if it is open
already).  The server should respond with a set of replies to update the
display.
@end deffn


@deffn Request open-all
Open all interior nodes.
@end deffn


@deffn Request open-groups
Close nodes which contain only leaves.  Open all others.
@end deffn


@deffn Request open-selected
Open nodes which have any selected leaves.  Close all others.
@end deffn


@deffn Request open-subtree tree
Open all interior nodes in the subtree rooted at @var{tree}.
@end deffn


@deffn Request list-selected filename
Write the names of all the selected nodes, separated by newlines, to
@var{filename}.  If @var{filename} is the empty string, write the names
to the standard output.
@end deffn



@c ======================================================================
@node Replies, Display, Requests, Top
@chapter Replies


These are the replies that the client may receive from the server.  Each
request from the client will generate at least one reply from the
server.  They follow the syntax of Emacs lisp function calls.


@deffn Reply phylo-display-all text
Replace the entire tree's contents with @var{text}.
@end deffn


@deffn Reply phylo-display-range start-node end-node text
Replace the range of the buffer starting at @var{start-node} and ending
at @var{end-node} (both endpoints inclusive) with @var{text}.
@var{start-node} is guaranteed to appear no later in the tree than
@var{end-node}; @var{start-node} and @var{end-node} may be the same
node.  All three are printed using the Emacs Lisp read syntax for
strings.
@end deffn


@deffn Reply phylo-message string
The client should display @var{string} in the minibuffer.
@end deffn


@deffn Reply phylo-error string
The client should signal an error, displaying @var{string} in the
minibuffer.  The client should expect no further replies to the request
with elicited this reply.
@end deffn


@deffn Reply phylo-okay string
The client should return to processing user input; the server has
processed all the clients' requests successfully.
@end deffn



@c ======================================================================
@node Display,  , Replies, Top
@chapter Display

We have already shown several examples of replies from the
@code{display} requests; in this section, we define the format used to
display tree nodes.

Consider the following listing, for a node with children.
@example
             1.1.2 METHANOBACTERIALES ...
@end example
Here is what each part of the line means.
@table @asis

@item indentation
Each line is indented according to its depth in the tree.  Children are
indented more than their parents.
   
@item @code{1.1.2}
This is the name of the node.  This is what requests should use to
identify the node.  The node name never contains spaces, so you can tell
where it ends and the description begins.  

@item @code{METHANOBACTERIALES}
This is the description of the node.

@item @code{...}
These are the node's @dfn{ellipses}; they indicate whether the node's
@code{open} mark is set or not.  If it is set, the ellipses are
@code{>>>}.  If it is clear, the ellipses are @code{...}.

@end table


Here is a sample listing line for a node without children:
@example
            Mc.jannasc   Methanococcus jannaschii str. JAL-1
@end example
Here is what each part of the line means.
@table @asis

@item indentation
An indication of the node's depth, as above.

@item @code{Mc.jannasc}
The name of the node, as above.

@item @code{Methanococcus jannaschii str. JAL-1}
The description of the node.  This extends to the end of the line.  Note
that if the node's description ends in @code{...}, then it's not
necessarily easy to tell whether this is a leaf node or an interior
node.  This is a bug.

@end table


The server highlights sections of some lines to indicate selection.  If
a node is selected, the name and description will be given the
@code{phylo-selected} face.  If a closed internal node has some selected
children, the ellipsis will be given the @code{phylo-selected} face.

The server gives sections of each line the @code{mouse-face} text
property, to make it easier for the user to see what they're about to
click on.  It will use the @code{phylo-mouse-selected} face for selected
nodes, and the @code{phylo-mouse-unselected} face for unselected nodes.


@bye