Read Me

=======================
Publications Map Readme
=======================

Publications Map is an Adobe Flex based application which displays data about
published works in a graphical layout. This package also contains programs
for generating data files and presenting data in alternative formats.

Original Design: Simon Antoun & Murdoch J. Gabbay (2008)
Updated By:      Andrew Dodd  & Murdoch J. Gabbay (2010)

---------------------------------------------
Package Contents and Quick Start Instructions
---------------------------------------------

Viewer (viewer.html):
---------------------
Open viewer.html with your browser to view a publications map.  This package 
comes with a default data file (data.xml).


Editor (editor.html): 
---------------------
Open editor.html with your browser to edit the publications map.  If you have 
just downloaded the package, you will get a simple default file  to start you 
off (data.xml).


DBLP Fetch Script (fetch-dblp.pl): 
----------------------------------
Run this with Perl to fetch your publications from DBLP 
    (http://www.informatik.uni-trier.de/~ley/db/index.html)
and write them to the data file used by the Viewer/Editor.

You can use fetch-dblp.pl or enter your publications by hand using the Editor, 
or use any combination of the two.

fetch-dblp.pl cannot yet read minds; you still have to make lines and organise 
and annotate the publications.


Web Listing Page (index.php): 
-----------------------------
Run index.php to generate html code for a publications page.
You can edit index.php and style.css yourself, to adjust the template.


Data File (data.xml): 
---------------------
This file stores the data for the publications map (nodes and edges). 
If you have just downloaded this package then data.xml contains a simple 
example publications map for you to explore and edit.
Note that for security reasons, editor.html cannot save to your disk; it can 
only copy xml data to the clipboard.  This means that after editing, you have
to cut-and-paste xml data yoursef. 


------------
Installation
------------

Common Instructions
-------------------
Untar the archive. On Windows you will require a third-party archiving tool 
such as 7-zip (http://www.7-zip.org/).  Unix-based systems may use tar:
tar zxf <filename>

The Web Listing Page is a PHP script and requires parsing before it can be 
used.  Generally this means placing it in the document root of a web-server 
with PHP installed and then viewing the file (index.php) through the server in 
a web-browser. 

For each component to work, the following files must be in the same directory:

Both Viewer & Editor: AC_OETags.js, data.xml, DataSchema.xml, 
    playerProductInstall.swf
Viewer: viewer.html, viewer.swf
Editor: editor.html, editor.html

Web Listing: index.php, data.xml, style.css

DBLP Fetch Script
-----------------
The DBLP Fetch Script is written in Perl (http://www.perl.org) and requires a
Perl interpreter to run.  Most Unix distributions will have Perl installed by 
default.  You can check for by running
perl -v
Contact your system vendor if this command is not found.

Windows users can download a version of Perl from http://strawberryperl.com or
use another version they prefer as long as it is version 5.8 or higher.

This script also depends on the XML::Simple.  This module is included with the
release however it may not be up to date so it is recommended this module is
manually installed from CPAN (http://www.cpan.org) and the XML folder in this
package's directory removed.

--------------------
Running Applications
--------------------

Viewer & Editor
---------------
The viewer and editor can be run by opening either viewer.html or editor.html 
in a web browser which has an Adobe Flash plugin installed. 

To put the viewer online, you should copy the files required for the viewer 
(named in the Installation section above) from the installation directory to
your web server. 

Web Listing
-----------
The Web Listing page should be installed to a suitable location on a webserver
and then invoked by visiting the page.  This page is simply an example of how 
to parse the data from data.xml and can be re-written to match layout needs.

In Linux, if you have php installed, you can also execute 
   php index.php > index.html
from the command line.

DBLP Fetch Script
-----------------
The DBLP Fetch Script should be invoked by running perl fetch-dblp.pl .  Unix
users may also use ./fetch-dblp.pl - the interpreter will work out which 
program to execute the script with.

The script requires some arguments to be passed to it - running the script
without any arguments will cause simple usage instructions to be printed to the
console.