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:
An index page (this file) will provide links to the rest
Each module will have it's own main page and possibly child pages if necessary.
Extra pages will be written providing information from other perspectives, for example a defintion of data in and out, the XRemote proctocol, performance issues.
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.
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.
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?
NB: Only the *.html and *.rel files are held in CVS as otherwise rebuilding pages would thrash the system somewhat.