annotate runtime/doc/develop.txt @ 5146:6ec6b7ff2d43 v7.4a

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