updated for version 7.0001v7.0001

1 files changed, 384 insertions, 0 deletions

diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
new file mode 100644
index 000000000..6e4f4e35a
--- /dev/null
+++ b/runtime/doc/develop.txt
@@ -0,0 +1,384 @@
+*develop.txt*   For Vim version 7.0aa.  Last change: 2004 Jan 17
+
+
+		  VIM REFERENCE MANUAL    by Bram Moolenaar
+
+
+Development of Vim.					*development*
+
+This text is important for those who want to be involved in further developing
+Vim.
+
+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 source
+code.
+
+Vim is open source software.  Everybody is encouraged to contribute to help
+improving 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.  A
+balance 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 for
+Vi.  When the user wants to, he can use Vim in compatible mode and hardly
+notice 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 a
+completely 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 and
+fast.
+- 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!
+- 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 rather
+than coercing its users into particular patterns of work.  This can be for
+items with a large impact (e.g., the 'compatible' option) or for details.  The
+defaults are carefully chosen such that most users will enjoy using Vim as it
+is.  Commands and options can be used to adjust Vim to the desire of the user
+and 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.  ;-)"
+- 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.  Please
+stick 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.  Always
+consider using the Vim version, because they were introduced with a reason.
+
+NORMAL NAME	VIM NAME	DIFFERENCE OF VIM VERSION
+free()		vim_free()	Checks for freeing NULL
+malloc()	alloc()		Checks for out of memory situation
+malloc()	lalloc()	Like alloc(), but has long argument
+strcpy()	STRCPY()	Includes cast to (char *), for char_u * args
+strchr()	vim_strchr()	Accepts special characters
+strrchr()	vim_strrchr()	Accepts special characters
+isspace()	vim_isspace()	Can handle characters > 128
+iswhite()	vim_iswhite()	Only TRUE for Tab and space
+memcpy()	vim_memmove()	Handles overlapped copies
+bcopy()		vim_memmove()	Handles overlapped copies
+memset()	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, we
+need to avoid using names that are already defined by the system.  This is a
+list of names that are known to cause trouble.  The name is given as a regexp
+pattern.
+
+is.*()		POSIX, ctype.h
+to.*()		POSIX, ctype.h
+
+d_.*		POSIX, dirent.h
+l_.*		POSIX, fcntl.h
+gr_.*		POSIX, grp.h
+pw_.*		POSIX, pwd.h
+sa_.*		POSIX, signal.h
+mem.*		POSIX, string.h
+str.*		POSIX, string.h
+wcs.*		POSIX, string.h
+st_.*		POSIX, stat.h
+tms_.*		POSIX, times.h
+tm_.*		POSIX, time.h
+c_.*		POSIX, termios.h
+MAX.*		POSIX, limits.h
+__.*		POSIX, system
+_[A-Z].*	POSIX, system
+E[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.h
+index		shadows global declaration
+time		shadows global declaration
+new		C++ reserved keyword
+try		Borland C++ doesn't like it to be used as a variable.
+
+basename()	GNU string function
+dirname()	GNU string function
+get_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_THING
+Features always start with "FEAT_": >
+    #define FEAT_FOO
+
+Don't use '\"', some compilers can't handle it.  '"' works fine.
+
+Don't use:
+    #if HAVE_SOME
+Some compilers can't handle that and complain that "HAVE_SOME" is not defined.
+Use
+    #ifdef HAVE_SOME
+or
+    #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 to
+use 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 comment
+just above the group of lines.  This makes it more easy to quickly see what is
+being 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, another
+window 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 stored
+in 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 been
+given 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.
+
+
+To be continued...
+
+==============================================================================
+4. Assumptions						*design-assumptions*
+
+Size of variables:
+char	    8 bit signed
+char_u	    8 bit unsigned
+int	    16, 32 or 64 bit signed
+unsigned    16, 32 or 64 bit unsigned
+long	    32 or 64 bit signed, can hold a pointer
+
+Note that some compilers cannot handle long lines or strings.  The C89
+standard specifies a limit of 509 characters.
+
+ vim:tw=78:ts=8:ft=help:norl: