Transform to reStructuredText
Because the Markdown language no longer satisfy my requirements, I started to learn reStructuredText,
another markup language initially built for writing python documentation just like in javadoc or etc.
I have already given up reStructuredText and switched back to markdown. Thus this file will not be udpated.
It is not that markdown has been updated with more features. It is because reStructuredText relies on too many external packages, and it is not popular enough to give us easy access on all platforms and web browsers. For example, the edito ReText (mentioned below) is complicated to setup on windows. Also, there is no firefox plugin to view reStructuredText. All these violates the principle of K.I.S.S. and I decided to fall back to markdown. If needed, I will write sophisticated documents using Latex and publish the pdf output.
Prepare some Editors
Because I have an Windows 8 OS on my PC, there is much trouble to get me some ready-to-use reStructuredText
editors. After some search, found:
- ReText, a WYSIWYG reStructuredText editor (also supports
Markdown, what a surprise!)
- Online reStructuredText Editor, well, Internet is a great tool for those who
does not want to bother installing software. But for me, Internet access sometimes could be troublesome.
- Also MarkItUp, a universal markup jQuery editor. I don't know
jQuery but this is interesting.
ReText is written in python using PyQT4, so theoretically it could run on any OS. It could be downloaded
from sourceforge's homepage, or from git.
python — we recommend using version 3.2 or higher
- Install python(Skipped);
There exits PyQT4 Windows installers :Find it here. Be careful to choose the corresponding edition.
Follow the installation guide and installing could be just "clicks".
easy_install -i http://pypi.douban.com/simple/ markups
-i http://pypi.douban.com/simple/ for better speed in China.
Some recommended packages in README
We also recommend having these packages installed:
Since installation maybe just a line of code
pip install xxx or
easy_install xxx, I skipped this part.
Running a python program is simple. After downloading and unpackaging the source code, you just have you tell python to start this program by:
Then everything done and enjoy it.
After words: To be honest, ReText is really ... too simple, the real time display is too troublesome - you have to scroll the webpage yourself to go to the editing place. Even the online editor (metioned above) is far better.
Ubuntu PPA Source
PPA Link: PPA for Dmitry Shachnev
HowTo Add PPA Source?
sudo add-apt-repository ppa:user/ppa-name
sudo apt-get update
sudo apt-get install xxx
sudo add-apt-repository ppa:mitya57/ppa
sudo apt-get update
sudo apt-get install
ReText is provided in ubuntu source, there is no need to add extra ppa-source!
python3-markups (version 0.3-1) will be installed
python3-pyqt4 (version 4.10.3-1ubuntu1) will be installed
python3-sip (version 4.15.2-1ubuntu1) will be installed
retext (version 4.1.0-1) will be installed
However, extra packages are required to parse files.Please choose the right version of package. For example, following package does not meet the requirements:
docutils-common (version 0.11-2) will be installed
python-docutils (version 0.11-2) will be installed
python-enchant (version 1.6.5-2build1) will be installed
python-markdown (version 2.3.1-1) will be installed
python-roman (version 1.4.0-2ubuntu1) will be installed
Instead, I should install the version for python 3:
Compared with Markdown, reStructuredText is rather big and comprehensive. There are many good documents to read, I personally suggest:
- A quick start
- The Quick Reference
- And crack the Cheat Sheet
- A good Introduction in Chinese reStructuredText简明教程
- Another Introduction in Chinese reStructuredText 简明教程
There are comments.