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