*develop.txt*   For Vim version 7.1.  Last change: 2007 May 11  		  VIM REFERENCE MANUAL    by Bram Moolenaar  Development of Vim.					*development* This text is important for those who want to be involved in further developingVim. 1. Design goals		|design-goals|2. Coding style		|coding-style|3. Design decisions	|design-decisions|4. Assumptions		|design-assumptions| See the file README.txt in the "src" directory for an overview of the sourcecode. Vim is open source software.  Everybody is encouraged to contribute to helpimproving Vim.  For sending patches a context diff "diff -c" is preferred.Also see http://www.vim.org/tips/tip.php?tip_id=618. ==============================================================================1. Design goals						*design-goals* Most important things come first (roughly). Note that quite a few items are contradicting.  This is intentional.  Abalance must be found between them.  VIM IS... VI COMPATIBLE					*design-compatible* First of all, it should be possible to use Vim as a drop-in replacement forVi.  When the user wants to, he can use Vim in compatible mode and hardlynotice any difference with the original Vi. Exceptions:- We don't reproduce obvious Vi bugs in Vim.- There are different versions of Vi.  I am using Version 3.7 (6/7/85) as a  reference.  But support for other versions is also included when possible.  The Vi part of POSIX is not considered a definitive source.- Vim adds new commands, you cannot rely on some command to fail because it  didn't exist in Vi.- Vim will have a lot of features that Vi doesn't have.  Going back from Vim  to Vi will be a problem, this cannot be avoided.- Some things are hardly ever used (open mode, sending an e-mail when  crashing, etc.).  Those will only be included when someone has a good reason  why it should be included and it's not too much work.- For some items it is debatable whether Vi compatibility should be  maintained.  There will be an option flag for these.  VIM IS... IMPROVED					*design-improved* The IMproved bits of Vim should make it a better Vi, without becoming acompletely different editor.  Extensions are done with a "Vi spirit".- Use the keyboard as much as feasible.  The mouse requires a third hand,  which we don't have.  Many terminals don't have a mouse.- When the mouse is used anyway, avoid the need to switch back to the  keyboard.  Avoid mixing mouse and keyboard handling.- Add commands and options in a consistent way.  Otherwise people will have a  hard time finding and remembering them.  Keep in mind that more commands and  options will be added later.- A feature that people do not know about is a useless feature.  Don't add  obscure features, or at least add hints in documentation that they exists.- Minimize using CTRL and other modifiers, they are more difficult to type.- There are many first-time and inexperienced Vim users.  Make it easy for  them to start using Vim and learn more over time.- There is no limit to the features that can be added.  Selecting new features  is one based on (1) what users ask for, (2) how much effort it takes to  implement and (3) someone actually implementing it.  VIM IS... MULTI PLATFORM				*design-multi-platform* Vim tries to help as many users on as many platforms as possible.- Support many kinds of terminals.  The minimal demands are cursor positioning  and clear-screen.  Commands should only use key strokes that most keyboards  have.  Support all the keys on the keyboard for mapping.- Support many platforms.  A condition is that there is someone willing to do  Vim development on that platform, and it doesn't mean messing up the code.- Support many compilers and libraries.  Not everybody is able or allowed to  install another compiler or GUI library.- People switch from one platform to another, and from GUI to terminal  version.  Features should be present in all versions, or at least in as many  as possible with a reasonable effort.  Try to avoid that users must switch  between platforms to accomplish their work efficiently.- That a feature is not possible on some platforms, or only possible on one  platform, does not mean it cannot be implemented.  [This intentionally  contradicts the previous item, these two must be balanced.]  VIM IS... WELL DOCUMENTED				*design-documented* - A feature that isn't documented is a useless feature.  A patch for a new  feature must include the documentation.- Documentation should be comprehensive and understandable.  Using examples is  recommended.- Don't make the text unnecessarily long.  Less documentation means that an  item is easier to find.  VIM IS... HIGH SPEED AND SMALL IN SIZE			*design-speed-size* Using Vim must not be a big attack on system resources.  Keep it small andfast.- Computers are becoming faster and bigger each year.  Vim can grow too, but  no faster than computers are growing.  Keep Vim usable on older systems.- Many users start Vim from a shell very often.  Startup time must be short.- Commands must work efficiently.  The time they consume must be as small as  possible.  Useful commands may take longer.- Don't forget that some people use Vim over a slow connection.  Minimize the  communication overhead.- Items that add considerably to the size and are not used by many people  should be a feature that can be disabled.- Vim is a component among other components.  Don't turn it into a massive  application, but have it work well together with other programs.  VIM IS... MAINTAINABLE					*design-maintain* - The source code should not become a mess.  It should be reliable code.- Use the same layout in all files to make it easy to read |coding-style|.- Use comments in a useful way!  Quoting the function name and argument names  is NOT useful.  Do explain what they are for.- Porting to another platform should be made easy, without having to change  too much platform-independent code.- Use the object-oriented spirit: Put data and code together.  Minimize the  knowledge spread to other parts of the code.  VIM IS... FLEXIBLE					*design-flexible* Vim should make it easy for users to work in their preferred styles ratherthan coercing its users into particular patterns of work.  This can be foritems with a large impact (e.g., the 'compatible' option) or for details.  Thedefaults are carefully chosen such that most users will enjoy using Vim as itis.  Commands and options can be used to adjust Vim to the desire of the userand its environment.  VIM IS... NOT						*design-not* - Vim is not a shell or an Operating System.  You will not be able to run a  shell inside Vim or use it to control a debugger.  This should work the  other way around: Use Vim as a component from a shell or in an IDE.  A satirical way to say this: "Unlike Emacs, Vim does not attempt to include  everything but the kitchen sink, but some people say that you can clean one  with it.  ;-)"  To use Vim with gdb see: http://www.agide.org and http://clewn.sf.net.- Vim is not a fancy GUI editor that tries to look nice at the cost of  being less consistent over all platforms.  But functional GUI features are  welcomed. ==============================================================================2. Coding style						*coding-style* These are the rules to use when making changes to the Vim source code.  Pleasestick to these rules, to keep the sources readable and maintainable. This list is not complete.  Look in the source code for more examples.  MAKING CHANGES						*style-changes* The basic steps to make changes to the code:1. Adjust the documentation.  Doing this first gives you an impression of how   your changes affect the user.2. Make the source code changes.3. Check ../doc/todo.txt if the change affects any listed item.4. Make a patch with "diff -c" against the unmodified code and docs.5. Make a note about what changed and include it with the patch.  USE OF COMMON FUNCTIONS					*style-functions* Some functions that are common to use, have a special Vim version.  Alwaysconsider using the Vim version, because they were introduced with a reason. NORMAL NAME	VIM NAME	DIFFERENCE OF VIM VERSIONfree()		vim_free()	Checks for freeing NULLmalloc()	alloc()		Checks for out of memory situationmalloc()	lalloc()	Like alloc(), but has long argumentstrcpy()	STRCPY()	Includes cast to (char *), for char_u * argsstrchr()	vim_strchr()	Accepts special charactersstrrchr()	vim_strrchr()	Accepts special charactersisspace()	vim_isspace()	Can handle characters > 128iswhite()	vim_iswhite()	Only TRUE for tab and spacememcpy()	mch_memmove()	Handles overlapped copiesbcopy()		mch_memmove()	Handles overlapped copiesmemset()	vim_memset()	Uniform for all systems  NAMES							*style-names* Function names can not be more than 31 characters long (because of VMS). Don't use "delete" as a variable name, C++ doesn't like it. Because of the requirement that Vim runs on as many systems as possible, weneed to avoid using names that are already defined by the system.  This is alist of names that are known to cause trouble.  The name is given as a regexppattern. is.*()		POSIX, ctype.hto.*()		POSIX, ctype.h d_.*		POSIX, dirent.hl_.*		POSIX, fcntl.hgr_.*		POSIX, grp.hpw_.*		POSIX, pwd.hsa_.*		POSIX, signal.hmem.*		POSIX, string.hstr.*		POSIX, string.hwcs.*		POSIX, string.hst_.*		POSIX, stat.htms_.*		POSIX, times.htm_.*		POSIX, time.hc_.*		POSIX, termios.hMAX.*		POSIX, limits.h__.*		POSIX, system_[A-Z].*	POSIX, systemE[A-Z0-9]*	POSIX, errno.h .*_t		POSIX, for typedefs.  Use .*_T instead. wait		don't use as argument to a function, conflicts with types.hindex		shadows global declarationtime		shadows global declarationnew		C++ reserved keywordtry		Borland C++ doesn't like it to be used as a variable. basename()	GNU string functiondirname()	GNU string functionget_env_value()	Linux system function  VARIOUS							*style-various* Typedef'ed names should end in "_T": >    typedef int some_T;Define'ed names should be uppercase: >    #define SOME_THINGFeatures always start with "FEAT_": >    #define FEAT_FOO Don't use '\"', some compilers can't handle it.  '"' works fine. Don't use:    #if HAVE_SOMESome compilers can't handle that and complain that "HAVE_SOME" is not defined.Use    #ifdef HAVE_SOMEor    #if defined(HAVE_SOME)  STYLE							*style-examples* General rule: One statement per line. Wrong:	    if (cond) a = 1; OK:	    if (cond)		a = 1; Wrong:	    while (cond); OK:	    while (cond)		; Wrong:	    do a = 1; while (cond); OK:	    do		a = 1;	    while (cond);  Functions start with: Wrong:	int function_name(int arg1, int arg2) OK:	/*	 * Explanation of what this function is used for.	 *	 * Return value explanation.	 */	    int	function_name(arg1, arg2)	    int		arg1;		/* short comment about arg1 */	    int		arg2;		/* short comment about arg2 */	{	    int		local;		/* comment about local */ 	    local = arg1 * arg2; NOTE: Don't use ANSI style function declarations.  A few people still have touse a compiler that doesn't support it.  SPACES AND PUNCTUATION					*style-spaces* No space between a function name and the bracket: Wrong:  func (arg);OK:	func(arg); Do use a space after if, while, switch, etc. Wrong:	if(arg)		for(;;)OK:	if (arg)	for (;;) Use a space after a comma and semicolon: Wrong:  func(arg1,arg2);	for (i = 0;i < 2;++i)OK:	func(arg1, arg2);	for (i = 0; i < 2; ++i) Use a space before and after '=', '+', '/', etc. Wrong:	var=a*5;OK:	var = a * 5; In general: Use empty lines to group lines of code together.  Put a commentjust above the group of lines.  This makes it more easy to quickly see what isbeing done. OK:	/* Prepare for building the table. */	get_first_item();	table_idx = 0; 	/* Build the table */	while (has_item())	    table[table_idx++] = next_item(); 	/* Finish up. */	cleanup_items();	generate_hash(table); ==============================================================================3. Design decisions					*design-decisions* Folding Several forms of folding should be possible for the same buffer.  For example,have one window that shows the text with function bodies folded, anotherwindow that shows a function body. Folding is a way to display the text.  It should not change the text itself.Therefore the folding has been implemented as a filter between the text storedin a buffer (buffer lines) and the text displayed in a window (logical lines).  Naming the window The word "window" is commonly used for several things: A window on the screen,the xterm window, a window inside Vim to view a buffer.To avoid confusion, other items that are sometimes called window have beengiven another name.  Here is an overview of the related items: screen		The whole display.  For the GUI it's something like 1024x768		pixels.  The Vim shell can use the whole screen or part of it.shell		The Vim application.  This can cover the whole screen (e.g.,		when running in a console) or part of it (xterm or GUI).window		View on a buffer.  There can be several windows in Vim,		together with the command line, menubar, toolbar, etc. they		fit in the shell.  Spell checking						*develop-spell* When spell checking was going to be added to Vim a survey was done over theavailable spell checking libraries and programs.  Unfortunately, the resultwas that none of them provided sufficient capabilities to be used as the spellchecking engine in Vim, for various reasons: - Missing support for multi-byte encodings.  At least UTF-8 must be supported,  so that more than one language can be used in the same file.  Doing on-the-fly conversion is not always possible (would require iconv  support).- For the programs and libraries: Using them as-is would require installing  them separately from Vim.  That's mostly not impossible, but a drawback.- Performance: A few tests showed that it's possible to check spelling on the  fly (while redrawing), just like syntax highlighting.  But the mechanisms  used by other code are much slower.  Myspell uses a hashtable, for example.  The affix compression that most spell checkers use makes it slower too.- For using an external program like aspell a communication mechanism would  have to be setup.  That's complicated to do in a portable way (Unix-only  would be relatively simple, but that's not good enough).  And performance  will become a problem (lots of process switching involved).- Missing support for words with non-word characters, such as "Etten-Leur" and  "et al.", would require marking the pieces of them OK, lowering the  reliability.- Missing support for regions or dialects.  Makes it difficult to accept  all English words and highlight non-Canadian words differently.- Missing support for rare words.  Many words are correct but hardly ever used  and could be a misspelled often-used word.- For making suggestions the speed is less important and requiring to install  another program or library would be acceptable.  But the word lists probably  differ, the suggestions may be wrong words.  Spelling suggestions				*develop-spell-suggestions* For making suggestions there are two basic mechanisms:1. Try changing the bad word a little bit and check for a match with a good   word.  Or go through the list of good words, change them a little bit and   check for a match with the bad word.  The changes are deleting a character,   inserting a character, swapping two characters, etc.2. Perform soundfolding on both the bad word and the good words and then find   matches, possibly with a few changes like with the first mechanism. The first is good for finding typing mistakes.  After experimenting withhashtables and looking at solutions from other spell checkers the conclusionwas that a trie (a kind of tree structure) is ideal for this.  Both forreducing memory use and being able to try sensible changes.  For example, wheninserting a character only characters that lead to good words need to betried.  Other mechanisms (with hashtables) need to try all possible letters atevery position in the word.  Also, a hashtable has the requirement that wordboundaries are identified separately, while a trie does not require this.That makes the mechanism a lot simpler. Soundfolding is useful when someone knows how the words sounds but doesn'tknow how it is spelled.  For example, the word "dictionary" might be writtenas "daktonerie".  The number of changes that the first method would need totry is very big, it's hard to find the good word that way.  After soundfoldingthe words become "tktnr" and "tkxnry", these differ by only two letters. To find words by their soundfolded equivalent (soundalike word) we need a listof all soundfolded words.  A few experiments have been done to find out whatthe best method is.  Alternatives:1. Do the sound folding on the fly when looking for suggestions.  This means   walking through the trie of good words, soundfolding each word and   checking how different it is from the bad word.  This is very efficient for   memory use, but takes a long time.  On a fast PC it takes a couple of   seconds for English, which can be acceptable for interactive use.  But for   some languages it takes more than ten seconds (e.g., German, Catalan),   which is unacceptable slow.  For batch processing (automatic corrections)   it's too slow for all languages.2. Use a trie for the soundfolded words, so that searching can be done just   like how it works without soundfolding.  This requires remembering a list   of good words for each soundfolded word.  This makes finding matches very   fast but requires quite a lot of memory, in the order of 1 to 10 Mbyte.   For some languages more than the original word list.3. Like the second alternative, but reduce the amount of memory by using affix   compression and store only the soundfolded basic word.  This is what Aspell   does.  Disadvantage is that affixes need to be stripped from the bad word   before soundfolding it, which means that mistakes at the start and/or end   of the word will cause the mechanism to fail.  Also, this becomes slow when   the bad word is quite different from the good word. The choice made is to use the second mechanism and use a separate file.  Thisway a user with sufficient memory can get very good suggestions while a userwho is short of memory or just wants the spell checking and no suggestionsdoesn't use so much memory.  Word frequency For sorting suggestions it helps to know which words are common.  In theory wecould store a word frequency with the word in the dictionary.  However, thisrequires storing a count per word.  That degrades word tree compression a lot.And maintaining the word frequency for all languages will be a heavy task.Also, it would be nice to prefer words that are already in the text.  This waythe words that appear in the specific text are preferred for suggestions. What has been implemented is to count words that have been seen duringdisplaying.  A hashtable is used to quickly find the word count.  The count isinitialized from words listed in COMMON items in the affix file, so that italso works when starting a new file. This isn't ideal, because the longer Vim is running the higher the countsbecome.  But in practice it is a noticeable improvement over not using the wordcount. ==============================================================================4. Assumptions						*design-assumptions* Size of variables:char	    8 bit signedchar_u	    8 bit unsignedint	    32 or 64 bit signed (16 might be possible with limited features)unsigned    32 or 64 bit unsigned (16 as with ints)long	    32 or 64 bit signed, can hold a pointer Note that some compilers cannot handle long lines or strings.  The C89standard specifies a limit of 509 characters.  vim:tw=78:ts=8:ft=help:norl: