Help: Evil documentation

Thu Jun 7 09:57:17 CEST 2012

Hi everyone,

as stated in a recent post one of the most important missing parts of
evil for a 1.0 is the documentation. The documentation should cover
the main configuration possibilities as well as give some insights to
evil's internal architecture. Of course, the first aspect is much more
important than the latter. It should give a new user enough
information to redefine key-bindings or tweak the customisation
options and the advanced user to define own commands and motions.

The documentation should be written in texinfo. There's a branch "doc"
that already contains some initial documentation that can be used as a
starting point but probably needs some restructuring. If anyone wants
to contribute some documentation the best way is to send patches for
the doc branch.

I've written down *my* thoughts of how the outline of the doc should
look like. Please feel free to comment, discuss, restructure, modify
.... This should only be considered as a first guideline, not as
something definite.

Some parts are probably relatively easy to fill like states and
keymaps, others are much more complicated and can probably only be
filled by developers. Fortunately, the non-developer parts are
probably more important. Please remember what information you missed
when you started with evil ;)

Your help is greatly appreciated.

Thanks in advance

Frank

-- PRELIMINARY OUTLINE ---
* Introduction
** What's evil  
   - differences to other packages, viper, vimpulse, vim-mode, ...
   - see Vim's documentation!
** Download, Installation
   - ELPA (soon?)
   - el-get
   - direct
** Mailing list, IRC, issue tracker

* States
** Overview
** Initial states
   - starting state for major modes

* Keymaps
** Overview  
** States and keymaps
   - state specific keymaps (global, local)
   - keymap hierarchy 
     - (which keymaps are enabled in which state)
 - priority of keymaps
** Defining key bindings
   - define key
   - Delayed initialisation of key bindings, evil-declare-key
** The ESC key
   - problems in the terminal

* Commands
** Overview
** Ranges (inclusive, exclusive, line, block)
** Motions
** Text objects
   - how to define text objects
   - helper functions
** Commands
** Operators
   - Motions/Text objects and operators
   - Operators in visual state
   - Operators in ex-state

* Interactive codes
** Overview
** Extended predefined codes
** Defining new codes

* Ex-state
** Overview
** Defining ex command bindings (evil-ex-define-cmd)
** Defining ex commands (aka operators/commands with special interactive codes)
** Ex argument handlers
** Key bindings in ex state   

* Searching
** isearch module
** evil built-in module

* The repeat system
** Overview
** Key sequence based recording
** Change based recording
** Programmable recording for commands

* Customisation options

* Helper Functions
  - functions/variables that can be used for own commands
** Current state, switching states