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:
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.
There are a lot of existing files the we wish to refer to and these are bing migrated from the old doc/web/ directory. For details of the progress on this refer to Doc Migration.
As html source files are held in the CVS an Id tag should be included in an HTML comment at the start of the file. The new script will include this automatically, but if one is missing it should consists of: <!-- -S-Id-S- --> except that -S- should be replaced by a dollar sign ('$').
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 files 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.
Pages regared as 'external' or 'old' can be intergrated into the menu system, but exercise caution when doing this as we use *.html as source and docgen writes *.shtml. If you add a directory to the build script then any exsiting *.shtml files could get overwritten if you cretaed a similar *.html.
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.