Merge pull request #1 from adambard/master

Merge from original adambard

1 files changed, 33 insertions, 25 deletions

diff --git a/rst.html.markdown b/rst.html.markdown
index 161a0610..56d54501 100644
--- a/rst.html.markdown
+++ b/rst.html.markdown
@@ -1,13 +1,14 @@
 ---
-language: restructured text
+language: restructured text (RST)
 contributors:
     - ["DamienVGN", "https://github.com/martin-damien"]
+    - ["Andre Polykanine", "https://github.com/Oire"]
 filename: restructuredtext.rst
 ---
 
-RST is file format formely created by Python community to write documentation (and so, is part of Docutils).
+RST, Restructured Text, is a file format created by the Python community to write documentation. It is part of [Docutils](https://docutils.sourceforge.io/rst.html).
 
-RST files are simple text files with lightweight syntaxe (comparing to HTML).
+RST is a markdown language like HTML but is much more lightweight and easier to read.
 
 
 ## Installation
@@ -20,48 +21,55 @@ To use Restructured Text, you will have to install [Python](http://www.python.or
 $ easy_install docutils
 ```
 
-If your system have `pip`, you can use it too:
+If your system has `pip`, you can use it too:
 
 ```bash
 $ pip install docutils
 ```
 
 
-## File syntaxe
+## File syntax
 
 A simple example of the file syntax:
 
-```rst
-.. Line with two dotes are special commands. But if no command can be found, the line is considered as a comment
+```
+.. Lines starting with two dots are special commands. But if no command can be found, the line is considered as a comment
 
 =========================================================
 Main titles are written using equals signs over and under
 =========================================================
 
-Note that theire must be as many equals signs as title characters.
+Note that each character, including spaces, needs an equals sign above and below.
 
-Title are underlined with equals signs too
-==========================================
+Titles also use equals signs but are only underneath
+====================================================
 
 Subtitles with dashes
 ---------------------
 
-And sub-subtitles with tilde
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+You can put text in *italic* or in **bold**, you can "mark" text as code with double backquote ``print()``.
+
+Special characters can be escaped using a backslash, e.g. \\ or \*.
 
-You can  put text in *italic* or in **bold**, you can "mark" text as code with double backquote ``: ``print()``.
+Lists are similar to Markdown, but a little more involved.
 
-Lists are as simple as markdown:
+Remember to line up list symbols (like - or \*) with the left edge of the previous text block, and remember to use blank lines to separate new lists from parent lists:    
 
 - First item
 - Second item
-    - Sub item
+
+  - Sub item
+    
+- Third item
 
 or
 
 * First item
 * Second item
-    * Sub item
+    
+  * Sub item
+
+* Third item
 
 Tables are really easy to write:
 
@@ -72,22 +80,22 @@ France      Paris
 Japan       Tokyo
 =========== ========
 
-More complexe tabless can be done easily (merged columns and/or rows) but I suggest you to read the complete doc for this :)
+More complex tables can be done easily (merged columns and/or rows) but I suggest you to read the complete doc for this :)
 
-Their is multiple ways to make links:
+There are multiple ways to make links:
 
-- By adding an underscore after a word : Github_ and by adding the target after the text (this have the advantage to not insert un-necessary URL inside the readed text).
-- By typing a full comprehensible URL : https://github.com/ (will be automatically converted in link)
-- By making a more "markdown" link: `Github <https://github.com/>`_ .
+- By adding an underscore after a word : Github_ and by adding the target URL after the text (this way has the advantage of not inserting unnecessary URLs in the visible text).
+- By typing a full comprehensible URL : https://github.com/ (will be automatically converted to a link)
+- By making a more Markdown-like link: `Github <https://github.com/>`_ .
 
-.. _Github https://github.com/
+.. _Github: https://github.com/
 
 ```
 
 
-## How to use it
+## How to Use It
 
-RST comes with docutils in which you have `rst2html` for exemple:
+RST comes with docutils where you have `rst2html`, for example:
 
 ```bash
 $ rst2html myfile.rst output.html
@@ -95,7 +103,7 @@ $ rst2html myfile.rst output.html
 
 *Note : On some systems the command could be rst2html.py*
 
-But their is more complexe applications that uses RST file format:
+But there are more complex applications that use the RST format:
 
 - [Pelican](http://blog.getpelican.com/), a static site generator
 - [Sphinx](http://sphinx-doc.org/), a documentation generator