ZMap Design Documentation


Introduction

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.

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:

Practicalities

Prototype System

Initially we will only provide HTML files as part of the ZMap source tree in ZMap/doc/Design_notes. Each ZMap source directory will have a README (or README.html) which will provide a link to the relevant page on this directory, and each page will have links to related pages and the index.

Current web standards and links to the web team can be found here and include CSS and some notes about header.ini which is a Perl script. To access HTML in the ZMap source tree we need to provide simple HTML files (.shtml actually - this is as needed for intweb) and scripts cannot be included as we are not running a web server locally.

Headers and Navigation

The Sanger NavBar can be used for related links on any set of pages uploaded to intweb and some way needs to be found to generate this for files in the ZMap source tree. As an interim measure a <div> will be used for a left hand list of links and another for the page's text; these will be set with styles such that they do not overlap. A script can be used to generate a local shtml file, and another one for files to upload to intweb. This is necessary to avoid having to edit many files to add links if we add a new one.

A script will be used to generate a usable page (*.shtml) from a headerless source file (*.html), and each file will have an optional *.rel file to specify related links.

External modules and the document tree

The pages proper will be stored in ZMap/doc/Design_notes (as new documentation files) and there are some existing file we wish to refer to. The pages will be set up with a document root of ZMap/doc and therefore it will be easy to refer to any previously written html files.

A directory (ZMap/doc/scripts} will be used to store scripts to maintain these files and should be added to a ZMap developer's path. Note that after editing a headerless source file it is necessay top re-generate the *.shtml using 'docgen filename', and of course the CVS has to be operated as well.

Note to self: maybe docgen could operate the CVS?

Adding a new file

NB: Only the *.html and *.rel files are held in CVS as otherwise rebuilding pages would thrash the system somewhat.

Scripts and Files scripts/navbar.rel list of links and descriptions used by navbar scripts
scripts/new create a new *.html and *.rel file. Two args: module name and description
scripts/docgen generate a local .shtml file
scripts/build build all *.shtml files
NB: this currenty does doc/ and Design_notes/* only. It must be run from ZMap/doc/.
<module>.rel list of links relevant to the module or page
ZMap/doc/css/dev_server.css as cut and paste from the Sanger web development pages