diff options
Diffstat (limited to 'runtime/doc/develop.txt')
| -rw-r--r-- | runtime/doc/develop.txt | 61 |
1 files changed, 36 insertions, 25 deletions
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index 76ccc42546..0e909aac65 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -6,22 +6,20 @@ Development of Nvim. *development* -1. Design goals |design-goals| -2. Design decisions |design-decisions| +1. Design goals |design-goals| +2. Developer guidelines |dev-help| Nvim is open source software. Everybody is encouraged to contribute. https://github.com/neovim/neovim/blob/master/CONTRIBUTING.md -See src/nvim/README.md for a high-level overview of the source code: - https://github.com/neovim/neovim/blob/master/src/nvim/README.md +See src/nvim/README.md for an overview of the source code. ============================================================================== -1. Design goals *design-goals* +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. +Note that some items conflict; this is intentional. A balance must be found. NVIM IS... IMPROVED *design-improved* @@ -41,7 +39,7 @@ completely different editor. Extensions are done with a "Vi spirit". - 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 + is based on (1) what users ask for, (2) how much effort it takes to implement and (3) someone actually implementing it. @@ -56,20 +54,14 @@ Vim tries to help as many users on as many platforms as possible. - 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.] + version. Features should be present in all versions. NVIM 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. +- Documentation should be comprehensive and understandable. Use examples. - Don't make the text unnecessarily long. Less documentation means that an item is easier to find. - Do not prefix doc-tags with "nvim-". Use |vim_diff.txt| to document @@ -77,12 +69,12 @@ NVIM IS... WELL DOCUMENTED *design-documented* to mark a specific feature. No other distinction is necessary. - If a feature is removed, delete its doc entry and move its tag to |vim_diff.txt|. +- Move deprecated features to |deprecated.txt|. NVIM 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. +Keep Nvim 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. @@ -118,13 +110,14 @@ 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 -include the kitchen sink... but you can use it for plumbing." +include the kitchen sink... but it's good for plumbing." ============================================================================== -2. Design decisions *design-decisions* +Developer guidelines *dev-help* -JARGON *dev-jargon* + +JARGON *dev-jargon* API client ~ All external UIs and remote plugins (as opposed to regular Vim plugins) are @@ -150,15 +143,14 @@ 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. +screen The whole display. 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. -PROVIDERS *dev-provider* +PROVIDERS *dev-provider* A goal of Nvim is to allow extension of the editor without special knowledge in the core. But some Vim components are too tightly coupled; in those cases @@ -202,7 +194,7 @@ Python host isn't installed then the plugin will "think" it is running in a Vim compiled without the |+python| feature. -API *dev-api* +API *dev-api* Use this pattern to name new API functions: nvim_{thing}_{action}_{arbitrary-qualifiers} @@ -233,4 +225,23 @@ _not_ a Buffer). The common {action} "list" indicates that it lists all bufs (plural) in the global context. +EXTERNAL UI *dev-ui* + +External UIs should be aware of the |api-contract|. In particular, future +versions of Nvim may add optional, new items to existing events. The API is +strongly backwards-compatible, but clients must not break if new fields are +added to existing events. + +External UIs are expected to implement some common features. + +- Users may want to configure UI-specific options. The UI should publish the + |GUIEnter| autocmd after attaching to Nvim: > + doautocmd GUIEnter +- Options can be monitored for changes by the |OptionSet| autocmd. E.g. if the + user sets the 'guifont' option, this autocmd notifies channel 42: > + autocmd OptionSet guifont call rpcnotify(42, 'option-changed', 'guifont', &guifont) +- cursor-shape change: 'guicursor' properties are sent in the mode_info_set UI + event. + + vim:tw=78:ts=8:ft=help:norl: |