Mercurial > vim
annotate runtime/doc/develop.txt @ 7196:42717d048817 v7.4.907
commit https://github.com/vim/vim/commit/d94464ee294a351ce7b6ba18e8bd3f24f1bef920
Author: Bram Moolenaar <Bram@vim.org>
Date: Mon Nov 2 15:28:18 2015 +0100
patch 7.4.907
Problem: Libraries for dynamically loading interfaces can only be defined
at compile time.
Solution: Add options to specify the dll names. (Kazuki Sakamoto,
closes #452)
author | Christian Brabandt <cb@256bit.org> |
---|---|
date | Mon, 02 Nov 2015 15:30:05 +0100 |
parents | c52a655d927d |
children | 41768bcebc9b |
rev | line source |
---|---|
5763 | 1 *develop.txt* For Vim version 7.4. Last change: 2014 Mar 27 |
7 | 2 |
3 | |
4 VIM REFERENCE MANUAL by Bram Moolenaar | |
5 | |
6 | |
7 Development of Vim. *development* | |
8 | |
9 This text is important for those who want to be involved in further developing | |
10 Vim. | |
11 | |
12 1. Design goals |design-goals| | |
13 2. Coding style |coding-style| | |
14 3. Design decisions |design-decisions| | |
15 4. Assumptions |design-assumptions| | |
16 | |
17 See the file README.txt in the "src" directory for an overview of the source | |
18 code. | |
19 | |
20 Vim is open source software. Everybody is encouraged to contribute to help | |
21 improving Vim. For sending patches a context diff "diff -c" is preferred. | |
4358 | 22 Also see http://vim.wikia.com/wiki/How_to_make_and_submit_a_patch. |
7 | 23 |
24 ============================================================================== | |
25 1. Design goals *design-goals* | |
26 | |
27 Most important things come first (roughly). | |
28 | |
29 Note that quite a few items are contradicting. This is intentional. A | |
30 balance must be found between them. | |
31 | |
32 | |
33 VIM IS... VI COMPATIBLE *design-compatible* | |
34 | |
35 First of all, it should be possible to use Vim as a drop-in replacement for | |
36 Vi. When the user wants to, he can use Vim in compatible mode and hardly | |
37 notice any difference with the original Vi. | |
38 | |
39 Exceptions: | |
40 - We don't reproduce obvious Vi bugs in Vim. | |
41 - There are different versions of Vi. I am using Version 3.7 (6/7/85) as a | |
42 reference. But support for other versions is also included when possible. | |
43 The Vi part of POSIX is not considered a definitive source. | |
44 - Vim adds new commands, you cannot rely on some command to fail because it | |
45 didn't exist in Vi. | |
46 - Vim will have a lot of features that Vi doesn't have. Going back from Vim | |
47 to Vi will be a problem, this cannot be avoided. | |
48 - Some things are hardly ever used (open mode, sending an e-mail when | |
49 crashing, etc.). Those will only be included when someone has a good reason | |
50 why it should be included and it's not too much work. | |
51 - For some items it is debatable whether Vi compatibility should be | |
52 maintained. There will be an option flag for these. | |
53 | |
54 | |
55 VIM IS... IMPROVED *design-improved* | |
56 | |
57 The IMproved bits of Vim should make it a better Vi, without becoming a | |
58 completely different editor. Extensions are done with a "Vi spirit". | |
59 - Use the keyboard as much as feasible. The mouse requires a third hand, | |
60 which we don't have. Many terminals don't have a mouse. | |
61 - When the mouse is used anyway, avoid the need to switch back to the | |
62 keyboard. Avoid mixing mouse and keyboard handling. | |
63 - Add commands and options in a consistent way. Otherwise people will have a | |
64 hard time finding and remembering them. Keep in mind that more commands and | |
65 options will be added later. | |
66 - A feature that people do not know about is a useless feature. Don't add | |
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
67 obscure features, or at least add hints in documentation that they exist. |
7 | 68 - Minimize using CTRL and other modifiers, they are more difficult to type. |
69 - There are many first-time and inexperienced Vim users. Make it easy for | |
70 them to start using Vim and learn more over time. | |
71 - There is no limit to the features that can be added. Selecting new features | |
72 is one based on (1) what users ask for, (2) how much effort it takes to | |
73 implement and (3) someone actually implementing it. | |
74 | |
75 | |
76 VIM IS... MULTI PLATFORM *design-multi-platform* | |
77 | |
78 Vim tries to help as many users on as many platforms as possible. | |
79 - Support many kinds of terminals. The minimal demands are cursor positioning | |
80 and clear-screen. Commands should only use key strokes that most keyboards | |
81 have. Support all the keys on the keyboard for mapping. | |
82 - Support many platforms. A condition is that there is someone willing to do | |
83 Vim development on that platform, and it doesn't mean messing up the code. | |
84 - Support many compilers and libraries. Not everybody is able or allowed to | |
85 install another compiler or GUI library. | |
86 - People switch from one platform to another, and from GUI to terminal | |
87 version. Features should be present in all versions, or at least in as many | |
88 as possible with a reasonable effort. Try to avoid that users must switch | |
89 between platforms to accomplish their work efficiently. | |
90 - That a feature is not possible on some platforms, or only possible on one | |
91 platform, does not mean it cannot be implemented. [This intentionally | |
92 contradicts the previous item, these two must be balanced.] | |
93 | |
94 | |
95 VIM IS... WELL DOCUMENTED *design-documented* | |
96 | |
97 - A feature that isn't documented is a useless feature. A patch for a new | |
98 feature must include the documentation. | |
99 - Documentation should be comprehensive and understandable. Using examples is | |
100 recommended. | |
101 - Don't make the text unnecessarily long. Less documentation means that an | |
102 item is easier to find. | |
103 | |
104 | |
105 VIM IS... HIGH SPEED AND SMALL IN SIZE *design-speed-size* | |
106 | |
107 Using Vim must not be a big attack on system resources. Keep it small and | |
108 fast. | |
109 - Computers are becoming faster and bigger each year. Vim can grow too, but | |
110 no faster than computers are growing. Keep Vim usable on older systems. | |
111 - Many users start Vim from a shell very often. Startup time must be short. | |
112 - Commands must work efficiently. The time they consume must be as small as | |
113 possible. Useful commands may take longer. | |
114 - Don't forget that some people use Vim over a slow connection. Minimize the | |
115 communication overhead. | |
116 - Items that add considerably to the size and are not used by many people | |
117 should be a feature that can be disabled. | |
118 - Vim is a component among other components. Don't turn it into a massive | |
119 application, but have it work well together with other programs. | |
120 | |
121 | |
122 VIM IS... MAINTAINABLE *design-maintain* | |
123 | |
124 - The source code should not become a mess. It should be reliable code. | |
125 - Use the same layout in all files to make it easy to read |coding-style|. | |
481 | 126 - Use comments in a useful way! Quoting the function name and argument names |
127 is NOT useful. Do explain what they are for. | |
7 | 128 - Porting to another platform should be made easy, without having to change |
129 too much platform-independent code. | |
130 - Use the object-oriented spirit: Put data and code together. Minimize the | |
131 knowledge spread to other parts of the code. | |
132 | |
133 | |
134 VIM IS... FLEXIBLE *design-flexible* | |
135 | |
136 Vim should make it easy for users to work in their preferred styles rather | |
137 than coercing its users into particular patterns of work. This can be for | |
138 items with a large impact (e.g., the 'compatible' option) or for details. The | |
139 defaults are carefully chosen such that most users will enjoy using Vim as it | |
140 is. Commands and options can be used to adjust Vim to the desire of the user | |
141 and its environment. | |
142 | |
143 | |
144 VIM IS... NOT *design-not* | |
145 | |
146 - Vim is not a shell or an Operating System. You will not be able to run a | |
147 shell inside Vim or use it to control a debugger. This should work the | |
148 other way around: Use Vim as a component from a shell or in an IDE. | |
149 A satirical way to say this: "Unlike Emacs, Vim does not attempt to include | |
150 everything but the kitchen sink, but some people say that you can clean one | |
151 with it. ;-)" | |
722 | 152 To use Vim with gdb see: http://www.agide.org and http://clewn.sf.net. |
7 | 153 - Vim is not a fancy GUI editor that tries to look nice at the cost of |
154 being less consistent over all platforms. But functional GUI features are | |
155 welcomed. | |
156 | |
157 ============================================================================== | |
158 2. Coding style *coding-style* | |
159 | |
160 These are the rules to use when making changes to the Vim source code. Please | |
161 stick to these rules, to keep the sources readable and maintainable. | |
162 | |
163 This list is not complete. Look in the source code for more examples. | |
164 | |
165 | |
166 MAKING CHANGES *style-changes* | |
167 | |
168 The basic steps to make changes to the code: | |
169 1. Adjust the documentation. Doing this first gives you an impression of how | |
170 your changes affect the user. | |
171 2. Make the source code changes. | |
172 3. Check ../doc/todo.txt if the change affects any listed item. | |
173 4. Make a patch with "diff -c" against the unmodified code and docs. | |
174 5. Make a note about what changed and include it with the patch. | |
175 | |
176 | |
177 USE OF COMMON FUNCTIONS *style-functions* | |
178 | |
179 Some functions that are common to use, have a special Vim version. Always | |
180 consider using the Vim version, because they were introduced with a reason. | |
181 | |
182 NORMAL NAME VIM NAME DIFFERENCE OF VIM VERSION | |
183 free() vim_free() Checks for freeing NULL | |
184 malloc() alloc() Checks for out of memory situation | |
185 malloc() lalloc() Like alloc(), but has long argument | |
186 strcpy() STRCPY() Includes cast to (char *), for char_u * args | |
187 strchr() vim_strchr() Accepts special characters | |
188 strrchr() vim_strrchr() Accepts special characters | |
189 isspace() vim_isspace() Can handle characters > 128 | |
1240 | 190 iswhite() vim_iswhite() Only TRUE for tab and space |
711 | 191 memcpy() mch_memmove() Handles overlapped copies |
192 bcopy() mch_memmove() Handles overlapped copies | |
7 | 193 memset() vim_memset() Uniform for all systems |
194 | |
195 | |
196 NAMES *style-names* | |
197 | |
198 Function names can not be more than 31 characters long (because of VMS). | |
199 | |
200 Don't use "delete" as a variable name, C++ doesn't like it. | |
201 | |
202 Because of the requirement that Vim runs on as many systems as possible, we | |
203 need to avoid using names that are already defined by the system. This is a | |
204 list of names that are known to cause trouble. The name is given as a regexp | |
205 pattern. | |
206 | |
207 is.*() POSIX, ctype.h | |
208 to.*() POSIX, ctype.h | |
209 | |
210 d_.* POSIX, dirent.h | |
211 l_.* POSIX, fcntl.h | |
212 gr_.* POSIX, grp.h | |
213 pw_.* POSIX, pwd.h | |
214 sa_.* POSIX, signal.h | |
215 mem.* POSIX, string.h | |
216 str.* POSIX, string.h | |
217 wcs.* POSIX, string.h | |
218 st_.* POSIX, stat.h | |
219 tms_.* POSIX, times.h | |
220 tm_.* POSIX, time.h | |
221 c_.* POSIX, termios.h | |
222 MAX.* POSIX, limits.h | |
223 __.* POSIX, system | |
224 _[A-Z].* POSIX, system | |
225 E[A-Z0-9]* POSIX, errno.h | |
226 | |
1121 | 227 .*_t POSIX, for typedefs. Use .*_T instead. |
7 | 228 |
229 wait don't use as argument to a function, conflicts with types.h | |
230 index shadows global declaration | |
231 time shadows global declaration | |
232 new C++ reserved keyword | |
233 try Borland C++ doesn't like it to be used as a variable. | |
234 | |
3281 | 235 clear Mac curses.h |
236 echo Mac curses.h | |
237 instr Mac curses.h | |
238 meta Mac curses.h | |
239 newwin Mac curses.h | |
240 nl Mac curses.h | |
241 overwrite Mac curses.h | |
242 refresh Mac curses.h | |
243 scroll Mac curses.h | |
244 typeahead Mac curses.h | |
245 | |
7 | 246 basename() GNU string function |
247 dirname() GNU string function | |
248 get_env_value() Linux system function | |
249 | |
250 | |
251 VARIOUS *style-various* | |
252 | |
502 | 253 Typedef'ed names should end in "_T": > |
254 typedef int some_T; | |
7 | 255 Define'ed names should be uppercase: > |
256 #define SOME_THING | |
257 Features always start with "FEAT_": > | |
258 #define FEAT_FOO | |
259 | |
260 Don't use '\"', some compilers can't handle it. '"' works fine. | |
261 | |
262 Don't use: | |
263 #if HAVE_SOME | |
264 Some compilers can't handle that and complain that "HAVE_SOME" is not defined. | |
265 Use | |
266 #ifdef HAVE_SOME | |
267 or | |
268 #if defined(HAVE_SOME) | |
269 | |
270 | |
271 STYLE *style-examples* | |
272 | |
273 General rule: One statement per line. | |
274 | |
275 Wrong: if (cond) a = 1; | |
276 | |
277 OK: if (cond) | |
278 a = 1; | |
279 | |
280 Wrong: while (cond); | |
281 | |
282 OK: while (cond) | |
283 ; | |
284 | |
285 Wrong: do a = 1; while (cond); | |
286 | |
287 OK: do | |
288 a = 1; | |
289 while (cond); | |
290 | |
291 | |
292 Functions start with: | |
293 | |
294 Wrong: int function_name(int arg1, int arg2) | |
295 | |
296 OK: /* | |
297 * Explanation of what this function is used for. | |
298 * | |
299 * Return value explanation. | |
300 */ | |
301 int | |
302 function_name(arg1, arg2) | |
303 int arg1; /* short comment about arg1 */ | |
304 int arg2; /* short comment about arg2 */ | |
305 { | |
306 int local; /* comment about local */ | |
307 | |
308 local = arg1 * arg2; | |
309 | |
310 NOTE: Don't use ANSI style function declarations. A few people still have to | |
311 use a compiler that doesn't support it. | |
312 | |
313 | |
314 SPACES AND PUNCTUATION *style-spaces* | |
315 | |
316 No space between a function name and the bracket: | |
317 | |
318 Wrong: func (arg); | |
319 OK: func(arg); | |
320 | |
321 Do use a space after if, while, switch, etc. | |
322 | |
323 Wrong: if(arg) for(;;) | |
324 OK: if (arg) for (;;) | |
325 | |
326 Use a space after a comma and semicolon: | |
327 | |
328 Wrong: func(arg1,arg2); for (i = 0;i < 2;++i) | |
329 OK: func(arg1, arg2); for (i = 0; i < 2; ++i) | |
330 | |
331 Use a space before and after '=', '+', '/', etc. | |
332 | |
333 Wrong: var=a*5; | |
334 OK: var = a * 5; | |
335 | |
336 In general: Use empty lines to group lines of code together. Put a comment | |
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
337 just above the group of lines. This makes it easier to quickly see what is |
7 | 338 being done. |
339 | |
340 OK: /* Prepare for building the table. */ | |
341 get_first_item(); | |
342 table_idx = 0; | |
343 | |
344 /* Build the table */ | |
345 while (has_item()) | |
346 table[table_idx++] = next_item(); | |
347 | |
348 /* Finish up. */ | |
349 cleanup_items(); | |
350 generate_hash(table); | |
351 | |
352 ============================================================================== | |
353 3. Design decisions *design-decisions* | |
354 | |
355 Folding | |
356 | |
357 Several forms of folding should be possible for the same buffer. For example, | |
358 have one window that shows the text with function bodies folded, another | |
359 window that shows a function body. | |
360 | |
361 Folding is a way to display the text. It should not change the text itself. | |
362 Therefore the folding has been implemented as a filter between the text stored | |
363 in a buffer (buffer lines) and the text displayed in a window (logical lines). | |
364 | |
365 | |
366 Naming the window | |
367 | |
368 The word "window" is commonly used for several things: A window on the screen, | |
369 the xterm window, a window inside Vim to view a buffer. | |
370 To avoid confusion, other items that are sometimes called window have been | |
371 given another name. Here is an overview of the related items: | |
372 | |
373 screen The whole display. For the GUI it's something like 1024x768 | |
374 pixels. The Vim shell can use the whole screen or part of it. | |
375 shell The Vim application. This can cover the whole screen (e.g., | |
376 when running in a console) or part of it (xterm or GUI). | |
377 window View on a buffer. There can be several windows in Vim, | |
378 together with the command line, menubar, toolbar, etc. they | |
379 fit in the shell. | |
380 | |
381 | |
236 | 382 Spell checking *develop-spell* |
383 | |
384 When spell checking was going to be added to Vim a survey was done over the | |
385 available spell checking libraries and programs. Unfortunately, the result | |
386 was that none of them provided sufficient capabilities to be used as the spell | |
387 checking engine in Vim, for various reasons: | |
388 | |
389 - Missing support for multi-byte encodings. At least UTF-8 must be supported, | |
390 so that more than one language can be used in the same file. | |
323 | 391 Doing on-the-fly conversion is not always possible (would require iconv |
392 support). | |
236 | 393 - For the programs and libraries: Using them as-is would require installing |
323 | 394 them separately from Vim. That's mostly not impossible, but a drawback. |
236 | 395 - Performance: A few tests showed that it's possible to check spelling on the |
396 fly (while redrawing), just like syntax highlighting. But the mechanisms | |
625 | 397 used by other code are much slower. Myspell uses a hashtable, for example. |
398 The affix compression that most spell checkers use makes it slower too. | |
300 | 399 - For using an external program like aspell a communication mechanism would |
400 have to be setup. That's complicated to do in a portable way (Unix-only | |
401 would be relatively simple, but that's not good enough). And performance | |
402 will become a problem (lots of process switching involved). | |
236 | 403 - Missing support for words with non-word characters, such as "Etten-Leur" and |
404 "et al.", would require marking the pieces of them OK, lowering the | |
405 reliability. | |
406 - Missing support for regions or dialects. Makes it difficult to accept | |
407 all English words and highlight non-Canadian words differently. | |
408 - Missing support for rare words. Many words are correct but hardly ever used | |
409 and could be a misspelled often-used word. | |
323 | 410 - For making suggestions the speed is less important and requiring to install |
411 another program or library would be acceptable. But the word lists probably | |
412 differ, the suggestions may be wrong words. | |
7 | 413 |
625 | 414 |
415 Spelling suggestions *develop-spell-suggestions* | |
416 | |
417 For making suggestions there are two basic mechanisms: | |
418 1. Try changing the bad word a little bit and check for a match with a good | |
419 word. Or go through the list of good words, change them a little bit and | |
420 check for a match with the bad word. The changes are deleting a character, | |
421 inserting a character, swapping two characters, etc. | |
422 2. Perform soundfolding on both the bad word and the good words and then find | |
423 matches, possibly with a few changes like with the first mechanism. | |
424 | |
425 The first is good for finding typing mistakes. After experimenting with | |
426 hashtables and looking at solutions from other spell checkers the conclusion | |
427 was that a trie (a kind of tree structure) is ideal for this. Both for | |
428 reducing memory use and being able to try sensible changes. For example, when | |
429 inserting a character only characters that lead to good words need to be | |
430 tried. Other mechanisms (with hashtables) need to try all possible letters at | |
431 every position in the word. Also, a hashtable has the requirement that word | |
432 boundaries are identified separately, while a trie does not require this. | |
433 That makes the mechanism a lot simpler. | |
434 | |
435 Soundfolding is useful when someone knows how the words sounds but doesn't | |
436 know how it is spelled. For example, the word "dictionary" might be written | |
437 as "daktonerie". The number of changes that the first method would need to | |
438 try is very big, it's hard to find the good word that way. After soundfolding | |
439 the words become "tktnr" and "tkxnry", these differ by only two letters. | |
440 | |
441 To find words by their soundfolded equivalent (soundalike word) we need a list | |
442 of all soundfolded words. A few experiments have been done to find out what | |
443 the best method is. Alternatives: | |
444 1. Do the sound folding on the fly when looking for suggestions. This means | |
445 walking through the trie of good words, soundfolding each word and | |
446 checking how different it is from the bad word. This is very efficient for | |
447 memory use, but takes a long time. On a fast PC it takes a couple of | |
448 seconds for English, which can be acceptable for interactive use. But for | |
449 some languages it takes more than ten seconds (e.g., German, Catalan), | |
450 which is unacceptable slow. For batch processing (automatic corrections) | |
1197 | 451 it's too slow for all languages. |
625 | 452 2. Use a trie for the soundfolded words, so that searching can be done just |
453 like how it works without soundfolding. This requires remembering a list | |
454 of good words for each soundfolded word. This makes finding matches very | |
455 fast but requires quite a lot of memory, in the order of 1 to 10 Mbyte. | |
456 For some languages more than the original word list. | |
457 3. Like the second alternative, but reduce the amount of memory by using affix | |
458 compression and store only the soundfolded basic word. This is what Aspell | |
459 does. Disadvantage is that affixes need to be stripped from the bad word | |
460 before soundfolding it, which means that mistakes at the start and/or end | |
461 of the word will cause the mechanism to fail. Also, this becomes slow when | |
462 the bad word is quite different from the good word. | |
463 | |
464 The choice made is to use the second mechanism and use a separate file. This | |
465 way a user with sufficient memory can get very good suggestions while a user | |
466 who is short of memory or just wants the spell checking and no suggestions | |
467 doesn't use so much memory. | |
468 | |
469 | |
470 Word frequency | |
471 | |
472 For sorting suggestions it helps to know which words are common. In theory we | |
473 could store a word frequency with the word in the dictionary. However, this | |
474 requires storing a count per word. That degrades word tree compression a lot. | |
475 And maintaining the word frequency for all languages will be a heavy task. | |
476 Also, it would be nice to prefer words that are already in the text. This way | |
477 the words that appear in the specific text are preferred for suggestions. | |
478 | |
479 What has been implemented is to count words that have been seen during | |
480 displaying. A hashtable is used to quickly find the word count. The count is | |
481 initialized from words listed in COMMON items in the affix file, so that it | |
482 also works when starting a new file. | |
483 | |
484 This isn't ideal, because the longer Vim is running the higher the counts | |
1197 | 485 become. But in practice it is a noticeable improvement over not using the word |
625 | 486 count. |
487 | |
7 | 488 ============================================================================== |
489 4. Assumptions *design-assumptions* | |
490 | |
491 Size of variables: | |
492 char 8 bit signed | |
493 char_u 8 bit unsigned | |
625 | 494 int 32 or 64 bit signed (16 might be possible with limited features) |
495 unsigned 32 or 64 bit unsigned (16 as with ints) | |
7 | 496 long 32 or 64 bit signed, can hold a pointer |
497 | |
498 Note that some compilers cannot handle long lines or strings. The C89 | |
499 standard specifies a limit of 509 characters. | |
500 | |
501 vim:tw=78:ts=8:ft=help:norl: |