******************************************************************
*                                                                *
*                  How to Use the AGD Server                     *
*                  =========================                     *
*                                                                *
******************************************************************


1. The AGD Server:
------------------


The AGD server (agd_server) is an executable program that 
allows to run all AGD algorithms from the command line. 
The program reads the input graph in GML or GraphWin format 
(see file graphformats.txt) from a given file and loads the 
corresponding options from a second file. It runs the selected 
algorithm and writes the result back to the input graph file. If 
an error occurs (e.g., if a precondition of the selected 
algorithm is violated) a diagnostic message is written to the 
input graph file. 

The program recognizes a special "list" parameter that prints a 
list of all available algorithms together with their default 
options. This command can be used to create an initial option 
file. The option file format is based on the GML format. The 
output of the list command for the current  AGD server version 
(1.4) can be found in file default_server_options.gml. 

The main reason for developing the AGD server program was to 
create a file or socket interface that allows applications 
implemented on different platforms (,e.g., not based on LEDA 
or not written in C++) to use the algorithms of the AGD library. 
Such a client application can easily contact the AGD server by 
writing the graph to be drawn to a temporary file (either in 
GraphWin or GML format), running the AGD server with appropriate 
options on this file, and reading the result from the same file. 
The application may ask for the list of all available AGD 
algorithms and their options (,e.g., for building a corresponding 
pull-down menu) by using the list command of the server. LEDA's 
graph editor GraphWin uses this method to incorporate the graph 
drawing algorithms of AGD.

2. The GraphWin Client:
-----------------------

This client for agd_server is integrated in LEDA's graph editor
GraphWin.  It looks for agd_server in the user's command search 
path and, if successful, includes a sub-menu containing the names 
of all available AGD algorithms into the main layout menu. Now,
these algorithms can easily be applied to the current graph by 
clicking on the corresponding menu item. 
This kind of interface is very flexible. In particular, if a new 
AGD version is installed on the system the client automatically 
updates the list of algorithms and the corresponding menu of the 
editor.

To install agd_server for GraphWin simply copy the agd_server to 
a directory in your command search path or set the environment 
variable AGD_SERVER to the complete path name of the server. 


3. The Command Line:
--------------------

The command line

	agd_server list [optfile] 

writes the list of AGD algorithms available in the agd_server 
and their default options in GML format to file optfile or the 
standard output stream (if optfile is missing). 

The command line to draw a graph using the agd_server has the 
following form.

	agd_server alg gfile optfile iform oform 

It reads a graph in format "iform" from file "gfile", applies 
algorithm "alg" to it using the options from file "optfile", 
and writes the result in format "oform" back to gfile. There 
are two possible file formats for iform and oform: "gw" for the 
GraphWin file format (see Section 6) and "gml" for the GML format 
(see Section 7). A default options file can be created by calling 
"agd_server list optfile" (see above) and edited as needed (see 
Section 5). 

Example: Let "graph.gw" contain the graph we want to draw using 
the agd_server in GraphWin file format. Suppose we want to use 
the Sugiyama algorithm with the options in the standard options 
file optfile. Then the corresponding command line looks as 
follows.

	agd_server Sugiyama graph.gw optfile gw gw

If everything worked correctly the file "graph.gw" contains the 
resulting layout of our input graph. If an error occured a 
diagnostic message is written to the file "graph.gw" .


4. Algorithms:
--------------

Currently the following algorithms are available in the 
AGD Server and can be used as parameter "alg".

"de Fraysseix et al."
Schnyder
Convex
ConvexDraw
PlanarStraight
PlanarDraw
Mixed-Model
PureOrthogonal
QuasiOrthogonalLayout
OrthogonalLayout
TreeLayout
Sugiyama
Planarization
"Spring Embedder"
Tutte
"Visibility Representation"

To use the algorithm "de Fraysseix et al." on the graph graph.gml 
in GML Format with the options file "optfile" write:

	agd_server "de Fraysseix et al." graph.gml optfile gml gml


5. The Options File:
--------------------

The command

	agd_server list optfile

generates an initial options file optfile. The contents of this 
file (for the current version of agd_server) can be found in the 
AGD manual. The file is in GML format.

An input in GML format is a list of GML objects. Each object 
consists of a key word and a value. A value may have one out of 
four possible types, an integer, a double, a string, or a list 
of GML objects. Since a value can be a list of objects, we get a 
tree structure on the input. Lists of GML objects start with 
[ and end with ]. 

The options file for the AGD server consists of four GML objects:
* Creator with string value "AGD_SERVER"
* Version with double value 1.4
* AGD_function_list with a list of available algorithms 
      (cf. Section 4)
* AGD_option_list with a list of available options for each 
       algorithm and the corresponding standard values

A detailed description of the various options of the algorithms 
can be found in the corresponding AGD manual page. To change an 
option for a layout algorithm do the following:
i)   Find the algorithm in AGD_option_list
ii)  Find the option you want to modify
iii) Change the option to the desired value with an ordinary text 
     editor.

Example: Suppose you want to use the Sugiyama algorithm with DFS 
ranking, Greedy Insert, node_distance 5.0, and level distance 7.0. 
The corresponding part of the standard options file looks as 
follows:

...
function "Sugiyama" [
                         ranking [
                                 ranking_wahl 0
                                 ranking_lst [
                                         lst "Hierarchical"
                                         lst "DFS"
                                 ]
                         ]
                         heuristic [
                                 heuristic_wahl 0
                                 heuristic_lst [
                                         lst "Split"
                                         lst "Barycenter"
                                         lst "Median"
                                         lst "Greedy Insert"
                                         lst "Greedy Switch"
                                 ]
                         ]
                         fixed_level_distance "false"
                         node_distance 3.00000
                         level_distance 3.00000
                         work_infos "false"
                         infos [
                                 name: "Sugiyama"
                                 author: "K. Sugiyama, S. Tagawa, M. Toda"
                                 Implementation: "C. Gutwenger, M. Krger"
                                 date: "March 1998"
                                 version: "2.0"
                         ]
                 ]
...

To use your parameters you simply change that part to:

function "Sugiyama" [
                         ranking [
                                 ranking_wahl 1
                                 ranking_lst [
                                         lst "Hierarchical"
                                         lst "DFS"
                                 ]
                         ]
                         heuristic [
                                 heuristic_wahl 3
                                 heuristic_lst [
                                         lst "Split"
                                         lst "Barycenter"
                                         lst "Median"
                                         lst "Greedy Insert"
                                         lst "Greedy Switch"
                                 ]
                         ]
                         fixed_level_distance "false"
                         node_distance 5.00000
                         level_distance 7.00000
                         work_infos "false"
                         infos [
                                 name: "Sugiyama"
                                 author: "K. Sugiyama, S. Tagawa, M. Toda"
                                 Implementation: "C. Gutwenger, M. Krger"
                                 date: "March 1998"
                                 version: "2.0"
                         ]
                 ]



