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

* New noorgtk look
* Added ``noorgtk.translation_font``
* Specifying more attributes in font options
* Arabic juz start signs when ``common.arabic_numbers`` is set
* Creating ``~/.noor`` if it does not exist

See the `configuration file`_ section for the description of new
options.  Also see `changing font`_ section for more information
about the new style of font options.

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

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 = homa 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

noorgtk keys

These keys can be used in the GTK interface for moving the text.  Note
that ``C-`` stands for control key, ``M-`` for alt key and ``S-`` for
shift key.

================  ============================
Action            Keys
================  ============================
move down         down, j, C-n
move up           up, k, C-p
next page         page-down, space, C-v, PgUp
previous page     page-up, S-space, M-v, PgDn
quit              q
================  ============================

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

  # the font to use
  font = my font name 18 bgcolor:pink
  translation_font = my font name 14
  fgcolor = black
  bgcolor = white

  # 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.