Issue #2000370 by benjifisher: In D8, .info files are now .info.yml files.
[project/vimrc.git] / README.txt
1 Vim configuration files for Drupal developers
2
3 The files in this directory are designed to make it easier for Drupal developers
4 to edit files using vim.
5
6 The home page for this project is http://drupal.org/project/vimrc, and the main
7 documentation page is http://drupal.org/node/1389006. Once the project is
8 installed, you can read the local documentation from within vim with
9         :help drupal
10
11 INSTALLATION WITH DRUSH
12
13 This is the recommended method. Drush will download this project to
14 ~/.drush/vimrc (or to /usr/share/drush/commands/vimrc--see `drush help dl`).
15 Then the installation script will install Pathogen, if needed, and continue as
16 described below. You can install to another directory if you prefer. From a
17 command line,
18         $ drush @none dl vimrc
19         $ drush help vimrc-install
20         $ drush -v vimrc-install <options>
21 If the drush version is at least 5.5, then the recommended plugins will be
22 installed in the bundle/ subdirectry of your vimfiles directory.
23
24 INSTALLATION WITH PATHOGEN
25
26 Pathogen (http://www.vim.org/scripts/script.php?script_id=2332) is a package
27 manager for vim. If you already have Pathogen installed, then put these files
28 wherever you like and add
29         :call pathogen#infect('path/to/vimrc/bundle')
30 near the top of your vimrc file (~/.vim or $HOME\_vimrc on Windows). Another
31 option is to make a symbolic link to the bundle/ directory under your vimfiles
32 directory. Explicitly,
33         $ mkdir ~/.vim/bundle
34         $ ln -s path/to/vimrc/bundle/vim-plugin-for-drupal ~/.vim/bundle
35 In this case, add the line
36         :call pathogen#infect()
37 to your vimrc file if it is not already there.
38
39 In either case, use the command
40         :Helptags
41 to install the included help file.
42
43 For more details, see bundle/vim-plugin-for-drupal/doc/drupal.txt .
44
45 BASIC INSTALLATION (without pathogen)
46
47 Copy the files from the bundle/vim-plugin-for-drupal/ subdirectory into your
48 vimfiles directory.  For most users, your vimfiles directory is ~/.vim; on
49 Windows, it is ~\vimfiles by default.  From within vim, use
50
51 :help vimfiles
52
53 for details.  If you have downloaded these files as vimrc.tar.gz and your
54 vimfiles directory is ~/.vim, then this should work on UNIX-like systems:
55
56 $ cd ~/.vim
57 $ tar xzf path/to/vimrc.tar.gz --strip-components 3 \
58   vimrc/bundle/vim-plugin-for-drupal
59
60 Note:  if there are filename conflicts, then tar will silently overwrite the
61 existing files.
62
63 When you are done, you should have the following directory structure inside your
64 vimfiles directory:
65
66         autoload/drupal.vim
67         compiler/coder.vim
68         doc/drupal.txt
69         ftdetect/drupal.vim
70         ftplugin/drini.vim
71         ftplugin/drupal.vim
72         plugin/drupal.vim
73         snipmate/drupal/php.snippets
74         snipmate/drupal6/php.snippets
75         snipmate/drupal7/php.snippets
76         syntax/drini.vim
77         syntax/drupal.vim
78         tagfiles/drupal6.tags
79         tagfiles/drupal7.tags
80         tagfiles/drupal8.tags
81
82 In order to use the tags defined in the help file, start vim and do
83         :helptags ~/.vim/doc
84 (assuming that the file is installed as ~/.vim/doc/drupal.txt).  See
85         :help add-local-help
86 for details.  After this step, you should be able to read the documentation with
87         :help drupal.txt
88
89 AUTOCOMPLETION IN .INFO FILES
90
91 The drini (DRupal INI) filetype is used for .info and similar files.  The
92 syntax/drini.vim included in this project defines keywords that can be
93 auto-completed using syntaxcomplete.vim, but this requires version 8.0 of that
94 script.  Version 7.0 is included in the vim 7.3 distribution (in the autoload/
95 directory) and is also available from
96 http://www.vim.org/scripts/script.php?script_id=3172 .  As of late 2011, the
97 only way to get version 8.0 is to patch version 7.0 with the patch at
98 http://drupal.org/node/1303122#comment-5213300 .
99
100 UPDATES AND SUPPORT
101
102 For the latest version of this project, see http://drupal.org/project/vimrc .
103 To file a bug report or feature request, see the corresponding issues queue:
104 http://drupal.org/project/issues/vimrc?status=All&categories=All
105
106 TROUBLESHOOTING
107
108 * If :help does not work:
109
110 If :help does not work in your installation of vim, you can find the official
111 vim documentation on-line at http://vimdoc.sourceforge.net/ .  It may be that
112 you have only a vim executable and not the "runtime" support files.
113
114 * If nothing works:
115
116 Some shared servers install a "tiny" version of Vim.  Many features of this
117 project will not work with such a version.  (See below for details.)  Check your
118 version of vim from a shell with
119
120 $ vim --version
121
122 The fourth line of output should tell you what sort of version you have.
123
124 It is possible to get a lot of the functionallity provided by the Drupal-Vim
125 plugins working with the tiny-vim by creating a vimrc file based on the contents
126 of the plugins.
127
128 * Creating the vimrc file
129
130 There are two methods to create the required vimrc file:
131
132 1) On Linux or Mac OS X, go to the directory where you have the files from this
133 project and from the subdirectory bundle/vim-plugin-for-drupal/ do
134
135 $ cat plugin/drupal.vim ftplugin/php_drupal.vim >> ~/.vimrc
136
137 This will add the contents of the two files to your vimrc file.
138 NOTE: Windows users should use ~\vimfiles instead of ~/.vimrc.  You will
139 probably need a method other than cat.
140
141 2) Create a vimrc file and add these two lines inside it:
142         source path/to/vimrc/bundle/vim-plugin-for-drupal/plugin/drupal.vim
143         source path/to/vimrc/bundle/vim-plugin-for-drupal/ftplugin/php_drupal.vim
144 NOTE: Where path/to/vimrc is where you extracted the contents of this project.
145
146 * Info on tiny-vim
147
148 You can find the original discussion here: http://drupal.org/node/1326562
149 This tiny-vim was found on a shared CentOS server and it identifies itself as:
150 ========================================================================
151 VIM - Vi IMproved 7.0 (2006 May 7, compiled Mar 5 2011 21:36:07)
152  Included patches: 1, 3-4, 7-9, 11, 13-17, 19-26, 29-31, 34-44, 47, 50-56,
153 58-64, 66-73, 75, 77-92, 94-107, 109, 202, 234-237
154  Compiled by
155  Tiny version without GUI.
156 ...
157 ========================================================================
158 Notice the fourth line!
159
160 Known to work on the tiny-vim are:
161 * Line numbers
162 * Multiple Undos
163 * Arrow keys are usable in Insert mode
164
165 Known NOT to work and their workarounds (if any):
166 * Vim Help, aka :help command. Luckily for us there is
167 http://vimdoc.sourceforge.net/
168 * Color/syntax highlighting
169 * Persistent Undo (introduced in Vim7.3, so a tiny 7.3 might have this feature)
170
171 Please help make this troubleshooting section better either by enriching it
172 yourself or by posting on the issue queue:
173 http://drupal.org/project/issues/vimrc.