noor / README.txt

 Noor, A python Quran viewer


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:
.. _PyGTK:
.. _Python:

New Features

* added sura hook for executing a command when a sura is shown

When a new sura is shown the hook is run (see `adding sura hooks`_
section).  These hooks can be used to play sura recitation, for
instance (see ``contrib/playsura`` script).

Getting Started


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 ```` 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 install`` to install
Noor.  After that you'll be able to run ```` in the terminal
from any location.


The noorhtmls interface can be used to output quran in html files in a
directory.  All you should do is to run:: 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.


Installing the CGI script, ````, 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 ```` file which looks like::

  # Add noor to the python path if its not installed:

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

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

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

Adding Translations

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

  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 or it can be a
utf-8 text file with translation of each aya in one line.

.. _Zekr:

Changing Font

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

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

  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

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

Adding Sura Hooks

Sura hooks are specified in ``~/.noor`` file and are run when a new
sura is shown in noorgtk.  The first argument of a hook is sura
number.  You can use noor's sura hook to start playing quran
recitation when noorgtk shows a sura.  Hook can be specified like::

  sura_hook = myprogram

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

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, n
move up                        up, k, C-p, 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

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

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::

  # 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; you can
  # replace them with fatha
  replace_superscript_alef_with_fatha = 1

  # 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

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

  # the url is mapped to in the server
  url =

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


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:

.. _Mercurial:


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]`_ mailing list.

.. _noor-dev [at]


Special thanks to Zekr_ project for their nice program.