Updating ZMap Documentation

Note Malcolm's working on this as a background task and needs to keep notes or else will forget what he's done, so here they are. As stuff gets done it gets marked with 'OK'.
Migrating the old doc trees to one new one

There are a number of doc directories scattered around the ZMap source tree and most are unused. We aim to clear these out and put all the documentation in the ZMap/doc/ directory tree and provide an HTML interface in this directory to help developers find the information they are looking for. All these files will be in the CVS and as such available to developers. At present there are no plans to host new files online (although page design allows for that possibility).

A new directory ZMap/doc/Design_notes will contain documentation of the various ZMap modules and further notes about how they interact and work. As work continues on ZMap design documents will be added to these files - these can be written in Open Office (eg if we wish to circulate them) and then exported as HTML once complete (which will allow easy cross referencing) or the location of the file noted.

A front page ZMap/doc/index.shtml will reference existing directories and provide some guidelines on where to find things. Here we are concerned with documentation accessable as part of the ZMap Source tree and not online data. The design directory will contain files generated by a script (to create a menu sidebar) and as such it's structure is constrained by how clever the script is.

There is some documentation online at intweb.sanger and the source of these is in the

ZMap/web directory. Those files that correspond to online resources will remain as is. ZMap/web sub-directories that look useful will be copied to doc/ and included in the index (most will be edited to the new format but on a temporary basis can simply be copied and added to CVS). The existing web/ files will be left untouched as they are in the CVS as simply removing them may cause build scripts to fail.

After this process all the online help documentation with the exception of doxygen generated files will be available via hyperlinks to copies of these files in the doc/ directory tree, and the online data will become static. After this we can update online documentation (if desired) by copying files to the web directory and running a new build script.

Previous/ Existing Structure
doc/

   CVS
   Design_notes            empty                   - use for new files
   obsolete                has useful stuff?       - ref from index?
   Papers                  early design notes      - ref from index
   project                 admin                   - move to Project_notes
   Project_notes           admin                   - ref from index
   Release_notes           admin                   - keep, ref from index
   talks                   powerpoint              - ref from index
   wemap                   ancient history         - remove
   (files)                                         - (mostly) move to Design_notes

web/        whole directory left as is initially
   CVS
   css         almost empty
   design      the new pages                       - move to doc/Design_notes and add to CVS
   dev         online local notes ref'd by developer     - copy to new
   developer   the developer page online           - add links from new
   expat       copy to new
   foocanvas   copy to new
   gfx         some bitmaps
   html        doxygen     nearly empty obsolete? - remove?
   releases    empty - remove
   user        a user guide to files in web/       - copy to new
   user_doc    user doc for the web                - copy to new
   (files)
New Structure
doc/
   CVS
   Papers
   Project_notes
   Release_notes
   talks
   css

   Design_notes   (Due to a CVS flake 'design' did not stick)
      modules     - code specific
      notes       - design and functional docs
      misc        - things that don't fit
      build       - there's stuff somewhere about this!
   scripts        - used to maintain the pages

   expat          - local notes on external modules
   foocanvas
   g2
   images
   user_doc       - copy of intweb files
   old/
      wemap
      obsolete
      project
Files removed from CVS (copies kept in old for the moment)
doc/
* column_config.README    - these get added to Design_notes
OK config.README
OK config.txt
OK pipeServer_config.txt
OK styles.README
* PERFORMANCE.README
* MAC_G2.README
* ZMAP_LACE_XML.README

*** Can't get the CVS to loose these directories!
*** 'cvs ls' says they are still there OK wemap/ - just delete and add any files wanted to somewhere OK obsolete/ OK project/ - copy to project notes OK src/docs - empty NOT: web/* - keep as is until really really obsolete
Files in the web directory
./CVS
./CVS/Root
./CVS/Repository
./CVS/Entries
./css
./css/CVS
./css/CVS/Root
./css/CVS/Repository
./css/CVS/Entries
./css/dev_server.css
./css/zmap-default.css
./README.int
./download.shtml
./index.shtml
./latest-src-release.shtml
./dev
./dev/CVS
./dev/CVS/Root
./dev/CVS/Repository
./dev/CVS/Entries
./dev/ZMap_XCode.shtml
./dev/coding_notes.html
./dev/foo_canvas.html
./dev/foocanvas.shtml
./dev/gdk_events.html
./dev/index.shtml./user
./user/CVS
./user/CVS/Root
./user/CVS/Repository
./user/CVS/Entries
./user/header.ini
./user/index.shtml

./dev/this_links.ini
./developer
./developer/CVS
./developer/CVS/Root
./developer/CVS/Repository
./developer/CVS/Entries
./developer/Acedb_ID_construction.shtml
./developer/ZMap_XCode.shtml
./developer/build_system.shtml
./developer/coding_notes.shtml
OK ./developer/debugging.shtml
./developer/gdk_events.shtml
./developer/index.shtml
./developer/parent_links.ini
./developer/this_links.ini
./expat
./expat/CVS
./expat/CVS/Root
./expat/CVS/Repository
./expat/CVS/Entries
./expat/expat.png
./expat/index.shtml
./expat/reference.html
./expat/style.css
./expat/valid-xhtml10.png
./expat/xmlwf.1
./expat/xmlwf.sgml./user
./user/CVS
./user/CVS/Root
./user/CVS/Repository
./user/CVS/Entries
./user/header.ini
./user/index.shtml

./foocanvas
./foocanvas/CVS
./foocanvas/CVS/Root
./foocanvas/CVS/Repository
./foocanvas/CVS/Entries
./foocanvas/.cvsignore
./foocanvas/dev_notes.shtml
./foocanvas/header.ini
./foocanvas/this_links.ini
./foocanvas/user_guide.shtml
./foocanvas/zmap_canvas_items.shtml
./foocanvas/zmap_container_items.shtml
./gfx
./gfx/CVS
./gfx/CVS/Root./user
./user/CVS
./user/CVS/Root
./user/CVS/Repository
./user/CVS/Entries
./user/header.ini
./user/index.shtml

./gfx/CVS/Repository
./gfx/CVS/Entries
./gfx/canvas_logo.png
./gfx/zmap.png
./gfx/zmap_logo.png
./html
./html/CVS
./html/CVS/Root
./html/CVS/Repository
./html/CVS/Entries
./html/dir.README
./html/this_links.ini
./releases
./releases/CVS
./releases/CVS/Root
./releases/CVS/Repository
./releases/CVS/Entries
./releases/README
OK./user
      ./user/CVS
      ./user/CVS/Root
      ./user/CVS/Repository
      ./user/CVS/Entries
      ./user/header.ini
      ./user/index.shtml      -- just ignore this one
./user_doc
./user_doc/CVS
./user_doc/CVS/Root
./user_doc/CVS/Repository
./user_doc/CVS/Entries
./user_doc/xremote
./user_doc/xremote/CVS
./user_doc/xremote/CVS/Root
./user_doc/xremote/CVS/Repository
./user_doc/xremote/CVS/Entries
./user_doc/xremote/xremote_overview.shtml
./user_doc/xremote/zmap_command.shtml
./user_doc/Cluster_tags.shtml
./user_doc/Tag_sets.shtml
./user_doc/align1.png
./user_doc/config_file_examples.shtml
./user_doc/configuration.shtml
./user_doc/index.shtml
./user_doc/keyboard_mouse.shtml
./user_doc/parent_links.ini
OK ./user_doc/styles.shtml
./user_doc/this_links.ini
./user_doc/user_interface.shtml
./user_doc/zmap_demo.txt