Source

noor / README.txt

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

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

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

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


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

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

  # should noor use arabic aya numbers
  arabic_numbers = 1

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

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