|
237
|
1 *usr_30.txt* For Vim version 7.0aa. Last change: 2005 Apr 01
|
|
7
|
2
|
|
|
3 VIM USER MANUAL - by Bram Moolenaar
|
|
|
4
|
|
|
5 Editing programs
|
|
|
6
|
|
|
7
|
|
|
8 Vim has various commands that aid in writing computer programs. Compile a
|
|
|
9 program and directly jump to reported errors. Automatically set the indent
|
|
|
10 for many languages and format comments.
|
|
|
11
|
|
|
12 |30.1| Compiling
|
|
|
13 |30.2| Indenting C files
|
|
|
14 |30.3| Automatic indenting
|
|
|
15 |30.4| Other indenting
|
|
|
16 |30.5| Tabs and spaces
|
|
|
17 |30.6| Formatting comments
|
|
|
18
|
|
|
19 Next chapter: |usr_31.txt| Exploiting the GUI
|
|
|
20 Previous chapter: |usr_29.txt| Moving through programs
|
|
|
21 Table of contents: |usr_toc.txt|
|
|
|
22
|
|
|
23 ==============================================================================
|
|
|
24 *30.1* Compiling
|
|
|
25
|
|
|
26 Vim has a set of so called "quickfix" commands. They enable you to compile a
|
|
|
27 program from within Vim and then go through the errors generated and fix them
|
|
|
28 (hopefully). You can then recompile and fix any new errors that are found
|
|
|
29 until finally your program compiles without any error.
|
|
|
30
|
|
|
31 The following command runs the program "make" (supplying it with any argument
|
|
|
32 you give) and captures the results: >
|
|
|
33
|
|
|
34 :make {arguments}
|
|
|
35
|
|
|
36 If errors were generated, they are captured and the editor positions you where
|
|
|
37 the first error occurred.
|
|
237
|
38 Take a look at an example ":make" session. (Typical :make sessions generate
|
|
7
|
39 far more errors and fewer stupid ones.) After typing ":make" the screen looks
|
|
|
40 like this:
|
|
|
41
|
|
|
42 :!make | &tee /tmp/vim215953.err ~
|
|
|
43 gcc -g -Wall -o prog main.c sub.c ~
|
|
|
44 main.c: In function 'main': ~
|
|
|
45 main.c:6: too many arguments to function 'do_sub' ~
|
|
|
46 main.c: At top level: ~
|
|
|
47 main.c:10: parse error before '}' ~
|
|
|
48 make: *** [prog] Error 1 ~
|
|
|
49
|
|
|
50 2 returned ~
|
|
|
51 "main.c" 11L, 111C ~
|
|
|
52 (3 of 6): too many arguments to function 'do_sub' ~
|
|
|
53 Hit ENTER or type command to continue ~
|
|
|
54
|
|
|
55 From this you can see that you have errors in the file "main.c". When you
|
|
|
56 press <Enter>, Vim displays the file "main.c", with the cursor positioned on
|
|
|
57 line 6, the first line with an error. You did not need to specify the file or
|
|
|
58 the line number, Vim knew where to go by looking in the error messages.
|
|
|
59
|
|
|
60 +---------------------------------------------------+
|
|
|
61 |int main() |
|
|
|
62 |{ |
|
|
|
63 | int i=3; |
|
|
|
64 cursor -> | do_sub("foo"); |
|
|
|
65 | ++i; |
|
|
|
66 | return (0); |
|
|
|
67 |} |
|
|
|
68 |} |
|
|
|
69 | ~ |
|
|
|
70 |(3 of 12): too many arguments to function 'do_sub' |
|
|
|
71 +---------------------------------------------------+
|
|
|
72
|
|
|
73 The following command goes to where the next error occurs: >
|
|
|
74
|
|
|
75 :cnext
|
|
|
76
|
|
|
77 Vim jumps to line 10, the last line in the file, where there is an extra '}'.
|
|
|
78 When there is not enough room, Vim will shorten the error message. To see
|
|
|
79 the whole message use: >
|
|
|
80
|
|
|
81 :cc
|
|
|
82
|
|
|
83 You can get an overview of all the error messages with the ":clist" command.
|
|
|
84 The output looks like this: >
|
|
|
85
|
|
|
86 :clist
|
|
|
87 < 3 main.c: 6:too many arguments to function 'do_sub' ~
|
|
|
88 5 main.c: 10:parse error before '}' ~
|
|
|
89
|
|
|
90 Only the lines where Vim recognized a file name and line number are listed
|
|
|
91 here. It assumes those are the interesting lines and the rest is just boring
|
|
|
92 messages. However, sometimes unrecognized lines do contain something you want
|
|
|
93 to see. Output from the linker, for example, about an undefined function.
|
|
|
94 To see all the messages add a "!" to the command: >
|
|
|
95
|
|
|
96 :clist!
|
|
|
97 < 1 gcc -g -Wall -o prog main.c sub.c ~
|
|
|
98 2 main.c: In function 'main': ~
|
|
|
99 3 main.c:6: too many arguments to function 'do_sub' ~
|
|
|
100 4 main.c: At top level: ~
|
|
|
101 5 main.c:10: parse error before '}' ~
|
|
|
102 6 make: *** [prog] Error 1 ~
|
|
|
103
|
|
|
104 Vim will highlight the current error. To go back to the previous error, use:
|
|
|
105 >
|
|
|
106 :cprevious
|
|
|
107
|
|
|
108 Other commands to move around in the error list:
|
|
|
109
|
|
|
110 :cfirst to first error
|
|
|
111 :clast to last error
|
|
|
112 :cc 3 to error nr 3
|
|
|
113
|
|
|
114
|
|
|
115 USING ANOTHER COMPILER
|
|
|
116
|
|
|
117 The name of the program to run when the ":make" command is executed is defined
|
|
|
118 by the 'makeprg' option. Usually this is set to "make", but Visual C++ users
|
|
|
119 should set this to "nmake" by executing the following command: >
|
|
|
120
|
|
|
121 :set makeprg=nmake
|
|
|
122
|
|
|
123 You can also include arguments in this option. Special characters need to
|
|
|
124 be escaped with a backslash. Example: >
|
|
|
125
|
|
|
126 :set makeprg=nmake\ -f\ project.mak
|
|
|
127
|
|
|
128 You can include special Vim keywords in the command specification. The %
|
|
|
129 character expands to the name of the current file. So if you execute the
|
|
|
130 command: >
|
|
|
131 :set makeprg=make\ %
|
|
|
132
|
|
|
133 When you are editing main.c, then ":make" executes the following command: >
|
|
|
134
|
|
|
135 make main.c
|
|
|
136
|
|
|
137 This is not too useful, so you will refine the command a little and use the :r
|
|
|
138 (root) modifier: >
|
|
|
139
|
|
|
140 :set makeprg=make\ %:r.o
|
|
|
141
|
|
|
142 Now the command executed is as follows: >
|
|
|
143
|
|
|
144 make main.o
|
|
|
145
|
|
|
146 More about these modifiers here: |filename-modifiers|.
|
|
|
147
|
|
|
148
|
|
|
149 OLD ERROR LISTS
|
|
|
150
|
|
|
151 Suppose you ":make" a program. There is an warning message in one file and an
|
|
|
152 error message in another. You fix the error and use ":make" again to check if
|
|
|
153 it was really fixed. Now you want to look at the warning message. It doesn't
|
|
|
154 show up in the last error list, since the file with the warning wasn't
|
|
|
155 compiled again. You can go back to the previous error list with: >
|
|
|
156
|
|
|
157 :colder
|
|
|
158
|
|
|
159 Then use ":clist" and ":cc {nr}" to jump to the place with the warning.
|
|
|
160 To go forward to the next error list: >
|
|
|
161
|
|
|
162 :cnewer
|
|
|
163
|
|
|
164 Vim remembers ten error lists.
|
|
|
165
|
|
|
166
|
|
|
167 SWITCHING COMPILERS
|
|
|
168
|
|
|
169 You have to tell Vim what format the error messages are that your compiler
|
|
|
170 produces. This is done with the 'errorformat' option. The syntax of this
|
|
|
171 option is quite complicated and it can be made to fit almost any compiler.
|
|
|
172 You can find the explanation here: |errorformat|.
|
|
|
173
|
|
|
174 You might be using various different compilers. Setting the 'makeprg' option,
|
|
|
175 and especially the 'errorformat' each time is not easy. Vim offers a simple
|
|
|
176 method for this. For example, to switch to using the Microsoft Visual C++
|
|
|
177 compiler: >
|
|
|
178
|
|
|
179 :compiler msvc
|
|
|
180
|
|
|
181 This will find the Vim script for the "msvc" compiler and set the appropriate
|
|
|
182 options.
|
|
|
183 You can write your own compiler files. See |write-compiler-plugin|.
|
|
|
184
|
|
|
185
|
|
|
186 OUTPUT REDIRECTION
|
|
|
187
|
|
|
188 The ":make" command redirects the output of the executed program to an error
|
|
|
189 file. How this works depends on various things, such as the 'shell'. If your
|
|
|
190 ":make" command doesn't capture the output, check the 'makeef' and
|
|
|
191 'shellpipe' options. The 'shellquote' and 'shellxquote' options might also
|
|
|
192 matter.
|
|
|
193
|
|
|
194 In case you can't get ":make" to redirect the file for you, an alternative is
|
|
|
195 to compile the program in another window and redirect the output into a file.
|
|
|
196 Then have Vim read this file with: >
|
|
|
197
|
|
|
198 :cfile {filename}
|
|
|
199
|
|
|
200 Jumping to errors will work like with the ":make" command.
|
|
|
201
|
|
|
202 ==============================================================================
|
|
|
203 *30.2* Indenting C files
|
|
|
204
|
|
|
205 A program is much easier to understand when the lines have been properly
|
|
|
206 indented. Vim offers various ways to make this less work.
|
|
|
207 For C programs set the 'cindent' option. Vim knows a lot about C programs
|
|
|
208 and will try very hard to automatically set the indent for you. Set the
|
|
|
209 'shiftwidth' option to the amount of spaces you want for a deeper level. Four
|
|
|
210 spaces will work fine. One ":set" command will do it: >
|
|
|
211
|
|
|
212 :set cindent shiftwidth=4
|
|
|
213
|
|
|
214 With this option enabled, when you type something such as "if (x)", the next
|
|
|
215 line will automatically be indented an additional level.
|
|
|
216
|
|
|
217 if (flag)
|
|
|
218 Automatic indent ---> do_the_work();
|
|
|
219 Automatic unindent <-- if (other_flag) {
|
|
|
220 Automatic indent ---> do_file();
|
|
|
221 keep indent do_some_more();
|
|
|
222 Automatic unindent <-- }
|
|
|
223
|
|
|
224 When you type something in curly braces ({}), the text will be indented at the
|
|
|
225 start and unindented at the end. The unindenting will happen after typing the
|
|
|
226 '}', since Vim can't guess what you are going to type.
|
|
|
227
|
|
|
228 One side effect of automatic indentation is that it helps you catch errors in
|
|
|
229 your code early. When you type a } to finish a function, only to find that
|
|
|
230 the automatic indentation gives it more indent than what you expected, there
|
|
|
231 is probably a } missing. Use the "%" command to find out which { matches the
|
|
|
232 } you typed.
|
|
|
233 A missing ) and ; also cause extra indent. Thus if you get more white
|
|
|
234 space than you would expect, check the preceding lines.
|
|
|
235
|
|
|
236 When you have code that is badly formatted, or you inserted and deleted lines,
|
|
|
237 you need to re-indent the lines. The "=" operator does this. The simplest
|
|
|
238 form is: >
|
|
|
239
|
|
|
240 ==
|
|
|
241
|
|
|
242 This indents the current line. Like with all operators, there are three ways
|
|
|
243 to use it. In Visual mode "=" indents the selected lines. A useful text
|
|
|
244 object is "a{". This selects the current {} block. Thus, to re-indent the
|
|
|
245 code code block the cursor is in: >
|
|
|
246
|
|
|
247 =a{
|
|
|
248
|
|
|
249 I you have really badly indented code, you can re-indent the whole file with:
|
|
|
250 >
|
|
|
251 gg=G
|
|
|
252
|
|
|
253 However, don't do this in files that have been carefully indented manually.
|
|
|
254 The automatic indenting does a good job, but in some situations you might want
|
|
|
255 to overrule it.
|
|
|
256
|
|
|
257
|
|
|
258 SETTING INDENT STYLE
|
|
|
259
|
|
|
260 Different people have different styles of indentation. By default Vim does a
|
|
|
261 pretty good job of indenting in a way that 90% of programmers do. There are
|
|
|
262 different styles, however; so if you want to, you can customize the
|
|
|
263 indentation style with the 'cinoptions' option.
|
|
|
264 By default 'cinoptions' is empty and Vim uses the default style. You can
|
|
|
265 add various items where you want something different. For example, to make
|
|
|
266 curly braces be placed like this:
|
|
|
267
|
|
|
268 if (flag) ~
|
|
|
269 { ~
|
|
|
270 i = 8; ~
|
|
|
271 j = 0; ~
|
|
|
272 } ~
|
|
|
273
|
|
|
274 Use this command: >
|
|
|
275
|
|
|
276 :set cinoptions+={2
|
|
|
277
|
|
|
278 There are many of these items. See |cinoptions-values|.
|
|
|
279
|
|
|
280 ==============================================================================
|
|
|
281 *30.3* Automatic indenting
|
|
|
282
|
|
|
283 You don't want to switch on the 'cindent' option manually every time you edit
|
|
|
284 a C file. This is how you make it work automatically: >
|
|
|
285
|
|
|
286 :filetype indent on
|
|
|
287
|
|
|
288 Actually, this does a lot more than switching on 'cindent' for C files. First
|
|
|
289 of all, it enables detecting the type of a file. That's the same as what is
|
|
|
290 used for syntax highlighting.
|
|
|
291 When the filetype is known, Vim will search for an indent file for this
|
|
|
292 type of file. The Vim distribution includes a number of these for various
|
|
|
293 programming languages. This indent file will then prepare for automatic
|
|
|
294 indenting specifically for this file.
|
|
|
295
|
|
|
296 If you don't like the automatic indenting, you can switch it off again: >
|
|
|
297
|
|
|
298 :filetype indent off
|
|
|
299
|
|
|
300 If you don't like the indenting for one specific type of file, this is how you
|
|
|
301 avoid it. Create a file with just this one line: >
|
|
|
302
|
|
|
303 :let b:did_indent = 1
|
|
|
304
|
|
|
305 Now you need to write this in a file with a specific name:
|
|
|
306
|
|
|
307 {directory}/indent/{filetype}.vim
|
|
|
308
|
|
|
309 The {filetype} is the name of the file type, such as "cpp" or "java". You can
|
|
|
310 see the exact name that Vim detected with this command: >
|
|
|
311
|
|
|
312 :set filetype
|
|
|
313
|
|
|
314 In this file the output is:
|
|
|
315
|
|
|
316 filetype=help ~
|
|
|
317
|
|
|
318 This you would use "help" for {filetype}.
|
|
|
319 For the {directory} part you need to use your runtime directory. Look at
|
|
|
320 the output of this command: >
|
|
|
321
|
|
|
322 set runtimepath
|
|
|
323
|
|
|
324 Now use the first item, the name before the first comma. Thus if the output
|
|
|
325 looks like this:
|
|
|
326
|
|
|
327 runtimepath=~/.vim,/usr/local/share/vim/vim60/runtime,~/.vim/after ~
|
|
|
328
|
|
|
329 You use "~/.vim" for {directory}. Then the resulting file name is:
|
|
|
330
|
|
|
331 ~/.vim/indent/help.vim ~
|
|
|
332
|
|
|
333 Instead of switching the indenting off, you could write your own indent file.
|
|
|
334 How to do that is explained here: |indent-expression|.
|
|
|
335
|
|
|
336 ==============================================================================
|
|
|
337 *30.4* Other indenting
|
|
|
338
|
|
|
339 The most simple form of automatic indenting is with the 'autoindent' option.
|
|
|
340 It uses the indent from the previous line. A bit smarter is the 'smartindent'
|
|
|
341 option. This is useful for languages where no indent file is available.
|
|
|
342 'smartindent'is not as smart as 'cindent', but smarter than 'autoindent'.
|
|
|
343 With 'smartindent' set, an extra level of indentation is added for each {
|
|
|
344 and removed for each }. An extra level of indentation will also be added for
|
|
|
345 any of the words in the 'cinwords' option. Lines that begin with # are
|
|
|
346 treated specially: all indentation is removed. This is done so that
|
|
|
347 preprocessor directives will all start in column 1. The indentation is
|
|
|
348 restored for the next line.
|
|
|
349
|
|
|
350
|
|
|
351 CORRECTING INDENTS
|
|
|
352
|
|
|
353 When you are using 'autoindent' or 'smartindent' to get the indent of the
|
|
|
354 previous line, there will be many times when you need to add or remove one
|
|
|
355 'shiftwidth' worth of indent. A quick way to do this is using the CTRL-D and
|
|
|
356 CTRL-T commands in Insert mode.
|
|
|
357 For example, you are typing a shell script that is supposed to look like
|
|
|
358 this:
|
|
|
359
|
|
|
360 if test -n a; then ~
|
|
|
361 echo a ~
|
|
|
362 echo "-------" ~
|
|
|
363 fi ~
|
|
|
364
|
|
|
365 Start off by setting these option: >
|
|
|
366
|
|
|
367 :set autoindent shiftwidth=3
|
|
|
368
|
|
|
369 You start by typing the first line, <Enter> and the start of the second line:
|
|
|
370
|
|
|
371 if test -n a; then ~
|
|
|
372 echo ~
|
|
|
373
|
|
|
374 Now you see that you need an extra indent. Type CTRL-T. The result:
|
|
|
375
|
|
|
376 if test -n a; then ~
|
|
|
377 echo ~
|
|
|
378
|
|
|
379 The CTRL-T command, in Insert mode, adds one 'shiftwidth' to the indent, no
|
|
|
380 matter where in the line you are.
|
|
|
381 You continue typing the second line, <Enter> and the third line. This time
|
|
|
382 the indent is OK. Then <Enter> and the last line. Now you have this:
|
|
|
383
|
|
|
384 if test -n a; then ~
|
|
|
385 echo a ~
|
|
|
386 echo "-------" ~
|
|
|
387 fi ~
|
|
|
388
|
|
|
389 To remove the superfluous indent in the last line press CTRL-D. This deletes
|
|
|
390 one 'shiftwidth' worth of indent, no matter where you are in the line.
|
|
|
391 When you are in Normal mode, you can use the ">>" and "<<" commands to
|
|
|
392 shift lines. ">" and "<" are operators, thus you have the usual three ways to
|
|
|
393 specify the lines you want to indent. A useful combination is: >
|
|
|
394
|
|
|
395 >i{
|
|
|
396
|
|
|
397 This adds one indent to the current block of lines, inside {}. The { and }
|
|
|
398 lines themselves are left unmodified. ">a{" includes them. In this example
|
|
|
399 the cursor is on "printf":
|
|
|
400
|
|
|
401 original text after ">i{" after ">a{"
|
|
|
402
|
|
|
403 if (flag) if (flag) if (flag) ~
|
|
|
404 { { { ~
|
|
|
405 printf("yes"); printf("yes"); printf("yes"); ~
|
|
|
406 flag = 0; flag = 0; flag = 0; ~
|
|
|
407 } } } ~
|
|
|
408
|
|
|
409 ==============================================================================
|
|
|
410 *30.5* Tabs and spaces
|
|
|
411
|
|
|
412 'tabstop' is set to eight by default. Although you can change it, you quickly
|
|
|
413 run into trouble later. Other programs won't know what tabstop value you
|
|
|
414 used. They probably use the default value of eight, and your text suddenly
|
|
|
415 looks very different. Also, most printers use a fixed tabstop value of eight.
|
|
|
416 Thus it's best to keep 'tabstop' alone. (If you edit a file which was written
|
|
|
417 with a different tabstop setting, see |25.3| for how to fix that.)
|
|
|
418 For indenting lines in a program, using a multiple of eight spaces makes
|
|
|
419 you quickly run into the right border of the window. Using a single space
|
|
|
420 doesn't provide enough visual difference. Many people prefer to use four
|
|
|
421 spaces, a good compromise.
|
|
|
422 Since a <Tab> is eight spaces and you want to use an indent of four spaces,
|
|
|
423 you can't use a <Tab> character to make your indent. There are two ways to
|
|
|
424 handle this:
|
|
|
425
|
|
|
426 1. Use a mix of <Tab> and space characters. Since a <Tab> takes the place of
|
|
|
427 eight spaces, you have fewer characters in your file. Inserting a <Tab>
|
|
|
428 is quicker than eight spaces. Backspacing works faster as well.
|
|
|
429
|
|
|
430 2. Use spaces only. This avoids the trouble with programs that use a
|
|
|
431 different tabstop value.
|
|
|
432
|
|
|
433 Fortunately, Vim supports both methods quite well.
|
|
|
434
|
|
|
435
|
|
|
436 SPACES AND TABS
|
|
|
437
|
|
|
438 If you are using a combination of tabs and spaces, you just edit normally.
|
|
|
439 The Vim defaults do a fine job of handling things.
|
|
|
440 You can make life a little easier by setting the 'softtabstop' option.
|
|
|
441 This option tells Vim to make the <Tab> key look and feel as if tabs were set
|
|
|
442 at the value of 'softtabstop', but actually use a combination of tabs and
|
|
|
443 spaces.
|
|
|
444 After you execute the following command, every time you press the <Tab> key
|
|
|
445 the cursor moves to the next 4-column boundary: >
|
|
|
446
|
|
|
447 :set softtabstop=4
|
|
|
448
|
|
|
449 When you start in the first column and press <Tab>, you get 4 spaces inserted
|
|
|
450 in your text. The second time, Vim takes out the 4 spaces and puts in a <Tab>
|
|
|
451 (thus taking you to column 8). Thus Vim uses as many <Tab>s as possible, and
|
|
|
452 then fills up with spaces.
|
|
|
453 When backspacing it works the other way around. A <BS> will always delete
|
|
|
454 the amount specified with 'softtabstop'. Then <Tabs> are used as many as
|
|
|
455 possible and spaces to fill the gap.
|
|
|
456 The following shows what happens pressing <Tab> a few times, and then using
|
|
|
457 <BS>. A "." stands for a space and "------->" for a <Tab>.
|
|
|
458
|
|
|
459 type result ~
|
|
|
460 <Tab> ....
|
|
|
461 <Tab><Tab> ------->
|
|
|
462 <Tab><Tab><Tab> ------->....
|
|
|
463 <Tab><Tab><Tab><BS> ------->
|
|
|
464 <Tab><Tab><Tab><BS><BS> ....
|
|
|
465
|
|
|
466 An alternative is to use the 'smarttab' option. When it's set, Vim uses
|
|
|
467 'shiftwidth' for a <Tab> typed in the indent of a line, and a real <Tab> when
|
|
|
468 typed after the first non-blank character. However, <BS> doesn't work like
|
|
|
469 with 'softtabstop'.
|
|
|
470
|
|
|
471
|
|
|
472 JUST SPACES
|
|
|
473
|
|
|
474 If you want absolutely no tabs in your file, you can set the 'expandtab'
|
|
|
475 option: >
|
|
|
476
|
|
|
477 :set expandtab
|
|
|
478
|
|
|
479 When this option is set, the <Tab> key inserts a series of spaces. Thus you
|
|
|
480 get the same amount of white space as if a <Tab> character was inserted, but
|
|
|
481 there isn't a real <Tab> character in your file.
|
|
|
482 The backspace key will delete each space by itself. Thus after typing one
|
|
|
483 <Tab> you have to press the <BS> key up to eight times to undo it. If you are
|
|
|
484 in the indent, pressing CTRL-D will be a lot quicker.
|
|
|
485
|
|
|
486
|
|
|
487 CHANGING TABS IN SPACES (AND BACK)
|
|
|
488
|
|
|
489 Setting 'expandtab' does not affect any existing tabs. In other words, any
|
|
|
490 tabs in the document remain tabs. If you want to convert tabs to spaces, use
|
|
|
491 the ":retab" command. Use these commands: >
|
|
|
492
|
|
|
493 :set expandtab
|
|
|
494 :%retab
|
|
|
495
|
|
|
496 Now Vim will have changed all indents to use spaces instead of tabs. However,
|
|
|
497 all tabs that come after a non-blank character are kept. If you want these to
|
|
|
498 be converted as well, add a !: >
|
|
|
499
|
|
|
500 :%retab!
|
|
|
501
|
|
|
502 This is a little bit dangerous, because it can also change tabs inside a
|
|
|
503 string. To check if these exist, you could use this: >
|
|
|
504
|
|
|
505 /"[^"\t]*\t[^"]*"
|
|
|
506
|
|
|
507 It's recommended not to use hard tabs inside a string. Replace them with
|
|
|
508 "\t" to avoid trouble.
|
|
|
509
|
|
|
510 The other way around works just as well: >
|
|
|
511
|
|
|
512 :set noexpandtab
|
|
|
513 :%retab!
|
|
|
514
|
|
|
515 ==============================================================================
|
|
|
516 *30.6* Formatting comments
|
|
|
517
|
|
|
518 One of the great things about Vim is that it understands comments. You can
|
|
|
519 ask Vim to format a comment and it will do the right thing.
|
|
|
520 Suppose, for example, that you have the following comment:
|
|
|
521
|
|
|
522 /* ~
|
|
|
523 * This is a test ~
|
|
|
524 * of the text formatting. ~
|
|
|
525 */ ~
|
|
|
526
|
|
|
527 You then ask Vim to format it by positioning the cursor at the start of the
|
|
|
528 comment and type: >
|
|
|
529
|
|
|
530 gq]/
|
|
|
531
|
|
|
532 "gq" is the operator to format text. "]/" is the motion that takes you to the
|
|
|
533 end of a comment. The result is:
|
|
|
534
|
|
|
535 /* ~
|
|
|
536 * This is a test of the text formatting. ~
|
|
|
537 */ ~
|
|
|
538
|
|
|
539 Notice that Vim properly handled the beginning of each line.
|
|
|
540 An alternative is to select the text that is to be formatted in Visual mode
|
|
|
541 and type "gq".
|
|
|
542
|
|
|
543 To add a new line to the comment, position the cursor on the middle line and
|
|
|
544 press "o". The result looks like this:
|
|
|
545
|
|
|
546 /* ~
|
|
|
547 * This is a test of the text formatting. ~
|
|
|
548 * ~
|
|
|
549 */ ~
|
|
|
550
|
|
|
551 Vim has automatically inserted a star and a space for you. Now you can type
|
|
|
552 the comment text. When it gets longer than 'textwidth', Vim will break the
|
|
|
553 line. Again, the star is inserted automatically:
|
|
|
554
|
|
|
555 /* ~
|
|
|
556 * This is a test of the text formatting. ~
|
|
|
557 * Typing a lot of text here will make Vim ~
|
|
|
558 * break ~
|
|
|
559 */ ~
|
|
|
560
|
|
|
561 For this to work some flags must be present in 'formatoptions':
|
|
|
562
|
|
|
563 r insert the star when typing <Enter> in Insert mode
|
|
|
564 o insert the star when using "o" or "O" in Normal mode
|
|
|
565 c break comment text according to 'textwidth'
|
|
|
566
|
|
|
567 See |fo-table| for more flags.
|
|
|
568
|
|
|
569
|
|
|
570 DEFINING A COMMENT
|
|
|
571
|
|
|
572 The 'comments' option defines what a comment looks like. Vim distinguishes
|
|
|
573 between a single-line comment and a comment that has a different start, end
|
|
|
574 and middle part.
|
|
|
575 Many single-line comments start with a specific character. In C++ // is
|
|
|
576 used, in Makefiles #, in Vim scripts ". For example, to make Vim understand
|
|
|
577 C++ comments: >
|
|
|
578
|
|
|
579 :set comments=://
|
|
|
580
|
|
|
581 The colon separates the flags of an item from the text by which the comment is
|
|
|
582 recognized. The general form of an item in 'comments' is:
|
|
|
583
|
|
|
584 {flags}:{text}
|
|
|
585
|
|
|
586 The {flags} part can be empty, as in this case.
|
|
|
587 Several of these items can be concatenated, separated by commas. This
|
|
|
588 allows recognizing different types of comments at the same time. For example,
|
|
|
589 let's edit an e-mail message. When replying, the text that others wrote is
|
|
|
590 preceded with ">" and "!" characters. This command would work: >
|
|
|
591
|
|
|
592 :set comments=n:>,n:!
|
|
|
593
|
|
|
594 There are two items, one for comments starting with ">" and one for comments
|
|
|
595 that start with "!". Both use the flag "n". This means that these comments
|
|
|
596 nest. Thus a line starting with ">" may have another comment after the ">".
|
|
|
597 This allows formatting a message like this:
|
|
|
598
|
|
|
599 > ! Did you see that site? ~
|
|
|
600 > ! It looks really great. ~
|
|
|
601 > I don't like it. The ~
|
|
|
602 > colors are terrible. ~
|
|
|
603 What is the URL of that ~
|
|
|
604 site? ~
|
|
|
605
|
|
|
606 Try setting 'textwidth' to a different value, e.g., 80, and format the text by
|
|
|
607 Visually selecting it and typing "gq". The result is:
|
|
|
608
|
|
237
|
609 > ! Did you see that site? It looks really great. ~
|
|
7
|
610 > I don't like it. The colors are terrible. ~
|
|
|
611 What is the URL of that site? ~
|
|
|
612
|
|
|
613 You will notice that Vim did not move text from one type of comment to
|
|
|
614 another. The "I" in the second line would have fit at the end of the first
|
|
|
615 line, but since that line starts with "> !" and the second line with ">", Vim
|
|
|
616 knows that this is a different kind of comment.
|
|
|
617
|
|
|
618
|
|
|
619 A THREE PART COMMENT
|
|
|
620
|
|
|
621 A C comment starts with "/*", has "*" in the middle and "*/" at the end. The
|
|
|
622 entry in 'comments' for this looks like this: >
|
|
|
623
|
|
|
624 :set comments=s1:/*,mb:*,ex:*/
|
|
|
625
|
|
|
626 The start is defined with "s1:/*". The "s" indicates the start of a
|
|
|
627 three-piece comment. The colon separates the flags from the text by which the
|
|
|
628 comment is recognized: "/*". There is one flag: "1". This tells Vim that the
|
|
|
629 middle part has an offset of one space.
|
|
|
630 The middle part "mb:*" starts with "m", which indicates it is a middle
|
|
|
631 part. The "b" flag means that a blank must follow the text. Otherwise Vim
|
|
|
632 would consider text like "*pointer" also to be the middle of a comment.
|
|
|
633 The end part "ex:*/" has the "e" for identification. The "x" flag has a
|
|
|
634 special meaning. It means that after Vim automatically inserted a star,
|
|
|
635 typing / will remove the extra space.
|
|
|
636
|
|
|
637 For more details see |format-comments|.
|
|
|
638
|
|
|
639 ==============================================================================
|
|
|
640
|
|
|
641 Next chapter: |usr_31.txt| Exploiting the GUI
|
|
|
642
|
|
|
643 Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl:
|
