Source

noor / README.txt

=============================
 Noor, A python Quran viewer
=============================


Overview
========

Noor_ is a program written in Python_ for viewing quran.  You can
specify translation files; If specified the translation of each aya is
shown after it.  These are the interfaces that come with noor:

===========   ===================================================
Interface     Description
===========   ===================================================
noorgtk       Uses PyGtk_ library
noorhtmls     Outputs quran in html files in the output directory
noorcgi       Can be used as a CGI script in web servers
noortxt       Outputs a sura to a text file
===========   ===================================================

.. _Noor: http://noor.sf.net/
.. _PyGTK: http://www.pygtk.org/
.. _Python: http://www.python.org/


New Features
============

* added support for translating dialogs
* added Farsi and Pashto languages
* added aya hook


Getting Started
===============

noorgtk
-------

For using the GTK interface you need to install Python_ and PyGTK_
(they are installed by default in some linux distributions like
Ubuntu).  You can start it by running ``noorgtk.py`` script either
from the command line or by double clicking it in the extracted
folder.  That is, no installation is necessary.

But if you like, you can run ``python setup.py install`` to install
Noor.  After that you'll be able to run ``noorgtk.py`` in the terminal
from any location.

noorhtmls
---------

The noorhtmls interface can be used to output quran in html files in a
directory.  All you should do is to run::

  noorhtmls.py output_folder

The ``index.html`` file will contain the list of suras and
``001.html`` through ``114.html`` files will contain the suras.  Note
that the configuration specified in the ``~/.noor`` file is considered
when generating the pages.

noorcgi
-------

Installing the CGI script, ``noorcgi.py``, is like installing any
other CGI script.  You probably have to copy it to the ``cgi-bin``
directory of your web server.  But before that you should either
install noor as described in the noorgtk_ section or change the line
in ``noorcgi.py`` file which looks like::

  # Add noor to the python path if its not installed:
  sys.path.append('/noor/extracted/folder/')

to point to the folder in which you've extracted noor.  Note that if
you want to use the CGI interface you no longer need to install
PyGTK_.


Noorgtk Tutorial
================

After starting ``noorgtk`` as described above, you'll be asked to
select a sura to view.  (Use ``gtk.ask_sura_at_start`` config or give
a command line argument to skip that).

Now you see the sura you've chosen.  Use up and down keys to move the
text.  Press ``a`` key; you'll be asked to enter an aya number.  After
pressing enter you'll be moved to that aya.

Now press ``c``.  A dialog pops up in which you can select a sura.

Press ``s`` this time; Noor will ask you to insert a sura number to
go to.  Also ``J`` (that is capital j) moves you to the start of a
juz.

Now press ``C-M-n`` or ``C-j`` (whichever you're most comfortable
with).  Noor will show the next sura.  Likewise ``C-M-p`` or ``C-k``
can be used for previous sura.

Some commands need an integer argument, such as goto aya, goto the
page before aya, goto sura and goto juz.  If you type a number before
using these commands, that number will be assumed to be the argument
and Noor *won't* ask the number in a dialog.

Note that many of Noor commands can be done in more than one way and
have more than one key-binding.  See the `noorgtk keys`_ and try its
commands.

Also you can tell noorgtk to start from a sura and aya using command
line arguments.  For instance ``noorgtk.py 100 3`` goes to the third
aya of the 100th sura.


Adding Translations
===================

You can edit the ``~/.noor`` file::

  [common]
  translation = /path/to/translation/file

The translation file can be in two formats.  It can be either a zip
file in the same format as Zekr_ translation files which can be
obtained from http://siahe.com/zekr/resources.html or it can be a
utf-8 text file with translation of each aya in one line.

.. _Zekr: http://siahe.com/zekr


Changing Font
=============

You can change the GTK or html fonts in ``~/.noor`` file::

  [gtk]
  font = nazli 19
  translation_font = irannastaliq size:14 fgcolor:#001100 fgcolor:#DDDDFF

  [html]
  font = nazli 6 fgcolor:554444
  translation_font = homa 4 fgcolor:444455

A font has face, size, fgcolor and bgcolor attributes.  These
attributes can be set using ``attr:value`` format where ``attr`` is
attribute name.  The old format still works; that is ``myfont 16`` is
the same as ``myfont size:16`` and also the same as ``face:myfont
size:16``.

