DANNO CLIENT SETUP
                            ~~~~~~~~~~~~~~~~~~

Copy all js, css, html, and php files to an Apache or Tomcat served location.
IMPORTANT!  To operate, at all, the files  and Danno server must be located
on the SAME HOST (for more details, lookup Same Host Problem security issue).

Currently, the client relies on php, which required the file be served by
Apache.  It is recommended that the Dano server be setup to use the Apache
"mod proxy" service so that the port number for Tomcat never appears anywhere
but the Apache config file (ie, don't include it in the Danno web xml path).
The lines below should be appended to the Apache configuration file. This
is normally /etc/httpd/conf/http.conf

  ProxyPreserveHost on
  ProxyPass /danno/ http://<host>:<port>/danno/
  ProxyPassReverse /danno/ http://<host>:<port>/danno/

After copying the files to the server, some editing is required.  The
following examples use an Apache server with Tomcat accessed via
'http://maenad.itee.uq.edu.au' with the cliens files copied to
a directory called 'dias-b' located of the server root.
Note the Tomcat port is mentioned ONLY in the httpd config script.

dannotate.html
~~~~~~~~~~~~~~
  Near "url=encodeURIComponent(window.location.href);"
  insert the host and any extra path details. Eg:
    window.location.href='http://maenad.itee.uq.edu.au/dias-b/pageproxy.php?env=ff&url='+url;
    
  If desired, set the "g_host" variable located in the embedded <script> tag
  to the host name. This enables a dangerous function which purges all 
  annotations and the call to it is normally commented out at the end of the
  HTML body.
  
dannotate.js
~~~~~~~~~~~~
  Under the CONSTANTS, set the DANNO_HOST to the host name. Eg:
    var DANNO_HOST = 'http://maenad.itee.uq.edu.au';
  If the php code resides someplece other than the root of the Apache
  server, adjust the path in the DANNO_PROXY and DANNO_CB constants.
    
dannotate4.php
~~~~~~~~~~~~~~
  Modify 2 variables located just after the header block.
    1. Check DEBUG is set "false" (unless you have problems)
    2. Change the value of the "$DANNO_URL" variable assignment
       to the Danno URL being used (no port).  Eg:
         $DANNO_URL = 'http://maenad.itee.uq.edu.au/danno/annotea';
    
pageproxy.php
~~~~~~~~~~~~~
  Edit the 3 Constants at the start of the code. Eg:
    1.  $HOST = 'http://http://maenad.itee.uq.edu.au';
    2.  $DANNO_HOST = "$HOST/danno";
    3.  $CLIENT_PATH = "$HOST/dias-b";
    
Confidence Testing
~~~~~~~~~~~~~~~~~~
1. Assuming the Danno XML configuration has been completed and tested, start Tomcat.
2. Access the 'dannotate.html" page through a Firefox 2 or 3 browser 
   (Safari and Opera may work too, but IE will definitely NOT WORK).
3. Drag the 3 Bookmarklets to the Browser toolbar (good ide to delete any old ones)
4. Highlight any text on the page and "press" the "Dannotate" tool.
   A form should popup for Annotation entry.  Enter a comment and change anything
   else you like (except the URL).  Press [Submit].
5. The popup should say "Success!" then auto-close after a 2 second delay.
   When it closes, a green highlighted "footnote" tag should have appeared somewhere
   after the selection. Mousing over this should cause a popup to display showing
   the annotation details with a "Reply" button.
6. Mouse into the popup and Reply (as before). A pink highlight footnote should
   appear that will activete the reply text popup.  For a good time, reply to the
   reply.
   
Statistics Page
~~~~~~~~~~~~~~~
  Two Perl scripts are provided to maintain a statistics page.  This page is
  linked from the word "Dannotate" in the top heading of the dannotate.html
  page, but unless a successful harvest/generate run is made, this link will
  be broken.  The scripts are:

    - harvest.pl
    - crstats.pl

  To setup automatic stats creation, we suggest that both perl scripts be
  copied to /usr/sbin and chmod'd to enable execution by root.

  To run the scripts, Perl needs the XML::LibXML modules installed.
  To check, execute the harvest.pl script with the help option:

    $> ./harvest.pl --help

  It will object strongly if the XML::LibXML module is not installed.  If this
  is the case, the best way to add it is through CPAN:

    1. $> perl -MCPAN -e shell
    2. cpan> install XML::LibXML  (interactive; hit enter and accept defaults)

  If you cannot get a CPAN shell, you may need to install that module.
  As root:

    $> yum install perl-cpan (accept all defaults and follow instructions).

  You may like to yum install perl-YAML first, but this is optional.

  Both scripts get the required database and DANNO info from command line
  arguments.  There are also a number of options that control the output.
  To see these, execute with the --help option. We suggest you do this at
  least once to see what is available.

  A sample cron job that invokes the scripts is supplied. You should copy
  this file to someplace like /usr/sbin and edit the script to set the URL
  for your DANNO server and MySQL:

    #!/bin/sh
    LOG=/var/log/dias-b.log
    NOW=`date`
    HTML_PATH=/var/www/html/dias-b
    HTML_FILE=$HTML_PATH/dannostats.html
    MYSQL_HOST=localhost
    DANNO_HOST=http://localhost

    echo "Danno harvest executed $NOW" > $LOG
    /usr/sbin/harvest.pl --danno=$DANNO_HOST --db-host=$MYSQL_HOST 2>>$LOG
    /usr/sbin/crstats.pl --html=$HTML_FILE --css --users 2>>$LOG

  Setup a cron job as root with:
  
    $> crontab -e

    0,30 * * * *  /usr/sbin/dodanno.sh

  This will refresh the stats page every 30 minutes.  Tailor the frequency
  to whatever you feel comfortable with. For convenience and debugging,
  the script outputs a log file to /var/log.

  NOTE on stats CSS
  ~~~~~~~~~~~~~~~~~
    The --css option to crstats.pl generates a sample css file to the same
    path as that specified for the html file.  You only need to do this once.
    If you modify the css, using --css will obviously trash you changes the
    next time the script runs.

Problems
~~~~~~~~
Read the source, Luke.


                                                Ron Chernich, January 22, 2009.
    
                                -oOo-