THIS DIRECTORY:
---------------
This directory contains tools used to analyse the data used in
KStars. It has tools to test, read and create the binary files used
for star data amongst other things.

Most of these programs (particularly the C / C++ programs) are rather
poorly written code, but somehow happen to work. Also, this directory
can be a pain to build (read the note in the Makefile for details). I
really don't know if it is worth spending time cleaning all this up,
since it's anyway something that very few people would be interested
in building (or so I think).

Most of the perl scripts are due to James Bowlin, who can be contacted
at <bowlin@mindspring.com>. Most of the C programs are my work, and I
can be contacted at <akarsh@kde.org>

Some of the Perl scripts require the HTMesh perl wrapper, which is
also present in this directory. The library is released under a
license more liberal than GPL, and the details are found in the README
file in the relevant directory. This library needs to be built (it
depends on the HTMesh C++ library, available in kstars/kstars/htmesh)
and installed before running many of the Perl scripts in this
directory.

Many of the Perl scripts and C++ programs as of this writing require a
MySQL database server to be available on localhost. The database is
used as an intermediary to hold the data loaded from ASCII data files
in a nice format.

DESCRIPTIONS OF FILES:
----------------------

read-hippo.pl        Reads the Hipparcos catalog files

reformat-hip.pl      Converts old format star data files into the new format,
                     where the fixed length Genetive name comes before the
                     variable length long name

mag-linenum.pl       Write the line number magnitude index file

max-length.pl        Find the longest line in a file

sort-hip-by-pm.pl    Sort the Hipparcos catalog data by proper motion

hipdatatomysql.pl    Reads Hipparcos star catalog text files and puts them into
                     a MySQL database (server on localhost). CAUTION: This script
                     will empty the table that it is writing into.

tycdatatomysql.pl    The Tycho star catalog text files used by KStars are in a
                     different format from the Hipparcos catalog files. This script
                     puts the data from the Tycho star catalog into a MySQL
                     database. It's just a modified version of hipdatatomysql.pl

binfiletester.c      C Program to test KStars' star data in binary format

nomadbinfiletester.c C Program to test KStars' deep star data from the
		     NOMAD catalog in binary format

mysql2bin.c          C Program to put data from the MySQL database (generated
		     using datatomysql.pl) into the binary data format defined
		     by KStars. [See README.fileformat in the kstars/data
		     directory]. To make this, you will need to have the
		     libmysqlclient-dev package or equivalent installed

nomaddatatomysql.pl  Reads the NOMAD catalog data in ASCII format and puts it into a
                     MySQL database for easy processing. This is just a modified
                     version of tycdatatomysql.pl

nomadbinfile2mysql.c Reads binary NOMAD catalog data and puts it in a
		     MySQL database for easy processing.

# TODO: Document the split and merge stuff.

BUILDING THE PROGRAMS:
----------------------

To build both the C programs, use:

   make

To build only mysql2bin, use: [Requires MySQL client library]

   make mysql2bin

To build only binfiletester, use:

   make binfiletester

To clean up, use:

   make clean

CREATING THE DATA FILES:
------------------------

To create and put the binary data files in kstars/data, first export
your MySQL DB username and password:

   export KSTARS_MYSQL_DB_USER='<your DB username>'
   export KSTARS_MYSQL_DB_PASS='<your DB password>'

If the database in which the star data table is stored is not
identical to the DB username, export that too:

   export KSTARS_MYSQL_DB_DB='<the DB name>'

If the table in which the data is present is not allstars (default if
you used datatomysql.pl to generate the tables), then export that too:

   export KSTARS_MYSQL_DB_TBL='<table name>'

Then, finally do:

   make datafiles

This will build mysql2bin, collect the data, and put it in
kstars/data.

If 'make datafiles' hangs (it typically takes about 5 - 10 minutes),
then you should first double check that it is really hanging by
setting VERBOSE to 1 on line 17 of mysql2bin.c and retry. If it shows
no progress, reduce the value of MYSQL_STARS_PER_QUERY in the #define
directive on line 24 of mysql2bin.c till it works. This is because the
database query may hang if the query results are too large in size. I
don't know why this happens, but it seems to work that way.

LICENSING INFORMATION:
----------------------
Copyright (c) 2008-2011 Akarsh Simha <akarsh.simha@kdemail.net>
This document is released under the terms of the GPL v2.
