Mercurial > vim
annotate runtime/doc/develop.txt @ 31499:16174b7435a0 v9.0.1082
patch 9.0.1082: some jsonc files are not recognized
Commit: https://github.com/vim/vim/commit/104b2ff4d0ec9248ba0b979aa3bbccb65fcad422
Author: kylo252 <59826753+kylo252@users.noreply.github.com>
Date: Mon Dec 19 20:42:49 2022 +0000
patch 9.0.1082: some jsonc files are not recognized
Problem: Some jsonc files are not recognized.
Solution: Add patterns for jsonc and move some from json to jsonc.
(closes #11711)
| author | Bram Moolenaar <Bram@vim.org> |
|---|---|
| date | Mon, 19 Dec 2022 21:45:03 +0100 |
| parents | 1e91e26ceebf |
| children | 4635e43f2c6f |
| rev | line source |
|---|---|
| 30547 | 1 *develop.txt* For Vim version 9.0. Last change: 2022 Sep 20 |
| 7 | 2 |
| 3 | |
| 4 VIM REFERENCE MANUAL by Bram Moolenaar | |
| 5 | |
| 6 | |
| 7 Development of Vim. *development* | |
| 8 | |
| 9 This text is important for those who want to be involved in further developing | |
| 10 Vim. | |
| 11 | |
| 12 1. Design goals |design-goals| | |
| 13 2. Coding style |coding-style| | |
| 14 3. Design decisions |design-decisions| | |
| 15 4. Assumptions |design-assumptions| | |
| 16 | |
| 17 See the file README.txt in the "src" directory for an overview of the source | |
| 18 code. | |
| 19 | |
| 20 Vim is open source software. Everybody is encouraged to contribute to help | |
| 13857 | 21 improving Vim. For sending patches a unified diff "diff -u" is preferred. |
| 22 You can create a pull request on github, but it's not required. | |
| 4358 | 23 Also see http://vim.wikia.com/wiki/How_to_make_and_submit_a_patch. |
| 7 | 24 |
| 25 ============================================================================== | |
| 26 1. Design goals *design-goals* | |
| 27 | |
| 28 Most important things come first (roughly). | |
| 29 | |
| 30 Note that quite a few items are contradicting. This is intentional. A | |
| 31 balance must be found between them. | |
| 32 | |
| 33 | |
| 34 VIM IS... VI COMPATIBLE *design-compatible* | |
| 35 | |
| 36 First of all, it should be possible to use Vim as a drop-in replacement for | |
| 21676 | 37 Vi. When the user wants to, Vim can be used in compatible mode and hardly |
| 38 any differences with the original Vi will be noticed. | |
| 7 | 39 |
| 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. | |
| 54 | |
| 55 | |
| 56 VIM IS... IMPROVED *design-improved* | |
| 57 | |
| 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 | |
|
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 | 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. | |
| 75 | |
| 76 | |
| 77 VIM IS... MULTI PLATFORM *design-multi-platform* | |
| 78 | |
| 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.] | |
| 94 | |
| 95 | |
| 96 VIM IS... WELL DOCUMENTED *design-documented* | |
| 97 | |
| 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. | |
| 104 | |
| 105 | |
| 106 VIM IS... HIGH SPEED AND SMALL IN SIZE *design-speed-size* | |
| 107 | |
| 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. | |
| 121 | |
| 122 | |
| 123 VIM IS... MAINTAINABLE *design-maintain* | |
| 124 | |
| 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|. | |
| 481 | 127 - Use comments in a useful way! Quoting the function name and argument names |
| 128 is NOT useful. Do explain what they are for. | |
| 7 | 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. | |
| 133 | |
| 134 | |
| 135 VIM IS... FLEXIBLE *design-flexible* | |
| 136 | |
| 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. | |
| 143 | |
| 144 | |
| 145 VIM IS... NOT *design-not* | |
| 146 | |
| 11914 | 147 - Vim is not a shell or an Operating System. It does provide a terminal |
| 148 window, in which you can run a shell or debugger. E.g. to be able to do | |
| 149 this over an ssh connection. But if you don't need a text editor with that | |
| 150 it is out of scope (use something like screen or tmux instead). | |
| 7 | 151 A satirical way to say this: "Unlike Emacs, Vim does not attempt to include |
| 152 everything but the kitchen sink, but some people say that you can clean one | |
| 153 with it. ;-)" | |
| 20115 | 154 To use Vim with gdb see |terminal-debugger|. Other (older) tools can be |
| 155 found at http://www.agide.org and http://clewn.sf.net. | |
| 7 | 156 - Vim is not a fancy GUI editor that tries to look nice at the cost of |
| 157 being less consistent over all platforms. But functional GUI features are | |
| 158 welcomed. | |
| 159 | |
| 160 ============================================================================== | |
| 161 2. Coding style *coding-style* | |
| 162 | |
| 163 These are the rules to use when making changes to the Vim source code. Please | |
| 164 stick to these rules, to keep the sources readable and maintainable. | |
| 165 | |
| 166 This list is not complete. Look in the source code for more examples. | |
| 167 | |
| 168 | |
| 169 MAKING CHANGES *style-changes* | |
| 170 | |
| 171 The basic steps to make changes to the code: | |
|
7707
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
172 1. Get the code from github. That makes it easier to keep your changed |
|
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
173 version in sync with the main code base (it may be a while before your |
|
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
174 changes will be included). You do need to spend some time learning git, |
|
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
175 it's not the most user friendly tool. |
|
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
176 2. Adjust the documentation. Doing this first gives you an impression of how |
| 7 | 177 your changes affect the user. |
|
7707
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
178 3. Make the source code changes. |
|
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
179 4. Check ../doc/todo.txt if the change affects any listed item. |
|
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
180 5. Make a patch with "git diff". You can also create a pull request on |
|
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
181 github, but it's the diff that matters. |
|
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
182 6. Make a note about what changed, preferably mentioning the problem and the |
|
10548
74effdaa369e
Updated runtime files.
Christian Brabandt <cb@256bit.org>
parents:
10198
diff
changeset
|
183 solution. Send an email to the |vim-dev| maillist with an explanation and |
|
7707
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
184 include the diff. Or create a pull request on github. |
|
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
185 |
|
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
186 |
|
13818
28ac7914b2b6
Update runtime files and translations
Christian Brabandt <cb@256bit.org>
parents:
13735
diff
changeset
|
187 C COMPILER *style-compiler* *ANSI-C* *C89* *C99* |
|
7707
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
188 |
|
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
189 The minimal C compiler version supported is C89, also known as ANSI C. |
|
13716
30f9ebe3e602
patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents:
11914
diff
changeset
|
190 Later standards, such as C99, are not widely supported, or at least not 100% |
|
30377
c9d2c554f314
patch 9.0.0524: build instructions for MS-Windows are outdated
Bram Moolenaar <Bram@vim.org>
parents:
29314
diff
changeset
|
191 supported. Therefore we use only some of the C99 features and explicitly |
|
c9d2c554f314
patch 9.0.0524: build instructions for MS-Windows are outdated
Bram Moolenaar <Bram@vim.org>
parents:
29314
diff
changeset
|
192 disallow some (this will gradually be adjusted over time). |
|
13716
30f9ebe3e602
patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents:
11914
diff
changeset
|
193 |
|
30f9ebe3e602
patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents:
11914
diff
changeset
|
194 Please don't make changes everywhere to use the C99 features, it causes merge |
|
30f9ebe3e602
patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents:
11914
diff
changeset
|
195 problems for existing patches. Only use them for new and changed code. |
|
30f9ebe3e602
patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents:
11914
diff
changeset
|
196 |
|
30f9ebe3e602
patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents:
11914
diff
changeset
|
197 Comments ~ |
|
30f9ebe3e602
patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents:
11914
diff
changeset
|
198 |
| 18719 | 199 Traditionally Vim uses /* comments */. We intend to keep it that way |
| 200 for file and function headers and larger blocks of code, E.g.: | |
| 201 /* | |
| 202 * The "foo" argument does something useful. | |
| 203 * Return OK or FAIL. | |
| 204 */ | |
| 205 For new code or lines of code that change, it is preferred to use // comments. | |
| 206 Especially when it comes after code: | |
|
13716
30f9ebe3e602
patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents:
11914
diff
changeset
|
207 int some_var; // single line comment useful here |
|
30f9ebe3e602
patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents:
11914
diff
changeset
|
208 |
|
30f9ebe3e602
patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents:
11914
diff
changeset
|
209 Enums ~ |
|
30f9ebe3e602
patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents:
11914
diff
changeset
|
210 |
|
30f9ebe3e602
patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents:
11914
diff
changeset
|
211 The last item in an enum may have a trailing comma. C89 didn't allow this. |
|
30f9ebe3e602
patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents:
11914
diff
changeset
|
212 |
|
30f9ebe3e602
patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents:
11914
diff
changeset
|
213 Types ~ |
|
7707
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
214 |
|
13716
30f9ebe3e602
patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents:
11914
diff
changeset
|
215 "long long" is allowed and can be expected to be 64 bits. Use %lld in printf |
|
30f9ebe3e602
patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents:
11914
diff
changeset
|
216 formats. Also "long long unsigned" with %llu. |
|
30f9ebe3e602
patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents:
11914
diff
changeset
|
217 |
|
30377
c9d2c554f314
patch 9.0.0524: build instructions for MS-Windows are outdated
Bram Moolenaar <Bram@vim.org>
parents:
29314
diff
changeset
|
218 Declarations ~ |
|
c9d2c554f314
patch 9.0.0524: build instructions for MS-Windows are outdated
Bram Moolenaar <Bram@vim.org>
parents:
29314
diff
changeset
|
219 |
|
c9d2c554f314
patch 9.0.0524: build instructions for MS-Windows are outdated
Bram Moolenaar <Bram@vim.org>
parents:
29314
diff
changeset
|
220 Now that the minimal supported compiler is MSVC 2015 declarations do not need |
|
c9d2c554f314
patch 9.0.0524: build instructions for MS-Windows are outdated
Bram Moolenaar <Bram@vim.org>
parents:
29314
diff
changeset
|
221 to be at the start of a block. However, it is often a good idea to do this |
|
c9d2c554f314
patch 9.0.0524: build instructions for MS-Windows are outdated
Bram Moolenaar <Bram@vim.org>
parents:
29314
diff
changeset
|
222 anyway. |
|
c9d2c554f314
patch 9.0.0524: build instructions for MS-Windows are outdated
Bram Moolenaar <Bram@vim.org>
parents:
29314
diff
changeset
|
223 |
|
c9d2c554f314
patch 9.0.0524: build instructions for MS-Windows are outdated
Bram Moolenaar <Bram@vim.org>
parents:
29314
diff
changeset
|
224 Declaration of the for loop variable inside the loop is recommended: |
|
c9d2c554f314
patch 9.0.0524: build instructions for MS-Windows are outdated
Bram Moolenaar <Bram@vim.org>
parents:
29314
diff
changeset
|
225 for (int i = 0; i < len; ++i) |
|
c9d2c554f314
patch 9.0.0524: build instructions for MS-Windows are outdated
Bram Moolenaar <Bram@vim.org>
parents:
29314
diff
changeset
|
226 Since this is clearly an advantage we'll use this more often. |
|
c9d2c554f314
patch 9.0.0524: build instructions for MS-Windows are outdated
Bram Moolenaar <Bram@vim.org>
parents:
29314
diff
changeset
|
227 |
|
c9d2c554f314
patch 9.0.0524: build instructions for MS-Windows are outdated
Bram Moolenaar <Bram@vim.org>
parents:
29314
diff
changeset
|
228 |
|
13716
30f9ebe3e602
patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents:
11914
diff
changeset
|
229 Not to be used ~ |
|
30f9ebe3e602
patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents:
11914
diff
changeset
|
230 |
|
30f9ebe3e602
patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents:
11914
diff
changeset
|
231 These C99 features are not to be used, because not enough compilers support |
|
30f9ebe3e602
patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents:
11914
diff
changeset
|
232 them: |
|
30f9ebe3e602
patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents:
11914
diff
changeset
|
233 - Variable length arrays (even in C11 this is an optional feature). |
|
30f9ebe3e602
patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents:
11914
diff
changeset
|
234 - _Bool and _Complex types. |
|
30f9ebe3e602
patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents:
11914
diff
changeset
|
235 - "inline" (it's hardly ever needed, let the optimizer do its work) |
|
13726
d35b1702a1da
patch 8.0.1735: flexible array member feature not supported by HP-UX
Christian Brabandt <cb@256bit.org>
parents:
13716
diff
changeset
|
236 - flexible array members: Not supported by HP-UX C compiler (John Marriott) |
| 7 | 237 |
| 238 | |
| 239 USE OF COMMON FUNCTIONS *style-functions* | |
| 240 | |
| 241 Some functions that are common to use, have a special Vim version. Always | |
| 242 consider using the Vim version, because they were introduced with a reason. | |
| 243 | |
| 244 NORMAL NAME VIM NAME DIFFERENCE OF VIM VERSION | |
| 245 free() vim_free() Checks for freeing NULL | |
| 246 malloc() alloc() Checks for out of memory situation | |
| 247 malloc() lalloc() Like alloc(), but has long argument | |
| 248 strcpy() STRCPY() Includes cast to (char *), for char_u * args | |
| 249 strchr() vim_strchr() Accepts special characters | |
| 250 strrchr() vim_strrchr() Accepts special characters | |
| 251 isspace() vim_isspace() Can handle characters > 128 | |
| 1240 | 252 iswhite() vim_iswhite() Only TRUE for tab and space |
| 711 | 253 memcpy() mch_memmove() Handles overlapped copies |
| 254 bcopy() mch_memmove() Handles overlapped copies | |
| 7 | 255 memset() vim_memset() Uniform for all systems |
| 256 | |
| 257 | |
| 258 NAMES *style-names* | |
| 259 | |
| 260 Function names can not be more than 31 characters long (because of VMS). | |
| 261 | |
|
7707
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
262 Don't use "delete" or "this" as a variable name, C++ doesn't like it. |
| 7 | 263 |
| 264 Because of the requirement that Vim runs on as many systems as possible, we | |
| 265 need to avoid using names that are already defined by the system. This is a | |
| 266 list of names that are known to cause trouble. The name is given as a regexp | |
| 267 pattern. | |
| 268 | |
| 269 is.*() POSIX, ctype.h | |
| 270 to.*() POSIX, ctype.h | |
| 271 | |
| 272 d_.* POSIX, dirent.h | |
| 273 l_.* POSIX, fcntl.h | |
| 274 gr_.* POSIX, grp.h | |
| 275 pw_.* POSIX, pwd.h | |
| 276 sa_.* POSIX, signal.h | |
| 277 mem.* POSIX, string.h | |
| 278 str.* POSIX, string.h | |
| 279 wcs.* POSIX, string.h | |
| 280 st_.* POSIX, stat.h | |
| 281 tms_.* POSIX, times.h | |
| 282 tm_.* POSIX, time.h | |
| 283 c_.* POSIX, termios.h | |
| 284 MAX.* POSIX, limits.h | |
| 285 __.* POSIX, system | |
| 286 _[A-Z].* POSIX, system | |
| 287 E[A-Z0-9]* POSIX, errno.h | |
| 288 | |
| 1121 | 289 .*_t POSIX, for typedefs. Use .*_T instead. |
| 7 | 290 |
| 291 wait don't use as argument to a function, conflicts with types.h | |
| 292 index shadows global declaration | |
| 293 time shadows global declaration | |
| 294 new C++ reserved keyword | |
| 295 | |
| 3281 | 296 clear Mac curses.h |
| 297 echo Mac curses.h | |
| 298 instr Mac curses.h | |
| 299 meta Mac curses.h | |
| 300 newwin Mac curses.h | |
| 301 nl Mac curses.h | |
| 302 overwrite Mac curses.h | |
| 303 refresh Mac curses.h | |
| 304 scroll Mac curses.h | |
| 305 typeahead Mac curses.h | |
| 306 | |
| 7 | 307 basename() GNU string function |
| 308 dirname() GNU string function | |
| 309 get_env_value() Linux system function | |
| 310 | |
| 311 | |
| 312 VARIOUS *style-various* | |
| 313 | |
| 502 | 314 Typedef'ed names should end in "_T": > |
| 315 typedef int some_T; | |
| 7 | 316 Define'ed names should be uppercase: > |
| 317 #define SOME_THING | |
| 318 Features always start with "FEAT_": > | |
| 319 #define FEAT_FOO | |
| 320 | |
| 321 Don't use '\"', some compilers can't handle it. '"' works fine. | |
| 322 | |
| 323 Don't use: | |
| 324 #if HAVE_SOME | |
| 325 Some compilers can't handle that and complain that "HAVE_SOME" is not defined. | |
| 326 Use | |
| 327 #ifdef HAVE_SOME | |
| 328 or | |
| 329 #if defined(HAVE_SOME) | |
| 330 | |
| 331 | |
| 332 STYLE *style-examples* | |
| 333 | |
| 334 General rule: One statement per line. | |
| 335 | |
| 336 Wrong: if (cond) a = 1; | |
| 337 | |
| 338 OK: if (cond) | |
| 339 a = 1; | |
| 340 | |
| 341 Wrong: while (cond); | |
| 342 | |
| 343 OK: while (cond) | |
| 344 ; | |
| 345 | |
| 346 Wrong: do a = 1; while (cond); | |
| 347 | |
| 348 OK: do | |
| 349 a = 1; | |
| 350 while (cond); | |
| 351 | |
|
7707
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
352 Wrong: if (cond) { |
|
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
353 cmd; |
|
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
354 cmd; |
|
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
355 } else { |
|
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
356 cmd; |
|
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
357 cmd; |
|
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
358 } |
|
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
359 |
|
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
360 OK: if (cond) |
|
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
361 { |
|
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
362 cmd; |
|
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
363 cmd; |
|
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
364 } |
|
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
365 else |
|
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
366 { |
|
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
367 cmd; |
|
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
368 cmd; |
|
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
369 } |
| 7 | 370 |
| 15878 | 371 When a block has one line the braces can be left out. When an if/else has |
| 372 braces on one block, it usually looks better when the other block also has | |
| 373 braces: | |
| 374 OK: if (cond) | |
| 375 cmd; | |
| 376 else | |
| 377 cmd; | |
| 378 | |
| 379 OK: if (cond) | |
| 380 { | |
| 381 cmd; | |
| 382 } | |
| 383 else | |
| 384 { | |
| 385 cmd; | |
| 386 cmd; | |
| 387 } | |
| 388 | |
|
7876
93f747af7b58
commit https://github.com/vim/vim/commit/5e9b2fa9bb0e6061cf18457c173cd141a5dc9c92
Christian Brabandt <cb@256bit.org>
parents:
7707
diff
changeset
|
389 Use ANSI (new style) function declarations with the return type on a separate |
|
93f747af7b58
commit https://github.com/vim/vim/commit/5e9b2fa9bb0e6061cf18457c173cd141a5dc9c92
Christian Brabandt <cb@256bit.org>
parents:
7707
diff
changeset
|
390 indented line. |
| 7 | 391 |
| 392 Wrong: int function_name(int arg1, int arg2) | |
| 393 | |
| 394 OK: /* | |
| 395 * Explanation of what this function is used for. | |
| 396 * | |
| 397 * Return value explanation. | |
| 398 */ | |
| 399 int | |
|
7707
41768bcebc9b
commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents:
5763
diff
changeset
|
400 function_name( |
| 15878 | 401 int arg1, // short comment about arg1 |
| 402 int arg2) // short comment about arg2 | |
| 7 | 403 { |
| 15878 | 404 int local; // comment about local |
| 7 | 405 |
| 406 local = arg1 * arg2; | |
| 407 | |
| 408 | |
| 409 | |
| 410 SPACES AND PUNCTUATION *style-spaces* | |
| 411 | |
| 412 No space between a function name and the bracket: | |
| 413 | |
| 414 Wrong: func (arg); | |
| 415 OK: func(arg); | |
| 416 | |
| 417 Do use a space after if, while, switch, etc. | |
| 418 | |
| 419 Wrong: if(arg) for(;;) | |
| 420 OK: if (arg) for (;;) | |
| 421 | |
| 422 Use a space after a comma and semicolon: | |
| 423 | |
| 424 Wrong: func(arg1,arg2); for (i = 0;i < 2;++i) | |
| 425 OK: func(arg1, arg2); for (i = 0; i < 2; ++i) | |
| 426 | |
| 427 Use a space before and after '=', '+', '/', etc. | |
| 428 | |
| 429 Wrong: var=a*5; | |
| 430 OK: var = a * 5; | |
| 431 | |
| 432 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
|
433 just above the group of lines. This makes it easier to quickly see what is |
| 7 | 434 being done. |
| 435 | |
| 436 OK: /* Prepare for building the table. */ | |
| 437 get_first_item(); | |
| 438 table_idx = 0; | |
| 439 | |
| 440 /* Build the table */ | |
| 441 while (has_item()) | |
| 442 table[table_idx++] = next_item(); | |
| 443 | |
| 444 /* Finish up. */ | |
| 445 cleanup_items(); | |
| 446 generate_hash(table); | |
| 447 | |
| 448 ============================================================================== | |
| 449 3. Design decisions *design-decisions* | |
| 450 | |
| 451 Folding | |
| 452 | |
| 453 Several forms of folding should be possible for the same buffer. For example, | |
| 454 have one window that shows the text with function bodies folded, another | |
| 455 window that shows a function body. | |
| 456 | |
| 457 Folding is a way to display the text. It should not change the text itself. | |
| 458 Therefore the folding has been implemented as a filter between the text stored | |
| 459 in a buffer (buffer lines) and the text displayed in a window (logical lines). | |
| 460 | |
| 461 | |
| 462 Naming the window | |
| 463 | |
| 464 The word "window" is commonly used for several things: A window on the screen, | |
| 465 the xterm window, a window inside Vim to view a buffer. | |
| 466 To avoid confusion, other items that are sometimes called window have been | |
| 467 given another name. Here is an overview of the related items: | |
| 468 | |
| 469 screen The whole display. For the GUI it's something like 1024x768 | |
| 470 pixels. The Vim shell can use the whole screen or part of it. | |
| 471 shell The Vim application. This can cover the whole screen (e.g., | |
| 472 when running in a console) or part of it (xterm or GUI). | |
| 473 window View on a buffer. There can be several windows in Vim, | |
| 474 together with the command line, menubar, toolbar, etc. they | |
| 475 fit in the shell. | |
| 476 | |
| 477 | |
| 236 | 478 Spell checking *develop-spell* |
| 479 | |
| 480 When spell checking was going to be added to Vim a survey was done over the | |
| 481 available spell checking libraries and programs. Unfortunately, the result | |
| 482 was that none of them provided sufficient capabilities to be used as the spell | |
| 483 checking engine in Vim, for various reasons: | |
| 484 | |
| 21991 | 485 - Missing support for multibyte encodings. At least UTF-8 must be supported, |
| 236 | 486 so that more than one language can be used in the same file. |
| 323 | 487 Doing on-the-fly conversion is not always possible (would require iconv |
| 488 support). | |
| 236 | 489 - For the programs and libraries: Using them as-is would require installing |
| 323 | 490 them separately from Vim. That's mostly not impossible, but a drawback. |
| 236 | 491 - Performance: A few tests showed that it's possible to check spelling on the |
| 492 fly (while redrawing), just like syntax highlighting. But the mechanisms | |
| 625 | 493 used by other code are much slower. Myspell uses a hashtable, for example. |
| 494 The affix compression that most spell checkers use makes it slower too. | |
| 300 | 495 - For using an external program like aspell a communication mechanism would |
| 496 have to be setup. That's complicated to do in a portable way (Unix-only | |
| 497 would be relatively simple, but that's not good enough). And performance | |
| 498 will become a problem (lots of process switching involved). | |
| 236 | 499 - Missing support for words with non-word characters, such as "Etten-Leur" and |
| 500 "et al.", would require marking the pieces of them OK, lowering the | |
| 501 reliability. | |
| 502 - Missing support for regions or dialects. Makes it difficult to accept | |
| 503 all English words and highlight non-Canadian words differently. | |
| 504 - Missing support for rare words. Many words are correct but hardly ever used | |
| 505 and could be a misspelled often-used word. | |
| 323 | 506 - For making suggestions the speed is less important and requiring to install |
| 507 another program or library would be acceptable. But the word lists probably | |
| 508 differ, the suggestions may be wrong words. | |
| 7 | 509 |
| 625 | 510 |
| 511 Spelling suggestions *develop-spell-suggestions* | |
| 512 | |
| 513 For making suggestions there are two basic mechanisms: | |
| 514 1. Try changing the bad word a little bit and check for a match with a good | |
| 515 word. Or go through the list of good words, change them a little bit and | |
| 516 check for a match with the bad word. The changes are deleting a character, | |
| 517 inserting a character, swapping two characters, etc. | |
| 518 2. Perform soundfolding on both the bad word and the good words and then find | |
| 519 matches, possibly with a few changes like with the first mechanism. | |
| 520 | |
| 521 The first is good for finding typing mistakes. After experimenting with | |
| 522 hashtables and looking at solutions from other spell checkers the conclusion | |
| 523 was that a trie (a kind of tree structure) is ideal for this. Both for | |
| 524 reducing memory use and being able to try sensible changes. For example, when | |
| 525 inserting a character only characters that lead to good words need to be | |
| 526 tried. Other mechanisms (with hashtables) need to try all possible letters at | |
| 527 every position in the word. Also, a hashtable has the requirement that word | |
| 528 boundaries are identified separately, while a trie does not require this. | |
| 529 That makes the mechanism a lot simpler. | |
| 530 | |
| 531 Soundfolding is useful when someone knows how the words sounds but doesn't | |
| 532 know how it is spelled. For example, the word "dictionary" might be written | |
| 533 as "daktonerie". The number of changes that the first method would need to | |
| 534 try is very big, it's hard to find the good word that way. After soundfolding | |
| 535 the words become "tktnr" and "tkxnry", these differ by only two letters. | |
| 536 | |
| 537 To find words by their soundfolded equivalent (soundalike word) we need a list | |
| 538 of all soundfolded words. A few experiments have been done to find out what | |
| 539 the best method is. Alternatives: | |
| 540 1. Do the sound folding on the fly when looking for suggestions. This means | |
| 541 walking through the trie of good words, soundfolding each word and | |
| 542 checking how different it is from the bad word. This is very efficient for | |
| 543 memory use, but takes a long time. On a fast PC it takes a couple of | |
| 544 seconds for English, which can be acceptable for interactive use. But for | |
| 545 some languages it takes more than ten seconds (e.g., German, Catalan), | |
| 17667 | 546 which is unacceptably slow. For batch processing (automatic corrections) |
| 1197 | 547 it's too slow for all languages. |
| 625 | 548 2. Use a trie for the soundfolded words, so that searching can be done just |
| 549 like how it works without soundfolding. This requires remembering a list | |
| 550 of good words for each soundfolded word. This makes finding matches very | |
| 551 fast but requires quite a lot of memory, in the order of 1 to 10 Mbyte. | |
| 552 For some languages more than the original word list. | |
| 553 3. Like the second alternative, but reduce the amount of memory by using affix | |
| 554 compression and store only the soundfolded basic word. This is what Aspell | |
| 555 does. Disadvantage is that affixes need to be stripped from the bad word | |
| 556 before soundfolding it, which means that mistakes at the start and/or end | |
| 557 of the word will cause the mechanism to fail. Also, this becomes slow when | |
| 558 the bad word is quite different from the good word. | |
| 559 | |
| 560 The choice made is to use the second mechanism and use a separate file. This | |
| 561 way a user with sufficient memory can get very good suggestions while a user | |
| 562 who is short of memory or just wants the spell checking and no suggestions | |
| 563 doesn't use so much memory. | |
| 564 | |
| 565 | |
| 566 Word frequency | |
| 567 | |
| 568 For sorting suggestions it helps to know which words are common. In theory we | |
| 569 could store a word frequency with the word in the dictionary. However, this | |
| 570 requires storing a count per word. That degrades word tree compression a lot. | |
| 571 And maintaining the word frequency for all languages will be a heavy task. | |
| 572 Also, it would be nice to prefer words that are already in the text. This way | |
| 573 the words that appear in the specific text are preferred for suggestions. | |
| 574 | |
| 575 What has been implemented is to count words that have been seen during | |
| 576 displaying. A hashtable is used to quickly find the word count. The count is | |
| 577 initialized from words listed in COMMON items in the affix file, so that it | |
| 578 also works when starting a new file. | |
| 579 | |
| 580 This isn't ideal, because the longer Vim is running the higher the counts | |
| 1197 | 581 become. But in practice it is a noticeable improvement over not using the word |
| 625 | 582 count. |
| 583 | |
| 7 | 584 ============================================================================== |
| 585 4. Assumptions *design-assumptions* | |
| 586 | |
| 587 Size of variables: | |
| 588 char 8 bit signed | |
| 589 char_u 8 bit unsigned | |
| 625 | 590 int 32 or 64 bit signed (16 might be possible with limited features) |
| 591 unsigned 32 or 64 bit unsigned (16 as with ints) | |
| 7 | 592 long 32 or 64 bit signed, can hold a pointer |
| 593 | |
| 594 Note that some compilers cannot handle long lines or strings. The C89 | |
| 595 standard specifies a limit of 509 characters. | |
| 596 | |
| 14421 | 597 vim:tw=78:ts=8:noet:ft=help:norl: |