INSTALLATION STEPS:

------------------
Compiling libquran
------------------
./configure
make
su -c 'make install'


-----------------------------
Using quran_install_component
-----------------------------
After compiling libquran, you should install the data to work with.
This includes the Qur'an text and audio recitations.
The individual data components can be downloaded from the project page:
http://www.arabeyes.org/project.php?proj=Quran
After that you need to install them using either:
 - The automatic way using quran_install_component:
    you just run the quran_install_component tool and give it the component
    name like that:
       quran_install_component COMPONENT_NAME
    So, if you downloaded the component quran_original_text.tbz2, you can install it
    by issuing the command:
       quran_install_component quran_original_text
    (notice that the extension ".tbz2" has been omitted)
 - The manual way (continue reading for how to do it)

Please note that you need at least one text component (at least the original text which might be named quran_original_text.tbz2, check the download page) for libquran to be useful.


-----------------------------------
The Configuration File (/etc/quran)
-----------------------------------
Make a new file (/etc/quran or ~/.quranrc), it should contain the path to
the quran data files (the various language packages), a typical one may
be:
/usr/local/share/quran_data

or it maybe on a cdrom or something:
/mnt/cdrom

in either case, it should point libquran to the path of the language
packages you have.


-----------------
Language Packages
-----------------
To use libquran, you must have at least one language package.
A language package is a collection of quranic related data for one language,
for instance, an arabic language package may contain one or more of the
following:
 - The original text XML file (it contains the original text of the Holy Qur'an)
 - One recitation or more of the Holy Qur'an.
 - One interpretation of the Holy Qur'an (a.k.a. Tafsir) or more.
But it doesn't have to contain all of them, it is valid for a language package to
contain only one of those data resources listed. However, you will only be able
to use the data you have on the language package, and it makes sense to at least
include the original text of the Holy Qur'an for an Arabic language package.


------------------------------
How To Make a Language Package
------------------------------
Making a language package is an easy thing to do.
The first thing to do is to decide what data components you want on it and
to actually gather them.
For instance, let's say we are creating a minimal Arabic Language package
that contains only the original text of the Holy Qur'an:
Now we should make a directory for our language package in the libquran
data files directory (which should be pointed to from /etc/quran or ~/.quranrc,
see the second section above), let's say it's /usr/local/share/quran_data.
 + cd /usr/local/share/quran_data
 + mkdir ar
 + cd ar
We copy the XML file that contains the original text of the Holy Qur'an to
the newly created directory:
 + cp /whatever/place/quran/xml/is/quran.xml.ar .
The final step is to create a configuration file (conf.xml) for our language
package:
 + touch conf.xml
then edit conf.xml using your favourite text editor and type on it:
<quran>
  <language code="ar" name="Arabic">
    <text>
      <author>Original Text</author>
      <copyright>None (Original Text)</copyright>
      <filename>quran.ar.xml</filename>
    </text>
  </language>
<quran>

and that is it, we now have a working language package :-)

But, let's say you also want to add an audio recitation or two and
an interpretaion of the Qur'an (Tafsir).
To add those we need first to get them. For example, we want to add
Ali_Hozaify recitation (see below) to this language package.
We get it (of course:-), it should be in OGG format speex-encoded
(http://www.speex.org) and numbered like that:
 sSSSaAAA.spx  (SSS: the chapter number, AAA: the verse number)
Anyway, if you get it from the URL below, you will find that it's already
in that format but make sure that all of the files are in ONE directory
that is only one level deep, something like:
 ali_hozaify/sSSSaAAA.spx
Now copy (or symlink it) to tha language package directory we made:
 + cd /usr/local/share/quran_data/ar
 + cp -r /some/directory/ali_hozaify .
 or symlink
 + ln -s /some/directory/ali_hozaify .
The final step to edit conf.xml again and modify it to be like this:
<quran>
  <language code="ar" name="Arabic">
    <text>
      <author>Original Text</author>
      <copyright>None (Original Text)</copyright>
      <filename>quran.ar.xml</filename>
    </text>
    <audio>
      <author>Ali Al-Hozaify</author>
      <copyright>(copyright holder)</copyright>
      <filename>ali_hozaify</filename>
    </audio>
  </language>
<quran>

To add an interpretation, you simply do the same step as for adding the
original text but using the <tafsir> tag in place of the <text> tag.

NOTE: You can have more than one audio recitation, interpretation or
translation by just adding another <audio>, <tafsir> or <text> tag
respectively just like the existing one:
<quran>
  <language code="ar" name="Arabic">
    <text>
      <author>Original Text</author>
      <copyright>None (Original Text)</copyright>
      <filename>quran.ar.xml</filename>
    </text>
    <audio>
      <author>Ali Al-Hozaify</author>
      <copyright>(copyright holder)</copyright>
      <filename>ali_hozaify</filename>
    </audio>
    <audio>
      <author>Mohammed Jebril</author>
      <copyright>(copyright holder)</copyright>
      <filename>jebril</filename>
    </audio>
  </language>
<quran>


-------------------------------------
Making a self-contained Qur'an CD-ROM
-------------------------------------
Meaning that, you make a CD that works out-of-the-box without even installing
it on the HD. With libquran and a client for it (gnomeQuran ot QtQuran) you can
easily do that.
(TODO)

--------------------------
Obtaining Data Components
--------------------------
There are existing audio packages, like the package of Ali Hozaify (that can be found in 
http://sourceforge.net/project/showfiles.php?group_id=34866&release_id=147894) and the 
package of Saeed Khayaat.

As for the original text of the Qur'an, in the mean time you can get it from Arabeyes
CVS repository.

Please notice that the offered text shouldn't be considered proper, it's not even complete
so it should only be used for "temporary" testing purposes until we complete and verify it.

About the translations of the Holy Qur'an, we are still on the issue of making
certified translations available, we hope to settle this issue soon.

There are currently no interpretations available.
You can stay updated by visiting the project page:
 http://www.arabeyes.org/project.php?proj=Quran
