diff --git a/doc/Design_notes/index.html b/doc/Design_notes/index.html
index 9dc59956e938c55ea5663295c88ff7735c62474e..eaf36a3bd31751b8a217da7f21d2593ee6a41936 100644
--- a/doc/Design_notes/index.html
+++ b/doc/Design_notes/index.html
@@ -4,21 +4,43 @@
<br />
<fieldset>
-<legend>Page Under Construction</legend>
-</fieldset>
+<legend>Pages Under Construction</legend>
<p>The documentation pages are being re-organised and updated. </p>
<p>Some old files are held in ZMap/web and will be moved into ZMap/doc on a gradual basis. The ZMap/Web directory will be maintained during this process as some build scripts depend on it and as the files are in the CVS it provides a backup. Some other files that have been deleted from ZMap/doc have been move to ZMap/doc/old on ~mh17 until they get transferred to the new directory tree.
</p>
<p>As files get added or copied or converted they will hopefully get added to this index page, which is intended to be in alpha order. As the number of files increase then we'll add some nice <div>s to put them in pretty columns.
</p>
-<fieldset>
+</fieldset>
-<legend>Index</legend>
+<fieldset><legend>Index</legend>
<a href="Design_notes/misc/about.shtml">About these pages</a><br />
<br />
<a href="Design_notes/modules/zmapConfig.shtml">Configuration files</a><br />
Coordinate systems<br />
+<a href="Design_notes/modules/zmapFeature.shtml">Featuresets</a><br />
+<a href="Design_notes/notes/performance.shtml">Performance</a><br />
<a href="Design_notes/modules/pipeServer.shtml">pipeServer Configuration</a><br />
+<a href="Design_notes/modules/zmapView.shtml">All about Views</a><br />
WindowCanvasItems<br />
</fieldset>
+
+<fieldset><legend>Thought for food</legend>
+<h3>Some things that need investigating and writing up.</h3>
+<p>X-Remote appears to talk to zmapControl, zmapView, and zmapWindow, so far. Who is in control?</p>
+</fieldset>
+
+<fieldset><legend>Unfinished Buisness</legend>
+<p>
+<ul>
+<li>normal thread shutdown needs to be written up and debugged <i>as not previously implemented</i>. View connection data needs to be cleared up.
+<li>pipeServer not to be asked for featuresets or styles to avoid log message
+<li>zmapView.c/processDataRequests() needs to merge the source_2_featureset not just assign it
+<li>delayed server needs to free view_con->context etc etc (memory leak)
+<li>implement X-Remote progress message
+<li>pipe server GFF gives 'cant find style log messages seqRequest() line 1072
+<li>sequence server is assumed to be ACEDB or some other server that is not delayed
+</ul>
+</p>
+
+</fieldset>
diff --git a/doc/Design_notes/misc/about.html b/doc/Design_notes/misc/about.html
index 509a5d7c64b0391728b1fe5f7fd542b58a309c4a..d4889bc7cf3595a8aafbb5dae25b7328cd23897f 100644
--- a/doc/Design_notes/misc/about.html
+++ b/doc/Design_notes/misc/about.html
@@ -1,4 +1,4 @@
-<!-- $Id: about.html,v 1.4 2010-03-09 09:44:02 mh17 Exp $ -->
+<!-- $Id: about.html,v 1.5 2010-03-19 16:26:47 mh17 Exp $ -->
<h2>ZMap Design Documentation</h2>
<br />
@@ -6,8 +6,9 @@
<fieldset>
<legend>Introduction</legend>
-<p>ZMap is a mature program and contains some duplicated and old versions of code. The main aim here is to document how it is supposed to work so that it is clear whether or not any section of code is correct, and to allow developers to learn the code more quickly.</p>
-<p>This is an attempt to collate previous notes about the design of ZMap and create more complete documentation of how Zmap works. It is organised as follows:</p>
+<p>This is an attempt to collate previous notes about the design of ZMap and create more complete documentation of how Zmap works.
+There may also be some historical notes and more recent design notes added as they are written.
+It is organised as follows:</p>
<ul>
<li><p>An index page (this file) will provide links to the rest</p>
diff --git a/doc/Design_notes/modules/zmapConfig.html b/doc/Design_notes/modules/zmapConfig.html
index 1773cdc1237dd345f869b880ff6cb8f82e9d1cd3..a80c7ed869e8948fc1facc9a401f7e5601d2da14 100644
--- a/doc/Design_notes/modules/zmapConfig.html
+++ b/doc/Design_notes/modules/zmapConfig.html
@@ -1,4 +1,4 @@
-<!-- $Id: zmapConfig.html,v 1.4 2010-03-10 14:08:25 mh17 Exp $ -->
+<!-- $Id: zmapConfig.html,v 1.5 2010-03-19 16:26:47 mh17 Exp $ -->
<h2> zmapConfig - configuration file handler </h2>
<fieldset> <legend>Summary</legend>
<p>This page refers to the zmapConfig directory as of 09 Dec 2009.</p>
@@ -34,7 +34,7 @@ There are modules in the code that edit a memory copy of config data. Although
</fieldset>
<fieldset><legend>Stanzas and Keys</legend>
<p>
-Here it is assumed that the reader is familiar with the <a href="Design_notes/notes/style_config.shtml">existing scheme</a> and some modifications have been perpetrated:
+Here it is assumed that the reader is familiar with the <a href="user_doc/configuration.shtml">existing scheme</a> and some modifications have been perpetrated:
</p>
<p>
In the [source] type stanzas options are available to define featuresets and styles. Coincidentally at present these are identical and style names could be defaulted to be the same as the featureset name - this makes sense as when a source provides featuresets data it would be expected to supply styles as part of this. ACEDB for example can suppy styles and link these to featuresets, other sources not neccessarily so.
@@ -43,7 +43,7 @@ In the [source] type stanzas options are available to define featuresets and sty
Styles may be defined in a config file which can be specified in the <b>[ZMap]</b> stanza with the key <b>styles-file=filename</b>, and only one will be allowed.
Individual source stanzas will not have a styles-file key.</p>
<p>
-Styles may be defined in a source stanza as before - it is inteneded that DAS servers will be able to request styles in future - but sources are not required to process this. ACEDB servers have styles defined by thier featuresets and do not use styles config. File and Pipe servers do not use styles config as they assume that featuresets are displayed using a style of the same name, however they will honour the list of styles if given.</p>
+Styles may be defined in a source stanza as before - it is intended that DAS servers will be able to request styles in future - but sources are not required to process this. ACEDB servers have styles defined by thier featuresets and do not use styles config. File and Pipe servers do not use styles config as they assume that featuresets are displayed using a style of the same name, however they will honour the list of styles if given.</p>
<p>
Options to specify ambiguous stanzas have been removed eg [sources], [source] etc.
diff --git a/doc/Design_notes/modules/zmapConfig.rel b/doc/Design_notes/modules/zmapConfig.rel
index 80095d74a077d6d332cc2acf08ea5f7e438a84f8..9858a818ed0f53c7f5f81938e7d2370c506d89ae 100644
--- a/doc/Design_notes/modules/zmapConfig.rel
+++ b/doc/Design_notes/modules/zmapConfig.rel
@@ -1,2 +1 @@
,Related,
-user_doc/styles,Styles user doc,
\ No newline at end of file
diff --git a/doc/Design_notes/modules/zmapFeature.html b/doc/Design_notes/modules/zmapFeature.html
index eb1446fa010afa0110109589924f86772a168cb4..b8471f4b502084bac5e0a233f3b00ec23b219e19 100644
--- a/doc/Design_notes/modules/zmapFeature.html
+++ b/doc/Design_notes/modules/zmapFeature.html
@@ -1,4 +1,88 @@
<h2> zmapFeature - Feature Context - the model part of MVC </h2>
-<fieldset> <legend>Summary</legend>
-Forthcoming...
+<fieldset> <legend>Index</legend>
+
+<a href="Design_notes/modules.zmapFeature.shtml#terminology">Terminology</a>
+<a href="Design_notes/modules.zmapFeature.shtml#mapping">Mapping to columns and styles</a>
+<a href="Design_notes/modules.zmapFeature.shtml#identity">Identifying</a>
</fieldset>
+
+<a name=terminology></a>
+<fieldset><legend>Terminology</legend>
+<p><b>Features</b> are organised in <b>columns</b> on the ZMap display, a group of these is known as a <b>featureset</b>.</p>
+<p>
+However it gets a little more complicated than that: in <b>include/Zmap/zmapServerProtocol.h</b> we find that a <b>feature source</b> is the name of a feature as it is known in a far-away database. Several of these can be placed in a single <b>featureset</b>.
+</p>
+<p>
+A <b>feature source</b> is not where a feature is retrieved from but the name of it. Various parts of ZMap also refer to a <b>source</b> in a zmapServer context in which case <b>source</b> refers to the name of the server as defined in a ZMap config file stanza or the zmapServer module itself. A server module can supply a mapping that specifies which <b>featureset</b> a <b>feature source</b> is to be placed in.
+</p>
+<p>Many of these words can get used interchangably.</p>
+<h4>Example</h4>
+EST_human is a <b>column</b> that contains the <b>feature sources</b> EST_human and Saturated_EST_Human, all three of which are know as <b>featursets</b>. <b>column</b> is unambiguous.
+
+</fieldset>
+
+<a name=mapping></a>
+<fieldset><legend>Mapping features (data sources) to featureset (display columns) and feature style</legend>
+<h3>Source to feature set</h3>
+<p>Traditionally, ACEDB provided this mapping during ZMap startup, but without an ACEDB connection we have no way of recieving this data.</p>
+<p>By default, any feature requested from a pipe or other server that does not support the REQ_FEATURESETS request will be mapped to
+a column of the same name - this will produce a wider than normal display, but the data will at least be visible.</p>
+<p>
+A new config stanza [featuresets] will be provided in ZMap to override this default mapping and will contain lines of the form:
+<pre>
+column = source1; source2; ... sourceN
+</pre>
+where 'column' is the name of the column that is used to display all the sources and sourceX is the name of a featureset used to request the data as receieved from Otterlace and as sent the a pipeServer or other.
+</p>
+<p><b>NB:</b> This stanza will only be read in when creating a view and not on requesting a column. To change this mapping it is necessary to update the file ZMap (config) and then create a new ZMap window.</p>
+
+<h3>Mapping Features to Styles</h3>
+<p>Traditionally ACEDB could map a feature to a style, but for a pipeServer that cannot do this (as GFF does not support this) the obvious solution is to have a 1-1 mapping of featuresets to styles of the same name. As styles can be inherited, if it is required to have two featuresets displayed using the same style then they can both inherit the same base style unmodified.
+</p>
+<h3>Merging data from different sources</h3>
+<p>Previous ACEDB functionality will remain honoured. If we end up with conflicting data being defined by different sources then the first defined data will have priority regardless of the source. This is in line with existing merge operations.
+Note that this implies that feature attributes can only be added to or changed but not removed (eg by taking out a background colour).
+</p>
+</fieldset>
+
+<a name=identity></a>
+<fieldset><legend>Identifying a featureset</legend>
+A featureset has a original_id and a unique_id (see zmapFeature.h) - the original_id is as given in a config file or from a database and is regarded as case insensitive. This is stored as as a GQuark and is translated into an internal_id which is in lower case, and for some features also includes extra information as necessary.</p>
+<p> There are functions (eg <b>zMapFeatureSetCreateID()</b> - simple lower casing) that do this. <i>(Need some more notes here).</i>
+
+<p>A zmapView has some data structures that map feature set sources to display columns and styles:
+<pre>
+ GHashTable *featureset_2_stylelist ; /* Mapping of each feature_set to all the styles it requires. */
+ GHashTable *source_2_featureset ; /* Mapping of a feature source to a featureset. */
+ GHashTable *source_2_sourcedata ; /* Mapping of a feature source to its data. */
+</pre>
+These are hash tables that map a featureset unique_id to another data structure.</p>
+<p>According to zmapViewRemoteReceive.c/xml_featureset_start_cb() <b>zmapView->source_2_featureset</b> is a hash table of <b>ZMapGFFSet</b> and <b>zmapView->source_2_sourcedata</b> is a hash table of <b>ZMapGFFSource</b>. We presume that the id fields relate to unique_id rather than original_id (styles have both, as for featuresets).</p>
+<pre>
+/* Struct for "feature set" information. Used to look up "meta" information for each feature set. */
+typedef struct
+{
+ GQuark feature_set_id ; /* The set name. */
+ char *description ; /* Description. */
+} ZMapGFFSetStruct, *ZMapGFFSet ;
+
+
+/* Struct holding "per source" information for GFF data. Can be used to look up the
+ * style for a GFF feature plus other stuff. */
+typedef struct
+{
+ GQuark source_id ; /* The source name. */
+ GQuark source_text ; /* Description. */
+ GQuark style_id ; /* The style for processing the source. */
+} ZMapGFFSourceStruct, *ZMapGFFSource ;
+</pre>
+<p><b>zmapView->featureset_2_stylelist</b> is more obscure: zmapView.c/addPrefined() sets zmapView->orig_styles as a <b>GData</b> (keyed data list), and then <b>zmapView->featureset_2_stylelist</b> as a <b>GHashTable</b> of <b>GLists</b> of <b>style quark id's</b>. (see zmapView.c/styleCB() and zmapGlibUtils.c/zMap_g_hashlist_insert());
+</p>
+<p>This last thing looks confusing: it looks like the style is is keyed off the style id rather than the featureset id; (it may be that the style names are identical to the featureset names in this case??). Identical code appears in zmapView.c/processDataRequests() to add in a 1-1 mapping from a (pipe) server that does not support this mapping.
+<b>zmapServer/acedb/acedbServer.c/parseMethodStyleNames()</b> set up a similar list with different featureset and style names.
+</p>
+<p>Some related information from <b>zmapGFF2Parser.c</b>: "NOTE the feature sets style has the same name as the feature set" - this relates to featureset expressed as a display column.</p>
+<p><b>NOTE:</b>In <b>zmapFeatureContext.c/zMapFeatureString2QuarkList()</b> the function <b>zMapStyleCreateID()</b> is used to get a feature ID, or so it seems... This function is used to make a list of featureset names in <b>zmapViewConnect()</b>.
+</fieldset>
+
+
diff --git a/doc/Design_notes/modules/zmapServer.html b/doc/Design_notes/modules/zmapServer.html
index 04839144f558daa5e2f070f5284daf49c5251639..a1d46a0fdcae9bdbcfed1eb91c51955d8d0d2df6 100644
--- a/doc/Design_notes/modules/zmapServer.html
+++ b/doc/Design_notes/modules/zmapServer.html
@@ -1,4 +1,16 @@
<h2> zmapServer - thread based external interfaces </h2>
<fieldset> <legend>Summary</legend>
-Forthcoming...
+<h3>Modules</h3>
+<p>The zmapServer module exist to provide concurrent thread base interfaces to external databases. It uses the zmapThread module.
+</p>
+--- put this in a table and extend ---<br />
+zmapServer is the front end that is used by zmapView etc to request data.<br />
+zmapServerProtocolHandler interfaces between zmapServer and the thread base servers.<br />
+acedb/, DAS, and pipe/ are the servers that run in these threads.
+<br />
+<br />
+
+<h3>Related pages</h3>
+<p><a href="Design_notes/modules/zmapView.shtml#reqdata">zmapView</a> contains some notes about requesting data from pipeServer modules and other issues.</p>
+<p><a href="Design_notes/modules/pipeServer.shtml">pipeServer</a> details usage of that module.</p>
</fieldset>
diff --git a/doc/Design_notes/modules/zmapView.html b/doc/Design_notes/modules/zmapView.html
index 73cb8637eed3429e55b0270b1a3e732335e27202..0467d4a7273afa1111429df960a5cf4bb5dfa15c 100644
--- a/doc/Design_notes/modules/zmapView.html
+++ b/doc/Design_notes/modules/zmapView.html
@@ -1,4 +1,4 @@
-<!-- $Id: zmapView.html,v 1.2 2010-03-10 12:22:09 mh17 Exp $ -->
+<!-- $Id: zmapView.html,v 1.3 2010-03-19 16:26:47 mh17 Exp $ -->
<h2> zmapView - a mixture of V and C from MVC </h2>
<fieldset> <legend>Summary</legend>
<p>zmapView is quite a large module! When adding a topic to this file please include a link here.</p>
@@ -12,24 +12,56 @@
<a name="reqdata"></a>
<fieldset><legend>Requesting data from database sources</legend>
<p>Historically, when ZMap creates a view it goes through a process of 'data loading' during which it requests all the data implied in its source stanzas. This has typically been ACEDB and this connection is maintained open for the life of the view to allow further requests by the user. Till this initial phase has completed the user may not interact with the view. With the advent of pipeServaers this model is no longer enough to cope with incremental/ optimised loading of data and we need to be able to specify sources as not active on startup, and to be able to start previously unknown sources on request from Otterlace.</p>
+
<h3>Configuring data sources</h3>
-<p>A source stanza in ZMap's configuration file ZMap specifies the URL of the data source and some other options including featuresets supported. A new option <b>delayed=true/false</b> will set whether or not a data source will be activated automatically on startup. A pipeServer source will default to delayed=true and other types false.</p>
-<p>Any request for data after the initial 'data loading' phase will be activated immediately regardles of the setting of 'delayed'.</p>
+<p>A source stanza in ZMap's configuration file ZMap specifies the URL of the data source and some other options including featuresets supported. A new option <b>delayed=true/false</b> will set whether or not a data source will be activated automatically on startup. A pipeServer source will default to delayed=true and other types false.<br />
+<b>NOTE</b>: this proves to be quite fiddly. In the short term (to allow testing of the real code) we will require delayed=true to be set where needed. It may be easier to specify active and delayed sources in [ZMap].
+</p>
+<p>Any request for data after the initial 'data loading' phase will be activated immediately regardless of the setting of 'delayed'.</p>
+<p>Feature columns may be populated by data from several featuresets and this mapping was originally specified by ACEDB. A new stanza [featuresets] is provided to allow this to be defined statically in the main <a href="Design_notes/modules/zmapConfig.shtml">ZMap configuration file</a> (NB: fix this link, it should point to the config user guide)</p>
+
+<h3>Requesting data at startup</h3>
+<p>An initial request for data must be configured as ZMap will not run without data, and this will prevent the situation where we have a blank window and no user control. It also provides an opportunity to add in predfined data - this can probably be tidied up with little mishap, such that predefined styles etc are added automatically and no initial data requests are required. However, it may be necessary to include all the navigator featuresets in the initial load.</p>
+<p>On startup the config file will be scanned and the list of data servers extracted. Those that are not configued as 'delayed' will be connected to and all featuresets they support requested. As at present if they support many featuresets then all will be requested together; if it is desired that these servers supply each feature set concurrently then seperate source stanzas must be defined for each one. (This should not be important as we expect minimal amount of data to be requested in this way, and the primary mechanism will be via X-Remote commands.</p>
+
<h3> Requesting data after startup</h3>
-</p>This can be done via a variety of interfaces, for example the Columns dialog, a Right Click menu or X-Remote commands. The View has a list of connections to data sources (corresponding to the source stanzas) that are kept active.
+<p>This can only occur after the initial 'data loading' phase. If triggered by a 'load column' request from the user this must be so as they do not have keyboard control till then. However, if commands are recevied on X-Remote during the initial load phase then this may simply take longer - extra featuresets will be subsumed into the initial set of requests.
+</p>
+</p>Requests can be triggered via a variety of interfaces, for example the Columns dialog, a Right Click menu or X-Remote commands. The View has a list of connections to data sources (corresponding to the source stanzas) that are kept active.
Currently the functions that process requests use the first connnection in the list, which has traditionally been ACEDB and the data request is typically the name of a featureset</p>
<p>The existing X-Remote protocol is suffcient for our purposes and will be used unchanged, this means that data will be requested by featureset name; a sample data request looks like this:
<pre>
-(coming RSN)
+<zmap>
+ <request action=\"load_features\">
+ <align>
+ <block>
+ <featureset name=\"EST_Human\">
+ </featureset>
+ <featureset name=\"Saturated_EST_Human\">
+ </featureset>
+ </block>
+ </align>
+ </request>
+</zmap>
</pre>
+<b>NOTE</b> Please refer to web/user_doc/xremote.orig/xremote_overview.shtml for all XML protocol stuff.
+Ed's working on this and then it needs to be moved to doc/user_doc
+
</p>
<p>On receipt of a request ZMap will re-read its config file and scan the list of source stanzas for the requested featuresets - this will define the data sources to request the data from (each source stanza defines the supported featuresets). A new connection will be started for each request to allow multiple requests to be processed by servers without imposing delays implied by queuing.
+Existing connections (ie non-delayed) may be used if not currently active.
+</p>
+
+<h3>Some loose ends</h3>
+<p>Styles are defined in a (large) file and it may be beneficial for Otterlace to be able to specify whether or not to re-read this file, or for indiviudual sources to have thier own styles files, or to be able to request a styles refresh without re-requesting data.</p>
+<p>The pipeServer interface has a requirement to supply styles despite these not being handled by GFF (due to legacy issues). It would be good to remove this requirement at some point - styles can be defined at startup and there is little sense in merging one set of styles with an identical one. However thease can be changed at runtime so it's not so clear cut. The GFF parser requires styles so to fix this would required a deeper mod than might first appear necessary.
</p>
+
<h3>The request process</h3>
-<p>A View has a set of data structures that implement a StepList (see <b>zmapView_P.h</b>), which allows a sequence or actions to be created and operated in turn, and also to specify actions to take in case of error. Currently (10 Mar 2010) the View has one of these lists and this is used to control the list of data servers together. To handle concurrent requests from different servers this will be changed to be a list of Step Lists, each operating independantly. </p>
-<p>The request process is modelled on the ACEDB interface, consisting of a number of steps defined as <b>ZMapServerReqType</b> in <b>include/ZMap/zmapServerProtocol.h</b>. Old code used the first connection in the view's list and assumes that this is already active and for request to pipeSevers this is not correct - the connection must be started fresh each time and closed when finished.
+<p>A View has a set of data structures that implement a StepList (see <b>zmapView_P.h</b>), which allows a sequence of actions to be created and operated in turn, and also to specify actions to take in case of error. Currently (10 Mar 2010) the View has one of these lists and this is used to control the list of data servers together. To handle concurrent requests from different servers this will be changed to be a list of Step Lists, each operating independantly. </p>
+<p>The request process is modelled on the ACEDB interface, consisting of a number of steps defined as <b>ZMapServerReqType</b> in <b>include/ZMap/zmapServerProtocol.h</b>. Old code used the first connection in the view's list and assumes that this is already active and for requests to pipeSevers this is not correct - the connection must be started fresh each time and closed when finished.
</p>
-<p>Code that handles this is found in <b>zmapView.c/zmapViewLoadFeatures()</b>, <b>zmapViewUtils.c/loadFeatures()</b>, and <b>zmapView.c/commandCB()</b> (to request a DNA sequence). The latter uses View->sequenece_server to fidn the right connection.
+<p>Code that handles this is found in <b>zmapView.c/zmapViewLoadFeatures()</b>, <b>zmapViewUtils.c/loadFeatures()</b>, and <b>zmapView.c/commandCB()</b> (to request a DNA sequence). The latter uses View->sequenece_server to find the right connection.
</p>
<p>The function <b>zmapView.c/zmapViewConnect()</b> is used for the initial 'data loadng' phase on startup and uses similar code.
</p>
@@ -38,21 +70,31 @@ Currently the functions that process requests use the first connnection in the l
<p> This will involve the following steps, (any legacy code left over by mistake can be removed)
<ul>
<li>implement delayed servers - not processed on startup
- <li>implement multiple step lists and restrict each step list to one connection
- <li>add create open and close steps to runtime requests
+ <li>implement multiple step lists and restrict each step list to one connection, clear up on completion.
<li>parse the ZMap file before each request and link featuresets to servers (this will allow config changes during runtime);
+ <li>add create open and close steps to runtime requests
<li>A callback will be added to the X-Remote protocol to report on the progress of requests
+ <li>Remove [server] sequence_server config, and trigger this with the DNA featureset.
</ul>
</p>
-<p>Note that a separate request will be allocated for each featureset, even if several are included in the same external request and as supported by the same data server. This is to allow maximum concurrency in the hope that data will be loaded faster. For example EST_human and Saturated_EST_Human need to be requested together and form a logical category together. This will also apply to ACEDB requests if more than one request is active.
+<p>Note that a separate request will be allocated for each featureset, even if several are included in the same external request and as supported by the same data server. This is to allow maximum concurrency in the hope that data will be loaded faster. For example EST_human and Saturated_EST_Human typically get requested together and form a logical category together. This will also apply to ACEDB requests if more than one request is active.</p>
+
+<h4>View step_list and connection_list: a strategy</h4>
+<p>The view has a list of active connections, originally none of these ever died. There is also a step list that refers to lists of connections. The connection_list will be modified so that each connection has its own step list, and the step list will no longer have a list of connections. The step list structures will not refer to thier connection - the code is only called from a few places and the view/ connection is available at all of them.</p>
+<p>The step list poll function (<b>zmapView.c/checkStateConnections()</b> will poll the entire connection list and inspect the step list for each. As the step list has a 'current' pointer this will be efficient, and servers that complete and are terminated can be removed from the connnection list.
+</p>
+<h4>View State and Busy Cursor</h4>
+<p>On the initial load the View will be set as 'data loading' and a busy cursor displayed until all loading has completed.
+</p>
+<p>Loading data after startup set the View to 'columns loading' and a busy cursor displayed until all requested columns have completed. It may be possible to delay the busy cursor till the first requested column is ready for display, but intitially we will not implement this as it may allow for race conditions to occur due to user activity. The view state 'columns loading' will revert to 'data loaded' on completion.
</p>
<h3>Data Compression</h3>
-Initially plain GFF format (version 2, replaced by version 3) will be used, but to reduce network bandwidth this may be GZipped - these should compress very well. It may be advantagous to GZip the data in smaller chunks, which will require less memory (important if we load 100 featuresets at once).
+<p>Initially plain GFF format (version 2, replaced by version 3) will be used, but to reduce network bandwidth this may be GZipped - these should compress very well. It may be advantagous to GZip the data in smaller chunks, which will require less memory (important if we load 100 featuresets at once).</p>
<h3>Progress reports</h3>
<p>Currently Otterlace shows a progress bar for data loading and to retain this while usihng pipeServers X-Remote messages will be added to drive this. Initially this will consist of reporting 'completed', but if GZip chunks are implemented this can be broken down somewhat.
The X-remote message format will be like:
<pre>
-hello
+hello: ref to x-remote doc mentioned above
</pre>
</p>
</fieldset>
diff --git a/doc/scripts/build b/doc/scripts/build
index 6578d7d275ed061944982fb75c133bd426566dae..8a3ab1ae79002f0025fc400d316c0c65ab03eedd 100755
--- a/doc/scripts/build
+++ b/doc/scripts/build
@@ -13,6 +13,7 @@ cd ../notes
docgen *.html
cd ../build
docgen *.html
-
+cd ../../user_doc
+docgen *.html
echo "need to update this for other directories eg foocanvas"
diff --git a/doc/scripts/docgen b/doc/scripts/docgen
index 9c39603059e6eeb164fda538e1a8502cd47e6480..9ee20c45a926b1d6c29f232db23cb1d0f01c2b7d 100755
--- a/doc/scripts/docgen
+++ b/doc/scripts/docgen
@@ -1,5 +1,5 @@
#!/usr/bin/perl
-# <!-- $Id: docgen,v 1.4 2010-03-10 12:21:38 mh17 Exp $ -->
+# <!-- $Id: docgen,v 1.5 2010-03-19 16:26:47 mh17 Exp $ -->
# generate a *.shtml file to STDOUT from headerless *.html
# css is in ZMap/doc/css/dev_server.css
# menu data is in ZMap/doc/<design>/scripts/ plus also the current dir (file.rel)
@@ -10,6 +10,24 @@ use Cwd;
my ($dir, $doc, $mydir, $css,$base);
my ($froot,$file);
+my $gotbase = 0;
+
+# read ~/.docgen.ini
+sub get_ini
+{
+ open(INI,"$ENV{HOME}/.docgen.ini") or return;
+ while($_ = <INI>)
+ {
+ chomp($_);
+ ($opt,$val) = split("=",$_);
+ if($opt eq "base")
+ {
+ $base = $val;
+ $base =~ s/~/$ENV{HOME}/;
+ $gotbase = 1;
+ }
+ }
+}
# create a menu box of related items
# syntax is file,name,prefix
@@ -113,10 +131,10 @@ sub gen_file
# generate a navbar div using a global as list of links and then adding on local ones
print OFILE "<div class=\"left\">\n";
- menudiv ($base . "/scripts/navbar.rel"); # the global menu in the doc/scripts directory
+ menudiv ($base . "scripts/navbar.rel"); # the global menu in the doc/scripts directory
menudiv ($froot . ".rel"); # menu related to this file in this directory
- print OFILE "</div>\n<div style=\"margin-right:5em;margin-left:10em;\">";
+ print OFILE "</div>\n<div style=\"margin-right:5em;margin-left:11em;\">\n";
while($_ = <IFILE>) # include our html source
{
@@ -129,12 +147,17 @@ sub gen_file
}
# here it is:
+get_ini();
for($i = $#ARGV;$i >= 0;$i--)
{
+ my $relbase;
($froot,$file) = get_file(shift @ARGV);
- ($dir,$doc,$mydir,$css,$base) = get_dirs();
-
+ ($dir,$doc,$mydir,$css,$relbase) = get_dirs();
+ if(!$gotbase)
+ {
+ $base = $relbase;
+ }
open(IFILE,$file) or die("Can't open $file\n");
$ofile = $froot. '.shtml';
open(OFILE,"> ". $ofile) or die("cannot open $ofile\n");
diff --git a/doc/scripts/navbar.rel b/doc/scripts/navbar.rel
index 9fb37e804b5d59bc7d54aaa773dc4190f64ff138..4810641e26c62db0526d5818559376d18e932605 100644
--- a/doc/scripts/navbar.rel
+++ b/doc/scripts/navbar.rel
@@ -25,7 +25,9 @@ zmapXML,,
,Build,Design_notes/build/
fix_copyright,CopyRight,
,External,
-foocanvas/foocanvas,Foo Canvas,
-g2/g2,G2,
+../foocanvas/foocanvas,Foo Canvas,
+../foocanvas/foocanvas_build,Foo Build,
+../g2/g2,G2,
,User Doc,user_doc/
styles,Styles,
+configuration,Config,
diff --git a/doc/user_doc/configuration.html b/doc/user_doc/configuration.html
index ce6acde16251f3856b31f4a835a4b4565b54e706..42030b4e7fd1bfc7228d0c5253ae6a86cb8eefdb 100644
--- a/doc/user_doc/configuration.html
+++ b/doc/user_doc/configuration.html
@@ -2,7 +2,7 @@
<!--#include virtual="/perl/header"-->
<!--#set var="author" value="edgrif@sanger.ac.uk" -->
-<!-- $Id: configuration.html,v 1.1 2010-03-19 11:07:35 mh17 Exp $ -->
+<!-- $Id: configuration.html,v 1.2 2010-03-19 16:26:47 mh17 Exp $ -->
<style>
pre{ width: 95%; background-color: #DDDDDD; border-style: solid; border-width: 1px; padding: 10px }
.example{ border-color: #000000 }
@@ -86,9 +86,11 @@ list = one ; two ; three ; four # multiple strings
<i>etc.</i>
</pre>
-
+<p>White space is not important.</p><p>
+Any text following (and including) a "#" is interpreted as a comment and ignored.</p><p>
+Some keywords are mandatory within a stanza and hence have no default value. If are not specified the stanza is ignored.</p>
<p>
-A longer annotated example can see seen <a href="config_file_examples.shtml">here</a>.
+A longer annotated example can see seen <a href="user_doc/config_file_examples.shtml">here</a>.
</p>
@@ -116,7 +118,7 @@ If the configuration directory does not exist then ZMap will not run.
<p>
By default the <code><b>ZMap</b></code> configuration file is searched for
in the configuration directory but an alternative file can be specified with
-the <a href="#commandline">--conf_file</a> option.
+the <a href="user_doc/configuration.html#commandline">--conf_file</a> option.
If this file does not exist ZMap will not run.
</p>
@@ -125,7 +127,7 @@ If this file does not exist ZMap will not run.
<p>This file should be located in the
configuration directory and named according to the value of the
-stylesfile option in the <a href="#stanzas">ZMap</a> stanza of
+stylesfile option in the <a href="user_doc/configuration.html#stanzas">ZMap</a> stanza of
the <code><b>ZMap</b></code> configuration file.</p>
</fieldset><br />
@@ -134,52 +136,28 @@ the <code><b>ZMap</b></code> configuration file.</p>
<fieldset>
<legend id="stanzas">ZMap Configuration File Stanzas</legend>
-
-<!-- Notes about connecting to doxygen generated html files.
-
-Our doxygen documentation generator creates html files from the C source
-header files which document the configuration information.
-
-The resulting html files are named in the following way:
-
-In the source file we have:
-
-/*! @addtogroup config_stanzas
- *
-etc....
-
-from this doxygen generates an html file called:
-
-group__config__stanzas.shtml
-
-I can't see a way to tell doxygen what name to call the file so it's just hard
-coded here.....
-
-These files are all in an "html" subdirectory at the same level as the directory
-containing these files.
-
--->
-
<p>
The following stanzas are supported by ZMap:
</p>
<ul>
- <li><b><a href="../html/group__config__stanzas.shtml#app">ZMap</a> -</b>
+ <li><b><a href="user_doc/configuration.shtml#app">ZMap</a> -</b>
main configuration stanza controlling the zmap application.
- <li><b><a href="../html/group__config__stanzas.shtml#view">View</a> -</b>
+ <li><b><a href="user_doc/configuration.shtml#view">View</a> -</b>
stanza(s) controlling display of a named set of features.
- <li><b><a href="../html/group__config__stanzas.shtml#source">Source</a> -</b>
+ <li><b><a href="user_doc/configuration.shtml#source">Source</a> -</b>
stanza(s) specifying data sources from which to load a feature view.
- <li><b><a href="../html/group__config__stanzas.shtml#style">Style</a> -</b>
+ <li><b><a href="user_doc/configuration.shtml#featuresets">Featuresets</a> -</b>
+ stanza(s) specifying how to map data sources into a feature column.
+ <li><b><a href="user_doc/configuration.shtml#style">Style</a> -</b>
stanza(s) specifying styles for displaying feature sets.
- <li><b><a href="../html/group__config__stanzas.shtml#window">Window</a> -</b>
+ <li><b><a href="user_doc/configuration.shtml#window">Window</a> -</b>
stanza controlling the ZMap feature display window.
- <li><b><a href="../html/group__config__stanzas.shtml#blixem">Blixem</a> -</b>
+ <li><b><a href="user_doc/configuration.shtml#blixem">Blixem</a> -</b>
stanza specifying parameters for running the blixem sequence viewer.
- <li><b><a href="../html/group__config__stanzas.shtml#logging">Logging</a> -</b>
+ <li><b><a href="user_doc/configuration.shtml#logging">Logging</a> -</b>
stanza controlling zmap logging facility.
- <li><b><a href="../html/group__config__stanzas.shtml#debug">Debug</a> -</b>
+ <li><b><a href="user_doc/configuration.shtml#debug">Debug</a> -</b>
stanza controlling zmap debugging output.
</ul>
@@ -187,12 +165,289 @@ The following stanzas are supported by ZMap:
<p>
ZMap will work with single or multiple data sources. If there is only one data source it can be named 'source' and will be used automatically. If there are multiple data sources each one must be named uniquely and listed in the sources key in the ZMap stanza.
<br />
-Styles should be defined a separate configuration file, referred to in the ZMap stanza wiht the 'stylesfile' key.
+Styles should be defined a separate configuration file, referred to in the ZMap stanza with the 'stylesfile' key.
</p>
</fieldset><br />
+<a name="app"></a>
+<fieldset><legend>ZMap Application Options</legend>
+These are options that control the fundamental way ZMap behaves.<p>
+</p><table border="1" cellpadding="3" cellspacing="3">
+<tbody><tr>
+<th>Stanza </th><th colspan="3" align="center>">"ZMap" </th></tr>
+<tr>
+<th>Keyword </th><th>Datatype </th><th>Default </th><th>Description </th></tr>
+<tr>
+<th>"show_mainwindow" </th><td>Boolean </td><td>true </td><td>If false
+then the intial main zmap window is not shown, this is useful when zmap
+is being controlled by another application and its not necessary for
+the user to directly open feature windows themselves. </td></tr>
+<tr>
+<th>"exit_timeout" </th><td>Int </td><td>5 </td><td>Time in seconds to
+wait for zmap to finish clearing up server connections before exiting.
+After this zmap will exit and some connections may not have been
+clearly terminated. </td></tr>
+<tr>
+<th>"default_sequence" </th><td>String </td><td>"" </td><td>if a particular sequence has its own unique configuration file, then the sequence name can be specified in the file. </td></tr>
+<tr>
+<th>"default_printer" </th><td>String </td><td>"" </td><td>Specify a printer which will be the default printer for screen shots from ZMap. </td></tr>
+<tr>
+<th>"script-dir" </th><td>String </td><td>"ZMap run-time directory" </td><td>Specify the directory where data retrieval scripts are stored by default. </td></tr>
+<tr>
+<th>"data-dir" </th><td>String </td><td>"ZMap run-time directory" </td><td>Specify the directory where GFF data files are stored by default. </td></tr>
+<tr>
+<th>"stylesfile" </th><td>string </td><td>"" </td><td>Styles specify
+how sets of features are displayed and processed. By default this
+information is fetched from the server for each feature set. As an
+alternative the styles can be specified in a file in $HOME/.ZMap. (see
+"style" stanza description) </td></tr>
+</tbody></table>
+</fieldset>
+
+<a name="logging"></a>
+<fieldset><legend>Logging Options</legend>
+ZMap writes messages to the logfile $HOME/.ZMap/zmap.log by default,
+but the log filepath and other parameters of logging can be specified
+in the "logging" stanza.<p>
+</p><table border="1" cellpadding="3" cellspacing="3">
+<tbody><tr>
+<th>Stanza </th><th colspan="3" align="center>">"logging" </th></tr>
+<tr>
+<th>Keyword </th><th>Datatype </th><th>Default </th><th>Description </th></tr>
+<tr>
+<th>"logging" </th><td>Boolean </td><td>true </td><td>Turn logging on or off. </td></tr>
+<tr>
+<th>"file" </th><td>Boolean </td><td>true </td><td>true: messages to logfile, false: messages to stdout or stderr. </td></tr>
+<tr>
+<th>"directory" </th><td>String </td><td>"$HOME/.ZMap" </td><td>Absolute or relative directory to hold logfiles (relative is relative to $HOME/.ZMap). </td></tr>
+<tr>
+<th>"filename" </th><td>String </td><td>"zmap.log" </td><td>Name of logfile, this is combined with "directory" to give the logfile path. </td></tr>
+</tbody></table>
+</fieldset>
+
+<a class="anchor" name="source"></a>
+<fieldset><legend>Data Source Options</legend>
+ZMap can obtain sequence data from files and servers of various kinds,
+source stanzas specify information about the source. Each source stanza
+should must have a unique name, and must be referenced in the 'sources'
+resource in the [ZMap] stanza.<p>
+Data sources are identified using urls in the following supported variants:</p><p>
+
+</p><pre> url = "<url_identifier>"</pre><p>
+</p><pre> where <url_identifier> should match ([] = optional)</pre><p>
+</p><pre> <protocol>://[[<username>:<password>@]<hostname>[:<port>]]/<location>#<format></pre><p>
+</p><pre> <protocol> may be one of acedb, file, pipe or http
+ <username> should be a username string
+ <password> should be a password string
+ <hostname> should be a hostname string
+ <port> should be a port number
+ <location> should identify the location on a particular server
+ <format> may be one of gff, das, das2 (default gff)</pre><p>
+</p><pre> examples</pre><p>
+</p><pre> <a href="file:///var/tmp/my_gff_file.gff#gff">file:///var/tmp/my_gff_file.gff#gff</a>
+ pipe:////software/anacode/bin/get_genes?dataset=human&name=1&analysis=ccds_gene&end=161655109...
+ <a href="http://das1.sanger.ac.uk:8080/das/h_sapiens#das">http://das1.sanger.ac.uk:8080/das/h_sapiens#das</a>
+ acedb://any:any:23100</pre><p>
+</p><pre> N.B. <location> might include a query string too. e.g.</pre><p>
+</p><pre> <a href="http://www.sanger.ac.uk/das/h_sapiens?chromosome=1#das">http://www.sanger.ac.uk/das/h_sapiens?chromosome=1#das</a>
+ Note that for file: and pipe: sources <a href="file:///file">file:///file</a> is a relative file name and <a href="file:////">file:////</a> is absolute.</pre><p>
+
+</p><table border="1" cellpadding="3" cellspacing="3">
+<tbody><tr>
+<th>Stanza </th><th colspan="3" align="center>">"source" </th></tr>
+<tr>
+<th>Keyword </th><th>Datatype </th><th>Default </th><th>Description </th></tr>
+<tr>
+<th>"url" </th><td>String </td><td>Mandatory </td><td>The url specifying where to find the source. </td></tr>
+<tr>
+<th>"featuresets" </th><td>String </td><td>"" </td><td>A list of
+feature sets to be retrieved from the source(s). The list also gives
+the order in which the feature sets will be displayed in the zmap
+window. If not specified, all available feature sets will be retrieved
+and they will be displayed in whichever order the list of available
+sets was returned by the server. </td></tr>
+<tr>
+<th>"navigatorsets" </th><td>String </td><td>"" </td><td>A list of feature sets to use in a navigator window. </td></tr>
+<tr>
+<th>"timeout" </th><td>Int </td><td>120 </td><td>Timeout in seconds to wait for a server to reply before aborting a request. </td></tr>
+<tr>
+<th>"version" </th><td>String </td><td>"" </td><td>The minimum version
+of the server supported, must be a standard version string in the form
+"version.release.update", e.g. "4.9.28". If the server is an earlier
+version than this the connection will not be made. </td></tr>
+<tr>
+<th>"use_acedb_methods" </th><td>Boolean </td><td>false </td><td><b>Only read for acedb databases.</b>
+If true, then zmap reads style information from Method class objects
+instead of the newer and more flexible ZMap_style classes. </td></tr>
+<tr>
+<th>"sequence" </th><td>Boolean </td><td>false </td><td>If true, this
+is the server that the sequence for the feature region should be
+fetched from, only one such server can be specified. </td></tr>
+<tr>
+<th>"writeback" </th><td>Boolean </td><td>false </td><td>If true, this
+is the server that user changes/annotations to features should be
+written back to. Only one such server can be specified. </td></tr>
+<tr>
+<th>"format" </th><td>string </td><td>"" </td><td>Defunct, use the "url" keyword/value to specify the format. </td></tr>
+<tr>
+<th>"styles" </th><td>string </td><td>"" </td><td>List of all styles to
+be retrieved from styles file. If not specified then all styles will be
+read if a file has been specified in the [ZMap] stanza, otherwise the
+source should provide the styles itself. By default a featureset will
+use a style of the same name.<p>
+</p></td></tr>
+</tbody></table>
+</fieldset>
+
+<a name="featuresets"></a>
+<fieldset><legend>Mapping data sources into display columns</legend>
+<p>Traditionally, ACEDB provided this mapping during ZMap startup, but without an ACEDB connection we have no way of recieving this data.</p>
+<p>By default, any feature requested from a pipe or other server that does not support the REQ_FEATURESETS request will be mapped to
+a column of the same name - this will produce a wider than normal display, but the data will at least be visible.</p>
+<p>
+The stanza [featuresets] may be used to override this default mapping and will contain lines of the form:
+<pre>
+column = source1; source2; ... sourceN
+</pre>
+where 'column' is the name of the column that is used to display all the sources and sourceX is the name of a featureset used to request the data as receieved from Otterlace and as sent by a pipeServer or other server.
+</p>
+<p><b>NB:</b> This stanza will only be read in when creating a view and not on requesting a column. To change this mapping it is necessary to update the file ZMap (config) and then create a new ZMap window.</p>
+</fieldset>
-
-<!--#include virtual="/perl/footer"-->
+<a name="style"></a>
+<fieldset><legend>Style Options</legend>
+<p>NB: this stanza appears in a separate config file specified in [ZMap] stylesfile=xxx. Available options are given <a href="user_doc/styles.shtml">here</a>.</p>
+</p>
+</fieldset>
+
+<a name="window"></a>
+<fieldset><legend>ZMap Feature Window Options</legend>
+The ZMap feature window is where sequence features are displayed,
+various aspects of it can be configured from colours to performance
+factors.<p>
+</p><table border="1" cellpadding="3" cellspacing="3">
+<tbody><tr>
+<th>Stanza </th><th colspan="3" align="center>">"ZMapWindow" </th></tr>
+<tr>
+<th>Keyword </th><th>Datatype </th><th>Default </th><th>Description </th></tr>
+<tr>
+<th>"canvas_maxsize" </th><td>Integer </td><td>30000 </td><td>Set the
+maximum vertical extent of the feature window. Setting a smaller size
+will result in faster display as less data gets mapped as you zoom in
+but will mean you have less data to scroll over. The default is to
+create close to the maximum window size possible, this is 32k for X
+Windows. </td></tr>
+<tr>
+<th>"canvas_maxbases" </th><td>Integer </td><td>0 </td><td>Set the vertical extent of the feature window using dna bases. Is just an alternative method of setting "canvas_maxsize". </td></tr>
+<tr>
+<th>"keep_empty_columns" </th><td>Boolean </td><td>false </td><td>Some
+requested feature sets may not contain any features, by default these
+will not be displayed. For multiple blocks/alignment display it may be
+clearer to get zmap to display empty "placeholder" columns for these
+sets so that columns in different blocks line up better. </td></tr>
+<tr>
+<th>"colour_root" </th><td>string </td><td>white" </td><td>Colour for window background, specified as in the "Type" stanza. </td></tr>
+<tr>
+<th>"colour_alignment" </th><td>string </td><td>"white" </td><td>Colour for each alignment background, specified as in the "Type" stanza. </td></tr>
+<tr>
+<th>"colour_block" </th><td>string </td><td>"white" </td><td>Colour for each block background, specified as in the "Type" stanza. </td></tr>
+<tr>
+<th>"colour_m_forward" </th><td>string </td><td>"white" </td><td>Colour for forward strand column group background in master alignment, specified as in the "Type" stanza. </td></tr>
+<tr>
+<th>"colour_m_reverse" </th><td>string </td><td>"white" </td><td>Colour for reverse strand column group background in master alignment, specified as in the "Type" stanza. </td></tr>
+<tr>
+<th>"colour_q_forward" </th><td>string </td><td>"light pink" </td><td>Colour for forward strand column group background in matched alignment, specified as in the "Type" stanza. </td></tr>
+<tr>
+<th>"colour_q_reverse" </th><td>string </td><td>"pink" </td><td>Colour for reverse strand column group background in matched alignment, specified as in the "Type" stanza. </td></tr>
+<tr>
+<th>"colour_m_forwardcol" </th><td>string </td><td>"white" </td><td>Colour for forward strand column background in master alignment, specified as in the "Type" stanza. </td></tr>
+<tr>
+<th>"colour_m_reversecol" </th><td>string </td><td>"white" </td><td>Colour for reverse strand column background in master alignment, specified as in the "Type" stanza. </td></tr>
+<tr>
+<th>"colour_q_forwardcol" </th><td>string </td><td>"light pink" </td><td>Colour for forward strand column background in matched alignment, specified as in the "Type" stanza. </td></tr>
+<tr>
+<th>"colour_q_reversecol" </th><td>string </td><td>"pink" </td><td>Colour for reverse strand column background in matched alignment, specified as in the "Type" stanza. </td></tr>
+</tbody></table>
+</fieldset>
+
+<a name="debug"></a>
+<fieldset><legend>Debugging Options</legend>
+You should only use these if you are a developer as they can impact the
+performance of ZMap significantly or cause it to write large amounts of
+data to stdout.<p>
+</p><table border="1" cellpadding="3" cellspacing="3">
+<tbody><tr>
+<th>Stanza </th><th colspan="3" align="center>">"debug" </th></tr>
+<tr>
+<th>Keyword </th><th>Datatype </th><th>Default </th><th>Description </th></tr>
+<tr>
+<th>"threads" </th><td>Boolean </td><td>false </td><td>Turns on/off debug output for the threading sections of ZMap. </td></tr>
+<tr>
+<th>"feature2style" </th><td>Boolean </td><td>false </td><td>Turns on/off debug output for mapping featuresets to styles. </td></tr>
+<tr>
+<th>"styles" </th><td>Boolean </td><td>false </td><td>Turns on/off debug output for style definitions. </td></tr>
+</tbody></table>
+</fieldset>
+
+<a name="align"></a>
+<fieldset><legend>Multiple Alignment Options</legend>
+ZMap can display multiple alignments, each alignment can contain
+multiple blocks. This stanza specifies which blocks in which alignment
+match each other. Note that all parameters are mandatory otherwise zmap
+will not know how to display the blocks.<p>
+</p><table border="1" cellpadding="3" cellspacing="3">
+<tbody><tr>
+<th>Stanza </th><th colspan="3" align="center>">"align" </th></tr>
+<tr>
+<th>Keyword </th><th>Datatype </th><th>Default </th><th>Description </th></tr>
+<tr>
+<th>"reference_seq" </th><td>String </td><td>Mandatory </td><td>Name of
+the "master" or reference sequence, this sequence is shown on the right
+of the window and blocks in other alignments are aligned to it. </td></tr>
+<tr>
+<th>"reference_start" </th><td>int </td><td>Mandatory </td><td>Start position of a block in the reference sequence. </td></tr>
+<tr>
+<th>"reference_end" </th><td>int </td><td>Mandatory </td><td>Start position of a block in the reference sequence. </td></tr>
+<tr>
+<th>"reference_strand" </th><td>int </td><td>Mandatory </td><td>Which strand of the reference sequence is being aligned, 1 means forward strand, -1 means reverse. </td></tr>
+<tr>
+<th>"non_reference_seq" </th><td>String </td><td>Mandatory </td><td>Name
+of the "master" or non reference sequence, this sequence is shown on
+the right of the window and blocks in other alignments are aligned to
+it. </td></tr>
+<tr>
+<th>"non_reference_start" </th><td>int </td><td>Mandatory </td><td>Start position of a block in the non reference sequence. </td></tr>
+<tr>
+<th>"non_reference_end" </th><td>int </td><td>Mandatory </td><td>Start position of a block in the non reference sequence. </td></tr>
+<tr>
+<th>"non_reference_strand" </th><td>int </td><td>Mandatory </td><td>Which strand of the non reference sequence is being aligned, 1 means forward strand, -1 means reverse. </td></tr>
+</tbody></table>
+</fieldset>
+
+<a name="blixem"></a>
+<fieldset><legend>Blixem Options</legend>
+ZMap can show multiple alignments using the blixem program, this stanza tells zmap how to find and run blixem.<p>
+</p><table border="1" cellpadding="3" cellspacing="3">
+<tbody><tr>
+<th>Stanza </th><th colspan="3" align="center>">ZMAPSTANZA_ALIGN_CONFIG </th></tr>
+<tr>
+<th>Keyword </th><th>Datatype </th><th>Default </th><th>Description </th></tr>
+<tr>
+<th>"netid" </th><td>String </td><td>Mandatory </td><td>The network id
+of the machine running pfetch from which blixem will retrieve the
+sequences to be shown in the multiple alignement. </td></tr>
+<tr>
+<th>"port" </th><td>int </td><td>Mandatory </td><td>The port number on the "netid" machine for the pfetch server. </td></tr>
+<tr>
+<th>"script" </th><td>String </td><td>Mandatory </td><td>The name of
+the blixem program, this could be a shell script which sets up some
+environment and then starts blixem or indeed another multiple alignment
+display program. </td></tr>
+<tr>
+<th>"scope" </th><td>Int </td><td>40000 </td><td>The span around the selected feature about which blixem will get and display data for the multiple alignment. </td></tr>
+<tr>
+<th>"homol_max" </th><td>Int </td><td>???? </td><td>The maximum number of homologies displayed ?? CHECK THIS.... </td></tr>
+</tbody></table>
+</fieldset>