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

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.


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.


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

  [gtk]
  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
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; you can
  # replace them with fatha
  replace_superscript_alef_with_fatha = 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.