adding a readme.txt

README.txt

@@ -0,0 +1,113 @@
+November 2013 --DRAFT--
+--------------------
+Introduction
+--------------------
+The MBmaint Perl package is used to maintain content in the Metabase DB. XML is used
+as an intermediate format. The database is queried with sqlxml (templates). 
+the user edits this reduced XML and sends it back to the database.
+
+XML is used because it can be edited manually now, and can populate and be edited
+in a form later.
+
+<more about how it works>
+
+
+
+
+--------------------
+Package Design
+--------------------
+The Perl MBmaint package currently contains two modules: DButil.pm and DSmeta.pm.
+
+1. DButil.pl module
+<descr here>
+
+
+
+2. DSmeta.pm module
+<descr here>
+
+
+
+Client programs
+--------------------
+There are two client programs:
+1. DSexportXML.pl 
+2. DSloadXML.pl 
+
+
+ --------------------
+ Installing MBmaint
+--------------------
+1. Get the latest source code release from Github:
+
+   git clone https://github.com/sbpcs/MBmaint.git MBmaint
+
+2. Create and edit the configuration file that contains authorization 
+   information necessary to connect to your database:
+
+   % cp config/MBmaint.ini.sample config/MBmaint.ini
+   % vi config/MBmaint.ini
+
+3. Install the required Perl modules:
+
+     Moose
+     Template
+     Config::Simple
+     DBIx
+     XML::LibXML
+     DateTime
+
+
+
+
+--------------------
+Sample workflow
+--------------------
+See what templates are available
+  ./DSexportXML.pl -l 
+
+export content of table "DataSetPersonnel" for dataset 6, send to a file
+  ./DSexportXML.pl DataSetPersonnel 6  > ds6_personnel.xml
+
+edit XML (see below)
+  vi ds6_personnel.xml
+
+send new content back to the database  
+   ./DSloadXML.pl -v ds6_personnel.xml 
+
+
+--------------------
+Notes on XML
+--------------------
+A. The DTD for this XML can be found at:
+http://sbc.lternet.edu/external/InformationManagement/Metabase/XML/metabase2_content-1.0.dtd
+
+B. There are two xml attributes:  
+pk="t" (the field is part of the table's primary key)
+references="Table.Column" (the field is referenced in the tables foreign key constraint)
+An XML editor, whether human or machine, need to know that this content requires 
+special handling. 
+
+Currently (2013), these attributes are not used by code, and XML is altered manually.
+
+C. to replace a field that is a primary key:
+1. copy the entire row
+2. edit replacement row with new content
+3. manually add this attribute to the original row element: 
+action="delete" 
+
+This attribute does not appear in any query templates; it must be added by the XML editor. It EXPLICITLY tell the code (loadXML.pm) to delete the row. 
+
+
+D. fields that are sql _xml type.
+some SBC and MCR metabase content is sql XML-type. This is in interim solution
+until metabase can be modified to accomodate the full suite of EML structures that 
+MCR and SBC use. XML content for xml-type SQL fields should be created outside of the 
+XML generated by query templates. The name of the file containing the XML goes into
+the file to be passed to loadXML.pm (eg, "methods.xml"), along with the attribute src="file". Other sources may be added in the future.
+
+
+
+
+