I recommend ``KacstQurn`` font for Quran text and ``IranNastaliq`` for
farsi translation.


Changing The Language
=====================

You can change the language of noorgtk dialogs and noorhtmls pages;
for instance::

  [common]
  lang = fa

will use Farsi.  The value of ``common.lang`` config should be a two
letter symbol of a language.  Currently ``fa`` and ``ps`` (for Pashto)
are available.  If you like, you can translate noor to other languages
(ask the mailing list if you need help).


Adding Hooks
============

Sura and aya hooks can be specified in ``~/.noor`` file and are run
when a new sura or aya is shown in noorgtk.

The first argument of a sura hook is the sura number.  You can use
noor's sura hook to start playing quran recitation when noorgtk shows
a sura.  Hook can be specified like::

  [gtk]
  sura_hook = my_sura_hook

See ``contrib/playsura`` hook as an example.

Aya hook is executed when a new aya is shown (see key-binding section;
next/previous/current aya).  The first argument of an aya hook is sura
number and the second one is aya number.  An aya hook can be specified
in gtk section of the config file::

  [gtk]
  aya_hook = my_aya_hook



Noorgtk Keys
============

These keys can be used in the GTK interface.  Note that ``C-`` stands
for control key, ``M-`` for alt key, ``S-`` for shift key and ``C-M``
for control and alt key pressed together.  For instance ``C-n`` means
pressing ``n`` key while holding the control key.

=============================  ============================
Action                         Keys
=============================  ============================
move down                      down, j, C-n
move up                        up, k, C-p
next page                      page-down, space, C-v
previous page                  page-up, S-space, M-v
sura start                     home, C-a
sura end                       end, C-e

next sura                      C-M-n, C-j
choose sura                    c
previous sura                  C-M-p, C-k

next aya                       n
previous aya                   p
current aya                    .

append digit to number         digits; [0-9]
clear number                   escape, C-g
goto n-th aya                  a, return, M-g
goto the page before n-th aya  b, S-return, M-G
goto n-th sura                 s, C-return, C-M-g, s
goto n-th juz start            J, C-M-return, C-M-G

about                          r
quit                           q
=============================  ============================

Note ``n`` here means the number typed so far.  Actually by pressing
digits you prefix commands.  For instance pressing ``2`` followed by
``1`` and followed by ``C-M-return``, you tell noor to go to the start
of the 21st juz.

If no prefix is typed for prefixed commands, noor will ask it in a
dialog.


Configuration File
==================

You can specify configuration options in ``~/.noor`` file.  Here is
the list of all options with a short description for some of them::

  [common]
  # the translation file
  translation = /path/to/translation.file

  # should noor use arabic aya numbers
  arabic_numbers = 1

  # some fonts do not handle superscript alef correctly
  hide_superscript_alef = 1

  [gtk]
  # the font to use
  font = my font name 18 bgcolor:pink
  translation_font = my font name 14
  fgcolor = black
  bgcolor = white
  # should noor ask which sura to show if no argument is given
  ask_sura_at_start = 1
  # if you want to run a program when a sura is shown
  #sura_hook = myprogram

  [html]
  # the font to use
  font = my font name 5
  translation_font = my font name 4 fgcolor:444455
  fgcolor = black
  bgcolor = #DDDDFF

  [cgi]
  # the url noorcgi.py is mapped to in the server
  url = noorcgi.py


Note that "html" section of config file is applied to both *noorcgi*
and *noorhtmls* interfaces.


License
=======

This program is under the terms of GNU GPL (GNU General Public
License).  Have a look at ``COPYING`` file for more information.


Source Repository
=================

Noor uses Mercurial_ CMS:

* Main repo: http://noor.sourceforge.net/hg/noor

.. _Mercurial: http://selenic.com/mercurial


Contributing
============

Patches to noor's code are welcome.

Patch style:

* Follow :PEP:`8`.
* Use four spaces for indentation.

You can submit your patches and discuss your ideas in the
`noor-dev [at] googlegroups.com`_ mailing list.

.. _noor-dev [at] googlegroups.com:
   http://groups.google.com/group/noor-dev


Thanks
======

Special thanks to Zekr_ project for their nice program.