root/BADataMunger/trunk/README.txt

Read me for BADataMunger
=================

BADataMunger is a collection of routines intended for manipulating, mining
and querying Classical Atlas Project compilation data (i.e., Barrington 
Atlas compilation data) for upload to Pleiades or other functions. Details of
major components are provided below. Please note, some code is out of
date. Other code is ugly. Hopefully someday soon we won't need this stuff
anymore.

Rights, origins, credit and blame
====================

Much of the code in BADataMunger was written by Tom Elliott for either
the Ancient World Mapping Center or the Institute for the Study of the 
Ancient World (ISAW) under the rubric of the Pleiades Project. Some funding 
for this work was provided by a grant from the National Endowment for the
Humanities for the initial development and interoperability prototyping
of Pleiades; additional funding has been provided by ISAW itself.

Copyright (c) 2008 Institute for the Study of the Ancient World, New York 
University and Ancient World Mapping Center, University of North 
Carolina at Chapel Hill

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program (LICENSE.txt).  If not, see <http://www.gnu.org/licenses/>.

BADataMunger contains helper functions for determining calculating 
permutations (xpermutations.py). It was written by Ulrich Hoffmann and 
distributed via ActiveState Code (formerly the Oreilly/Activestate Python Cookbook). 
At the time of download, it was marked "public domain", and Activestate now 
applies the terms of the Python License  ( http://www.python.org/psf/license/ ).

Dependencies
=========

See DEPENDENCIES.txt


Tests
====

There are no comprehensive tests. See "blame" above.


Components and using them
===================

Some modules, classes and functions have docstrings. >>>help(modulename) will 
sometimes provide useful information.

Here are a few of the main tasks supported herein:

Creating Barrington Atlas IDs

    module: batlaspipe.py
    
    
Converting BA Directory files to XHTML or home-brewed XML that includes BAtlas
IDs

    module: dir2xml.py
    deficiencies:
    * does not currently calculate descriptions as expected for old-school Pleiades
    * there are problems with roads (some information not coming through?)
    * not all creators contributors are in the config files?
    * maybe id-stamp rows in XHTML with old-style ids so we can link up with 
       parsed data?


Parsing out bibliography from directory files

    module: pipebiblio.py
    
    
Parsing feature information out of directory files and munging it together with geodata

    module: pipegeo.py
    
    
Older or supporting modules may or may not work.