update doc and spec

INSTALL.md

@@ -6,26 +6,26 @@
 
 3. Install Linux tools on local machine.
 ```bash
-    sudo apt-get update
-    sudo apt-get install git-all
-    sudo apt-get install gettext
-    sudo apt-get install python-webpy
-    sudo apt-get install python-jinja2
-    sudo apt-get install python-lxml
+    $ sudo apt-get update
+    $ sudo apt-get install git-all
+    $ sudo apt-get install gettext
+    $ sudo apt-get install python-webpy
+    $ sudo apt-get install python-jinja2
+    $ sudo apt-get install python-lxml
 ```
 
 4. (optional) Install [Open Chinese Convert](https://code.google.com/p/opencc/) and [pyOpenCC](https://pypi.python.org/pypi/pyopencc) to convert between Traditional Chinese and Simplified Chinese.
 ```bash
     # install pyopencc (on Ubuntu 13.04)
-    sudo apt-get install libopencc-dev python-dev
-    git clone https://github.com/cute/pyopencc.git
-    cd pyopencc
-    python setup.py build_ext -I /usr/include/opencc/
-    sudo python setup.py install
+    $ sudo apt-get install libopencc-dev python-dev
+    $ git clone https://github.com/cute/pyopencc.git
+    $ cd pyopencc
+    $ python setup.py build_ext -I /usr/include/opencc/
+    $ sudo python setup.py install
 ```
 
    Usage Example:
-```bash
+```python
     import pyopencc
     cc = pyopencc.OpenCC('zhs2zht.ini')
     Traditional_Chinese_string = cc.convert(Simplified_Chinese_string)

SPEC.md

@@ -36,20 +36,22 @@ Besides, in the settings of the website, options should be provided to users to
 
 ### Current Implementation
 
-The following 6 pathes are root pathes, and the sub-structures of the root pathes are the same.
-<strong>/</strong>
-<strong>/zh_TW/</strong>
-<strong>/zh_CN/</strong>
-<strong>/en_US/</strong>
-<strong>/fr_FR/</strong>
-<strong>/vi_VN/</strong>
+The following 6 pathes are top-level pathes, and the sub-structures of the top-level pathes are the same.
+
+* <strong>/</strong>
+* <strong>/zh_TW/</strong>
+* <strong>/zh_CN/</strong>
+* <strong>/en_US/</strong>
+* <strong>/fr_FR/</strong>
+* <strong>/vi_VN/</strong>
 
 The only difference in above 6 pathes is that <strong>/</strong> will detect http ACCEPT_LANGUAGES header and show corresponding {{ locale }} language of the website, if the {{ locale }} language is not supported, then English (en_US) is shown by default. Pathes start with <strong>/{{ locale }}/</strong> will show corresponding {{ locale }} language of the website, regardless of the http ACCEPT_LANGUAGES header.
 
 In <strong>/</strong>, there are links pointing to <strong>/browse/{{ first_char_of_pali_word }}</strong>, the possible first character of Pali words are:
+
 ['a', 'ā', 'b', 'c', 'd', 'ḍ', 'e', 'g', 'h', 'i', 'ī', 'j', 'k', 'l', 'ḷ', 'm', 'ŋ', 'n', 'ñ', 'ṅ', 'ṇ', 'o', 'p', 'r', 's', 't', 'ṭ', 'u', 'ū', 'v', 'y', '-', '°']
 
-Under <strong>/browse/{{ first_char_of_pali_word }}</strong>, there are links to words starting with the same first character. For example, there are 30,000+ words starting with "a".
+Under <strong>/browse/{{ first_char_of_pali_word }}</strong>, there are links to words starting with the same first character. For example, there are more than 30,000 words starting with "a".
 
 Every Pali word should a unique URL. For example, the URL of the word 'sacca' is <strong>/browse/s/sacca</strong>.
 

docs/AWS.md

@@ -8,38 +8,38 @@ For AMI image, choose 'Ubuntu Server 12.04.1 LTS'. Attche one Elastic IP address
 
 ```bash
 # login to the instance by SSH
-ssh -i {{ key pair name }}.pem ubuntu@{{ Elastic IP Address }}
+$ ssh -i {{ key pair name }}.pem ubuntu@{{ Elastic IP Address }}
 
 # upgrade system
-sudo apt-get update
+$ sudo apt-get update
 
 # install apache2 and mod_wsgi
-sudo apt-get install libapache2-mod-wsgi
-
-# install tool for installing and managing Python packages.
-sudo apt-get install python-setuptools
-sudo apt-get install python-pip
+$ sudo apt-get install libapache2-mod-wsgi
 
 # install python server-side library to run website.
-sudo apt-get install python-webpy
-#sudo pip install web.py
-sudo apt-get install python-jinja2
-#sudo pip install jinja2
-sudo apt-get install python-lxml
+$ sudo apt-get install python-webpy
+$ sudo apt-get install python-jinja2
+$ sudo apt-get install python-lxml
+
+# (optional) You can also install web.py and jinja2 by pip
+#$ sudo apt-get install python-setuptools
+#$ sudo apt-get install python-pip
+#$ sudo pip install web.py
+#$ sudo pip install jinja2
 
 # install git
-sudo apt-get install git-all
+$ sudo apt-get install git-all
 
 # install tools for i18n
-sudo apt-get install gettext
+$ sudo apt-get install gettext
 
 # install latest version of nodejs
-sudo add-apt-repository ppa:chris-lea/node.js
-sudo apt-get update
-sudo apt-get install nodejs
+$ sudo add-apt-repository ppa:chris-lea/node.js
+$ sudo apt-get update
+$ sudo apt-get install nodejs
 
 # install grunt
-sudo npm install -g grunt-cli
+$ sudo npm install -g grunt-cli
 ```
 
 References:

docs/CONTRAST_READING.md

@@ -1,33 +1,33 @@
 ### How to add more contrast (parallel) readings for tipitaka website?
 
-Answer: It is actually very easy to add more contrast readings of some specific language because this feature has been put in first priority in the beginning. First take a look at [CSCD directory](https://github.com/siongui/data/tree/master/pali/common/romn/cscd) at [data](https://github.com/siongui/data) repository. This directory contains all the Roman pali texts released by [The Pali Tipitaka](http://www.tipitaka.org/). The xml files in this directory are the <em>base</em> format of the translation. Then take a look at [translation directory](https://github.com/siongui/data/tree/master/pali/common/translation) at [data](https://github.com/siongui/data) repository. All available translations are sorted according to lagnauges, then sorted by translators in sub-directories.
+Answer: First take a look at [CSCD directory](https://github.com/siongui/data/tree/master/pali/common/romn/cscd) at [data](https://github.com/siongui/data) repository. This directory contains all the Roman pali texts released by [The Pali Tipitaka](http://www.tipitaka.org/). The xml files in this directory are the <strong><em>base</em></strong> format (i.e., template) of the translation. Then take a look at [translation directory](https://github.com/siongui/data/tree/master/pali/common/translation) at [data](https://github.com/siongui/data) repository. All available translations are sorted according to lagnauges, then sorted by translators in sub-directories.
 
-I will use the first chapter [Yamakavaggo](https://github.com/siongui/data/blob/master/pali/common/romn/cscd/s0502m.mul0.xml) of Dhammapada as example. One of the traditional chinese translation is available [here](https://github.com/siongui/data/blob/master/pali/common/translation/zh_TW/2/s0502m.mul0.xml). Take a look at the original pali texts and translated texts. You will find the texts inside the <em>p</em> tag are 1-to-1 mapping. So if you want to add contrast reading of Yamakavaggo of some specifice language, you can replace the texts inside the <em>p</em> tag with corresponding translated texts of the language. If translation of some lines are not available. Just leave the origianl pali texts unchanged. After finished, make a pull requests on [data](https://github.com/siongui/data) repository, or mail the translated xml file to me (siongui@gmail.com). It is recommended to release your work in public domain.
+I will use the first chapter [Yamakavaggo](https://github.com/siongui/data/blob/master/pali/common/romn/cscd/s0502m.mul0.xml) of Dhammapada as example. One of the Traditional Chinese translation is available [here](https://github.com/siongui/data/blob/master/pali/common/translation/zh_TW/2/s0502m.mul0.xml). Take a look at the original pali texts and translated texts. You will find the texts inside the <strong><em>p</em></strong> tag are 1-to-1 mapping. So if you want to add contrast reading of Yamakavaggo of some specifice language, first you copy [Yamakavaggo xml file](https://github.com/siongui/data/blob/master/pali/common/romn/cscd/s0502m.mul0.xml) to your working directory, then edit the xml file and replace the pali texts inside the <em>p</em> tag with corresponding translated texts of the language. If translation of some lines are not available, please leave the origianl pali texts unchanged. After finished, make a pull requests on [data](https://github.com/siongui/data) repository, or mail the translated xml file to me (siongui@gmail.com). It is recommended to release your work in public domain.
 
-Here another example is given. To translate the Akammaniyavaggo, the third vagga of AN 1. First take a look at [cscd dir](https://github.com/siongui/data/tree/master/pali/common/romn/cscd) on [data](https://github.com/siongui/data) repo. All templates to be translated are here, actually the xml files in this dir are orginal pali texts. The xml which contains Akammaniyavaggo is [s0401m.mul2.xml](https://github.com/siongui/data/blob/master/pali/common/romn/cscd/s0401m.mul2.xml) in this dir. Please copy this xml file to another directory and translate this file directly.
+Here another example is given. To translate the Akammaniyavaggo, the third vagga of AN 1. First take a look at [cscd directory](https://github.com/siongui/data/tree/master/pali/common/romn/cscd) on [data](https://github.com/siongui/data) repository. All templates to be translated are put here, actually the xml files in this directory are orginal pali texts. The xml file which contains Akammaniyavaggo is [s0401m.mul2.xml](https://github.com/siongui/data/blob/master/pali/common/romn/cscd/s0401m.mul2.xml) in this directory. Please copy this xml file to another directory and translate this file directly.
 
-The following is something you should know when translating:
+The following is what you may need to know when translating:
 
-1. <em>hi</em> tag: We suggest to respect this tag and the content inside, this marks the number of gatha or paragraph so the better choice is to respect it and do not modify it and the content inside.
+1. <strong><em>hi</em></strong> tag: We suggest to respect this tag and the content inside, this marks the number of gatha or paragraph so the better choice is to respect it and do not modify it and the content inside.
 
-2. <em>pb</em> tag: Not sure what this tag is for, usually this is removed in the translation.
+2. <strong><em>pb</em></strong> tag: Not sure what this tag is for, usually this is removed in the translation.
 
-3. use <em>note</em> tag to mark footnote: for example,
+3. use <strong><em>note</em></strong> tag to mark footnote: for example,
 ```xml
-<p><hi>...</hi> I am example <note>I am footnote of example</note> ...some other content here.... </p>
+<p><hi> ... </hi> I am example <note>I am footnote of example</note> </p>
 ```
    In original xml files of pali texts, VRI use <em>note</em> tag to mark different version of the canon. We can remove their note tag and use this note tag to mark the notes in translation.
 
-4. It is often the case that translators do not translate all of the pali texts in the xml file. Please leave the un-translated part <em>UNCHANGED</em>.
+4. It is often the case that translators do not translate all of the pali texts in the xml file. Please leave the un-translated part <strong><em>UNCHANGED</em></strong>.
 
 5. If & is used by translators in their translations, please escape it with <strong><em>\&amp;</em></strong>
 
-6. After you finish edit the xml file, please check the char encoding of your translated file by the following command in Ubuntu Linux:
+6. After you finish to edit the xml file, please check the char encoding of your translated file by the following command in Ubuntu Linux:
 ```bash
 $ cd dir_of_your_translated_xml_file
 $ chardet xml_file_name
 ```
-   If you see from the output that the encoding of the xml file is UTF-8, please the first line in xml file. Change UTF-16 to UTF-8 in the first line.
+   If you see from the output that the encoding of the xml file is UTF-8, please modify the first line in xml file. Change <strong>UTF-16</strong> to <strong>UTF-8</strong> in the first line.
 
-7. <em>br</em> tag is allowed in the xml.
+7. <strong><em>br</em></strong> tag is allowed in the xml file of translations.
 

docs/INSTALL_GAE.md

@@ -6,22 +6,22 @@
 
 3. Install Linux tools on local machine.
 ```bash
-    sudo apt-get install git-all
-    sudo apt-get install gettext
+    $ sudo apt-get install git-all
+    $ sudo apt-get install gettext
 ```
 
 4. (optional) Install [Open Chinese Convert](https://code.google.com/p/opencc/) and [pyOpenCC](https://pypi.python.org/pypi/pyopencc) to convert between Traditional Chinese and Simplified Chinese.
 ```bash
     # install pyopencc (on Ubuntu 13.04)
-    sudo apt-get install libopencc-dev python-dev
-    git clone https://github.com/cute/pyopencc.git
-    cd pyopencc
-    python setup.py build_ext -I /usr/include/opencc/
-    sudo python setup.py install
+    $ sudo apt-get install libopencc-dev python-dev
+    $ git clone https://github.com/cute/pyopencc.git
+    $ cd pyopencc
+    $ python setup.py build_ext -I /usr/include/opencc/
+    $ sudo python setup.py install
 ```
 
    Usage Example:
-```bash
+```python
     import pyopencc
     cc = pyopencc.OpenCC('zhs2zht.ini')
     Traditional_Chinese_string = cc.convert(Simplified_Chinese_string)

docs/README_GAE.md

@@ -59,6 +59,7 @@ Please [install necessary tools for development](INSTALL_GAE.md) before setting
 ```
 
 6. Create index of words in dictionary books.
+   After data files created, upload them to Google App Engine dev server:
 ```bash
     $ cd PALI_DIR/common/pytools/
     $ python dic1parseBooks.py
@@ -95,7 +96,8 @@ Please [install necessary tools for development](INSTALL_GAE.md) before setting
     $ python setTranslationData.py
 ```
 
-8. Create data files (<strong>PALI_DIR/tipitaka/app/js/treeviewAllJson-service.js</strong> and <strong>REPO_DIR/tipitaka/gaelibs/json/treeviewAll.json</strong>) used for Pāḷi Tipiṭaka and path of webpages of online Pāḷi Tipiṭaka website. After data files created, upload them to Google App Engine:
+8. Create data files used for Pāḷi Tipiṭaka and path of webpages of online Pāḷi Tipiṭaka website.
+   After data files created, upload them to Google App Engine dev server:
 ```bash
     $ cd PALI_DIR/common/pytools/
     $ python tpk1getTocs.py
@@ -120,7 +122,7 @@ Please [install necessary tools for development](INSTALL_GAE.md) before setting
     # http://localhost:8080/
 ```
 
-9. Deploy on [Google App Engine (Python)](https://developers.google.com/appengine/docs/python/gettingstartedpython27/uploading): Before deployment, please modify the application name at the first line in <i><b>PALI_DIR/tipitaka/app.yaml</b></i> and <i><b>REPO_DIR/dictionary/app.yaml</b></i>. 
+9. Deploy on [Google App Engine (Python)](https://developers.google.com/appengine/docs/python/gettingstartedpython27/uploading): Before deployment, please modify the application name to your app name at the first line in <i><b>PALI_DIR/tipitaka/app.yaml</b></i> and <i><b>REPO_DIR/dictionary/app.yaml</b></i>. 
 ```bash
     # deploy dictionary website
     $ cd PALI_DIR/dictionary

docs/TRANSLATION.md

@@ -1,3 +1,5 @@
-### How to make dictionay and tipitaka website to support my language?
+### How to make dictionay and tipitaka websites support my language?
 
-Answer: It is actually very easy to support new language because the websites are developed with internationalization in mind in the beginning. Fetch this [Traditional Chinese po file](https://github.com/siongui/pali/blob/master/common/locale/zh_TW/LC_MESSAGES/messages.po) to your computer. Lines that starts with <em>msgid</em> are the English texts, and Lines that starts with <em>msgstr</em> are corresponding translated texts of your language. If you want the website to support your language, put translated texts here. Then make pull requests at the [pali](https://github.com/siongui/pali) repository on the github, or mail the po file to the author (siongui@gmail.com). It is recommended to release your translation in public domain.
+Answer: Fetch this [Traditional Chinese po file](https://github.com/siongui/pali/blob/master/common/locale/zh_TW/LC_MESSAGES/messages.po) to your computer. Lines that starts with <em>msgid</em> are the English texts, and Lines that starts with <em>msgstr</em> are corresponding translated texts of your language. If you want the website to support your language, put translated texts here. Then make pull requests at the [pali](https://github.com/siongui/pali) repository on the github, or mail the po file to the author (siongui@gmail.com). It is recommended to release your translation in public domain.
+
+Note: Your translated po file must be put in appropriate [locale](http://www.roseindia.net/tutorials/I18N/locales-list.shtml) directory. For example, the po file contains Vietnamese translation must be put in <strong>common/locale/vi_VN/LC_MESSAGES/messages.po</strong>, and the po file contains French translation must be put in <strong>common/locale/fr_FR/LC_MESSAGES/messages.po</strong>.