Update documentation

README.md

@@ -2,20 +2,20 @@
 
 ###Introduction
 
-Vim is a powerful text editor with a big, increasing community. Even though it
+Vim is a powerful text editor with a big community that is constantly growing.
-is more than 20 years old, people still extend and improve it, mostly using
+Even though the editor is over two decades old, people still extend and improve
-vimscript or one of the supported scripting languages.
+it, mostly using vimscript or one of the supported scripting languages.
 
 ###Problem
 
-Over its 20 years of life, vim has accumulated about 300k lines of scary C89
+Over its more than 20 years of life, vim has accumulated about 300k lines of
-code that very few people understand or have the guts to mess with.
+scary C89 code that very few people understand or have the guts to mess with.
 
 Another issue, is that as the only person responsible for maintaing vim's big
 codebase, Bram Moolenaar has to be extra-careful before accepting patches,
 because once merged, the new code will be his responsibility.
 
-These problems make it pretty hard to have new features and bug fixes merged
+These problems make it very difficult to have new features and bug fixes merged
 into the core. Vim just cant keep up with the development speed of its plugin
 echosystem.
 
@@ -26,41 +26,62 @@ the following goals:
 
 - Simplify maintenance to improve the speed that bug fixes and
   features get merged.
-- Split the responsibility between multiple developers.
+- Split the maintainance work between multiple developers.
 - Enable the implementation of new/modern user interfaces without any modifications
   to the core source. 
 - Improve the extensibility power with a new plugin architecture based on
   external processes. Plugins will be written in any programming language
