neovim/runtime/doc/develop.txt

*develop.txt*   For Vim version 7.4.  Last change: 2016 Jan 31


		  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. Design decisions	|design-decisions|

See the file "src/nvim/README.md" for a high-level 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://vim.wikia.com/wiki/How_to_make_and_submit_a_patch.

==============================================================================
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... 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 exist.
- 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 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 rather
than coercing its users into particular patterns of work.  This can be for
items with a large impact 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.


NVIM IS... NOT						*design-not*

Nvim is not an Operating System; instead it should be composed with other
tools, or hosted as a component. Marvim once said: "Unlike Emacs, Nvim does
not attempt to include everything but the kitchen sink, but some people use it
for plumbing."


==============================================================================
2. 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.



 vim:tw=78:ts=8:ft=help:norl: