From 19524ccd99fcac27383f82eab5b3f229e14c30fc Mon Sep 17 00:00:00 2001 From: mh17 <mh17> Date: Tue, 9 Mar 2010 10:41:33 +0000 Subject: [PATCH] notes about migration --- doc/Design_notes/misc/convert.html | 252 +++++++++++++++++++++++++++++ 1 file changed, 252 insertions(+) create mode 100644 doc/Design_notes/misc/convert.html diff --git a/doc/Design_notes/misc/convert.html b/doc/Design_notes/misc/convert.html new file mode 100644 index 000000000..d6bbb2df5 --- /dev/null +++ b/doc/Design_notes/misc/convert.html @@ -0,0 +1,252 @@ +<!-- CVS info: $Id: convert.html,v 1.1 2010-03-09 10:41:33 mh17 Exp $ --> + +<h2>Updating ZMap Documentation</h2> +<fieldset><legend>Note</legend> +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'. +</fieldset> + +<fieldset><legend>Migrating the old doc trees to one new one</legend> +<p> +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). +</p> + +<p> +A new directory <b>ZMap/doc/Design_notes</b> 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. +</p> +<p> +A front page <b>ZMap/doc/index.shtml</b> 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. +</p> +<p>There is some documentation online at intweb.sanger and the source of these is in the <p>ZMap/web directory</b>. 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.</p> + +<p> +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. +</p> +</fieldset> + +<fieldset><legend>Previous/ Existing Structure</legend> +<pre> +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) +</pre> +</fieldset> + +<fieldset><legend>New Structure</legend> +<pre> +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 +</pre> +</fieldset> + +<fieldset><legend>Files removed from CVS (copies kept in old for the moment)</fieldset> +<pre> +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 + +Design_notes/ +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 +</pre> +</fieldset> + +<fieldset><legend>Files in the web directory</legend> +<pre> +./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 +./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 +</pre> +</fieldset> \ No newline at end of file -- GitLab