-  without any explicit support from the editor. This can be saw as a better
+  without any explicit support from the editor.
-  implementation of the [job control patch](https://groups.google.com/forum/#!topic/vim_dev/QF7Bzh1YABU)
 
-Those goals should be achieved with little impact on vim's editing model or
+A consequence of achieving those goals is that new developers will join the
-vimscript in general. Most vimscript plugins should continue to work normally.
+community, consequently improving the editor for all users.
 
-The following topics summarizes the major changes that will be performed:
+It is important to empathise that this is not a project to rewrite vim from the
+scratch or transform it into an IDE(though the new features provided will make
+it possible to build IDE-like distributions of the editor). The changes
+implemented here should have little impact on vim's editing model or vimscript
+in general. Most vimscript plugins should continue to work normally.
 
+Each of the following topics will briefly explain the major changes that will
+be performed in the first iterations:
+
+* <a href="#build"><b>Migrate to a cmake-based build</b></a>
 * <a href="#legacy"><b>Legacy support and compile-time features</b></a>
 * <a href="#platform"><b>Platform-specific code </b></a>
 * <a href="#plugins"><b>New plugin architecture</b></a>
 * <a href="#gui"><b>New GUI architecture</b></a>
 * <a href="#split"><b>Split into many repositories</b></a>
 
+<a name="build"></a>
+##### Migrate to a cmake-based build
+
+The source tree has dozens(if not hundreds) of files dedicated to building vim
+with on various platforms with different configurations, and many of these files
+look abandoned or outdated. Most users dont care about selecting individual
+features and just compile using '--with-features=huge', which still generates an
+executable that is small enough even for lightweight systems(by today's
+standards).
+
+All those files will be removed and vim will be built using
+[cmake](www.cmake.org), a modern build system that generates build scripts for
+the most relevant platforms.
+
 <a name="legacy"></a>
 ##### Legacy support and compile-time features
 
 Vim has a significant amount of code dedicated to supporting legacy systems and
 compilers. All that code increases the maintainance burden and will be removed.
 
-Most optional features will no longer be optional, with the exception of some
+Most optional features will no longer be optional(see above), with the exception
-broken and useless fetures(eg: netbeans integration, sun workshop) which will be
+of some broken and useless fetures(eg: netbeans integration, sun workshop) which
-removed permanently. Vi emulation will also be removed(probably leave the 'set
+will be removed permanently. Vi emulation will also be removed(probably leave
-nocompatible' command as a no-op).
+the 'set nocompatible' command as a no-op).
 
 These changes wont affect most users. Those that only have a C89 compiler
-installed or develop on legacy systems such as Amiga, BeOS or MSDOS have two
+installed or use vim on legacy systems such as Amiga, BeOS or MSDOS have two
-choices:
+options:
 
-- Upgrade their software.
+- Upgrade their software
 - Continue using vim
 
 <a name="platform"></a>
@@ -68,8 +89,11 @@ choices:
 
 Most of the platform-specific code will be removed and
 [libuv](https://github.com/joyent/libuv) will be used to handle system
-differences. libuv has support for most unixes and windows, so the vast
+differences.
-majority of vim's community will be supported.
+
+libuv is a modern multi-platform library with functions to perform
+common system tasks, and supports most unixes and windows, so the vast majority
+of vim's community will be covered.
 
 <a name="plugins"></a>
 ##### New plugin architecture
@@ -78,8 +102,9 @@ All code supporting embedded scripting language interpreters will be replaced
 by a new plugin system that will support extensions written in any programming
 language.
 
-Compatibility layers will be provided for easily porting vim plugins written in some
+Compatibility layers will be provided for vim plugins written in some of the
-of the currently supported scripting languages such as python or ruby.
+currently supported scripting languages such as python or ruby. Most plugins
+should work on neovim with little modifications, if any.
 
 This is how the new plugin system will work:
 
@@ -90,26 +115,29 @@ This is how the new plugin system will work:
 - Plugins will be able to listen to events and send commands to vim
   asynchronously.
 
-Here's a sample plugin session using [json-rpc](http://www.jsonrpc.org/specification) (jsonrpc version omitted):
+This system will be built on top of a job control mechanism similar to the one
+provided by the [job control patch](https://groups.google.com/forum/#!topic/vim_dev/QF7Bzh1YABU)
+
+Here's an idea of how a plugin session will work using [json-rpc](http://www.jsonrpc.org/specification) (jsonrpc version omitted):
 
 ```js
-plugin -> vim: {"id": 1, "method": "listenEvent", "params": {"eventName": "keyPressed"}}
+plugin -> neovim: {"id": 1, "method": "listenEvent", "params": {"eventName": "keyPressed"}}
-vim -> plugin: {"id": 1, "result": true}
+neovim -> plugin: {"id": 1, "result": true}
-vim -> plugin: {"method": "event", "params": {"name": "keyPressed", "eventArgs": {"keys": ["C"]}}}
+neovim -> plugin: {"method": "event", "params": {"name": "keyPressed", "eventArgs": {"keys": ["C"]}}}
-vim -> plugin: {"method": "event", "params": {"name": "keyPressed", "eventArgs": {"keys": ["Ctrl", "Space"]}}}
+neovim -> plugin: {"method": "event", "params": {"name": "keyPressed", "eventArgs": {"keys": ["Ctrl", "Space"]}}}
-plugin -> vim: {"id": 2, "method": "showPopup", "params": {"size": {"width": 10, "height": 2} "position": {"column": 2, "line": 3}, "items": ["Completion1", "Completion2"]}}
+plugin -> neovim: {"id": 2, "method": "showPopup", "params": {"size": {"width": 10, "height": 2} "position": {"column": 2, "line": 3}, "items": ["Completion1", "Completion2"]}}
-plugin -> vim: {"id": 2, "result": true}}
+plugin -> neovim: {"id": 2, "result": true}}
 ```
 
-That shows the conversation between vim and an hypotetical completion plugin
+That shows an hypothetical conversation between neovim and completion plugin
-that popups completions when the user presses Ctrl+Space. The above scheme gives
+that displays completions when the user presses Ctrl+Space. The above scheme
-neovim near limitless extensibility and also improves stability as plugins will
+gives neovim near limitless extensibility and also improves stability as plugins
-be automatically sandboxed from the main executable. 
+will automatically be isolated from the main executable. 
 
-This system can also easily emulate scripting languages interfaces to vim. A
+This system can also easily emulate the current scripting languages interfaces
-plugin could, for example, emulate the current python interface by discovering
+to vim. For example, a plugin can emulate the python interface by running python
-python scripts in vim's runtime dir and exposing a 'vim' module with an API
+scripts sent by vim in its own context and by exposing a 'vim' module with an
-matching the current one. Calls to the API would simply be translated to
+API matching the current one. Calls to the API would simply be translated to
 json-rpc messages sent to vim.
 
 
@@ -118,7 +146,7 @@ json-rpc messages sent to vim.
 
 Another contributing factor to vim's huge codebase is the explicit support for
 dozens of widget toolkits for GUI interfaces. Like the legacy code support, gui
-handling code will be removed from neovim's core.
+handling code will be removed from the core.
 
 Neovim will handle GUIs similarly to how it will handle plugins:
 
@@ -128,8 +156,8 @@ Neovim will handle GUIs similarly to how it will handle plugins:
   using json-rpc or msgpack-rpc.
 
 The difference between plugins and GUIs is that plugins will be started by
-neovim, where GUIs will start neovim(or perhaps attach to a running session).
+neovim, where neovim will be started by programs running the GUI. Here's a sample
-Here's a sample diagram of the process tree:
+diagram of the process tree:
 
 ```
 GUI program
@@ -143,7 +171,7 @@ GUI program
          ---> Plugin 3
 ```
 
-Sample:
+Hypothetical GUI session:
 
 ```js
 gui -> vim: {"id": 1, "method": "initClient", "params": {"size": {"rows": 20, "columns": 25}}}
@@ -157,23 +185,62 @@ This new GUI architecture creates many interesting possibilities:
 
 - Modern GUIs written in high-level programming languages that integrate better
   with the operating system. We can have GUIs written using C#/WPF on
-  Windows or Ruby/Cocoa on Mac.
+  Windows or Ruby/Cocoa on Mac, for example.
 - Plugins will be able emit custom events that may be handled directly by GUIs.
   This will enable the implementaton of advanced features such as sublime's
   minimap. 
-- A multiplexing daemon could could keep neovim instances running in a
+- A multiplexing daemon could keep neovim instances running in a headless
-  headless server, while multiple remote GUIs could attach/detach to share
+  server, while multiple remote GUIs could attach/detach to share editing
-  editing sessions.
+  sessions.
-- Neovim can be easily embedded into other programs.
+- Simplified headless testing.
+- Embedding the editor into other programs.
 
-<a name="split"></a>
+Here's a diagram that illustrates how a client-server process tree might look
-##### Split into many repositories
+like:
+
+```
+Server daemon listening on tcp sockets <------ GUI 1 (attach/detach to running instances using tcp sockets)
+  |                                       |
+  ---> Neovim                             | 
+         |                                GUI 2 (sharing the same session with GUI 1)
+         ---> Plugin 1
+         |
+         ---> Plugin 2
+         |
+         ---> Plugin 3
+```
+
+
+<a name="development"></a>
+##### Development
+
+Development will happen on the [neovim organization](https://github.com/neovim),
+and the code will be split across many repositories. There will be separate
+repositories for GUIs, plugins, runtime files(official vimscript) and
+distributions. This will let the editor receive improvements much faster as the
+patches dont have to go all through a single person for approval.
+
+Travis will also be used for continuous integration, so pull requests will be
+automatically checked.
+
+###Future
+
+The changes described are relatively simple to integrate and will be part of the
+first iteration. Here are more possibilities for the future:
+
+- Refactor the way input is read. Heres a great simplification of how vim
+  currently works: `while (true) { process_input(getc()); }`, we want to remove
+  the `while(true)` chunks from the core and provide something like this:
+  `process_input(char c)`. This will help extract the editor logic into a
+  library.
+- Remove all globals. Basically every function will receive a pointer to a
+  struct representing the editor and containing data currently held by global
+  variables. Helpful if a 'libvim' is implemented in the future.
+- Replace the current vimscript C implementation by [lua](www.lua.org)
+  or [luajit](www.luajit.org) and compile vimscript into lua, similarly to how
+  coffeescript is compiled into javascript. This will greatly reduce the
+  maintainance burden and give vimscript a real boost in performance.
   
-Neovim's code will be split across many repositories in the [neovim
-organization](https://github.com/neovim). There will be separate repositories
-for GUIs, plugins, runtime files(official vimscript) and distributions. This
-will let neovim will receive improvements much faster as the patches wont have
-to pass through the approval of a single person.
 
 ###Status
 
@@ -188,6 +255,10 @@ Here's a list of things that have been done so far:
   normalize source code formatting.
 - The autotools build system was replaced by [cmake](http://www.cmake.org/)
 
+and of what is being currently worked on:
+
+- Port all IO to libuv
+
 ###Dependencies
 
 For Ubuntu 12.04: