Bram Moolenaar | 6856393 | 2017-01-10 13:31:15 +0100 | [diff] [blame] | 1 | *develop.txt* For Vim version 8.0. Last change: 2017 Jan 05 |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 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. |
Bram Moolenaar | 531da59 | 2013-05-06 05:58:55 +0200 | [diff] [blame] | 22 | Also see http://vim.wikia.com/wiki/How_to_make_and_submit_a_patch. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 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 |
Bram Moolenaar | 8f3f58f | 2010-01-06 20:52:26 +0100 | [diff] [blame] | 67 | obscure features, or at least add hints in documentation that they exist. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 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|. |
Bram Moolenaar | ae5bce1 | 2005-08-15 21:41:48 +0000 | [diff] [blame] | 126 | - Use comments in a useful way! Quoting the function name and argument names |
| 127 | is NOT useful. Do explain what they are for. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 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. ;-)" |
Bram Moolenaar | eca1575 | 2006-03-10 21:35:45 +0000 | [diff] [blame] | 152 | To use Vim with gdb see: http://www.agide.org and http://clewn.sf.net. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 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: |
Bram Moolenaar | 13d5aee | 2016-01-21 23:36:05 +0100 | [diff] [blame] | 169 | 1. Get the code from github. That makes it easier to keep your changed |
| 170 | version in sync with the main code base (it may be a while before your |
| 171 | changes will be included). You do need to spend some time learning git, |
| 172 | it's not the most user friendly tool. |
| 173 | 2. Adjust the documentation. Doing this first gives you an impression of how |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 174 | your changes affect the user. |
Bram Moolenaar | 13d5aee | 2016-01-21 23:36:05 +0100 | [diff] [blame] | 175 | 3. Make the source code changes. |
| 176 | 4. Check ../doc/todo.txt if the change affects any listed item. |
| 177 | 5. Make a patch with "git diff". You can also create a pull request on |
| 178 | github, but it's the diff that matters. |
| 179 | 6. Make a note about what changed, preferably mentioning the problem and the |
Bram Moolenaar | 6856393 | 2017-01-10 13:31:15 +0100 | [diff] [blame] | 180 | solution. Send an email to the |vim-dev| maillist with an explanation and |
Bram Moolenaar | 13d5aee | 2016-01-21 23:36:05 +0100 | [diff] [blame] | 181 | include the diff. Or create a pull request on github. |
| 182 | |
| 183 | |
| 184 | C COMPILER *style-compiler* |
| 185 | |
| 186 | The minimal C compiler version supported is C89, also known as ANSI C. |
| 187 | Later standards don't add much and C89 is the widest supported. |
| 188 | |
| 189 | One restriction that this implies: no // comments, only /* comments */. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 190 | |
| 191 | |
| 192 | USE OF COMMON FUNCTIONS *style-functions* |
| 193 | |
| 194 | Some functions that are common to use, have a special Vim version. Always |
| 195 | consider using the Vim version, because they were introduced with a reason. |
| 196 | |
| 197 | NORMAL NAME VIM NAME DIFFERENCE OF VIM VERSION |
| 198 | free() vim_free() Checks for freeing NULL |
| 199 | malloc() alloc() Checks for out of memory situation |
| 200 | malloc() lalloc() Like alloc(), but has long argument |
| 201 | strcpy() STRCPY() Includes cast to (char *), for char_u * args |
| 202 | strchr() vim_strchr() Accepts special characters |
| 203 | strrchr() vim_strrchr() Accepts special characters |
| 204 | isspace() vim_isspace() Can handle characters > 128 |
Bram Moolenaar | 9e368db | 2007-05-12 13:25:01 +0000 | [diff] [blame] | 205 | iswhite() vim_iswhite() Only TRUE for tab and space |
Bram Moolenaar | 36fc535 | 2006-03-04 21:49:37 +0000 | [diff] [blame] | 206 | memcpy() mch_memmove() Handles overlapped copies |
| 207 | bcopy() mch_memmove() Handles overlapped copies |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 208 | memset() vim_memset() Uniform for all systems |
| 209 | |
| 210 | |
| 211 | NAMES *style-names* |
| 212 | |
| 213 | Function names can not be more than 31 characters long (because of VMS). |
| 214 | |
Bram Moolenaar | 13d5aee | 2016-01-21 23:36:05 +0100 | [diff] [blame] | 215 | Don't use "delete" or "this" as a variable name, C++ doesn't like it. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 216 | |
| 217 | Because of the requirement that Vim runs on as many systems as possible, we |
| 218 | need to avoid using names that are already defined by the system. This is a |
| 219 | list of names that are known to cause trouble. The name is given as a regexp |
| 220 | pattern. |
| 221 | |
| 222 | is.*() POSIX, ctype.h |
| 223 | to.*() POSIX, ctype.h |
| 224 | |
| 225 | d_.* POSIX, dirent.h |
| 226 | l_.* POSIX, fcntl.h |
| 227 | gr_.* POSIX, grp.h |
| 228 | pw_.* POSIX, pwd.h |
| 229 | sa_.* POSIX, signal.h |
| 230 | mem.* POSIX, string.h |
| 231 | str.* POSIX, string.h |
| 232 | wcs.* POSIX, string.h |
| 233 | st_.* POSIX, stat.h |
| 234 | tms_.* POSIX, times.h |
| 235 | tm_.* POSIX, time.h |
| 236 | c_.* POSIX, termios.h |
| 237 | MAX.* POSIX, limits.h |
| 238 | __.* POSIX, system |
| 239 | _[A-Z].* POSIX, system |
| 240 | E[A-Z0-9]* POSIX, errno.h |
| 241 | |
Bram Moolenaar | 9964e46 | 2007-05-05 17:54:07 +0000 | [diff] [blame] | 242 | .*_t POSIX, for typedefs. Use .*_T instead. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 243 | |
| 244 | wait don't use as argument to a function, conflicts with types.h |
| 245 | index shadows global declaration |
| 246 | time shadows global declaration |
| 247 | new C++ reserved keyword |
| 248 | try Borland C++ doesn't like it to be used as a variable. |
| 249 | |
Bram Moolenaar | 6be7f87 | 2012-01-20 21:08:56 +0100 | [diff] [blame] | 250 | clear Mac curses.h |
| 251 | echo Mac curses.h |
| 252 | instr Mac curses.h |
| 253 | meta Mac curses.h |
| 254 | newwin Mac curses.h |
| 255 | nl Mac curses.h |
| 256 | overwrite Mac curses.h |
| 257 | refresh Mac curses.h |
| 258 | scroll Mac curses.h |
| 259 | typeahead Mac curses.h |
| 260 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 261 | basename() GNU string function |
| 262 | dirname() GNU string function |
| 263 | get_env_value() Linux system function |
| 264 | |
| 265 | |
| 266 | VARIOUS *style-various* |
| 267 | |
Bram Moolenaar | e344bea | 2005-09-01 20:46:49 +0000 | [diff] [blame] | 268 | Typedef'ed names should end in "_T": > |
| 269 | typedef int some_T; |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 270 | Define'ed names should be uppercase: > |
| 271 | #define SOME_THING |
| 272 | Features always start with "FEAT_": > |
| 273 | #define FEAT_FOO |
| 274 | |
| 275 | Don't use '\"', some compilers can't handle it. '"' works fine. |
| 276 | |
| 277 | Don't use: |
| 278 | #if HAVE_SOME |
| 279 | Some compilers can't handle that and complain that "HAVE_SOME" is not defined. |
| 280 | Use |
| 281 | #ifdef HAVE_SOME |
| 282 | or |
| 283 | #if defined(HAVE_SOME) |
| 284 | |
| 285 | |
| 286 | STYLE *style-examples* |
| 287 | |
| 288 | General rule: One statement per line. |
| 289 | |
| 290 | Wrong: if (cond) a = 1; |
| 291 | |
| 292 | OK: if (cond) |
| 293 | a = 1; |
| 294 | |
| 295 | Wrong: while (cond); |
| 296 | |
| 297 | OK: while (cond) |
| 298 | ; |
| 299 | |
| 300 | Wrong: do a = 1; while (cond); |
| 301 | |
| 302 | OK: do |
| 303 | a = 1; |
| 304 | while (cond); |
| 305 | |
Bram Moolenaar | 13d5aee | 2016-01-21 23:36:05 +0100 | [diff] [blame] | 306 | Wrong: if (cond) { |
| 307 | cmd; |
| 308 | cmd; |
| 309 | } else { |
| 310 | cmd; |
| 311 | cmd; |
| 312 | } |
| 313 | |
| 314 | OK: if (cond) |
| 315 | { |
| 316 | cmd; |
| 317 | cmd; |
| 318 | } |
| 319 | else |
| 320 | { |
| 321 | cmd; |
| 322 | cmd; |
| 323 | } |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 324 | |
Bram Moolenaar | 5e9b2fa | 2016-02-01 22:37:05 +0100 | [diff] [blame] | 325 | Use ANSI (new style) function declarations with the return type on a separate |
| 326 | indented line. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 327 | |
| 328 | Wrong: int function_name(int arg1, int arg2) |
| 329 | |
| 330 | OK: /* |
| 331 | * Explanation of what this function is used for. |
| 332 | * |
| 333 | * Return value explanation. |
| 334 | */ |
| 335 | int |
Bram Moolenaar | 13d5aee | 2016-01-21 23:36:05 +0100 | [diff] [blame] | 336 | function_name( |
| 337 | int arg1, /* short comment about arg1 */ |
| 338 | int arg2) /* short comment about arg2 */ |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 339 | { |
| 340 | int local; /* comment about local */ |
| 341 | |
| 342 | local = arg1 * arg2; |
| 343 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 344 | |
| 345 | |
| 346 | SPACES AND PUNCTUATION *style-spaces* |
| 347 | |
| 348 | No space between a function name and the bracket: |
| 349 | |
| 350 | Wrong: func (arg); |
| 351 | OK: func(arg); |
| 352 | |
| 353 | Do use a space after if, while, switch, etc. |
| 354 | |
| 355 | Wrong: if(arg) for(;;) |
| 356 | OK: if (arg) for (;;) |
| 357 | |
| 358 | Use a space after a comma and semicolon: |
| 359 | |
| 360 | Wrong: func(arg1,arg2); for (i = 0;i < 2;++i) |
| 361 | OK: func(arg1, arg2); for (i = 0; i < 2; ++i) |
| 362 | |
| 363 | Use a space before and after '=', '+', '/', etc. |
| 364 | |
| 365 | Wrong: var=a*5; |
| 366 | OK: var = a * 5; |
| 367 | |
| 368 | In general: Use empty lines to group lines of code together. Put a comment |
Bram Moolenaar | 8f3f58f | 2010-01-06 20:52:26 +0100 | [diff] [blame] | 369 | just above the group of lines. This makes it easier to quickly see what is |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 370 | being done. |
| 371 | |
| 372 | OK: /* Prepare for building the table. */ |
| 373 | get_first_item(); |
| 374 | table_idx = 0; |
| 375 | |
| 376 | /* Build the table */ |
| 377 | while (has_item()) |
| 378 | table[table_idx++] = next_item(); |
| 379 | |
| 380 | /* Finish up. */ |
| 381 | cleanup_items(); |
| 382 | generate_hash(table); |
| 383 | |
| 384 | ============================================================================== |
| 385 | 3. Design decisions *design-decisions* |
| 386 | |
| 387 | Folding |
| 388 | |
| 389 | Several forms of folding should be possible for the same buffer. For example, |
| 390 | have one window that shows the text with function bodies folded, another |
| 391 | window that shows a function body. |
| 392 | |
| 393 | Folding is a way to display the text. It should not change the text itself. |
| 394 | Therefore the folding has been implemented as a filter between the text stored |
| 395 | in a buffer (buffer lines) and the text displayed in a window (logical lines). |
| 396 | |
| 397 | |
| 398 | Naming the window |
| 399 | |
| 400 | The word "window" is commonly used for several things: A window on the screen, |
| 401 | the xterm window, a window inside Vim to view a buffer. |
| 402 | To avoid confusion, other items that are sometimes called window have been |
| 403 | given another name. Here is an overview of the related items: |
| 404 | |
| 405 | screen The whole display. For the GUI it's something like 1024x768 |
| 406 | pixels. The Vim shell can use the whole screen or part of it. |
| 407 | shell The Vim application. This can cover the whole screen (e.g., |
| 408 | when running in a console) or part of it (xterm or GUI). |
| 409 | window View on a buffer. There can be several windows in Vim, |
| 410 | together with the command line, menubar, toolbar, etc. they |
| 411 | fit in the shell. |
| 412 | |
| 413 | |
Bram Moolenaar | 402d2fe | 2005-04-15 21:00:38 +0000 | [diff] [blame] | 414 | Spell checking *develop-spell* |
| 415 | |
| 416 | When spell checking was going to be added to Vim a survey was done over the |
| 417 | available spell checking libraries and programs. Unfortunately, the result |
| 418 | was that none of them provided sufficient capabilities to be used as the spell |
| 419 | checking engine in Vim, for various reasons: |
| 420 | |
| 421 | - Missing support for multi-byte encodings. At least UTF-8 must be supported, |
| 422 | so that more than one language can be used in the same file. |
Bram Moolenaar | 9ba0eb8 | 2005-06-13 22:28:56 +0000 | [diff] [blame] | 423 | Doing on-the-fly conversion is not always possible (would require iconv |
| 424 | support). |
Bram Moolenaar | 402d2fe | 2005-04-15 21:00:38 +0000 | [diff] [blame] | 425 | - For the programs and libraries: Using them as-is would require installing |
Bram Moolenaar | 9ba0eb8 | 2005-06-13 22:28:56 +0000 | [diff] [blame] | 426 | them separately from Vim. That's mostly not impossible, but a drawback. |
Bram Moolenaar | 402d2fe | 2005-04-15 21:00:38 +0000 | [diff] [blame] | 427 | - Performance: A few tests showed that it's possible to check spelling on the |
| 428 | fly (while redrawing), just like syntax highlighting. But the mechanisms |
Bram Moolenaar | 4770d09 | 2006-01-12 23:22:24 +0000 | [diff] [blame] | 429 | used by other code are much slower. Myspell uses a hashtable, for example. |
| 430 | The affix compression that most spell checkers use makes it slower too. |
Bram Moolenaar | 51485f0 | 2005-06-04 21:55:20 +0000 | [diff] [blame] | 431 | - For using an external program like aspell a communication mechanism would |
| 432 | have to be setup. That's complicated to do in a portable way (Unix-only |
| 433 | would be relatively simple, but that's not good enough). And performance |
| 434 | will become a problem (lots of process switching involved). |
Bram Moolenaar | 402d2fe | 2005-04-15 21:00:38 +0000 | [diff] [blame] | 435 | - Missing support for words with non-word characters, such as "Etten-Leur" and |
| 436 | "et al.", would require marking the pieces of them OK, lowering the |
| 437 | reliability. |
| 438 | - Missing support for regions or dialects. Makes it difficult to accept |
| 439 | all English words and highlight non-Canadian words differently. |
| 440 | - Missing support for rare words. Many words are correct but hardly ever used |
| 441 | and could be a misspelled often-used word. |
Bram Moolenaar | 9ba0eb8 | 2005-06-13 22:28:56 +0000 | [diff] [blame] | 442 | - For making suggestions the speed is less important and requiring to install |
| 443 | another program or library would be acceptable. But the word lists probably |
| 444 | differ, the suggestions may be wrong words. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 445 | |
Bram Moolenaar | 4770d09 | 2006-01-12 23:22:24 +0000 | [diff] [blame] | 446 | |
| 447 | Spelling suggestions *develop-spell-suggestions* |
| 448 | |
| 449 | For making suggestions there are two basic mechanisms: |
| 450 | 1. Try changing the bad word a little bit and check for a match with a good |
| 451 | word. Or go through the list of good words, change them a little bit and |
| 452 | check for a match with the bad word. The changes are deleting a character, |
| 453 | inserting a character, swapping two characters, etc. |
| 454 | 2. Perform soundfolding on both the bad word and the good words and then find |
| 455 | matches, possibly with a few changes like with the first mechanism. |
| 456 | |
| 457 | The first is good for finding typing mistakes. After experimenting with |
| 458 | hashtables and looking at solutions from other spell checkers the conclusion |
| 459 | was that a trie (a kind of tree structure) is ideal for this. Both for |
| 460 | reducing memory use and being able to try sensible changes. For example, when |
| 461 | inserting a character only characters that lead to good words need to be |
| 462 | tried. Other mechanisms (with hashtables) need to try all possible letters at |
| 463 | every position in the word. Also, a hashtable has the requirement that word |
| 464 | boundaries are identified separately, while a trie does not require this. |
| 465 | That makes the mechanism a lot simpler. |
| 466 | |
| 467 | Soundfolding is useful when someone knows how the words sounds but doesn't |
| 468 | know how it is spelled. For example, the word "dictionary" might be written |
| 469 | as "daktonerie". The number of changes that the first method would need to |
| 470 | try is very big, it's hard to find the good word that way. After soundfolding |
| 471 | the words become "tktnr" and "tkxnry", these differ by only two letters. |
| 472 | |
| 473 | To find words by their soundfolded equivalent (soundalike word) we need a list |
| 474 | of all soundfolded words. A few experiments have been done to find out what |
| 475 | the best method is. Alternatives: |
| 476 | 1. Do the sound folding on the fly when looking for suggestions. This means |
| 477 | walking through the trie of good words, soundfolding each word and |
| 478 | checking how different it is from the bad word. This is very efficient for |
| 479 | memory use, but takes a long time. On a fast PC it takes a couple of |
| 480 | seconds for English, which can be acceptable for interactive use. But for |
| 481 | some languages it takes more than ten seconds (e.g., German, Catalan), |
| 482 | which is unacceptable slow. For batch processing (automatic corrections) |
Bram Moolenaar | 82038d7 | 2007-05-10 17:15:45 +0000 | [diff] [blame] | 483 | it's too slow for all languages. |
Bram Moolenaar | 4770d09 | 2006-01-12 23:22:24 +0000 | [diff] [blame] | 484 | 2. Use a trie for the soundfolded words, so that searching can be done just |
| 485 | like how it works without soundfolding. This requires remembering a list |
| 486 | of good words for each soundfolded word. This makes finding matches very |
| 487 | fast but requires quite a lot of memory, in the order of 1 to 10 Mbyte. |
| 488 | For some languages more than the original word list. |
| 489 | 3. Like the second alternative, but reduce the amount of memory by using affix |
| 490 | compression and store only the soundfolded basic word. This is what Aspell |
| 491 | does. Disadvantage is that affixes need to be stripped from the bad word |
| 492 | before soundfolding it, which means that mistakes at the start and/or end |
| 493 | of the word will cause the mechanism to fail. Also, this becomes slow when |
| 494 | the bad word is quite different from the good word. |
| 495 | |
| 496 | The choice made is to use the second mechanism and use a separate file. This |
| 497 | way a user with sufficient memory can get very good suggestions while a user |
| 498 | who is short of memory or just wants the spell checking and no suggestions |
| 499 | doesn't use so much memory. |
| 500 | |
| 501 | |
| 502 | Word frequency |
| 503 | |
| 504 | For sorting suggestions it helps to know which words are common. In theory we |
| 505 | could store a word frequency with the word in the dictionary. However, this |
| 506 | requires storing a count per word. That degrades word tree compression a lot. |
| 507 | And maintaining the word frequency for all languages will be a heavy task. |
| 508 | Also, it would be nice to prefer words that are already in the text. This way |
| 509 | the words that appear in the specific text are preferred for suggestions. |
| 510 | |
| 511 | What has been implemented is to count words that have been seen during |
| 512 | displaying. A hashtable is used to quickly find the word count. The count is |
| 513 | initialized from words listed in COMMON items in the affix file, so that it |
| 514 | also works when starting a new file. |
| 515 | |
| 516 | This isn't ideal, because the longer Vim is running the higher the counts |
Bram Moolenaar | 82038d7 | 2007-05-10 17:15:45 +0000 | [diff] [blame] | 517 | become. But in practice it is a noticeable improvement over not using the word |
Bram Moolenaar | 4770d09 | 2006-01-12 23:22:24 +0000 | [diff] [blame] | 518 | count. |
| 519 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 520 | ============================================================================== |
| 521 | 4. Assumptions *design-assumptions* |
| 522 | |
| 523 | Size of variables: |
| 524 | char 8 bit signed |
| 525 | char_u 8 bit unsigned |
Bram Moolenaar | 4770d09 | 2006-01-12 23:22:24 +0000 | [diff] [blame] | 526 | int 32 or 64 bit signed (16 might be possible with limited features) |
| 527 | unsigned 32 or 64 bit unsigned (16 as with ints) |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 528 | long 32 or 64 bit signed, can hold a pointer |
| 529 | |
| 530 | Note that some compilers cannot handle long lines or strings. The C89 |
| 531 | standard specifies a limit of 509 characters. |
| 532 | |
| 533 | vim:tw=78:ts=8:ft=help:norl: |