README: Convert to markdown

doc/python-syntax.txt

@@ -3,20 +3,21 @@
 ===============================================================================
 Introduction                          *python-syntax* *ft-python-syntax* *python.vim*
 
-This is an enhanced version of the original Python syntax highlighting script. Based on
-`python.vim` from Vim 6.1 distribution by Neil Schemenauer.
+This is an enhanced version of the original Vim 6.1 Python syntax highlighting
+`python.vim` by Neil Schemenauer.
 
 Features
 --------
 
 * Added support for Python 3 syntax highlighting
-* Added commands `Python2Syntax` and `Python3Syntax` commands which allow to switch
-  between Python 2 and Python 3 syntaxes respectively without reloads/restarts
+* Added commands `Python2Syntax` and `Python3Syntax` allowing to easily switch
+  between Python 2 and Python 3.
 * Updated string highlighting
 * Enhanced special symbols highlighting inside strings
 * Enhanced highlighting of numeric constants
 * Added optional highlighting for %-formatting inside strings
-* Added highlighting for magic comments: source code encoding and #! (executable) strings
+* Added highlighting for magic comments: source code encoding and
+  shebangs (`#!`)
 * Added highlighting for new exceptions and builtins
 * Added highlighting for doctests
 * Added highlighting for new `@decorator` syntax introduced in Python 2.4a2
@@ -26,68 +27,78 @@ Features
   * Invalid numeric constants
   * Invalid %-formatting inside strings
   * Invalid variable names
-  * Trailing spaces (triggered by the `python_highlight_space_errors` option)
+  * Trailing spaces (Enabled with `g:python_highlight_space_errors`)
 
-Folding is done by the plugin `SimpylFold` (`https://github.com/tmhedberg/SimpylFold`)
+Folding is done by the plugin SimpylFold
+(https://github.com/tmhedberg/SimpylFold).
 
 ===============================================================================
 Configuration                                       *python-syntax-configuration*
 
-Enable option with: >
+Option variables
+----------------
 
-    let VARIABLE = 1
-<
-Disable option with: >
+Set variable to `1` to enable or `0` to disable.
 
-    let VARIABLE = 0
-<
 For example to enable all syntax highlighting features you can add the
 following command to your `~/.config/nvim/init.vim` or `~/.vimrc`: >
 
     let g:python_highlight_all = 1
 <
--------------------------------------------------------------------------------
-Select Python version                                     *python-syntax-version*
 
-`g:python_version_2` or `b:python_version_2`
-    Enable highlighting for Python 2 (Python 3 highlighting is enabled by
-    default).
+`g:python_version_2` (default `0`)
+    Python 2 mode
 
-Commands to easily switch between modes:
+`b:python_version_2` (default `0`)
+    Python 2 mode (buffer local)
+
+`g:python_highlight_builtins` (default `0`)
+    Highlight builtin functions and objects
+
+`g:python_highlight_builtins` (default `0`)
+    Highlight builtin functions and objects
+
+`g:python_highlight_builtin_objs` (default `0`)
+    Highlight builtin objects only
+
+`g:python_highlight_builtin_funcs` (default `0`)
+    Highlight builtin functions only
+
+`g:python_highlight_exceptions` (default `0`)
+    Highlight standard exceptions
+
+`g:python_highlight_string_formatting` (default `0`)
+    Highlight `%` string formatting
+
+`g:python_highlight_string_format` (default `0`)
+    Highlight syntax of `str.format` syntax
+
+`g:python_highlight_string_templates` (default `0`)
+    Highlight syntax of `string.Template`
+
+`g:python_highlight_indent_errors` (default `0`)
+    Highlight indentation errors
+
+`g:python_highlight_space_errors` (default `0`)
+    Highlight trailing spaces
+
+`g:python_highlight_doctests` (default `0`)
+    Highlight doc-tests
+
+`g:python_highlight_all` (default `0`)
+    Enable all highlight options above, except for previously set.
+
+`g:python_highlight_file_headers_as_comments` (default `0`)
+    Highlight shebang and coding headers as comments
+
+`g:python_slow_sync` (default `1`)
+    Disable for slow machines
+
+Commands
+--------
 
 `Python2Syntax`
     Switch to Python 2
+
 `Python3Syntax`
     Switch to Python 3
-
--------------------------------------------------------------------------------
-Option variables                  *python-syntax-options* *python-syntax-variables*
-
-`g:python_highlight_builtins`
-    Highlight builtin functions and objects
-`g:python_highlight_builtin_objs`
-    Highlight builtin objects only
-`g:python_highlight_builtin_funcs`
-    Highlight builtin functions only
-`g:python_highlight_exceptions`
-    Highlight standard exceptions
-`g:python_highlight_string_formatting`
-    Highlight `%` string formatting
-`g:python_highlight_string_format`
-    Highlight syntax of `str.format` syntax
-`g:python_highlight_string_templates`
-    Highlight syntax of `string.Template`
-`g:python_highlight_indent_errors`
-    Highlight indentation errors
-`g:python_highlight_space_errors`
-    Highlight trailing spaces
-`g:python_highlight_doctests`
-    Highlight doc-tests
-`g:python_print_as_function`
-    Highlight `print` statement as function for Python 2
-`g:python_highlight_file_headers_as_comments`
-    Highlight shebang and coding headers as comments
-`g:python_highlight_all`
-    Enable all the options above - NOTE: Doesn't override any previously set options
-`g:python_slow_sync`
-    Disable for slow machines