Browse Source

Add README file

Dmitry Vasiliev 6 years ago
parent
commit
40456e7708
1 changed files with 135 additions and 0 deletions
  1. 135
    0
      README.rst

+ 135
- 0
README.rst View File

@@ -0,0 +1,135 @@
1
+Python syntax highlighting script for Vim
2
+=========================================
3
+
4
+.. contents::
5
+
6
+About
7
+-----
8
+
9
+Enhanced version of the original Python syntax highlighting script. Based on
10
+``python.vim`` from Vim 6.1 distribution by Neil Schemenauer (nas at python dot
11
+ca). Check also `python.vim page on vim.org
12
+<http://www.vim.org/scripts/script.php?script_id=790>`_.
13
+
14
+Please use the following channels for reporting bugs, offering suggestions or
15
+feedback:
16
+
17
+- python.vim issue tracker: https://github.com/hdima/python-syntax/issues
18
+- Email: Dmitry Vasiliev (dima at hlabs.org)
19
+- Send a message or follow me for updates on Twitter: `@hdima
20
+  <https://twitter.com/hdima>`__
21
+
22
+Features
23
+--------
24
+
25
+Changes from the original ``python.vim`` are:
26
+
27
+- Added support for Python 3 syntax highlighting
28
+- Added ``:Python2Syntax`` and ``:Python3Syntax`` commands which allow to
29
+  switch between Python 2 and Python 3 syntaxes respectively without
30
+  reloads/restarts
31
+- Updated strings highlighting
32
+- Enhanced special symbols highlighting inside strings
33
+- Enhanced highlighting of numeric constants
34
+- Added optional highlighting for %-formatting inside strings
35
+- Added highlighting for magic comments: source code encoding and #!
36
+  (executable) strings
37
+- Added highlighting for new exceptions and builtins
38
+- Added highlighting for doctests
39
+- Added highlighting for new ``@decorator`` syntax introduced in Python 2.4a2
40
+- Added highlighting for the following errors:
41
+
42
+  - invalid symbols in source file
43
+  - mixing spaces and tabs
44
+  - invalid numeric constants
45
+  - invalid %-formatting inside strings
46
+  - invalid variable names
47
+  - trailing spaces (triggered by the ``python_highlight_space_errors`` option)
48
+
49
+Some of these features was later backported into the original ``python.vim``.
50
+
51
+How to install
52
+--------------
53
+
54
+The easiest installation method is to place `syntax/python.vim
55
+<https://github.com/hdima/python-syntax/blob/master/syntax/python.vim>`_ script
56
+into your ``~/.vim/syntax/`` directory.
57
+
58
+You can also use `Pathogen <https://github.com/tpope/vim-pathogen>`_ or `Vundle
59
+<https://github.com/gmarik/vundle>`_ plugin managers in which case you can
60
+install the whole `python.vim repository
61
+<https://github.com/hdima/python-syntax>`_ into the corresponding plugins
62
+directory.
63
+
64
+Script options
65
+--------------
66
+
67
+There are two commands to enable or disable an option:
68
+
69
+``:let OPTION_NAME = 1``
70
+  Enable option
71
+``:let OPTION_NAME = 0``
72
+  Disable option
73
+
74
+For example to enable all syntax highlighting features you can place the
75
+following command in your ``~/.vimrc`` script::
76
+
77
+  let python_highlight_all = 1
78
+
79
+Option and commands to select Python version
80
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
81
+
82
+``python_version_2``
83
+  Enable highlighting for Python 2 (Python 3 highlighting is enabled by
84
+  default). Can also be set as a local to buffer ``b:python_version_2``
85
+  variable.
86
+
87
+The following local to buffer commands can be used to switch between two
88
+highlighting modes:
89
+
90
+``:Python2Syntax``
91
+  Switch to Python 2 highlighting mode
92
+``:Python3Syntax``
93
+  Switch to Python 3 highlighting mode
94
+
95
+Options used by the script
96
+~~~~~~~~~~~~~~~~~~~~~~~~~~
97
+
98
+``python_highlight_builtins``
99
+  Highlight builtin functions and objects
100
+``python_highlight_builtin_objs``
101
+  Highlight builtin objects only
102
+``python_highlight_builtin_funcs``
103
+  Highlight builtin functions only
104
+``python_highlight_exceptions``
105
+  Highlight standard exceptions
106
+``python_highlight_string_formatting``
107
+  Highlight ``%`` string formatting
108
+``python_highlight_string_format``
109
+  Highlight syntax of ``str.format`` syntax
110
+``python_highlight_string_templates``
111
+  Highlight syntax of ``string.Template``
112
+``python_highlight_indent_errors``
113
+  Highlight indentation errors
114
+``python_highlight_space_errors``
115
+  Highlight trailing spaces
116
+``python_highlight_doctests``
117
+  Highlight doc-tests
118
+``python_print_as_function``
119
+  Highlight ``print`` statement as function for Python 2
120
+``python_highlight_all``
121
+  Enable all the options above. *NOTE: This option don't override any
122
+  previously set options*
123
+``python_slow_sync``
124
+  Can be set to 0 for slow machines
125
+
126
+Contributors
127
+------------
128
+
129
+- Jeroen Ruigrok van der Werven
130
+- Pedro Algarvio
131
+- John Eikenberry
132
+- Caleb Adamantine
133
+- Andrea Riciputi
134
+- Anton Butanaev
135
+- Marc Weber